Document log_suspend() and fix the description of the change_winsize() return value.

diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat
index 24d3956f8d8ee509e6e27875767d23d91184c82b..ac5549226ac50c0d747dbac571900355f2bbddec 100644 (file)
--- a/doc/sudo_plugin.cat
+++ b/doc/sudo_plugin.cat
@@ -868,6 +868,7 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
          void (*deregister_hooks)(int version,
             int (*deregister_hook)(struct sudo_hook *hook));
          int (*change_winsize)(unsigned int lines, unsigned int cols);
+         int (*log_suspend)(int signo);
      };
 
      When an I/O plugin is loaded, s\bsu\bud\bdo\bo runs the command in a pseudo-tty.
@@ -1130,8 +1131,19 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
 
            The c\bch\bha\ban\bng\bge\be_\b_w\bwi\bin\bns\bsi\biz\bze\be() function is called whenever the window size of
            the terminal changes from the initial values specified in the
-           user_info list.  It returns 1 on success, 0 on failure, -1 if an
-           error occurred (which will terminate the running command).
+           user_info list.  Returns -1 if an error occurred, in which case no
+           further calls to c\bch\bha\ban\bng\bge\be_\b_w\bwi\bin\bns\bsi\biz\bze\be() will be made,
+
+     log_suspend
+           int (*log_suspend)(int signo);
+
+           The l\blo\bog\bg_\b_s\bsu\bus\bsp\bpe\ben\bnd\bd() function is called whenever a command is
+           suspended or resumed.  The _\bs_\bi_\bg_\bn_\bo argument is either the signal that
+           caused the command to be suspended or SIGCONT if the command was
+           resumed.  Logging this information makes it possible to skip the
+           period of time when the command was suspended during playback of a
+           session.  Returns -1 if an error occurred, in which case no further
+           calls to l\blo\bog\bg_\b_s\bsu\bus\bsp\bpe\ben\bnd\bd() will be made,
 
      _\bI_\b/_\bO _\bP_\bl_\bu_\bg_\bi_\bn _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
 
@@ -1619,6 +1631,9 @@ P\bPL\bLU\bUG\bGI\bIN\bN A\bAP\bPI\bI C\bCH\bHA\bAN\bNG\bGE\bEL\bLO\bOG\bG
      Version 1.12 (sudo 1.8.21)
            The change_winsize field was added to the io_plugin struct.
 
+     Version 1.13 (sudo 1.8.26)
+           The log_suspend field was added to the io_plugin struct.
+
 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
      sudo.conf(4), sudoers(4), sudo(1m)
 
@@ -1648,4 +1663,4 @@ D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
      file distributed with s\bsu\bud\bdo\bo or https://www.sudo.ws/license.html for
      complete details.
 
-Sudo 1.8.26                     October 6, 2018                    Sudo 1.8.26
+Sudo 1.8.26                     October 7, 2018                    Sudo 1.8.26

diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in
index 71ca646b4ba2e60308f957d58edf5e9422bb1149..7428cc3ded7b629c263b6b1e4f0276e740a032ef 100644 (file)
--- a/doc/sudo_plugin.man.in
+++ b/doc/sudo_plugin.man.in
@@ -15,7 +15,7 @@
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.TH "SUDO_PLUGIN" "5" "October 6, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDO_PLUGIN" "5" "October 7, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -1470,6 +1470,7 @@ struct io_plugin {
     void (*deregister_hooks)(int version,
        int (*deregister_hook)(struct sudo_hook *hook));
     int (*change_winsize)(unsigned int lines, unsigned int cols);
+    int (*log_suspend)(int signo);
 };
 .RE
 .fi
@@ -1991,8 +1992,32 @@ function is called whenever the window size of the terminal changes from
 the initial values specified in the
 \fRuser_info\fR
 list.
-It returns 1 on success, 0 on failure, \-1 if an error occurred (which
-will terminate the running command).
+Returns \-1 if an error occurred, in which case no further calls to
+\fBchange_winsize\fR()
+will be made,
+.RE
+.TP 6n
+log_suspend
+.nf
+.RS 6n
+int (*log_suspend)(int signo);
+.RE
+.fi
+.RS 6n
+.sp
+The
+\fBlog_suspend\fR()
+function is called whenever a command is suspended or resumed.
+The
+\fIsigno\fR
+argument is either the signal that caused the command to be suspended or
+\fRSIGCONT\fR
+if the command was resumed.
+Logging this information makes it possible to skip the period of time when
+the command was suspended during playback of a session.
+Returns \-1 if an error occurred, in which case no further calls to
+\fBlog_suspend\fR()
+will be made,
 .RE
 .PP
 \fII/O Plugin Version Macros\fR
@@ -2883,6 +2908,11 @@ Version 1.12 (sudo 1.8.21)
 The
 \fRchange_winsize\fR
 field was added to the io_plugin struct.
+.TP 6n
+Version 1.13 (sudo 1.8.26)
+The
+\fRlog_suspend\fR
+field was added to the io_plugin struct.
 .SH "SEE ALSO"
 sudo.conf(@mansectform@),
 sudoers(@mansectform@),

diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in
index dfa6e51ba473798d40739461c527eb0ed46e9bb8..c518fe196968fadd2715b4809b37c3a42af5e146 100644 (file)
--- a/doc/sudo_plugin.mdoc.in
+++ b/doc/sudo_plugin.mdoc.in
@@ -14,7 +14,7 @@
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 6, 2018
+.Dd October 7, 2018
 .Dt SUDO_PLUGIN @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -1299,6 +1299,7 @@ struct io_plugin {
     void (*deregister_hooks)(int version,
        int (*deregister_hook)(struct sudo_hook *hook));
     int (*change_winsize)(unsigned int lines, unsigned int cols);
+    int (*log_suspend)(int signo);
 };
 .Ed
 .Pp
@@ -1742,8 +1743,27 @@ function is called whenever the window size of the terminal changes from
 the initial values specified in the
 .Li user_info
 list.
-It returns 1 on success, 0 on failure, \-1 if an error occurred (which
-will terminate the running command).
+Returns \-1 if an error occurred, in which case no further calls to
+.Fn change_winsize
+will be made,
+.It log_suspend
+.Bd -literal -compact
+int (*log_suspend)(int signo);
+.Ed
+.Pp
+The
+.Fn log_suspend
+function is called whenever a command is suspended or resumed.
+The
+.Fa signo
+argument is either the signal that caused the command to be suspended or
+.Dv SIGCONT
+if the command was resumed.
+Logging this information makes it possible to skip the period of time when
+the command was suspended during playback of a session.
+Returns \-1 if an error occurred, in which case no further calls to
+.Fn log_suspend
+will be made,
 .El
 .Pp
 .Em I/O Plugin Version Macros
@@ -2528,6 +2548,10 @@ list.
 The
 .Li change_winsize
 field was added to the io_plugin struct.
+.It Version 1.13 (sudo 1.8.26)
+The
+.Li log_suspend
+field was added to the io_plugin struct.
 .El
 .Sh SEE ALSO
 .Xr sudo.conf @mansectform@ ,