Chris' smb.conf parsing doco
[samba.git] / 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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181