Document what happens when the on_suspend/on_resume callbacks

return an error.

diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat
index 164271a3c7db1a66f3465121b3e5f064eaa7b347..720f60f5dcfdb01b88d1593bc5c1a31260e59509 100644 (file)
--- a/doc/sudo_plugin.cat
+++ b/doc/sudo_plugin.cat
@@ -1320,11 +1320,13 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
      contain function pointers to be called when the s\bsu\bud\bdo\bo process is suspended
      and/or resumed during conversation input.  The _\bo_\bn_\b__\bs_\bu_\bs_\bp_\be_\bn_\bd and _\bo_\bn_\b__\br_\be_\bs_\bu_\bm_\be
      functions are called with the signal that caused s\bsu\bud\bdo\bo to be suspended and
-     the _\bc_\bl_\bo_\bs_\bu_\br_\be 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 _\bc_\bl_\bo_\bs_\bu_\br_\be 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 @@ D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
      file distributed with s\bsu\bud\bdo\bo 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 c5bc35e3751bd39bbf930f201cd97e211ad523fa..7591c430a144b0eea7cf189ee7e46347456d3a2a 100644 (file)
--- 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 d4a5f9ceb78d8a06d18c74976d6d50e805dfdc28..981b6493a6730e186bc4de88d990df2bc7c3b11c 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 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.