~zulcss/samba/server-dailies-3.4

<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.74.0"><link rel="home" 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#id2556929">New Output Syntax</a></span></dt><dt><span class="sect1"><a href="debug.html#id2557038">The DEBUG() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id2557144">The DEBUGADD() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id2557180">The DEBUGLVL() Macro</a></span></dt><dt><span class="sect1"><a href="debug.html#id2557271">New Functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="debug.html#id2557276">dbgtext()</a></span></dt><dt><span class="sect2"><a href="debug.html#id2557292">dbghdr()</a></span></dt><dt><span class="sect2"><a href="debug.html#id2557311">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="id2556929"></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.

[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="id2557038"></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

100

[1998/07/30 16:00:51, 0] file.c:function(258)

101

True

102

[1998/07/30 16:00:51, 0] file.c:function(261)

103

104

</pre><p>Which isn't much use. The format buffer kludge fixes this problem.

105

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2557144"></a>The DEBUGADD() Macro</h2></div></div></div><p>

106

In addition to the kludgey solution to the broken line problem

107

described above, there is a clean solution. The DEBUGADD() macro never

108

generates a header. It will append new text to the current debug

109

message even if the format buffer is empty. The syntax of the

110

DEBUGADD() macro is the same as that of the DEBUG() macro.

111

</p><pre class="programlisting">

112

DEBUG( 0, ("This is the first line.\n" ) );

113

DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) );

114

</pre><p>Produces</p><pre class="programlisting">

115

[1998/07/30 16:00:51, 0] file.c:function(512)

116

This is the first line.

117

This is the second line.

118

This is the third line.

119

</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2557180"></a>The DEBUGLVL() Macro</h2></div></div></div><p>

120

One of the problems with the DEBUG() macro was that DEBUG() lines

121

tended to get a bit long. Consider this example from

122

nmbd_sendannounce.c:

123

</p><pre class="programlisting">

124

DEBUG(3,("send_local_master_announcement: type %x for name %s on subnet %s for workgroup %s\n",

125

type, global_myname, subrec->subnet_name, work->work_group));

126

</pre><p>

127

One solution to this is to break it down using DEBUG() and DEBUGADD(),

128

as follows:

129

</p><pre class="programlisting">

130

DEBUG( 3, ( "send_local_master_announcement: " ) );

131

DEBUGADD( 3, ( "type %x for name %s ", type, global_myname ) );

132

DEBUGADD( 3, ( "on subnet %s ", subrec->subnet_name ) );

133

DEBUGADD( 3, ( "for workgroup %s\n", work->work_group ) );

134

</pre><p>

135

A similar, but arguably nicer approach is to use the DEBUGLVL() macro.

136

This macro returns True if the message level is less than or equal to

137

the global DEBUGLEVEL value, so:

138

</p><pre class="programlisting">

139

if( DEBUGLVL( 3 ) )

140

{

141

dbgtext( "send_local_master_announcement: " );

142

dbgtext( "type %x for name %s ", type, global_myname );

143

dbgtext( "on subnet %s ", subrec->subnet_name );

144

dbgtext( "for workgroup %s\n", work->work_group );

145

}

146

</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>

147

The test is performed only once.

148

</p></li><li><p>

149

You can allocate variables off of the stack that will only be used

150

within the DEBUGLVL() block.

151

</p></li><li><p>

152

Processing that is only relevant to debug output can be contained

153

within the DEBUGLVL() block.

154

</p></li></ol></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2557271"></a>New Functions</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2557276"></a>dbgtext()</h3></div></div></div><p>

155

This function prints debug message text to the debug file (and

156

possibly to syslog) via the format buffer. The function uses a

157

variable argument list just like printf() or Debug1(). The

158

input is printed into a buffer using the vslprintf() function,

159

and then passed to format_debug_text().

160

161

If you use DEBUGLVL() you will probably print the body of the

162

message using dbgtext().

163

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2557292"></a>dbghdr()</h3></div></div></div><p>

164

This is the function that writes a debug message header.

165

Headers are not processed via the format buffer. Also note that

166

if the format buffer is not empty, a call to dbghdr() will not

167

produce any output. See the comments in dbghdr() for more info.

168

</p><p>

169

It is not likely that this function will be called directly. It

170

is used by DEBUG() and DEBUGADD().

171

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2557311"></a>format_debug_text()</h3></div></div></div><p>

172

This is a static function in debug.c. It stores the output text

173

for the body of the message in a buffer until it encounters a

174

newline. When the newline character is found, the buffer is

175

written to the debug file via the Debug1() function, and the

176

buffer is reset. This allows us to add the indentation at the

177

beginning of each line of the message body, and also ensures

178

that the output is written a line at a time (which cleans up

179

syslog output).

180

</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>