Document tracing

diff --git a/doc/sudo.conf.cat b/doc/sudo.conf.cat
index 553e08c3e1c1876eab6ed1f87284441c7920e232..f3ff74e562efd9448b1ab52a7ff99aec7459d66a 100644 (file)
--- a/doc/sudo.conf.cat
+++ b/doc/sudo.conf.cat
@@ -243,11 +243,25 @@ D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
      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 s\bsu\bud\bdo\bo front end, in order of decreasing
-     severity, are: _\bc_\br_\bi_\bt, _\be_\br_\br, _\bw_\ba_\br_\bn, _\bn_\bo_\bt_\bi_\bc_\be, _\bd_\bi_\ba_\bg, _\bi_\bn_\bf_\bo, _\bt_\br_\ba_\bc_\be and _\bd_\be_\bb_\bu_\bg.
-     Each priority, when specified, also includes all priorities higher than
-     it.  For example, a priority of _\bn_\bo_\bt_\bi_\bc_\be would include debug messages
-     logged at _\bn_\bo_\bt_\bi_\bc_\be and higher.
+     The following priorities are supported, in order of decreasing severity:
+     _\bc_\br_\bi_\bt, _\be_\br_\br, _\bw_\ba_\br_\bn, _\bn_\bo_\bt_\bi_\bc_\be, _\bd_\bi_\ba_\bg, _\bi_\bn_\bf_\bo, _\bt_\br_\ba_\bc_\be and _\bd_\be_\bb_\bu_\bg.  Each priority,
+     when specified, also includes all priorities higher than it.  For
+     example, a priority of _\bn_\bo_\bt_\bi_\bc_\be would include debug messages logged at
+     _\bn_\bo_\bt_\bi_\bc_\be and higher.
+
+     The priorities _\bt_\br_\ba_\bc_\be and _\bd_\be_\bb_\bu_\bg 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 s\bsu\bud\bdo\bo front-end:
 
@@ -391,4 +405,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/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 59bb5ddbab95d24d5b5982731e1979b337b028fd..c121d8d5c0859aba9d7deef180ad13aac32b8bb2 100644 (file)
--- 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 8615bf3a597f5a547df91b602994677cd1e49a53..c987f513b5f29acd64d1737d024e4af96621a7b7 100644 (file)
--- 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: