testing/mozbase/mozprocess/tests/iniparser/iniparser.h@6474c204b198
testing/mozbase/mozprocess/tests/iniparser/iniparser.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
2 /*-------------------------------------------------------------------------*/
3 /**
4 @file iniparser.h
5 @author N. Devillard
6 @date Sep 2007
7 @version 3.0
8 @brief Parser for ini files.
9 */
10 /*--------------------------------------------------------------------------*/
12 /*
13 $Id: iniparser.h,v 1.26 2011-03-02 20:15:13 ndevilla Exp $
14 $Revision: 1.26 $
15 */
17 #ifndef _INIPARSER_H_
18 #define _INIPARSER_H_
20 /*---------------------------------------------------------------------------
21 Includes
22 ---------------------------------------------------------------------------*/
24 #include <stdio.h>
25 #include <stdlib.h>
26 #include <string.h>
28 /*
29 * The following #include is necessary on many Unixes but not Linux.
30 * It is not needed for Windows platforms.
31 * Uncomment it if needed.
32 */
33 /* #include <unistd.h> */
35 #include "dictionary.h"
37 /*-------------------------------------------------------------------------*/
38 /**
39 @brief Get number of sections in a dictionary
40 @param d Dictionary to examine
41 @return int Number of sections found in dictionary
43 This function returns the number of sections found in a dictionary.
44 The test to recognize sections is done on the string stored in the
45 dictionary: a section name is given as "section" whereas a key is
46 stored as "section:key", thus the test looks for entries that do not
47 contain a colon.
49 This clearly fails in the case a section name contains a colon, but
50 this should simply be avoided.
52 This function returns -1 in case of error.
53 */
54 /*--------------------------------------------------------------------------*/
56 int iniparser_getnsec(dictionary * d);
59 /*-------------------------------------------------------------------------*/
60 /**
61 @brief Get name for section n in a dictionary.
62 @param d Dictionary to examine
63 @param n Section number (from 0 to nsec-1).
64 @return Pointer to char string
66 This function locates the n-th section in a dictionary and returns
67 its name as a pointer to a string statically allocated inside the
68 dictionary. Do not free or modify the returned string!
70 This function returns NULL in case of error.
71 */
72 /*--------------------------------------------------------------------------*/
74 char * iniparser_getsecname(dictionary * d, int n);
77 /*-------------------------------------------------------------------------*/
78 /**
79 @brief Save a dictionary to a loadable ini file
80 @param d Dictionary to dump
81 @param f Opened file pointer to dump to
82 @return void
84 This function dumps a given dictionary into a loadable ini file.
85 It is Ok to specify @c stderr or @c stdout as output files.
86 */
87 /*--------------------------------------------------------------------------*/
89 void iniparser_dump_ini(dictionary * d, FILE * f);
91 /*-------------------------------------------------------------------------*/
92 /**
93 @brief Dump a dictionary to an opened file pointer.
94 @param d Dictionary to dump.
95 @param f Opened file pointer to dump to.
96 @return void
98 This function prints out the contents of a dictionary, one element by
99 line, onto the provided file pointer. It is OK to specify @c stderr
100 or @c stdout as output files. This function is meant for debugging
101 purposes mostly.
102 */
103 /*--------------------------------------------------------------------------*/
104 void iniparser_dump(dictionary * d, FILE * f);
106 /*-------------------------------------------------------------------------*/
107 /**
108 @brief Get the string associated to a key
109 @param d Dictionary to search
110 @param key Key string to look for
111 @param def Default value to return if key not found.
112 @return pointer to statically allocated character string
114 This function queries a dictionary for a key. A key as read from an
115 ini file is given as "section:key". If the key cannot be found,
116 the pointer passed as 'def' is returned.
117 The returned char pointer is pointing to a string allocated in
118 the dictionary, do not free or modify it.
119 */
120 /*--------------------------------------------------------------------------*/
121 char * iniparser_getstring(dictionary * d, char * key, char * def);
123 /*-------------------------------------------------------------------------*/
124 /**
125 @brief Get the string associated to a key, convert to an int
126 @param d Dictionary to search
127 @param key Key string to look for
128 @param notfound Value to return in case of error
129 @return integer
131 This function queries a dictionary for a key. A key as read from an
132 ini file is given as "section:key". If the key cannot be found,
133 the notfound value is returned.
135 Supported values for integers include the usual C notation
136 so decimal, octal (starting with 0) and hexadecimal (starting with 0x)
137 are supported. Examples:
139 - "42" -> 42
140 - "042" -> 34 (octal -> decimal)
141 - "0x42" -> 66 (hexa -> decimal)
143 Warning: the conversion may overflow in various ways. Conversion is
144 totally outsourced to strtol(), see the associated man page for overflow
145 handling.
147 Credits: Thanks to A. Becker for suggesting strtol()
148 */
149 /*--------------------------------------------------------------------------*/
150 int iniparser_getint(dictionary * d, char * key, int notfound);
152 /*-------------------------------------------------------------------------*/
153 /**
154 @brief Get the string associated to a key, convert to a double
155 @param d Dictionary to search
156 @param key Key string to look for
157 @param notfound Value to return in case of error
158 @return double
160 This function queries a dictionary for a key. A key as read from an
161 ini file is given as "section:key". If the key cannot be found,
162 the notfound value is returned.
163 */
164 /*--------------------------------------------------------------------------*/
165 double iniparser_getdouble(dictionary * d, char * key, double notfound);
167 /*-------------------------------------------------------------------------*/
168 /**
169 @brief Get the string associated to a key, convert to a boolean
170 @param d Dictionary to search
171 @param key Key string to look for
172 @param notfound Value to return in case of error
173 @return integer
175 This function queries a dictionary for a key. A key as read from an
176 ini file is given as "section:key". If the key cannot be found,
177 the notfound value is returned.
179 A true boolean is found if one of the following is matched:
181 - A string starting with 'y'
182 - A string starting with 'Y'
183 - A string starting with 't'
184 - A string starting with 'T'
185 - A string starting with '1'
187 A false boolean is found if one of the following is matched:
189 - A string starting with 'n'
190 - A string starting with 'N'
191 - A string starting with 'f'
192 - A string starting with 'F'
193 - A string starting with '0'
195 The notfound value returned if no boolean is identified, does not
196 necessarily have to be 0 or 1.
197 */
198 /*--------------------------------------------------------------------------*/
199 int iniparser_getboolean(dictionary * d, char * key, int notfound);
202 /*-------------------------------------------------------------------------*/
203 /**
204 @brief Set an entry in a dictionary.
205 @param ini Dictionary to modify.
206 @param entry Entry to modify (entry name)
207 @param val New value to associate to the entry.
208 @return int 0 if Ok, -1 otherwise.
210 If the given entry can be found in the dictionary, it is modified to
211 contain the provided value. If it cannot be found, -1 is returned.
212 It is Ok to set val to NULL.
213 */
214 /*--------------------------------------------------------------------------*/
215 int iniparser_set(dictionary * ini, char * entry, char * val);
218 /*-------------------------------------------------------------------------*/
219 /**
220 @brief Delete an entry in a dictionary
221 @param ini Dictionary to modify
222 @param entry Entry to delete (entry name)
223 @return void
225 If the given entry can be found, it is deleted from the dictionary.
226 */
227 /*--------------------------------------------------------------------------*/
228 void iniparser_unset(dictionary * ini, char * entry);
230 /*-------------------------------------------------------------------------*/
231 /**
232 @brief Finds out if a given entry exists in a dictionary
233 @param ini Dictionary to search
234 @param entry Name of the entry to look for
235 @return integer 1 if entry exists, 0 otherwise
237 Finds out if a given entry exists in the dictionary. Since sections
238 are stored as keys with NULL associated values, this is the only way
239 of querying for the presence of sections in a dictionary.
240 */
241 /*--------------------------------------------------------------------------*/
242 int iniparser_find_entry(dictionary * ini, char * entry) ;
244 /*-------------------------------------------------------------------------*/
245 /**
246 @brief Parse an ini file and return an allocated dictionary object
247 @param ininame Name of the ini file to read.
248 @return Pointer to newly allocated dictionary
250 This is the parser for ini files. This function is called, providing
251 the name of the file to be read. It returns a dictionary object that
252 should not be accessed directly, but through accessor functions
253 instead.
255 The returned dictionary must be freed using iniparser_freedict().
256 */
257 /*--------------------------------------------------------------------------*/
258 dictionary * iniparser_load(char * ininame);
260 /*-------------------------------------------------------------------------*/
261 /**
262 @brief Free all memory associated to an ini dictionary
263 @param d Dictionary to free
264 @return void
266 Free all memory associated to an ini dictionary.
267 It is mandatory to call this function before the dictionary object
268 gets out of the current context.
269 */
270 /*--------------------------------------------------------------------------*/
271 void iniparser_freedict(dictionary * d);
273 #endif
