2 Copyright (c) 2000-2011 by Nicolas Devillard.
5 Permission is hereby granted, free of charge, to any person obtaining a
6 copy of this software and associated documentation files (the "Software"),
7 to deal in the Software without restriction, including without limitation
8 the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 and/or sell copies of the Software, and to permit persons to whom the
10 Software is furnished to do so, subject to the following conditions:
12 The above copyright notice and this permission notice shall be included in
13 all copies or substantial portions of the Software.
15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 DEALINGS IN THE SOFTWARE.
26 /*-------------------------------------------------------------------------*/
30 @brief Parser for ini files.
32 /*--------------------------------------------------------------------------*/
34 /*---------------------------------------------------------------------------
36 ---------------------------------------------------------------------------*/
47 * The following #include is necessary on many Unixes but not Linux.
48 * It is not needed for Windows platforms.
49 * Uncomment it if needed.
51 /* #include <unistd.h> */
53 #include "dictionary.h"
55 /*-------------------------------------------------------------------------*/
57 @brief Get number of sections in a dictionary
58 @param d Dictionary to examine
59 @return int Number of sections found in dictionary
61 This function returns the number of sections found in a dictionary.
62 The test to recognize sections is done on the string stored in the
63 dictionary: a section name is given as "section" whereas a key is
64 stored as "section:key", thus the test looks for entries that do not
67 This clearly fails in the case a section name contains a colon, but
68 this should simply be avoided.
70 This function returns -1 in case of error.
72 /*--------------------------------------------------------------------------*/
74 int iniparser_getnsec(dictionary * d);
77 /*-------------------------------------------------------------------------*/
79 @brief Get name for section n in a dictionary.
80 @param d Dictionary to examine
81 @param n Section number (from 0 to nsec-1).
82 @return Pointer to char string
84 This function locates the n-th section in a dictionary and returns
85 its name as a pointer to a string statically allocated inside the
86 dictionary. Do not free or modify the returned string!
88 This function returns NULL in case of error.
90 /*--------------------------------------------------------------------------*/
92 char * iniparser_getsecname(dictionary * d, int n);
95 /*-------------------------------------------------------------------------*/
97 @brief Save a dictionary to a loadable ini file
98 @param d Dictionary to dump
99 @param f Opened file pointer to dump to
102 This function dumps a given dictionary into a loadable ini file.
103 It is Ok to specify @c stderr or @c stdout as output files.
105 /*--------------------------------------------------------------------------*/
107 void iniparser_dump_ini(dictionary * d, FILE * f);
109 /*-------------------------------------------------------------------------*/
111 @brief Save a dictionary section to a loadable ini file
112 @param d Dictionary to dump
113 @param s Section name of dictionary to dump
114 @param f Opened file pointer to dump to
117 This function dumps a given section of a given dictionary into a loadable ini
118 file. It is Ok to specify @c stderr or @c stdout as output files.
120 /*--------------------------------------------------------------------------*/
122 void iniparser_dumpsection_ini(dictionary * d, char * s, FILE * f);
124 /*-------------------------------------------------------------------------*/
126 @brief Dump a dictionary to an opened file pointer.
127 @param d Dictionary to dump.
128 @param f Opened file pointer to dump to.
131 This function prints out the contents of a dictionary, one element by
132 line, onto the provided file pointer. It is OK to specify @c stderr
133 or @c stdout as output files. This function is meant for debugging
136 /*--------------------------------------------------------------------------*/
137 void iniparser_dump(dictionary * d, FILE * f);
139 /*-------------------------------------------------------------------------*/
141 @brief Get the number of keys in a section of a dictionary.
142 @param d Dictionary to examine
143 @param s Section name of dictionary to examine
144 @return Number of keys in section
146 /*--------------------------------------------------------------------------*/
147 int iniparser_getsecnkeys(dictionary * d, char * s);
149 /*-------------------------------------------------------------------------*/
151 @brief Get the number of keys in a section of a dictionary.
152 @param d Dictionary to examine
153 @param s Section name of dictionary to examine
154 @return pointer to statically allocated character strings
156 This function queries a dictionary and finds all keys in a given section.
157 Each pointer in the returned char pointer-to-pointer is pointing to
158 a string allocated in the dictionary; do not free or modify them.
160 This function returns NULL in case of error.
162 /*--------------------------------------------------------------------------*/
163 char ** iniparser_getseckeys(dictionary * d, char * s);
165 /*-------------------------------------------------------------------------*/
167 @brief Get the string associated to a key
168 @param d Dictionary to search
169 @param key Key string to look for
170 @param def Default value to return if key not found.
171 @return pointer to statically allocated character string
173 This function queries a dictionary for a key. A key as read from an
174 ini file is given as "section:key". If the key cannot be found,
175 the pointer passed as 'def' is returned.
176 The returned char pointer is pointing to a string allocated in
177 the dictionary, do not free or modify it.
179 /*--------------------------------------------------------------------------*/
180 char * iniparser_getstring(dictionary * d, const char * key, char * def);
182 /*-------------------------------------------------------------------------*/
184 @brief Get the string associated to a key, convert to an int
185 @param d Dictionary to search
186 @param key Key string to look for
187 @param notfound Value to return in case of error
190 This function queries a dictionary for a key. A key as read from an
191 ini file is given as "section:key". If the key cannot be found,
192 the notfound value is returned.
194 Supported values for integers include the usual C notation
195 so decimal, octal (starting with 0) and hexadecimal (starting with 0x)
196 are supported. Examples:
199 - "042" -> 34 (octal -> decimal)
200 - "0x42" -> 66 (hexa -> decimal)
202 Warning: the conversion may overflow in various ways. Conversion is
203 totally outsourced to strtol(), see the associated man page for overflow
206 Credits: Thanks to A. Becker for suggesting strtol()
208 /*--------------------------------------------------------------------------*/
209 int iniparser_getint(dictionary * d, const char * key, int notfound);
211 /*-------------------------------------------------------------------------*/
213 @brief Get the string associated to a key, convert to a double
214 @param d Dictionary to search
215 @param key Key string to look for
216 @param notfound Value to return in case of error
219 This function queries a dictionary for a key. A key as read from an
220 ini file is given as "section:key". If the key cannot be found,
221 the notfound value is returned.
223 /*--------------------------------------------------------------------------*/
224 double iniparser_getdouble(dictionary * d, const char * key, double notfound);
226 /*-------------------------------------------------------------------------*/
228 @brief Get the string associated to a key, convert to a boolean
229 @param d Dictionary to search
230 @param key Key string to look for
231 @param notfound Value to return in case of error
234 This function queries a dictionary for a key. A key as read from an
235 ini file is given as "section:key". If the key cannot be found,
236 the notfound value is returned.
238 A true boolean is found if one of the following is matched:
240 - A string starting with 'y'
241 - A string starting with 'Y'
242 - A string starting with 't'
243 - A string starting with 'T'
244 - A string starting with '1'
246 A false boolean is found if one of the following is matched:
248 - A string starting with 'n'
249 - A string starting with 'N'
250 - A string starting with 'f'
251 - A string starting with 'F'
252 - A string starting with '0'
254 The notfound value returned if no boolean is identified, does not
255 necessarily have to be 0 or 1.
257 /*--------------------------------------------------------------------------*/
258 int iniparser_getboolean(dictionary * d, const char * key, int notfound);
261 /*-------------------------------------------------------------------------*/
263 @brief Set an entry in a dictionary.
264 @param ini Dictionary to modify.
265 @param entry Entry to modify (entry name)
266 @param val New value to associate to the entry.
267 @return int 0 if Ok, -1 otherwise.
269 If the given entry can be found in the dictionary, it is modified to
270 contain the provided value. If it cannot be found, -1 is returned.
271 It is Ok to set val to NULL.
273 /*--------------------------------------------------------------------------*/
274 int iniparser_set(dictionary * ini, const char * entry, const char * val);
277 /*-------------------------------------------------------------------------*/
279 @brief Delete an entry in a dictionary
280 @param ini Dictionary to modify
281 @param entry Entry to delete (entry name)
284 If the given entry can be found, it is deleted from the dictionary.
286 /*--------------------------------------------------------------------------*/
287 void iniparser_unset(dictionary * ini, const char * entry);
289 /*-------------------------------------------------------------------------*/
291 @brief Finds out if a given entry exists in a dictionary
292 @param ini Dictionary to search
293 @param entry Name of the entry to look for
294 @return integer 1 if entry exists, 0 otherwise
296 Finds out if a given entry exists in the dictionary. Since sections
297 are stored as keys with NULL associated values, this is the only way
298 of querying for the presence of sections in a dictionary.
300 /*--------------------------------------------------------------------------*/
301 int iniparser_find_entry(dictionary * ini, const char * entry) ;
303 /*-------------------------------------------------------------------------*/
305 @brief Parse an ini file and return an allocated dictionary object
306 @param ininame Name of the ini file to read.
307 @return Pointer to newly allocated dictionary
309 This is the parser for ini files. This function is called, providing
310 the name of the file to be read. It returns a dictionary object that
311 should not be accessed directly, but through accessor functions
314 The returned dictionary must be freed using iniparser_freedict().
316 /*--------------------------------------------------------------------------*/
317 dictionary * iniparser_load(const char * ininame);
319 /*-------------------------------------------------------------------------*/
321 @brief Free all memory associated to an ini dictionary
322 @param d Dictionary to free
325 Free all memory associated to an ini dictionary.
326 It is mandatory to call this function before the dictionary object
327 gets out of the current context.
329 /*--------------------------------------------------------------------------*/
330 void iniparser_freedict(dictionary * d);