mirror of
https://github.com/samba-team/samba.git
synced 2024-12-23 17:34:34 +03:00
8f8a9f0190
(This used to be commit 9f672c26d6
)
324 lines
8.8 KiB
XML
324 lines
8.8 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
|
|
<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>
|