From 8f79d5c1c7f94da471d719dc2c59e45d70b58cb8 Mon Sep 17 00:00:00 2001
From: Robert Manner <robert.manner@balabit.com>
Date: Mon, 10 Feb 2020 10:22:56 +0100
Subject: [PATCH] doc/sudo_plugin_python: update python manual for constant ->
 enum changes

---
 doc/sudo_plugin_python.man.in  | 76 ++++++++++++++++-----------------
 doc/sudo_plugin_python.mdoc.in | 78 +++++++++++++++++-----------------
 2 files changed, 77 insertions(+), 77 deletions(-)

diff --git a/doc/sudo_plugin_python.man.in b/doc/sudo_plugin_python.man.in
index 84b686f1a..6a1a00b40 100644
--- a/doc/sudo_plugin_python.man.in
+++ b/doc/sudo_plugin_python.man.in
@@ -100,15 +100,15 @@ l l.
 .PP
 \fBDefine\fR	\fBValue\fR
 .PP
-\fRsudo.RC_OK\fR	1
+\fRsudo.RC.OK\fR	1
 .PP
-\fRsudo.RC_ACCEPT\fR	1
+\fRsudo.RC.ACCEPT\fR	1
 .PP
-\fRsudo.RC_REJECT\fR	0
+\fRsudo.RC.REJECT\fR	0
 .PP
-\fRsudo.RC_ERROR\fR	-1
+\fRsudo.RC.ERROR\fR	-1
 .PP
-\fRsudo.RC_USAGE_ERROR\fR	-2
+\fRsudo.RC.USAGE_ERROR\fR	-2
 .TE
 .RE
 .PP
@@ -116,10 +116,10 @@ If a function returns
 \fINone\fR
 (for example, if it does not call return),
 it will be considered to have returned
-\fRsudo.RC_OK\fR.
+\fRsudo.RC.OK\fR.
 If an exception is raised, the backtrace will be shown to the user and
 the plugin function will return
-\fRsudo.RC_ERROR\fR.
+\fRsudo.RC.ERROR\fR.
 If that is not acceptable, you must catch the exception and handle it yourself.
 .SS "Python Plugin Loader"
 Running the Python interpreter and bridging between C and Python is
@@ -276,15 +276,15 @@ The tuple values are as follows:
 .TP 6n
 \fIrc\fR
 The result of the policy check, one of the
-\fRsudo.RC_*\fR
+\fRsudo.RC.*\fR
 constants.
-\fRsudo.RC_ACCEPT\fR
+\fRsudo.RC.ACCEPT\fR
 if the command is allowed,
-\fRsudo.RC_REJECT\fR
+\fRsudo.RC.REJECT\fR
 if not allowed,
-\fRsudo.RC_ERROR\fR
+\fRsudo.RC.ERROR\fR
 for a general error, or
-\fRsudo.RC_USAGE_ERROR\fR
+\fRsudo.RC.USAGE_ERROR\fR
 for a usage error.
 .TP 6n
 \fIcommand_info_out\fR
@@ -372,11 +372,11 @@ The tuple values are as follows:
 .TP 6n
 \fIrc\fR
 The result of the session init, one of the
-\fRsudo.RC_*\fR
+\fRsudo.RC.*\fR
 constants.
-\fRsudo.RC_OK\fR
+\fRsudo.RC.OK\fR
 on success, 0 on failure, or
-\fRsudo.RC_ERROR\fR
+\fRsudo.RC.ERROR\fR
 if an error occurred.
 .TP 6n
 \fIuser_env_out\fR
@@ -577,7 +577,7 @@ settings in the form of
 strings.
 .TP 6n
 \fIversion\fR
-The version of the Python Policy Plugin API.
+The version of the Python I/O Plugin API.
 .TP 6n
 \fIuser_info\fR
 A tuple of information about the user running the command in the form of
@@ -657,10 +657,10 @@ sudo_plugin(@mansectform@).
 The
 \fBopen\fR()
 function should return a result code, one of the
-\fRsudo.RC_*\fR
+\fRsudo.RC.*\fR
 constants.
 If the function returns
-\fRsudo.REJECT\fR,
+\fRsudo.RC.REJECT\fR,
 no I/O will be sent to the plugin.
 .RE
 .TP 6n
@@ -687,22 +687,22 @@ The function arguments are as follows:
 The input (or output) buffer in the form of a string.
 .PP
 The function should return a result code, one of the
-\fRsudo.RC_*\fR
+\fRsudo.RC.*\fR
 constants.
 .sp
 If
-\fRsudo.RC_ERROR\fR
+\fRsudo.RC.ERROR\fR
 is returned, the running command will be terminated and all of the plugin's logging
 functions will be disabled.
 Other I/O logging plugins will still receive any remaining
 input or output that has not yet been processed.
 .sp
 If an input logging function rejects the data by returning
-\fRsudo.RC_REJECT\fR,
+\fRsudo.RC.REJECT\fR,
 the command will be terminated and the data will not be passed to the
 command, though it will still be sent to any other I/O logging plugins.
 If an output logging function rejects the data by returning
