diff options
Diffstat (limited to 'docs/docbook/devdoc/debug.xml')
| -rw-r--r-- | docs/docbook/devdoc/debug.xml | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/docs/docbook/devdoc/debug.xml b/docs/docbook/devdoc/debug.xml deleted file mode 100644 index 7e81cc825d..0000000000 --- a/docs/docbook/devdoc/debug.xml +++ /dev/null @@ -1,321 +0,0 @@ -<chapter id="debug"> -<chapterinfo> - <author> - <firstname>Chris</firstname><surname>Hertel</surname> - </author> - <pubdate>July 1998</pubdate> -</chapterinfo> - -<title>The samba DEBUG system</title> - -<sect1> -<title>New Output Syntax</title> - -<para> - The syntax of a debugging log file is represented as: -</para> - -<para><programlisting> - >debugfile< :== { >debugmsg< } - - >debugmsg< :== >debughdr< '\n' >debugtext< - - >debughdr< :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')' - - >debugtext< :== { >debugline< } - - >debugline< :== TEXT '\n' -</programlisting></para> - -<para> -TEXT is a string of characters excluding the newline character. -</para> - -<para> -LEVEL is the DEBUG level of the message (an integer in the range - 0..10). -</para> - -<para> -TIME is a timestamp. -</para> - -<para> -FILE is the name of the file from which the debug message was -generated. -</para> - -<para> -FUNCTION is the function from which the debug message was generated. -</para> - -<para> -LINE is the line number of the debug statement that generated the -message. -</para> - -<para>Basically, what that all means is:</para> -<orderedlist> -<listitem><para> -A debugging log file is made up of debug messages. -</para></listitem> -<listitem><para> -Each debug message is made up of a header and text. The header is -separated from the text by a newline. -</para></listitem> -<listitem><para> -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). -</para></listitem> -<listitem><para> -The message text is made up of zero or more lines, each terminated -by a newline. -</para></listitem> -</orderedlist> - -<para>Here's some example output:</para> - -<para><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 -</programlisting></para> - -<para> -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. -</para> - -</sect1> - -<sect1> -<title>The DEBUG() Macro</title> - -<para> -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. -</para> - -<para>That's confusing.</para> - -<para>Here's an example which may help a bit. If you would write</para> - -<para><programlisting> -printf( "This is a %s message.\n", "debug" ); -</programlisting></para> - -<para> -to send the output to stdout, then you would write -</para> - -<para><programlisting> -DEBUG( 0, ( "This is a %s message.\n", "debug" ) ); -</programlisting></para> - -<para> -to send the output to the debug file. All of the normal printf() -formatting escapes work. -</para> - -<para> -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. -</para> - -<para> -The output of the above example would be something like: -</para> - -<para><programlisting> - [1998/07/30 16:00:51, 0] file.c:function(128) - This is a debug message. -</programlisting></para> - -<para> -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. -</para> - -<para> -...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: -</para> - -<para><programlisting> - DEBUG( 0, ("The test returned " ) ); - if( test() ) - DEBUG(0, ("True") ); - else - DEBUG(0, ("False") ); - DEBUG(0, (".\n") ); -</programlisting></para> - -<para> -Without the format buffer, the output (assuming test() returned true) -would look like this: -</para> - -<para><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) - . -</programlisting></para> - -<para>Which isn't much use. The format buffer kludge fixes this problem. -</para> - -</sect1> - -<sect1> -<title>The DEBUGADD() Macro</title> - -<para> -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. -</para> - -<para><programlisting> - DEBUG( 0, ("This is the first line.\n" ) ); - DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) ); -</programlisting></para> - -<para>Produces</para> - -<para><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. -</programlisting></para> - -</sect1> - -<sect1> -<title>The DEBUGLVL() Macro</title> - -<para> -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: -</para> - -<para><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)); -</programlisting></para> - -<para> -One solution to this is to break it down using DEBUG() and DEBUGADD(), -as follows: -</para> - -<para><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 ) ); -</programlisting></para> - -<para> -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: -</para> - -<para><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 ); - } -</programlisting></para> - -<para>(The dbgtext() function is explained below.)</para> - -<para>There are a few advantages to this scheme:</para> -<orderedlist> -<listitem><para> -The test is performed only once. -</para></listitem> -<listitem><para> -You can allocate variables off of the stack that will only be used -within the DEBUGLVL() block. -</para></listitem> -<listitem><para> -Processing that is only relevant to debug output can be contained -within the DEBUGLVL() block. -</para></listitem> -</orderedlist> - -</sect1> - -<sect1> -<title>New Functions</title> - -<sect2> -<title>dbgtext()</title> -<para> -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(). -</para> -</sect2> - -<sect2> -<title>dbghdr()</title> -<para> -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. -</para> - -<para> -It is not likely that this function will be called directly. It -is used by DEBUG() and DEBUGADD(). -</para> -</sect2> - -<sect2> -<title>format_debug_text()</title> -<para> -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). -</para> -</sect2> -</sect1> -</chapter> |