This commit was manufactured by cvs2svn to create tag
[Samba.git] / source / parsing.doc
blobd26a64ae4e8a264f17d0135ce2bf96461ab2680e
1 Chris Hertel, Samba Team
2 November 1997
4 This is a quick overview of the lexical analysis, syntax, and semantics
5 of the smb.conf file.
7 Lexical Analysis:
9   Basically, the file is processed on a line by line basis.  There are
10   four types of lines that are recognized by the lexical analyzer
11   (params.c):
13   Blank lines           - Lines containing only whitespace.
14   Comment lines         - Lines beginning with either a semi-colon or a
15                           pound sign (';' or '#').
16   Section header lines  - Lines beginning with an open square bracket
17                           ('[').
18   Parameter lines       - Lines beginning with any other character.
19                           (The default line type.)
21   The first two are handled exclusively by the lexical analyzer, which
22   ignores them.  The latter two line types are scanned for
24   - Section names
25   - Parameter names
26   - Parameter values
28   These are the only tokens passed to the parameter loader
29   (loadparm.c).  Parameter names and values are divided from one
30   another by an equal sign: '='.
33   Handling of Whitespace:
35   Whitespace is defined as all characters recognized by the isspace()
36   function (see ctype(3C)) except for the newline character ('\n')
37   The newline is excluded because it identifies the end of the line.
39   - The lexical analyzer scans past white space at the beginning of a
40     line.
42   - Section and parameter names may contain internal white space.  All
43     whitespace within a name is compressed to a single space character. 
45   - Internal whitespace within a parameter value is kept verbatim with
46     the exception of carriage return characters ('\r'), all of which
47     are removed.
49   - Leading and trailing whitespace is removed from names and values.
52   Handling of Line Continuation:
54   Long section header and parameter lines may be extended across
55   multiple lines by use of the backslash character ('\\').  Line
56   continuation is ignored for blank and comment lines.
58   If the last (non-whitespace) character within a section header or on
59   a parameter line is a backslash, then the next line will be
60   (logically) concatonated with the current line by the lexical
61   analyzer.  For example:
63     param name = parameter value string \
64     with line continuation.
66   Would be read as
68     param name = parameter value string     with line continuation.
70   Note that there are five spaces following the word 'string',
71   representing the one space between 'string' and '\\' in the top
72   line, plus the four preceeding the word 'with' in the second line.
73   (Yes, I'm counting the indentation.)
75   Line continuation characters are ignored on blank lines and at the end
76   of comments.  They are *only* recognized within section and parameter
77   lines.
80   Line Continuation Quirks:
81   
82   Note the following example:
84     param name = parameter value string \
85     \
86     with line continuation.
88   The middle line is *not* parsed as a blank line because it is first
89   concatonated with the top line.  The result is
91     param name = parameter value string         with line continuation.
93   The same is true for comment lines.
95     param name = parameter value string \
96     ; comment \
97     with a comment.
99   This becomes:
100   
101     param name = parameter value string     ; comment     with a comment.
103   On a section header line, the closing bracket (']') is considered a
104   terminating character, and the rest of the line is ignored.  The lines
105   
106     [ section   name ] garbage \
107     param  name  = value
109   are read as
111     [section name]
112     param name = value
116 Syntax:
118   The syntax of the smb.conf file is as follows:
120   <file>            :==  { <section> } EOF
122   <section>         :==  <section header> { <parameter line> }
124   <section header>  :==  '[' NAME ']'
126   <parameter line>  :==  NAME '=' VALUE NL
129   Basically, this means that
130   
131     - a file is made up of zero or more sections, and is terminated by
132       an EOF (we knew that).
134     - A section is made up of a section header followed by zero or more
135       parameter lines.
137     - A section header is identified by an opening bracket and
138       terminated by the closing bracket.  The enclosed NAME identifies
139       the section.
141     - A parameter line is divided into a NAME and a VALUE.  The *first*
142       equal sign on the line separates the NAME from the VALUE.  The
143       VALUE is terminated by a newline character (NL = '\n').
146 About params.c:
148   The parsing of the config file is a bit unusual if you are used to
149   lex, yacc, bison, etc.  Both lexical analysis (scanning) and parsing
150   are performed by params.c.  Values are loaded via callbacks to
151   loadparm.c.
153 --------------------------------------------------------------------------
155                                   Samba DEBUG
156                                        
157 Chris Hertel, Samba Team
158 July, 1998
159    
160    Here's the scoop on the update to the DEBUG() system.
161    
162    First, my goals are:
163      * Backward compatibility (ie., I don't want to break any Samba code
164        that already works).
165      * Debug output should be timestamped and easy to read (format-wise).
166      * Debug output should be parsable by software.
167      * There should be convenient tools for composing debug messages.
168        
169    NOTE: the Debug functionality has been moved from util.c to the new
170    debug.c module.
171    
172 New Output Syntax
174    The syntax of a debugging log file is represented as:
175   <debugfile> :== { <debugmsg> }
177   <debugmsg>  :== <debughdr> '\n' <debugtext>
179   <debughdr>  :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')'
181   <debugtext> :== { <debugline> }
183   <debugline> :== TEXT '\n'
185    TEXT is a string of characters excluding the newline character.
186    LEVEL is the DEBUG level of the message (an integer in the range
187    0..10).
188    TIME is a timestamp.
189    FILE is the name of the file from which the debug message was
190    generated.
191    FUNCTION is the function from which the debug message was generated.
192    LINE is the line number of the debug statement that generated the
193    message.
194    
195    Basically, what that all means is:
196      * A debugging log file is made up of debug messages.
197      * Each debug message is made up of a header and text. The header is
198        separated from the text by a newline.
199      * The header begins with the timestamp and debug level of the
200        message enclosed in brackets. The filename, function, and line
201        number at which the message was generated follow. The filename is
202        terminated by a colon, and the function name is terminated by the
203        parenthesis which contain the line number. Depending upon the
204        compiler, the function name may be missing (it is generated by the
205        __FUNCTION__ macro, which is not universally implemented, dangit).
206      * The message text is made up of zero or more lines, each terminated
207        by a newline.
208        
209    Here's some example output:
211     [1998/08/03 12:55:25, 1] nmbd.c:(659)
212       Netbios nameserver version 1.9.19-prealpha started.
213       Copyright Andrew Tridgell 1994-1997
214     [1998/08/03 12:55:25, 3] loadparm.c:(763)
215       Initializing global parameters
217    Note that in the above example the function names are not listed on
218    the header line. That's because the example above was generated on an
219    SGI Indy, and the SGI compiler doesn't support the __FUNCTION__ macro.
220    
221 The DEBUG() Macro
223    Use of the DEBUG() macro is unchanged. DEBUG() takes two parameters.
224    The first is the message level, the second is the body of a function
225    call to the Debug1() function.
226    
227    That's confusing.
228    
229    Here's an example which may help a bit. If you would write
231      printf( "This is a %s message.\n", "debug" );
233    to send the output to stdout, then you would write
235      DEBUG( 0, ( "This is a %s message.\n", "debug" ) );
237    to send the output to the debug file.  All of the normal printf()
238    formatting escapes work.
239    
240    Note that in the above example the DEBUG message level is set to 0.
241    Messages at level 0 always print.  Basically, if the message level is
242    less than or equal to the global value DEBUGLEVEL, then the DEBUG
243    statement is processed.
244    
245    The output of the above example would be something like:
247     [1998/07/30 16:00:51, 0] file.c:function(128)
248       This is a debug message.
250    Each call to DEBUG() creates a new header *unless* the output produced
251    by the previous call to DEBUG() did not end with a '\n'. Output to the
252    debug file is passed through a formatting buffer which is flushed
253    every time a newline is encountered. If the buffer is not empty when
254    DEBUG() is called, the new input is simply appended.
256    ...but that's really just a Kludge. It was put in place because
257    DEBUG() has been used to write partial lines. Here's a simple (dumb)
258    example of the kind of thing I'm talking about:
260     DEBUG( 0, ("The test returned " ) );
261     if( test() )
262       DEBUG(0, ("True") );
263     else
264       DEBUG(0, ("False") );
265     DEBUG(0, (".\n") );
267    Without the format buffer, the output (assuming test() returned true)
268    would look like this:
270     [1998/07/30 16:00:51, 0] file.c:function(256)
271       The test returned
272     [1998/07/30 16:00:51, 0] file.c:function(258)
273       True
274     [1998/07/30 16:00:51, 0] file.c:function(261)
275       .
277    Which isn't much use. The format buffer kludge fixes this problem.
278    
279 The DEBUGADD() Macro
281    In addition to the kludgey solution to the broken line problem
282    described above, there is a clean solution. The DEBUGADD() macro never
283    generates a header. It will append new text to the current debug
284    message even if the format buffer is empty. The syntax of the
285    DEBUGADD() macro is the same as that of the DEBUG() macro.
287     DEBUG( 0, ("This is the first line.\n" ) );
288     DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) );
290    Produces
291     [1998/07/30 16:00:51, 0] file.c:function(512)
292       This is the first line.
293       This is the second line.
294       This is the third line.
296 The DEBUGLVL() Macro
298    One of the problems with the DEBUG() macro was that DEBUG() lines
299    tended to get a bit long. Consider this example from
300    nmbd_sendannounce.c:
302   DEBUG(3,("send_local_master_announcement: type %x for name %s on subnet %s for workgroup %s\n",
303             type, global_myname, subrec->subnet_name, work->work_group));
305    One solution to this is to break it down using DEBUG() and DEBUGADD(),
306    as follows:
308   DEBUG( 3, ( "send_local_master_announcement: " ) );
309   DEBUGADD( 3, ( "type %x for name %s ", type, global_myname ) );
310   DEBUGADD( 3, ( "on subnet %s ", subrec->subnet_name ) );
311   DEBUGADD( 3, ( "for workgroup %s\n", work->work_group ) );
313    A similar, but arguably nicer approach is to use the DEBUGLVL() macro.
314    This macro returns True if the message level is less than or equal to
315    the global DEBUGLEVEL value, so:
317   if( DEBUGLVL( 3 ) )
318     {
319     dbgtext( "send_local_master_announcement: " );
320     dbgtext( "type %x for name %s ", type, global_myname );
321     dbgtext( "on subnet %s ", subrec->subnet_name );
322     dbgtext( "for workgroup %s\n", work->work_group );
323     }
325    (The dbgtext() function is explained below.)
326    
327    There are a few advantages to this scheme:
328      * The test is performed only once.
329      * You can allocate variables off of the stack that will only be used
330        within the DEBUGLVL() block.
331      * Processing that is only relevant to debug output can be contained
332        within the DEBUGLVL() block.
333        
334 New Functions
336    dbgtext()
337           This function prints debug message text to the debug file (and
338           possibly to syslog) via the format buffer. The function uses a
339           variable argument list just like printf() or Debug1(). The
340           input is printed into a buffer using the vslprintf() function,
341           and then passed to format_debug_text().
342           
343           If you use DEBUGLVL() you will probably print the body of the
344           message using dbgtext(). 
345           
346    dbghdr()
347           This is the function that writes a debug message header.
348           Headers are not processed via the format buffer. Also note that
349           if the format buffer is not empty, a call to dbghdr() will not
350           produce any output. See the comments in dbghdr() for more info.
351           
352           It is not likely that this function will be called directly. It
353           is used by DEBUG() and DEBUGADD().
354           
355    format_debug_text()
356           This is a static function in debug.c. It stores the output text
357           for the body of the message in a buffer until it encounters a
358           newline. When the newline character is found, the buffer is
359           written to the debug file via the Debug1() function, and the
360           buffer is reset. This allows us to add the indentation at the
361           beginning of each line of the message body, and also ensures
362           that the output is written a line at a time (which cleans up
363           syslog output).