From 5ff2c80250495005646ad9cc9fb46dc6281efa8b Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Thu, 24 Jul 2014 14:39:50 -0600 Subject: [PATCH] Document tracing --- doc/sudo.conf.cat | 26 ++++++++++++++++++++------ doc/sudo.conf.man.in | 31 +++++++++++++++++++++++++++---- doc/sudo.conf.mdoc.in | 28 ++++++++++++++++++++++++---- 3 files changed, 71 insertions(+), 14 deletions(-) diff --git a/doc/sudo.conf.cat b/doc/sudo.conf.cat index 553e08c3e..f3ff74e56 100644 --- a/doc/sudo.conf.cat +++ b/doc/sudo.conf.cat @@ -243,11 +243,25 @@ DDEESSCCRRIIPPTTIIOONN future release may add support for per-plugin Debug lines and/or support for multiple debugging files for a single program. - The priorities used by the ssuuddoo front end, in order of decreasing - severity, are: _c_r_i_t, _e_r_r, _w_a_r_n, _n_o_t_i_c_e, _d_i_a_g, _i_n_f_o, _t_r_a_c_e and _d_e_b_u_g. - Each priority, when specified, also includes all priorities higher than - it. For example, a priority of _n_o_t_i_c_e would include debug messages - logged at _n_o_t_i_c_e and higher. + The following priorities are supported, in order of decreasing severity: + _c_r_i_t, _e_r_r, _w_a_r_n, _n_o_t_i_c_e, _d_i_a_g, _i_n_f_o, _t_r_a_c_e and _d_e_b_u_g. Each priority, + when specified, also includes all priorities higher than it. For + example, a priority of _n_o_t_i_c_e would include debug messages logged at + _n_o_t_i_c_e and higher. + + The priorities _t_r_a_c_e and _d_e_b_u_g also include function call tracing which + logs when a function is entered and when it returns. For example, the + following trace is for the get_user_groups() function located in + src/sudo.c: + + sudo[123] -> get_user_groups @ src/sudo.c:385 + sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 + + When the function is entered, indicated by a right arrow `->', the + program, process ID, function, source file and line number are logged. + When the function returns, indicated by a left arrow `<-', the same + information is logged along with the return value. In this case, the + return value is a string. The following subsystems are used by the ssuuddoo front-end: @@ -391,4 +405,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for complete details. -Sudo 1.8.11 January 22, 2014 Sudo 1.8.11 +Sudo 1.8.11 July 24, 2014 Sudo 1.8.11 diff --git a/doc/sudo.conf.man.in b/doc/sudo.conf.man.in index 59bb5ddba..c121d8d5c 100644 --- a/doc/sudo.conf.man.in +++ b/doc/sudo.conf.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" "5" "January 22, 2014" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual" +.TH "SUDO" "5" "July 24, 2014" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual" .nh .if n .ad l .SH "NAME" @@ -474,9 +474,7 @@ and the plugins. A future release may add support for per-plugin lines and/or support for multiple debugging files for a single program. .PP -The priorities used by the -\fBsudo\fR -front end, in order of decreasing severity, are: +The following priorities are supported, in order of decreasing severity: \fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR and \fIdebug\fR. @@ -487,6 +485,31 @@ would include debug messages logged at \fInotice\fR and higher. .PP +The priorities +\fItrace\fR +and +\fIdebug\fR +also include function call tracing which logs when a function is +entered and when it returns. +For example, the following trace is for the get_user_groups() +function located in src/sudo.c: +.nf +.sp +.RS 6n +sudo[123] -> get_user_groups @ src/sudo.c:385 +sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 +.RE +.fi +.PP +When the function is entered, indicated by a right arrow +\(oq->\(cq, +the program, process ID, function, source file and line number +are logged. +When the function returns, indicated by a left arrow +\(oq<-\(cq, +the same information is logged along with the return value. +In this case, the return value is a string. +.PP The following subsystems are used by the \fBsudo\fR front-end: diff --git a/doc/sudo.conf.mdoc.in b/doc/sudo.conf.mdoc.in index 8615bf3a5..c987f513b 100644 --- a/doc/sudo.conf.mdoc.in +++ b/doc/sudo.conf.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 January 22, 2014 +.Dd July 24, 2014 .Dt SUDO @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -427,9 +427,7 @@ and the plugins. A future release may add support for per-plugin lines and/or support for multiple debugging files for a single program. .Pp -The priorities used by the -.Nm sudo -front end, in order of decreasing severity, are: +The following priorities are supported, in order of decreasing severity: .Em crit , err , warn , notice , diag , info , trace and .Em debug . @@ -440,6 +438,28 @@ would include debug messages logged at .Em notice and higher. .Pp +The priorities +.Em trace +and +.Em debug +also include function call tracing which logs when a function is +entered and when it returns. +For example, the following trace is for the get_user_groups() +function located in src/sudo.c: +.Bd -literal -offset indent +sudo[123] -> get_user_groups @ src/sudo.c:385 +sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 +.Ed +.Pp +When the function is entered, indicated by a right arrow +.Ql -> , +the program, process ID, function, source file and line number +are logged. +When the function returns, indicated by a left arrow +.Ql <- , +the same information is logged along with the return value. +In this case, the return value is a string. +.Pp The following subsystems are used by the .Nm sudo front-end: -- 2.40.0