source3/parsing.doc

   1 Chris Hertel, Samba Team
   2 November 1997
   3
   4 This is a quick overview of the lexical analysis, syntax, and semantics
   5 of the smb.conf file.
   6
   7 Lexical Analysis:
   8
   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):
  12
  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.)
  20
  21   The first two are handled exclusively by the lexical analyzer, which
  22   ignores them.  The latter two line types are scanned for
  23
  24   - Section names
  25   - Parameter names
  26   - Parameter values
  27
  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: '='.
  31
  32
  33   Handling of Whitespace:
  34
  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.
  38
  39   - The lexical analyzer scans past white space at the beginning of a
  40     line.
  41
  42   - Section and parameter names may contain internal white space.  All
  43     whitespace within a name is compressed to a single space character.
  44
  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.
  48
  49   - Leading and trailing whitespace is removed from names and values.
  50
  51
  52   Handling of Line Continuation:
  53
  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.
  57
  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:
  62
  63     param name = parameter value string \
  64     with line continuation.
  65
  66   Would be read as
  67
  68     param name = parameter value string     with line continuation.
  69
  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.)
  74
  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.
  78
  79
  80   Line Continuation Quirks:
  81
  82   Note the following example:
  83
  84     param name = parameter value string \
  85     \
  86     with line continuation.
  87
  88   The middle line is *not* parsed as a blank line because it is first
  89   concatonated with the top line.  The result is
  90
  91     param name = parameter value string         with line continuation.
  92
  93   The same is true for comment lines.
  94
  95     param name = parameter value string \
  96     ; comment \
  97     with a comment.
  98
  99   This becomes:
 100
 101     param name = parameter value string     ; comment     with a comment.
 102
 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
 108
 109   are read as
 110
 111     [section name]
 112     param name = value
 113
 114
 115
 116 Syntax:
 117
 118   The syntax of the smb.conf file is as follows:
 119
 120   <file>            :==  { <section> } EOF
 121
 122   <section>         :==  <section header> { <parameter line> }
 123
 124   <section header>  :==  '[' NAME ']'
 125
 126   <parameter line>  :==  NAME '=' VALUE NL
 127
 128
 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).
 133
 134     - A section is made up of a section header followed by zero or more
 135       parameter lines.
 136
 137     - A section header is identified by an opening bracket and
 138       terminated by the closing bracket.  The enclosed NAME identifies
 139       the section.
 140
 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').
 144
 145
 146 About params.c:
 147
 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.
 152
 153 --------------------------------------------------------------------------
 154
 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
 173
 174    The syntax of a debugging log file is represented as:
 175   <debugfile> :== { <debugmsg> }
 176
 177   <debugmsg>  :== <debughdr> '\n' <debugtext>
 178
 179   <debughdr>  :== '[' TIME ',' LEVEL ']' FILE ':' [FUNCTION] '(' LINE ')'
 180
 181   <debugtext> :== { <debugline> }
 182
 183   <debugline> :== TEXT '\n'
 184
 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:
 210
 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
 216
 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
 222
 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
 230
 231      printf( "This is a %s message.\n", "debug" );
 232
 233    to send the output to stdout, then you would write
 234
 235      DEBUG( 0, ( "This is a %s message.\n", "debug" ) );
 236
 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:
 246
 247     [1998/07/30 16:00:51, 0] file.c:function(128)
 248       This is a debug message.
 249
 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.
 255
 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:
 259
 260     DEBUG( 0, ("The test returned " ) );
 261     if( test() )
 262       DEBUG(0, ("True") );
 263     else
 264       DEBUG(0, ("False") );
 265     DEBUG(0, (".\n") );
 266
 267    Without the format buffer, the output (assuming test() returned true)
 268    would look like this:
 269
 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       .
 276
 277    Which isn't much use. The format buffer kludge fixes this problem.
 278
 279 The DEBUGADD() Macro
 280
 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.
 286
 287     DEBUG( 0, ("This is the first line.\n" ) );
 288     DEBUGADD( 0, ("This is the second line.\nThis is the third line.\n" ) );
 289
 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.
 295
 296 The DEBUGLVL() Macro
 297
 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:
 301
 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));
 304
 305    One solution to this is to break it down using DEBUG() and DEBUGADD(),
 306    as follows:
 307
 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 ) );
 312
 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:
 316
 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     }
 324
 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
 335
 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).