s3: Slightly simplify smbd_smb2_request_process_negprot
[Samba/gebeck_regimport.git] / docs-xml / Samba3-Developers-Guide / parsing.xml
blobd695f9313cf06a2542bce2b6d006389313856f29
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <chapter id="parsing">
4 <chapterinfo>
5         <author>
6                 <firstname>Chris</firstname><surname>Hertel</surname>
7         </author>
8         <pubdate>November 1997</pubdate>
9 </chapterinfo>
11 <title>The smb.conf file</title>
13 <sect1>
14 <title>Lexical Analysis</title>
16 <para>
17 Basically, the file is processed on a line by line basis.  There are
18 four types of lines that are recognized by the lexical analyzer
19 (params.c):
20 </para>
22 <orderedlist>
23 <listitem><para>
24 Blank lines - Lines containing only whitespace.
25 </para></listitem>
26 <listitem><para>
27 Comment lines - Lines beginning with either a semi-colon or a
28 pound sign (';' or '#').
29 </para></listitem>
30 <listitem><para>
31 Section header lines - Lines beginning with an open square bracket ('[').
32 </para></listitem>
33 <listitem><para>
34 Parameter lines - Lines beginning with any other character.
35 (The default line type.)
36 </para></listitem>
37 </orderedlist>
39 <para>
40 The first two are handled exclusively by the lexical analyzer, which
41 ignores them.  The latter two line types are scanned for
42 </para>
44 <orderedlist>
45 <listitem><para>
46   - Section names
47 </para></listitem>
48 <listitem><para>
49   - Parameter names
50 </para></listitem>
51 <listitem><para>
52   - Parameter values
53 </para></listitem>
54 </orderedlist>
56 <para>
57 These are the only tokens passed to the parameter loader
58 (loadparm.c).  Parameter names and values are divided from one
59 another by an equal sign: '='.
60 </para>
62 <sect2>
63 <title>Handling of Whitespace</title>
65 <para>
66 Whitespace is defined as all characters recognized by the isspace()
67 function (see ctype(3C)) except for the newline character ('\n')
68 The newline is excluded because it identifies the end of the line.
69 </para>
71 <orderedlist>
72 <listitem><para>
73 The lexical analyzer scans past white space at the beginning of a line.
74 </para></listitem>
76 <listitem><para>
77 Section and parameter names may contain internal white space.  All
78 whitespace within a name is compressed to a single space character. 
79 </para></listitem>
81 <listitem><para>
82 Internal whitespace within a parameter value is kept verbatim with 
83 the exception of carriage return characters ('\r'), all of which
84 are removed.
85 </para></listitem>
87 <listitem><para>
88 Leading and trailing whitespace is removed from names and values.
89 </para></listitem>
91 </orderedlist>
93 </sect2>
95 <sect2>
96 <title>Handling of Line Continuation</title>
98 <para>
99 Long section header and parameter lines may be extended across
100 multiple lines by use of the backslash character ('\\').  Line
101 continuation is ignored for blank and comment lines.
102 </para>
104 <para>
105 If the last (non-whitespace) character within a section header or on
106 a parameter line is a backslash, then the next line will be
107 (logically) concatonated with the current line by the lexical
108 analyzer.  For example:
109 </para>
111 <para><programlisting>
112         param name = parameter value string \
113         with line continuation.
114 </programlisting></para>
116 <para>Would be read as</para>
118 <para><programlisting>
119     param name = parameter value string     with line continuation.
120 </programlisting></para>
122 <para>
123 Note that there are five spaces following the word 'string',
124 representing the one space between 'string' and '\\' in the top
125 line, plus the four preceeding the word 'with' in the second line.
126 (Yes, I'm counting the indentation.)
127 </para>
129 <para>
130 Line continuation characters are ignored on blank lines and at the end
131 of comments.  They are *only* recognized within section and parameter
132 lines.
133 </para>
135 </sect2>
137 <sect2>
138 <title>Line Continuation Quirks</title>
140 <para>Note the following example:</para>
142 <para><programlisting>
143         param name = parameter value string \
144     \
145     with line continuation.
146 </programlisting></para>
148 <para>
149 The middle line is *not* parsed as a blank line because it is first
150 concatonated with the top line.  The result is
151 </para>
153 <para><programlisting>
154 param name = parameter value string         with line continuation.
155 </programlisting></para>
157 <para>The same is true for comment lines.</para>
159 <para><programlisting>
160         param name = parameter value string \
161         ; comment \
162     with a comment.
163 </programlisting></para>
165 <para>This becomes:</para>
167 <para><programlisting>
168 param name = parameter value string     ; comment     with a comment.
169 </programlisting></para>
171 <para>
172 On a section header line, the closing bracket (']') is considered a
173 terminating character, and the rest of the line is ignored.  The lines
174 </para>
176 <para><programlisting>
177         [ section   name ] garbage \
178     param  name  = value
179 </programlisting></para>
181 <para>are read as</para>
183 <para><programlisting>
184         [section name]
185     param name = value
186 </programlisting></para>
188 </sect2>
189 </sect1>
191 <sect1>
192 <title>Syntax</title>
194 <para>The syntax of the smb.conf file is as follows:</para>
196 <para><programlisting>
197   &lt;file&gt;            :==  { &lt;section&gt; } EOF
198   &lt;section&gt;         :==  &lt;section header&gt; { &lt;parameter line&gt; }
199   &lt;section header&gt;  :==  '[' NAME ']'
200   &lt;parameter line&gt;  :==  NAME '=' VALUE NL
201 </programlisting></para>
203 <para>Basically, this means that</para>
205 <orderedlist>
206 <listitem><para>
207         a file is made up of zero or more sections, and is terminated by
208         an EOF (we knew that).
209 </para></listitem>
211 <listitem><para>
212         A section is made up of a section header followed by zero or more
213         parameter lines.
214 </para></listitem>
216 <listitem><para>
217         A section header is identified by an opening bracket and
218         terminated by the closing bracket.  The enclosed NAME identifies
219         the section.
220 </para></listitem>
222 <listitem><para>
223         A parameter line is divided into a NAME and a VALUE.  The *first*
224         equal sign on the line separates the NAME from the VALUE.  The
225         VALUE is terminated by a newline character (NL = '\n').
226 </para></listitem>
228 </orderedlist>
230 <sect2>
231 <title>About params.c</title>
233 <para>
234 The parsing of the config file is a bit unusual if you are used to
235 lex, yacc, bison, etc.  Both lexical analysis (scanning) and parsing
236 are performed by params.c.  Values are loaded via callbacks to
237 loadparm.c.
238 </para>
239 </sect2>
240 </sect1>
241 </chapter>