![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ini_file.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / src / xpdev|
Return to ini_file.txt CVS log | Up to [Synchronet] / sbbs / src / xpdev |
1.1 root 1: $Id: ini_file.txt,v 1.2 2005/10/13 10:16:07 rswindell Exp $
2:
3: Synchronet/xpdev ini_file module
4: --------------------------------
5: The basic format of the files supported by the xpdev ini_file module is that
6: of the Windows .ini file, with some additional features.
7:
8: The basic Windows .ini file format is as follows:
9:
10: 1. The file contains ASCII text only with LF or CR/LF-terminated lines.
11:
12: 2. The file is separated into logical "sections". Each section may have its
13: own list of keys with associated values, one per line.
14:
15: 3. A section begins with a line consisting only of "[" <section name> "]".
16:
17: 4. White space before or after the section name is ignored.
18:
19: 5. A section ends when the end of file is reached or a new section begins.
20:
21: 6. Keys and associated values within a section are specified, each on their
22: line, in the format: <key_name> "=" <value>
23:
24: 7. White space before and after the key/value separator ("=") is ignored.
25:
26: 8. Comments are lines with a semicolon (";") as the first non-whitespace
27: character.
28:
29: 9. Blank lines between or within sections are ignored.
30:
31: Example basic Windows .ini file content:
32:
33: ; for 16-bit app support
34: [fonts]
35: [extensions]
36: [Mail]
37: MAPI=1
38: CMCDLLNAME32=mapi32.dll
39: CMCDLLNAME=mapi.dll
40: CMC=1
41: MAPIX=1
42: MAPIXVER=1.0.0.1
43: OLEMessaging=1
44: [SciCalc]
45: layout=0
46: [MSUCE]
47: Advanced=1
48: CodePage=Unicode
49: Font=Terminal
50:
51:
52: Synchronet/xpdev extended-ini_file format
53: =========================================
54: The Synchronet/xpdev ini_file module supports a somewhat "extended" .ini file
55: format with the following additions:
56:
57: Filenames
58: ---------
59: INI filenames typically end in a ".ini" suffix, but that is not a requirement.
60:
61: If the application uses the ini_file module's iniFileName() function to
62: determine the correct ini filename for the current system, different ini files
63: may be used for different systems on the same network, reading from the same
64: directory.
65:
66: The different ini filename permutations supported (assuming "file.ini" is the
67: base filename) are:
68:
69: path/file.<host>.<domain>.ini
70: path/file.<host>.ini
71: path/file.<platform>.ini
72: path/file.ini
73:
74: Root section
75: ------------
76: Key/value pairs in the file *before* the first section definition are
77: considered part of the "root" section. This section is often used to define
78: key/value pairs that apply globally to all the following sections. The root
79: section may have other uses as well.
80:
81: Section Prefixes
82: ----------------
83: Section names may be include a section "prefix", a fixed portion of the
84: section name that may be used be the application to logically group
85: related sections. Section pre-fixes typically end in a colon, but that is
86: not a requirement.
87:
88: Literal string values
89: ---------------------
90: String values separated by the key name with a colon (':') instead of an
91: equals sign ('='), are parsed as "literal" strings, which means the string
92: will retain any trailing white-space on the line. This may be enhanced in
93: the future to support C escape sequences, multiple/broken lines, etc.
94:
95: Section name list
96: -----------------
97: If one wishes to specify a list of sections for all values to be applied to
98: they may specify a list of section names, separated by '|', where a single
99: section name would normally be specified. Example:
100: "[telnet|rlogin]"
101:
102: Boolean values
103: --------------
104: Values with an either true or false (1 or 0) state can have their value
105: specified as a number (0, or non-zero), or the following strings (yes,
106: English only): "true", "yes", or "on" (interpretted as 1), or "false",
107: "no", or "off" (interpretted as 0). Any otherwise unrecognized text strings
108: will be interpretted as 0 (false).
109:
110: Integer values
111: --------------
112: Integer values may be negative or positive whole numbers of up to
113: (at least) 32-bits in size.
114:
115: Integer values may be specified in octal (base 8), decimal (base 10),
116: hexadecimal (base 16), or base 36 formats based on the following
117: interpretation of the specified value text:
118:
119: If the first character is 0 and the second character is not 'x' or 'X', the
120: string is interpreted as an octal integer; otherwise, it is interpreted as
121: a decimal number. If the first character is '0' and the second character is
122: 'x' or 'X', the string is interpreted as a hexadecimal integer. If the
123: first character is '1' through '9', the string is interpreted as a decimal
124: integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the
125: values 10 through 35.
126:
127: The exception to this rule are the values of "true", "yes", or "on",
128: always interpretted as the value of 1 (one).
129:
130: Long integer values
131: -------------------
132: Long integer values may be positive whole numbers of up to (at least)
133: 32-bits in size. Otherwise, long integer values are interpretted the same as
134: normal integer values.
135:
136: Log levels
137: ----------
138: The ini_file module includes built-in support for the standard Unix syslog
139: levels: Emergency (0), Alert (1), Critical (2), Error (3), Warning (4),
140: Notice (5), Informational (6), and Debugging (7).
141:
142: The higher the log level, the more log output will be generated.
143:
144: Partial or complete log level names may be specified for the log level
145: value, or the numeric equivalent.
146:
147: Byte counts
148: -----------
149: Byte count values (e.g. file sizes) may be specified as positive numbers
150: (fractional numbers are supported), optionally with a 'T', 'G', 'M', or 'K'
151: suffix to specify terabytes, gigabytes, megabytes, or kilobytes, respectively.
152:
153: Date/Time stamps
154: ----------------
155: Date and time values may be specified in any of the following formats:
156:
157: ISO-8601 date and time format: "CCYYMMDDThhmmss"
158: Euro/Canadian numeric date format: "DD.MM.[CC]YY [time] [p]"
159: American numeric date format: "MM/DD/[CC]YY [time] [p]"
160: Perversion of RFC822 date format: "DD[-]Mon [CC]YY [time] [p]"
161: IETF standard (RFC2822) date format: "Wday, DD Mon [CC]YY [time]"
162: Preferred date format: "Mon DD[,] [CC]YY [time] [p]"
163: JavaScript Date.toString() format: "Wday Mon DD [CC]YY [time]"
164: ctime() format: "Wday Mon DD [time] [CC]YY"
165: time_t format: seconds since Jan 1, 1970 UTC
166:
167: where:
168: CC = Century (i.e. "19" or "20")
169: YY = Year number (e.g. "05")
170: MM = Month number (1-12)
171: DD = Day of month (1-31)
172: hh = Hour of day (0-23)
173: mm = Minute of hour (0-59)
174: ss = Second of minute (0-59)
175: p = AM/PM designation
176: time = Time of day specified as "hh[:mm[:ss]]"
177: Mon = Month name (e.g. "Jan", "Feb", etc.)
178: Wday = Weekday name (e.g. "Mon", "Tue", etc.)
179: [] = Optional parameter
180:
181: Bit-fields
182: ----------
183: Bit-field values may be specified as a positive number (same rules of
184: interpretation as integer values), a bit-name, or a list of numbers or
185: bit-names separated by the '|' character.
186:
187: Bit-fields are often used to specify multiple boolean-type values in
188: a single key/value pair.
189:
190: Include directive
191: -----------------
192: An ini file may be include/imported/inserted into a another with the
193: "!include" directive. The line must begin with "!include", followed by
194: white space, and then a filename to include (optionally with a path).
195: Sections may span files.
196:
197: file1.ini:
198: [section_one]
199: key1 = value1
200: !include file2.ini
201:
202: file2.ini:
203: key2 = value2
204:
205: In the above example, both key1 and key2 are part of section_one.
206:
207: End-of-file directive
208: ---------------------
209: An ini file may be prematurely terminated with the "!eof" directive. This
210: stops the ini_file module functions from processing any lines following this
211: directive.
212:
213:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.