Document signal handler behavior in plugin API 1.3

diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat
index e433be588dbe1fbcb87bf9d0895db855ee0796c2..ae265109bbde227b0deeb8d879ab19e77a7ee67a 100644 (file)
--- a/doc/sudo_plugin.cat
+++ b/doc/sudo_plugin.cat
@@ -1069,6 +1069,29 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
 
      Same as for the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI.
 
+   S\bSi\big\bgn\bna\bal\bl h\bha\ban\bnd\bdl\ble\ber\brs\bs
+     The s\bsu\bud\bdo\bo front end installs default signal handlers to trap common
+     signals while the plugin functions are run.  The following signals are
+     trapped by default before the command is executed:
+
+     o\bo   SIGALRM
+     o\bo   SIGHUP
+     o\bo   SIGINT
+     o\bo   SIGQUIT
+     o\bo   SIGTERM
+     o\bo   SIGTSTP
+     o\bo   SIGUSR1
+     o\bo   SIGUSR2
+
+     If a fatal signal is received before the command is executed, s\bsu\bud\bdo\bo will
+     call the plugin's c\bcl\blo\bos\bse\be() function with an exit status of 128 plus the
+     value of the signal that was received.  This allows for consistent
+     logging of commands killed by a signal for plugins that log such
+     information in their c\bcl\blo\bos\bse\be() function.
+
+     A plugin may temporarily install its own signal handlers but must restore
+     the original handler before the plugin function returns.
+
    H\bHo\boo\bok\bk f\bfu\bun\bnc\bct\bti\bio\bon\bn A\bAP\bPI\bI
      Beginning with plugin API version 1.2, it is possible to install hooks
      for certain functions called by the s\bsu\bud\bdo\bo front end.
@@ -1388,6 +1411,13 @@ P\bPL\bLU\bUG\bGI\bIN\bN A\bAP\bPI\bI C\bCH\bHA\bAN\bNG\bGE\bEL\bLO\bOG\bG
            used to merge in environment variables stored in the PAM handle
            before a command is run.
 
+     Version 1.3
+           Support for the _\be_\bx_\be_\bc_\b__\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd entry has been added to the
+           command_info list.
+
+           The s\bsu\bud\bdo\bo front end now installs default signal handlers to trap
+           common signals while the plugin functions are run.
+
 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
      sudoers(4), sudo(1m)
 

diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in
index 6a07c2b2add5a29b499173fe2a90cd218604a245..b800da4141abc4576b521e13ca234b1da03f5aec 100644 (file)
--- a/doc/sudo_plugin.man.in
+++ b/doc/sudo_plugin.man.in
@@ -1971,6 +1971,53 @@ section for a description of
 .PP
 Same as for the
 \fIPolicy plugin API\fR.
+.SS "Signal handlers"
+The
+\fBsudo\fR
+front end installs default signal handlers to trap common signals
+while the plugin functions are run.
+The following signals are trapped by default before the command is
+executed:
+.TP 4n
+\fBo\fR
+\fRSIGALRM\fR
+.PD 0
+.TP 4n
+\fBo\fR
+\fRSIGHUP\fR
+.TP 4n
+\fBo\fR
+\fRSIGINT\fR
+.TP 4n
+\fBo\fR
+\fRSIGQUIT\fR
+.TP 4n
+\fBo\fR
+\fRSIGTERM\fR
+.TP 4n
+\fBo\fR
+\fRSIGTSTP\fR
+.TP 4n
+\fBo\fR
+\fRSIGUSR1\fR
+.TP 4n
+\fBo\fR
+\fRSIGUSR2\fR
+.PD
+.PP
+If a fatal signal is received before the command is executed,
+\fBsudo\fR
+will call the plugin's
+\fBclose\fR()
+function with an exit status of 128 plus the value of the signal
+that was received.
+This allows for consistent logging of commands killed by a signal
+for plugins that log such information in their
+\fBclose\fR()
+function.
+.PP
+A plugin may temporarily install its own signal handlers but must
+restore the original handler before the plugin function returns.
 .SS "Hook function API"
 Beginning with plugin API version 1.2, it is possible to install
 hooks for certain functions called by the
@@ -2532,6 +2579,18 @@ Policy plugin function is now passed a pointer
 to the user environment which can be updated as needed.
 This can be used to merge in environment variables stored in the PAM
 handle before a command is run.
+.TP 6n
+Version 1.3
+Support for the
+\fIexec_background\fR
+entry has been added to the
+\fRcommand_info\fR
+list.
+.sp
+The
+\fBsudo\fR
+front end now installs default signal handlers to trap common signals
+while the plugin functions are run.
 .SH "SEE ALSO"
 sudoers(@mansectform@),
 sudo(@mansectsu@)

diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in
index e677bc400362d38b12a4cca275ed26efd99b3b40..946d69d048bbdabde7e5fb4888022746318ee86c 100644 (file)
--- a/doc/sudo_plugin.mdoc.in
+++ b/doc/sudo_plugin.mdoc.in
@@ -1718,6 +1718,46 @@ section for a description of
 .Pp
 Same as for the
 .Sx Policy plugin API .
+.Ss Signal handlers
+The
+.Nm sudo
+front end installs default signal handlers to trap common signals
+while the plugin functions are run.
+The following signals are trapped by default before the command is
+executed:
+.Pp
+.Bl -bullet -compact
+.It
+.Dv SIGALRM
+.It
+.Dv SIGHUP
+.It
+.Dv SIGINT
+.It
+.Dv SIGQUIT
+.It
+.Dv SIGTERM
+.It
+.Dv SIGTSTP
+.It
+.Dv SIGUSR1
+.It
+.Dv SIGUSR2
+.El
+.Pp
+If a fatal signal is received before the command is executed,
+.Nm sudo
+will call the plugin's
+.Fn close
+function with an exit status of 128 plus the value of the signal
+that was received.
+This allows for consistent logging of commands killed by a signal
+for plugins that log such information in their
+.Fn close
+function.
+.Pp
+A plugin may temporarily install its own signal handlers but must
+restore the original handler before the plugin function returns.
 .Ss Hook function API
 Beginning with plugin API version 1.2, it is possible to install
 hooks for certain functions called by the
@@ -2195,6 +2235,17 @@ Policy plugin function is now passed a pointer
 to the user environment which can be updated as needed.
 This can be used to merge in environment variables stored in the PAM
 handle before a command is run.
+.It Version 1.3
+Support for the
+.Em exec_background
+entry has been added to the
+.Li command_info
+list.
+.Pp
+The
+.Nm sudo
+front end now installs default signal handlers to trap common signals
+while the plugin functions are run.
 .El
 .Sh SEE ALSO
 .Xr sudoers @mansectform@ ,