From 241174ea2dc5ee388855b0405a194be421cce453 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Wed, 9 Sep 2015 15:14:06 -0600 Subject: [PATCH] Document what happens when the on_suspend/on_resume callbacks return an error. --- doc/sudo_plugin.cat | 14 ++++++++------ doc/sudo_plugin.man.in | 5 ++++- doc/sudo_plugin.mdoc.in | 5 ++++- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 164271a3c..720f60f5d 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -1320,11 +1320,13 @@ DDEESSCCRRIIPPTTIIOONN contain function pointers to be called when the ssuuddoo process is suspended and/or resumed during conversation input. The _o_n___s_u_s_p_e_n_d and _o_n___r_e_s_u_m_e functions are called with the signal that caused ssuuddoo to be suspended and - the _c_l_o_s_u_r_e pointer from the struct sudo_conv_callback. The intended use - is to allow the plugin to release resources, such as locks, that should - not be held indefinitely while suspended and then reacquire them when the - process is resumed. Note that the functions are not actually invoked - from within a signal handler. + the _c_l_o_s_u_r_e pointer from the struct sudo_conv_callback. These functions + should return 0 on success and -1 on error. On error, the conversation + will end and the conversation function will return a value of -1. The + intended use is to allow the plugin to release resources, such as locks, + that should not be held indefinitely while suspended and then reacquire + them when the process is resumed. Note that the functions are not + actually invoked from within a signal handler. The plugin is responsible for freeing the reply buffer located in each struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents @@ -1532,4 +1534,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or http://www.sudo.ws/license.html for complete details. -Sudo 1.8.15 September 2, 2015 Sudo 1.8.15 +Sudo 1.8.15 September 9, 2015 Sudo 1.8.15 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index c5bc35e37..7591c430a 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -16,7 +16,7 @@ .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.TH "SUDO_PLUGIN" "5" "September 2, 2015" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.TH "SUDO_PLUGIN" "5" "September 9, 2015" "Sudo @PACKAGE_VERSION@" "File Formats Manual" .nh .if n .ad l .SH "NAME" @@ -2353,6 +2353,9 @@ to be suspended and the \fIclosure\fR pointer from the \fRstruct sudo_conv_callback\fR. +These functions should return 0 on success and \-1 on error. +On error, the conversation will end and the conversation function +will return a value of \-1. The intended use is to allow the plugin to release resources, such as locks, that should not be held indefinitely while suspended and then reacquire them when the process is resumed. diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in index d4a5f9ceb..981b6493a 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 September 2, 2015 +.Dd September 9, 2015 .Dt SUDO_PLUGIN @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -2055,6 +2055,9 @@ to be suspended and the .Fa closure pointer from the .Li struct sudo_conv_callback . +These functions should return 0 on success and \-1 on error. +On error, the conversation will end and the conversation function +will return a value of \-1. The intended use is to allow the plugin to release resources, such as locks, that should not be held indefinitely while suspended and then reacquire them when the process is resumed. -- 2.40.0