-\fRsudo.RC_REJECT\fR,
+\fRsudo.RC.REJECT\fR,
 the command will be terminated and the data will not be written to the
 terminal, though it will still be sent to any other I/O logging plugins.
 .RE
@@ -964,7 +964,7 @@ member variables:
 \fImsg_type\fR
 Specifies the type of the conversation.
 See the
-\fRsudo.CONV_*\fR
+\fRsudo.CONV.*\fR
 constants below.
 .TP 6n
 \fImsg\fR
@@ -989,25 +989,25 @@ To specify the message type, the following constants are available:
 .PD 0
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_PROMPT_ECHO_OFF
+sudo.CONV.PROMPT_ECHO_OFF
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_PROMPT_ECHO_ON
+sudo.CONV.PROMPT_ECHO_ON
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_ERROR_MSG
+sudo.CONV.ERROR_MSG
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_INFO_MSG
+sudo.CONV.INFO_MSG
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_PROMPT_MASK
+sudo.CONV.PROMPT_MASK
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_PROMPT_ECHO_OK
+sudo.CONV.PROMPT_ECHO_OK
 .TP 3n
 \fB\(bu\fR
-sudo.CONV_PREFER_TTY
+sudo.CONV.PREFER_TTY
 .RE
 .PD
 .PP
@@ -1206,21 +1206,21 @@ l l l.
 .PP
 \fBsudo.conf name\fR	\fBPython constant\fR	\fBdescription\fR
 .PP
-crit	sudo.DEBUG_CRIT	only cricital messages
+crit	sudo.DEBUG.CRIT	only cricital messages
 .PP
-err	sudo.DEBUG_ERROR	
+err	sudo.DEBUG.ERROR	
 .PP
-warn	sudo.DEBUG_WARN	
+warn	sudo.DEBUG.WARN	
 .PP
-notice	sudo.DEBUG_NOTICE	
+notice	sudo.DEBUG.NOTICE	
 .PP
-diag	sudo.DEBUG_DIAG	
+diag	sudo.DEBUG.DIAG	
 .PP
-info	sudo.DEBUG_INFO	
+info	sudo.DEBUG.INFO	
 .PP
-trace	sudo.DEBUG_TRACE	
+trace	sudo.DEBUG.TRACE	
 .PP
-debug	sudo.DEBUG_DEBUG	very extreme verbose debugging
+debug	sudo.DEBUG.DEBUG	very extreme verbose debugging
 .TE
 .SS "Debug example"
 Sudo ships an example debug plugin by default.
diff --git a/doc/sudo_plugin_python.mdoc.in b/doc/sudo_plugin_python.mdoc.in
index ea9e5aa31..5c2bf60d8 100644
--- a/doc/sudo_plugin_python.mdoc.in
+++ b/doc/sudo_plugin_python.mdoc.in
@@ -85,23 +85,23 @@ result code, as documented in
 .Xr sudo_plugin @mansctsu@ ,
 that indicates whether or not the method was successful.
 The Python sudo module defines the following constants to improve readability:
-.Bl -column "sudo.RC_USAGE_ERROR" "XXX" -offset 4n
+.Bl -column "sudo.RC.USAGE_ERROR" "XXX" -offset 4n
 .It Sy Define Ta Sy Value
-.It Dv sudo.RC_OK Ta 1
-.It Dv sudo.RC_ACCEPT Ta 1
-.It Dv sudo.RC_REJECT Ta 0
-.It Dv sudo.RC_ERROR Ta -1
-.It Dv sudo.RC_USAGE_ERROR Ta -2
+.It Dv sudo.RC.OK Ta 1
+.It Dv sudo.RC.ACCEPT Ta 1
+.It Dv sudo.RC.REJECT Ta 0
+.It Dv sudo.RC.ERROR Ta -1
+.It Dv sudo.RC.USAGE_ERROR Ta -2
 .El
 .Pp
 If a function returns
 .Em None
 (for example, if it does not call return),
 it will be considered to have returned
-.Dv sudo.RC_OK .
+.Dv sudo.RC.OK .
 If an exception is raised, the backtrace will be shown to the user and
 the plugin function will return
-.Dv sudo.RC_ERROR .
+.Dv sudo.RC.ERROR .
 If that is not acceptable, you must catch the exception and handle it yourself.
 .Ss Python Plugin Loader
 Running the Python interpreter and bridging between C and Python is
@@ -235,15 +235,15 @@ The tuple values are as follows:
 .Bl -tag -width 4n
 .It Fa rc
 The result of the policy check, one of the
-.Dv sudo.RC_*
+.Dv sudo.RC.*
 constants.
-.Dv sudo.RC_ACCEPT
+.Dv sudo.RC.ACCEPT
 if the command is allowed,
-.Dv sudo.RC_REJECT
+.Dv sudo.RC.REJECT
 if not allowed,
-.Dv sudo.RC_ERROR
+.Dv sudo.RC.ERROR
 for a general error, or
-.Dv sudo.RC_USAGE_ERROR
+.Dv sudo.RC.USAGE_ERROR
 for a usage error.
 .It Fa command_info_out
 Optional (only required when the command is accepted).
@@ -316,11 +316,11 @@ The tuple values are as follows:
 .Bl -tag -width 4n
 .It Fa rc
 The result of the session init, one of the
-.Dv sudo.RC_*
+.Dv sudo.RC.*
 constants.
-.Dv sudo.RC_OK
+.Dv sudo.RC.OK
 on success, 0 on failure, or
-.Dv sudo.RC_ERROR
+.Dv sudo.RC.ERROR
 if an error occurred.
 .It Fa user_env_out
 Optional.
@@ -469,7 +469,7 @@ settings in the form of
 .Dq key=value
 strings.
 .It Fa version
-The version of the Python Policy Plugin API.
+The version of the Python I/O Plugin API.
 .It Fa user_info
 A tuple of information about the user running the command in the form of
 .Dq key=value
@@ -539,10 +539,10 @@ documentation in
 The
 .Fn open
 function should return a result code, one of the
-.Dv sudo.RC_*
+.Dv sudo.RC.*
 constants.
 If the function returns
-.Dv sudo.REJECT ,
+.Dv sudo.RC.REJECT ,
 no I/O will be sent to the plugin.
 .It Sy log_ttyin , log_ttyout , log_stdin , log_stdout , log_stderr
 .Bd -literal -compact
@@ -565,22 +565,22 @@ The input (or output) buffer in the form of a string.
 .El
 .Pp
 The function should return a result code, one of the
-.Dv sudo.RC_*
+.Dv sudo.RC.*
 constants.
 .Pp
 If
-.Dv sudo.RC_ERROR
+.Dv sudo.RC.ERROR
 is returned, the running command will be terminated and all of the plugin's logging
 functions will be disabled.
 Other I/O logging plugins will still receive any remaining
 input or output that has not yet been processed.
 .Pp
 If an input logging function rejects the data by returning
-.Dv sudo.RC_REJECT ,
+.Dv sudo.RC.REJECT ,
 the command will be terminated and the data will not be passed to the
 command, though it will still be sent to any other I/O logging plugins.
 If an output logging function rejects the data by returning
-.Dv sudo.RC_REJECT ,
+.Dv sudo.RC.REJECT ,
 the command will be terminated and the data will not be written to the
 terminal, though it will still be sent to any other I/O logging plugins.
 .It Sy change_winsize
@@ -780,7 +780,7 @@ member variables:
 .It Fa msg_type
 Specifies the type of the conversation.
 See the
-.Dv sudo.CONV_*
+.Dv sudo.CONV.*
 constants below.
 .It Fa msg
 The message to display to the user.
@@ -802,19 +802,19 @@ To specify the message type, the following constants are available:
 .Pp
 .Bl -bullet -compact -offset 4n -width 1n
 .It
-sudo.CONV_PROMPT_ECHO_OFF
+sudo.CONV.PROMPT_ECHO_OFF
 .It
-sudo.CONV_PROMPT_ECHO_ON
+sudo.CONV.PROMPT_ECHO_ON
 .It
-sudo.CONV_ERROR_MSG
+sudo.CONV.ERROR_MSG
 .It
-sudo.CONV_INFO_MSG
+sudo.CONV.INFO_MSG
 .It
-sudo.CONV_PROMPT_MASK
+sudo.CONV.PROMPT_MASK
 .It
-sudo.CONV_PROMPT_ECHO_OK
+sudo.CONV.PROMPT_ECHO_OK
 .It
-sudo.CONV_PREFER_TTY
+sudo.CONV.PREFER_TTY
 .El
 .Pp
 See the
@@ -985,14 +985,14 @@ one or more messages to log
 .Em Available log levels:
 .Bl -column "name in sudo.conf" "Python constant" "only cricital messages"
 .It Sy sudo.conf name Ta Sy Python constant Ta Sy description
-.It crit Ta sudo.DEBUG_CRIT Ta only cricital messages
-.It err Ta sudo.DEBUG_ERROR Ta
-.It warn Ta sudo.DEBUG_WARN Ta
-.It notice Ta sudo.DEBUG_NOTICE Ta
-.It diag Ta sudo.DEBUG_DIAG Ta
-.It info Ta sudo.DEBUG_INFO Ta
-.It trace Ta sudo.DEBUG_TRACE Ta
-.It debug Ta sudo.DEBUG_DEBUG Ta very extreme verbose debugging
+.It crit Ta sudo.DEBUG.CRIT Ta only cricital messages
+.It err Ta sudo.DEBUG.ERROR Ta
+.It warn Ta sudo.DEBUG.WARN Ta
+.It notice Ta sudo.DEBUG.NOTICE Ta
+.It diag Ta sudo.DEBUG.DIAG Ta
+.It info Ta sudo.DEBUG.INFO Ta
+.It trace Ta sudo.DEBUG.TRACE Ta
+.It debug Ta sudo.DEBUG.DEBUG Ta very extreme verbose debugging
 .El
 .Ss Debug example
 Sudo ships an example debug plugin by default.