From 3f6ffead0bc91d344d98160658bce447a91fffe4 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Sun, 11 Sep 2022 19:06:23 -0600 Subject: [PATCH] Move the init_session() errstr description to where it belongs. --- docs/sudo_plugin.man.in | 96 ++++++++++++++++++++-------------------- docs/sudo_plugin.mdoc.in | 91 ++++++++++++++++++------------------- 2 files changed, 92 insertions(+), 95 deletions(-) diff --git a/docs/sudo_plugin.man.in b/docs/sudo_plugin.man.in index d37c6577e..450b315c1 100644 --- a/docs/sudo_plugin.man.in +++ b/docs/sudo_plugin.man.in @@ -1824,21 +1824,28 @@ function can be used to tear down the session that was opened by \fRinit_session\fR. .sp -The -\fIpwd\fR -argument points to a passwd struct for the user the -command will be run as if the user-ID the command will run as was found -in the password database, otherwise it will be -\fRNULL\fR. +Returns 1 on success, 0 on failure, and \-1 on error. +On error, the plugin may optionally call the +\fBconversation\fR() +or +\fBplugin_printf\fR() +function with +\fRSUDO_CONF_ERROR_MSG\fR +to present additional +error information to the user. .sp +The function arguments are as follows: +.TP 6n +pwd +If the user-ID the command will run as was found in the password database, +\fIpwd\fR +will describe that user, otherwise it will be +\fRNULL\fR. +.TP 6n +user_env_out The -\fIuser_env_out\fR -argument points to the environment the command will -run in, in the form of a \fRNULL\fR-terminated -vector of -\(lqname=value\(rq -strings. +environment vector to use when executing the command. This is the same string passed back to the front-end via the Policy Plugin's \fIuser_env_out\fR @@ -1863,17 +1870,37 @@ version specified by the front-end before using \fIuser_env_out\fR. Failure to do so may result in a crash. +.TP 6n +errstr +If the +\fBinit_session\fR() +function returns a value other than 1, the plugin may +store a message describing the failure or error in +\fIerrstr\fR. +The +\fBsudo\fR +front-end will then pass this value to any registered audit plugins. +The string stored in +\fIerrstr\fR +must remain valid until the plugin's +\fBclose\fR() +function is called. .sp -Returns 1 on success, 0 on failure, and \-1 on error. -On error, the plugin may optionally call the -\fBconversation\fR() -or -\fBplugin_printf\fR() -function with -\fRSUDO_CONF_ERROR_MSG\fR -to present additional -error information to the user. +The +\fIerrstr\fR +parameter is only available starting with +API version 1.15. +A plugin +\fBmust\fR +check the API version specified by the +\fBsudo\fR +front-end before using +\fIerrstr\fR. +Failure to do so may result in a crash. +.PD 0 +.PP .RE +.PD .TP 6n register_hooks .nf @@ -2017,33 +2044,6 @@ version 1.15 or higher, \fBevent_alloc\fR() will not be set. .RE -.TP 6n -errstr -If the -\fBinit_session\fR() -function returns a value other than 1, the plugin may -store a message describing the failure or error in -\fIerrstr\fR. -The -\fBsudo\fR -front-end will then pass this value to any registered audit plugins. -The string stored in -\fIerrstr\fR -must remain valid until the plugin's -\fBclose\fR() -function is called. -.sp -The -\fIerrstr\fR -parameter is only available starting with -API version 1.15. -A plugin -\fBmust\fR -check the API version specified by the -\fBsudo\fR -front-end before using -\fIerrstr\fR. -Failure to do so may result in a crash. .PP \fIPolicy Plugin Version Macros\fR .nf diff --git a/docs/sudo_plugin.mdoc.in b/docs/sudo_plugin.mdoc.in index 8724f64a9..eca7f9a33 100644 --- a/docs/sudo_plugin.mdoc.in +++ b/docs/sudo_plugin.mdoc.in @@ -1630,21 +1630,27 @@ function can be used to tear down the session that was opened by .Li init_session . .Pp -The -.Em pwd -argument points to a passwd struct for the user the -command will be run as if the user-ID the command will run as was found -in the password database, otherwise it will be -.Dv NULL . +Returns 1 on success, 0 on failure, and \-1 on error. +On error, the plugin may optionally call the +.Fn conversation +or +.Fn plugin_printf +function with +.Dv SUDO_CONF_ERROR_MSG +to present additional +error information to the user. .Pp +The function arguments are as follows: +.Bl -tag -width 4n +.It pwd +If the user-ID the command will run as was found in the password database, +.Fa pwd +will describe that user, otherwise it will be +.Dv NULL . +.It user_env_out The -.Em user_env_out -argument points to the environment the command will -run in, in the form of a .Dv NULL Ns -terminated -vector of -.Dq name=value -strings. +environment vector to use when executing the command. This is the same string passed back to the front-end via the Policy Plugin's .Em user_env_out @@ -1669,16 +1675,33 @@ version specified by the front-end before using .Em user_env_out . Failure to do so may result in a crash. +.It errstr +If the +.Fn init_session +function returns a value other than 1, the plugin may +store a message describing the failure or error in +.Fa errstr . +The +.Nm sudo +front-end will then pass this value to any registered audit plugins. +The string stored in +.Fa errstr +must remain valid until the plugin's +.Fn close +function is called. .Pp -Returns 1 on success, 0 on failure, and \-1 on error. -On error, the plugin may optionally call the -.Fn conversation -or -.Fn plugin_printf -function with -.Dv SUDO_CONF_ERROR_MSG -to present additional -error information to the user. +The +.Fa errstr +parameter is only available starting with +API version 1.15. +A plugin +.Sy must +check the API version specified by the +.Nm sudo +front-end before using +.Fa errstr . +Failure to do so may result in a crash. +.El .It register_hooks .Bd -literal -compact void (*register_hooks)(int version, @@ -1807,32 +1830,6 @@ front-end doesn't support API version 1.15 or higher, .Fn event_alloc will not be set. -.It errstr -If the -.Fn init_session -function returns a value other than 1, the plugin may -store a message describing the failure or error in -.Fa errstr . -The -.Nm sudo -front-end will then pass this value to any registered audit plugins. -The string stored in -.Fa errstr -must remain valid until the plugin's -.Fn close -function is called. -.Pp -The -.Fa errstr -parameter is only available starting with -API version 1.15. -A plugin -.Sy must -check the API version specified by the -.Nm sudo -front-end before using -.Fa errstr . -Failure to do so may result in a crash. .El .Pp .Em Policy Plugin Version Macros