From 5433eb546a2d235d389430d1e7b9863868b07af3 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Sun, 7 Oct 2018 07:18:29 -0600 Subject: [PATCH] Document log_suspend() and fix the description of the change_winsize() return value. --- doc/sudo_plugin.cat | 21 ++++++++++++++++++--- doc/sudo_plugin.man.in | 36 +++++++++++++++++++++++++++++++++--- doc/sudo_plugin.mdoc.in | 30 +++++++++++++++++++++++++++--- 3 files changed, 78 insertions(+), 9 deletions(-) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 24d3956f8..ac5549226 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -868,6 +868,7 @@ DDEESSCCRRIIPPTTIIOONN 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, ssuuddoo runs the command in a pseudo-tty. @@ -1130,8 +1131,19 @@ DDEESSCCRRIIPPTTIIOONN The cchhaannggee__wwiinnssiizzee() 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 cchhaannggee__wwiinnssiizzee() will be made, + + log_suspend + int (*log_suspend)(int signo); + + The lloogg__ssuussppeenndd() function is called whenever a command is + suspended or resumed. The _s_i_g_n_o 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 lloogg__ssuussppeenndd() will be made, _I_/_O _P_l_u_g_i_n _V_e_r_s_i_o_n _M_a_c_r_o_s @@ -1619,6 +1631,9 @@ PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG 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. + SSEEEE AALLSSOO sudo.conf(4), sudoers(4), sudo(1m) @@ -1648,4 +1663,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo 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 71ca646b4..7428cc3de 100644 --- 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 dfa6e51ba..c518fe196 100644 --- 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@ , -- 2.40.0