xref: /dpdk/lib/cfgfile/rte_cfgfile.h (revision d5d13ef979c83d33518c70727b5a4ef091bd8134)
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4 
5 #ifndef __INCLUDE_RTE_CFGFILE_H__
6 #define __INCLUDE_RTE_CFGFILE_H__
7 
8 #include <stddef.h>
9 
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13 
14 /**
15  * @file
16  * Configuration File management.
17  *
18  * This library allows reading application defined parameters
19  * from standard format configuration file.
20  */
21 
22 #ifndef CFG_NAME_LEN
23 #define CFG_NAME_LEN 64
24 #endif
25 
26 #ifndef CFG_VALUE_LEN
27 #define CFG_VALUE_LEN 256
28 #endif
29 
30 /** Configuration file */
31 struct rte_cfgfile;
32 
33 /** Configuration file entry */
34 struct rte_cfgfile_entry {
35 	char name[CFG_NAME_LEN]; /**< Name */
36 	char value[CFG_VALUE_LEN]; /**< Value */
37 };
38 
39 /** Configuration file operation optional arguments */
40 struct rte_cfgfile_parameters {
41 	/** Config file comment character; one of '!', '#', '%', ';', '@' */
42 	char comment_character;
43 };
44 
45 /**@{ cfgfile load operation flags */
46 enum {
47 	/**
48 	 * Indicates that the file supports key value entries before the first
49 	 * defined section.  These entries can be accessed in the "GLOBAL"
50 	 * section.
51 	 */
52 	CFG_FLAG_GLOBAL_SECTION = 1,
53 
54 	/**
55 	 * Indicates that file supports key value entries where the value can
56 	 * be zero length (e.g., "key=").
57 	 */
58 	CFG_FLAG_EMPTY_VALUES = 2,
59 };
60 /**@} */
61 
62 /** Defines the default comment character used for parsing config files. */
63 #define CFG_DEFAULT_COMMENT_CHARACTER ';'
64 
65 /**
66  * Open config file.
67  *
68  * @param filename
69  *   Config file name.
70  * @param flags
71  *   Config file flags.
72  * @return
73  *   Handle to configuration file on success, NULL otherwise.
74  */
75 struct rte_cfgfile *rte_cfgfile_load(const char *filename, int flags);
76 
77 /**
78  * Open config file with specified optional parameters.
79  *
80  * @param filename
81  *   Config file name
82  * @param flags
83  *   Config file flags
84  * @param params
85  *   Additional configuration attributes.  Must be configured with desired
86  *   values prior to invoking this API.
87  * @return
88  *   Handle to configuration file on success, NULL otherwise
89  */
90 struct rte_cfgfile *rte_cfgfile_load_with_params(const char *filename,
91 	int flags, const struct rte_cfgfile_parameters *params);
92 
93 /**
94  * Create new cfgfile instance with empty sections and entries
95  *
96  * @param flags
97  *   - CFG_FLAG_GLOBAL_SECTION
98  *     Indicates that the file supports key value entries before the first
99  *     defined section.  These entries can be accessed in the "GLOBAL"
100  *     section.
101  *   - CFG_FLAG_EMPTY_VALUES
102  *     Indicates that file supports key value entries where the value can
103  *     be zero length (e.g., "key=").
104  * @return
105  *   Handle to cfgfile instance on success, NULL otherwise
106  */
107 struct rte_cfgfile *rte_cfgfile_create(int flags);
108 
109 /**
110  * Add section in cfgfile instance.
111  *
112  * @param cfg
113  *   Pointer to the cfgfile structure.
114  * @param sectionname
115  *   Section name which will be add to cfgfile.
116  * @return
117  *   0 on success, -ENOMEM if can't add section
118  */
119 int
120 rte_cfgfile_add_section(struct rte_cfgfile *cfg, const char *sectionname);
121 
122 /**
123  * Add entry to specified section in cfgfile instance.
124  *
125  * @param cfg
126  *   Pointer to the cfgfile structure.
127  * @param sectionname
128  *   Given section name to add an entry.
129  * @param entryname
130  *   Entry name to add.
131  * @param entryvalue
132  *   Entry value to add.
133  * @return
134  *   0 on success, -EEXIST if entry already exist, -EINVAL if bad argument
135  */
136 int rte_cfgfile_add_entry(struct rte_cfgfile *cfg,
137 		const char *sectionname, const char *entryname,
138 		const char *entryvalue);
139 
140 /**
141  * Update value of specified entry name in given section in config file
142  *
143  * @param cfg
144  *   Config file
145  * @param sectionname
146  *   Section name
147  * @param entryname
148  *   Entry name to look for the value change
149  * @param entryvalue
150  *   New entry value. Can be also an empty string if CFG_FLAG_EMPTY_VALUES = 1
151  * @return
152  *   0 on success, -EINVAL if bad argument
153  */
154 int rte_cfgfile_set_entry(struct rte_cfgfile *cfg, const char *sectionname,
155 		const char *entryname, const char *entryvalue);
156 
157 /**
158  * Save object cfgfile to file on disc
159  *
160  * @param cfg
161  *   Config file structure
162  * @param filename
163  *   File name to save data
164  * @return
165  *   0 on success, errno otherwise
166  */
167 int rte_cfgfile_save(struct rte_cfgfile *cfg, const char *filename);
168 
169 /**
170  * Get number of sections in config file.
171  *
172  * @param cfg
173  *   Config file.
174  * @param sec_name
175  *   Section name.
176  * @param length
177  *   Maximum section name length.
178  * @return
179  *   Number of sections.
180  */
181 int rte_cfgfile_num_sections(struct rte_cfgfile *cfg, const char *sec_name,
182 	size_t length);
183 
184 /**
185  * Get name of all config file sections.
186  *
187  * Fills in the array sections with the name of all the sections in the file
188  * (up to the number of max_sections sections).
189  *
190  * @param cfg
191  *   Config file.
192  * @param sections
193  *   Array containing section names after successful invocation.
194  *   Each element of this array should be preallocated by the user
195  *   with at least CFG_NAME_LEN characters.
196  * @param max_sections
197  *   Maximum number of section names to be stored in sections array.
198  * @return
199  *   Number of populated sections names.
200  */
201 int rte_cfgfile_sections(struct rte_cfgfile *cfg, char *sections[],
202 	int max_sections);
203 
204 /**
205  * Check if given section exists in config file.
206  *
207  * @param cfg
208  *   Config file.
209  * @param sectionname
210  *   Section name.
211  * @return
212  *   TRUE (value different than 0) if section exists, FALSE (value 0) otherwise.
213  */
214 int rte_cfgfile_has_section(struct rte_cfgfile *cfg, const char *sectionname);
215 
216 /**
217  * Get number of entries in given config file section.
218  *
219  * If multiple sections have the given name,
220  * this function operates on the first one.
221  *
222  * @param cfg
223  *   Config file.
224  * @param sectionname
225  *   Section name.
226  * @return
227  *   Number of entries in section on success, -1 otherwise.
228  */
229 int rte_cfgfile_section_num_entries(struct rte_cfgfile *cfg,
230 	const char *sectionname);
231 
232 /**
233  * Get number of entries in given config file section.
234  *
235  * The index of a section is the same as the index of its name
236  * in the result of rte_cfgfile_sections.
237  * This API can be used when there are multiple sections with the same name.
238  *
239  * @param cfg
240  *   Config file.
241  * @param sectionname
242  *   Section name.
243  * @param index
244  *   Section index.
245  * @return
246  *   Number of entries in section on success, -1 otherwise.
247  */
248 int rte_cfgfile_section_num_entries_by_index(struct rte_cfgfile *cfg,
249 	char *sectionname,
250 	int index);
251 
252 /**
253  * Get section entries as key-value pairs.
254  *
255  * If multiple sections have the given name,
256  * this function operates on the first one.
257  *
258  * @param cfg
259  *   Config file.
260  * @param sectionname
261  *   Section name.
262  * @param entries
263  *   Pre-allocated array of at least max_entries entries where the section
264  *   entries are stored as key-value pair after successful invocation.
265  * @param max_entries
266  *   Maximum number of section entries to be stored in entries array.
267  * @return
268  *   Number of entries populated on success, -1 otherwise.
269  */
270 int rte_cfgfile_section_entries(struct rte_cfgfile *cfg,
271 	const char *sectionname,
272 	struct rte_cfgfile_entry *entries,
273 	int max_entries);
274 
275 /**
276  * Get section entries as key-value pairs.
277  *
278  * The index of a section is the same as the index of its name
279  * in the result of rte_cfgfile_sections.
280  * This API can be used when there are multiple sections with the same name.
281  *
282  * @param cfg
283  *   Config file.
284  * @param index
285  *   Section index.
286  * @param sectionname
287  *   Pre-allocated string of at least CFG_NAME_LEN characters
288  *   where the section name is stored after successful invocation.
289  * @param entries
290  *   Pre-allocated array of at least max_entries entries where the section
291  *   entries are stored as key-value pair after successful invocation.
292  * @param max_entries
293  *   Maximum number of section entries to be stored in entries array.
294  * @return
295  *   Number of entries populated on success, -1 otherwise.
296  */
297 int rte_cfgfile_section_entries_by_index(struct rte_cfgfile *cfg,
298 	int index,
299 	char *sectionname,
300 	struct rte_cfgfile_entry *entries,
301 	int max_entries);
302 
303 /**
304  * Get value of the named entry in named config file section.
305  *
306  * If multiple sections have the given name,
307  * this function operates on the first one.
308  *
309  * @param cfg
310  *   Config file.
311  * @param sectionname
312  *   Section name.
313  * @param entryname
314  *   Entry name.
315  * @return
316  *   Entry value on success, NULL otherwise.
317  */
318 const char *rte_cfgfile_get_entry(struct rte_cfgfile *cfg,
319 	const char *sectionname,
320 	const char *entryname);
321 
322 /**
323  * Check if given entry exists in named config file section.
324  *
325  * If multiple sections have the given name,
326  * this function operates on the first one.
327  *
328  * @param cfg
329  *   Config file.
330  * @param sectionname
331  *   Section name.
332  * @param entryname
333  *   Entry name.
334  * @return
335  *   TRUE (value different than 0) if entry exists, FALSE (value 0) otherwise.
336  */
337 int rte_cfgfile_has_entry(struct rte_cfgfile *cfg, const char *sectionname,
338 	const char *entryname);
339 
340 /**
341  * Close config file.
342  *
343  * @param cfg
344  *   Config file.
345  * @return
346  *   0 on success, -1 otherwise.
347  */
348 int rte_cfgfile_close(struct rte_cfgfile *cfg);
349 
350 #ifdef __cplusplus
351 }
352 #endif
353 
354 #endif
355