diff options
| author | vorlon <vorlon@alioth.debian.org> | 2008-03-24 08:23:36 +0000 |
|---|---|---|
| committer | vorlon <vorlon@alioth.debian.org> | 2008-03-24 08:23:36 +0000 |
| commit | bba625b04e0d12c2c03a345554d98b8575f4f380 (patch) | |
| tree | 1333f979a7278d10b7c56c4f0b34fa6d3e75b2e1 /docs/htmldocs/Samba3-Developers-Guide/debug.html | |
| parent | 74a2535fdc9252584a2ca4256431b28b20ed4f58 (diff) | |
| download | samba-bba625b04e0d12c2c03a345554d98b8575f4f380.tar.gz | |
Load samba-3.2.0pre2 into branches/samba/upstream-3.2.upstream/3.2.0_pre2
git-svn-id: svn://svn.debian.org/svn/pkg-samba/branches/samba/upstream-3.2@1780 fc4039ab-9d04-0410-8cac-899223bdd6b0
Diffstat (limited to 'docs/htmldocs/Samba3-Developers-Guide/debug.html')
| -rw-r--r-- | docs/htmldocs/Samba3-Developers-Guide/debug.html | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/docs/htmldocs/Samba3-Developers-Guide/debug.html b/docs/htmldocs/Samba3-Developers-Guide/debug.html new file mode 100644 index 0000000000..f56fe13b6c --- /dev/null +++ b/docs/htmldocs/Samba3-Developers-Guide/debug.html @@ -0,0 +1,180 @@ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 4. The samba DEBUG system</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt02.html" title="Part II. Samba Basics"><link rel="prev" href="architecture.html" title="Chapter 3. Samba Architecture"><link rel="next" href="internals.html" title="Chapter 5. Samba Internals"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. The samba DEBUG system</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="architecture.html">Prev</a> </td><th width="60%" align="center">Part II. Samba Basics</th><td width="20%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="debug"></a>Chapter 4. The samba DEBUG system</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Chris</span> <span class="surname">Hertel</span></h3></div></div><div><p class="pubdate">July 1998</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="debug.html#id330279">New Output Syntax</a></span></dt><dt><span class="sect1"><a href="debug.html#id330374">The DEBUG() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id330466">The DEBUGADD() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id330498">The DEBUGLVL() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id330576">New Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="debug.html#id330582">dbgtext()</a></span></dt><dt><span class="sect2"><a href="debug.html#id330595">dbghdr()</a></span></dt><dt><span class="sect2"><a href="debug.html#id330612">format_debug_text()</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330279"></a>New Output Syntax</h2></div></div></div><p> + The syntax of a debugging log file is represented as: +</p><pre class="programlisting"> + >debugfile< :== { >debugmsg< } + + >debugmsg< :== >debughdr< '\n' >debugtext< + + >debughdr< :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')' + + >debugtext< :== { >debugline< } + + >debugline< :== TEXT '\n' +</pre><p> +TEXT is a string of characters excluding the newline character. +</p><p> +LEVEL is the DEBUG level of the message (an integer in the range + 0..10). +</p><p> +TIME is a timestamp. +</p><p> +FILE is the name of the file from which the debug message was +generated. +</p><p> +FUNCTION is the function from which the debug message was generated. +</p><p> +LINE is the line number of the debug statement that generated the +message. +</p><p>Basically, what that all means is:</p><div class="orderedlist"><ol type="1"><li><p> +A debugging log file is made up of debug messages. +</p></li><li><p> +Each debug message is made up of a header and text. The header is +separated from the text by a newline. +</p></li><li><p> +The header begins with the timestamp and debug level of the +message enclosed in brackets. The filename, function, and line +number at which the message was generated follow. The filename is +terminated by a colon, and the function name is terminated by the +parenthesis which contain the line number. Depending upon the +compiler, the function name may be missing (it is generated by the +__FUNCTION__ macro, which is not universally implemented, dangit). +</p></li><li><p> +The message text is made up of zero or more lines, each terminated +by a newline. +</p></li></ol></div><p>Here's some example output:</p><pre class="programlisting"> + [1998/08/03 12:55:25, 1] nmbd.c:(659) + Netbios nameserver version 1.9.19-prealpha started. + Copyright Andrew Tridgell 1994-1997 + [1998/08/03 12:55:25, 3] loadparm.c:(763) + Initializing global parameters +</pre><p> +Note that in the above example the function names are not listed on +the header line. That's because the example above was generated on an +SGI Indy, and the SGI compiler doesn't support the __FUNCTION__ macro. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330374"></a>The DEBUG() Macro</h2></div></div></div><p> +Use of the DEBUG() macro is unchanged. DEBUG() takes two parameters. +The first is the message level, the second is the body of a function +call to the Debug1() function. +</p><p>That's confusing.</p><p>Here's an example which may help a bit. If you would write</p><pre class="programlisting"> +printf( "This is a %s message.\n", "debug" ); +</pre><p> +to send the output to stdout, then you would write +</p><pre class="programlisting"> +DEBUG( 0, ( "This is a %s message.\n", "debug" ) ); +</pre><p> +to send the output to the debug file. All of the normal printf() +formatting escapes work. +</p><p> +Note that in the above example the DEBUG message level is set to 0. +Messages at level 0 always print. Basically, if the message level is +less than or equal to the global value DEBUGLEVEL, then the DEBUG +statement is processed. +</p><p> +The output of the above example would be something like: +</p><pre class="programlisting"> + [1998/07/30 16:00:51, 0] file.c:function(128) + This is a debug message. +</pre><p> +Each call to DEBUG() creates a new header *unless* the output produced +by the previous call to DEBUG() did not end with a '\n'. Output to the +debug file is passed through a formatting buffer which is flushed +every time a newline is encountered. If the buffer is not empty when +DEBUG() is called, the new input is simply appended. +</p><p> +...but that's really just a Kludge. It was put in place because +DEBUG() has been used to write partial lines. Here's a simple (dumb) +example of the kind of thing I'm talking about: +</p><pre class="programlisting"> + DEBUG( 0, ("The test returned " ) ); + if( test() ) + DEBUG(0, ("True") ); + else + DEBUG(0, ("False") ); + DEBUG(0, (".\n") ); +</pre><p> +Without the format buffer, the output (assuming test() returned true) +would look like this: +</p><pre class="programlisting"> + [1998/07/30 16:00:51, 0] file.c:function(256) + The test returned + [1998/07/30 16:00:51, 0] file.c:function(258) + True + [1998/07/30 16:00:51, 0] file.c:function(261) + . +</pre><p>Which isn't much use. The format buffer kludge fixes this problem. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330466"></a>The DEBUGADD() Macro</h2></div></div></div><p> +In addition to the kludgey solution to the broken line problem +described above, there is a clean solution. The DEBUGADD() macro never +generates a header. It will append new text to the current debug +message even if the format buffer is empty. The syntax of the +DEBUGADD() macro is the same as that of the DEBUG() macro. +</p><pre class="programlisting"> + DEBUG( 0, ("This is the first line.\n" ) ); + DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) ); +</pre><p>Produces</p><pre class="programlisting"> + [1998/07/30 16:00:51, 0] file.c:function(512) + This is the first line. + This is the second line. + This is the third line. +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330498"></a>The DEBUGLVL() Macro</h2></div></div></div><p> +One of the problems with the DEBUG() macro was that DEBUG() lines +tended to get a bit long. Consider this example from +nmbd_sendannounce.c: +</p><pre class="programlisting"> + DEBUG(3,("send_local_master_announcement: type %x for name %s on subnet %s for workgroup %s\n", + type, global_myname, subrec->subnet_name, work->work_group)); +</pre><p> +One solution to this is to break it down using DEBUG() and DEBUGADD(), +as follows: +</p><pre class="programlisting"> + DEBUG( 3, ( "send_local_master_announcement: " ) ); + DEBUGADD( 3, ( "type %x for name %s ", type, global_myname ) ); + DEBUGADD( 3, ( "on subnet %s ", subrec->subnet_name ) ); + DEBUGADD( 3, ( "for workgroup %s\n", work->work_group ) ); +</pre><p> +A similar, but arguably nicer approach is to use the DEBUGLVL() macro. +This macro returns True if the message level is less than or equal to +the global DEBUGLEVEL value, so: +</p><pre class="programlisting"> + if( DEBUGLVL( 3 ) ) + { + dbgtext( "send_local_master_announcement: " ); + dbgtext( "type %x for name %s ", type, global_myname ); + dbgtext( "on subnet %s ", subrec->subnet_name ); + dbgtext( "for workgroup %s\n", work->work_group ); + } +</pre><p>(The dbgtext() function is explained below.)</p><p>There are a few advantages to this scheme:</p><div class="orderedlist"><ol type="1"><li><p> +The test is performed only once. +</p></li><li><p> +You can allocate variables off of the stack that will only be used +within the DEBUGLVL() block. +</p></li><li><p> +Processing that is only relevant to debug output can be contained +within the DEBUGLVL() block. +</p></li></ol></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330576"></a>New Functions</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id330582"></a>dbgtext()</h3></div></div></div><p> +This function prints debug message text to the debug file (and +possibly to syslog) via the format buffer. The function uses a +variable argument list just like printf() or Debug1(). The +input is printed into a buffer using the vslprintf() function, +and then passed to format_debug_text(). + +If you use DEBUGLVL() you will probably print the body of the +message using dbgtext(). +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id330595"></a>dbghdr()</h3></div></div></div><p> +This is the function that writes a debug message header. +Headers are not processed via the format buffer. Also note that +if the format buffer is not empty, a call to dbghdr() will not +produce any output. See the comments in dbghdr() for more info. +</p><p> +It is not likely that this function will be called directly. It +is used by DEBUG() and DEBUGADD(). +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id330612"></a>format_debug_text()</h3></div></div></div><p> +This is a static function in debug.c. It stores the output text +for the body of the message in a buffer until it encounters a +newline. When the newline character is found, the buffer is +written to the debug file via the Debug1() function, and the +buffer is reset. This allows us to add the indentation at the +beginning of each line of the message body, and also ensures +that the output is written a line at a time (which cleans up +syslog output). +</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="architecture.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="internals.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Samba Architecture </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Samba Internals</td></tr></table></div></body></html> |