git.maemo.org Git - samba/blob - docs/htmldocs/Samba3-Developers-Guide/parsing.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 11. The smb.conf file</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt03.html" title="Part III. Samba Subsystems"><link rel="prev" href="vfs.html" title="Chapter 10. VFS Modules"><link rel="next" href="wins.html" title="Chapter 12. Samba WINS 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 11. The smb.conf file</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vfs.html">Prev</a> </td><th width="60%" align="center">Part III. Samba Subsystems</th><td width="20%" align="right"> <a accesskey="n" href="wins.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="parsing"></a>Chapter 11. The smb.conf file</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">November 1997</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="parsing.html#id2526486">Lexical Analysis</a></span></dt><dd><dl><dt><span class="sect2"><a href="parsing.html#id2526562">Handling of Whitespace</a></span></dt><dt><span class="sect2"><a href="parsing.html#id2526607">Handling of Line Continuation</a></span></dt><dt><span class="sect2"><a href="parsing.html#id2526660">Line Continuation Quirks</a></span></dt></dl></dd><dt><span class="sect1"><a href="parsing.html#id2526741">Syntax</a></span></dt><dd><dl><dt><span class="sect2"><a href="parsing.html#id2526801">About params.c</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="id2526486"></a>Lexical Analysis</h2></div></div></div><p>
   2 Basically, the file is processed on a line by line basis.  There are
   3 four types of lines that are recognized by the lexical analyzer
   4 (params.c):
   5 </p><div class="orderedlist"><ol type="1"><li><p>
   6 Blank lines - Lines containing only whitespace.
   7 </p></li><li><p>
   8 Comment lines - Lines beginning with either a semi-colon or a
   9 pound sign (';' or '#').
  10 </p></li><li><p>
  11 Section header lines - Lines beginning with an open square bracket ('[').
  12 </p></li><li><p>
  13 Parameter lines - Lines beginning with any other character.
  14 (The default line type.)
  15 </p></li></ol></div><p>
  16 The first two are handled exclusively by the lexical analyzer, which
  17 ignores them.  The latter two line types are scanned for
  18 </p><div class="orderedlist"><ol type="1"><li><p>
  19   - Section names
  20 </p></li><li><p>
  21   - Parameter names
  22 </p></li><li><p>
  23   - Parameter values
  24 </p></li></ol></div><p>
  25 These are the only tokens passed to the parameter loader
  26 (loadparm.c).  Parameter names and values are divided from one
  27 another by an equal sign: '='.
  28 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2526562"></a>Handling of Whitespace</h3></div></div></div><p>
  29 Whitespace is defined as all characters recognized by the isspace()
  30 function (see ctype(3C)) except for the newline character ('\n')
  31 The newline is excluded because it identifies the end of the line.
  32 </p><div class="orderedlist"><ol type="1"><li><p>
  33 The lexical analyzer scans past white space at the beginning of a line.
  34 </p></li><li><p>
  35 Section and parameter names may contain internal white space.  All
  36 whitespace within a name is compressed to a single space character.
  37 </p></li><li><p>
  38 Internal whitespace within a parameter value is kept verbatim with
  39 the exception of carriage return characters ('\r'), all of which
  40 are removed.
  41 </p></li><li><p>
  42 Leading and trailing whitespace is removed from names and values.
  43 </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2526607"></a>Handling of Line Continuation</h3></div></div></div><p>
  44 Long section header and parameter lines may be extended across
  45 multiple lines by use of the backslash character ('\\').  Line
  46 continuation is ignored for blank and comment lines.
  47 </p><p>
  48 If the last (non-whitespace) character within a section header or on
  49 a parameter line is a backslash, then the next line will be
  50 (logically) concatonated with the current line by the lexical
  51 analyzer.  For example:
  52 </p><pre class="programlisting">
  53         param name = parameter value string \
  54         with line continuation.
  55 </pre><p>Would be read as</p><pre class="programlisting">
  56     param name = parameter value string     with line continuation.
  57 </pre><p>
  58 Note that there are five spaces following the word 'string',
  59 representing the one space between 'string' and '\\' in the top
  60 line, plus the four preceeding the word 'with' in the second line.
  61 (Yes, I'm counting the indentation.)
  62 </p><p>
  63 Line continuation characters are ignored on blank lines and at the end
  64 of comments.  They are *only* recognized within section and parameter
  65 lines.
  66 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2526660"></a>Line Continuation Quirks</h3></div></div></div><p>Note the following example:</p><pre class="programlisting">
  67         param name = parameter value string \
  68     \
  69     with line continuation.
  70 </pre><p>
  71 The middle line is *not* parsed as a blank line because it is first
  72 concatonated with the top line.  The result is
  73 </p><pre class="programlisting">
  74 param name = parameter value string         with line continuation.
  75 </pre><p>The same is true for comment lines.</p><pre class="programlisting">
  76         param name = parameter value string \
  77         ; comment \
  78     with a comment.
  79 </pre><p>This becomes:</p><pre class="programlisting">
  80 param name = parameter value string     ; comment     with a comment.
  81 </pre><p>
  82 On a section header line, the closing bracket (']') is considered a
  83 terminating character, and the rest of the line is ignored.  The lines
  84 </p><pre class="programlisting">
  85         [ section   name ] garbage \
  86     param  name  = value
  87 </pre><p>are read as</p><pre class="programlisting">
  88         [section name]
  89     param name = value
  90 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2526741"></a>Syntax</h2></div></div></div><p>The syntax of the smb.conf file is as follows:</p><pre class="programlisting">
  91   &lt;file&gt;            :==  { &lt;section&gt; } EOF
  92   &lt;section&gt;         :==  &lt;section header&gt; { &lt;parameter line&gt; }
  93   &lt;section header&gt;  :==  '[' NAME ']'
  94   &lt;parameter line&gt;  :==  NAME '=' VALUE NL
  95 </pre><p>Basically, this means that</p><div class="orderedlist"><ol type="1"><li><p>
  96         a file is made up of zero or more sections, and is terminated by
  97         an EOF (we knew that).
  98 </p></li><li><p>
  99         A section is made up of a section header followed by zero or more
 100         parameter lines.
 101 </p></li><li><p>
 102         A section header is identified by an opening bracket and
 103         terminated by the closing bracket.  The enclosed NAME identifies
 104         the section.
 105 </p></li><li><p>
 106         A parameter line is divided into a NAME and a VALUE.  The *first*
 107         equal sign on the line separates the NAME from the VALUE.  The
 108         VALUE is terminated by a newline character (NL = '\n').
 109 </p></li></ol></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2526801"></a>About params.c</h3></div></div></div><p>
 110 The parsing of the config file is a bit unusual if you are used to
 111 lex, yacc, bison, etc.  Both lexical analysis (scanning) and parsing
 112 are performed by params.c.  Values are loaded via callbacks to
 113 loadparm.c.
 114 </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vfs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="wins.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. VFS Modules </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. Samba WINS Internals</td></tr></table></div></body></html>