1/*-
2 *   BSD LICENSE
3 *
4 *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5 *   All rights reserved.
6 *
7 *   Redistribution and use in source and binary forms, with or without
8 *   modification, are permitted provided that the following conditions
9 *   are met:
10 *
11 *     * Redistributions of source code must retain the above copyright
12 *       notice, this list of conditions and the following disclaimer.
13 *     * Redistributions in binary form must reproduce the above copyright
14 *       notice, this list of conditions and the following disclaimer in
15 *       the documentation and/or other materials provided with the
16 *       distribution.
17 *     * Neither the name of Intel Corporation nor the names of its
18 *       contributors may be used to endorse or promote products derived
19 *       from this software without specific prior written permission.
20 *
21 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 */
33
34#ifndef __INCLUDE_RTE_CFGFILE_H__
35#define __INCLUDE_RTE_CFGFILE_H__
36
37#include <stddef.h>
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/**
44* @file
45* RTE Configuration File
46*
47* This library allows reading application defined parameters from standard
48* format configuration file.
49*
50***/
51
52#ifndef CFG_NAME_LEN
53#define CFG_NAME_LEN 64
54#endif
55
56#ifndef CFG_VALUE_LEN
57#define CFG_VALUE_LEN 256
58#endif
59
60/** Configuration file */
61struct rte_cfgfile;
62
63/** Configuration file entry */
64struct rte_cfgfile_entry {
65	char name[CFG_NAME_LEN]; /**< Name */
66	char value[CFG_VALUE_LEN]; /**< Value */
67};
68
69/**
70* Open config file
71*
72* @param filename
73*   Config file name
74* @param flags
75*   Config file flags, Reserved for future use. Must be set to 0.
76* @return
77*   Handle to configuration file on success, NULL otherwise
78*/
79struct rte_cfgfile *rte_cfgfile_load(const char *filename, int flags);
80
81/**
82* Get number of sections in config file
83*
84* @param cfg
85*   Config file
86* @param sec_name
87*   Section name
88* @param length
89*   Maximum section name length
90* @return
91*   Number of sections
92*/
93int rte_cfgfile_num_sections(struct rte_cfgfile *cfg, const char *sec_name,
94	size_t length);
95
96/**
97* Get name of all config file sections.
98*
99* Fills in the array sections with the name of all the sections in the file
100* (up to the number of max_sections sections).
101*
102* @param cfg
103*   Config file
104* @param sections
105*   Array containing section names after successful invocation. Each element
106*   of this array should be preallocated by the user with at least
107*   CFG_NAME_LEN characters.
108* @param max_sections
109*   Maximum number of section names to be stored in sections array
110* @return
111*   Number of populated sections names
112*/
113int rte_cfgfile_sections(struct rte_cfgfile *cfg, char *sections[],
114	int max_sections);
115
116/**
117* Check if given section exists in config file
118*
119* @param cfg
120*   Config file
121* @param sectionname
122*   Section name
123* @return
124*   TRUE (value different than 0) if section exists, FALSE (value 0) otherwise
125*/
126int rte_cfgfile_has_section(struct rte_cfgfile *cfg, const char *sectionname);
127
128/**
129* Get number of entries in given config file section
130*
131* If multiple sections have the given name this function operates on the
132* first one.
133*
134* @param cfg
135*   Config file
136* @param sectionname
137*   Section name
138* @return
139*   Number of entries in section on success, -1 otherwise
140*/
141int rte_cfgfile_section_num_entries(struct rte_cfgfile *cfg,
142	const char *sectionname);
143
144/**
145* Get section entries as key-value pairs
146*
147* If multiple sections have the given name this function operates on the
148* first one.
149*
150* @param cfg
151*   Config file
152* @param sectionname
153*   Section name
154* @param entries
155*   Pre-allocated array of at least max_entries entries where the section
156*   entries are stored as key-value pair after successful invocation
157* @param max_entries
158*   Maximum number of section entries to be stored in entries array
159* @return
160*   Number of entries populated on success, -1 otherwise
161*/
162int rte_cfgfile_section_entries(struct rte_cfgfile *cfg,
163	const char *sectionname,
164	struct rte_cfgfile_entry *entries,
165	int max_entries);
166
167/**
168* Get section entries as key-value pairs
169*
170* The index of a section is the same as the index of its name in the
171* result of rte_cfgfile_sections. This API can be used when there are
172* multiple sections with the same name.
173*
174* @param cfg
175*   Config file
176* @param index
177*   Section index
178* @param sectionname
179*   Pre-allocated string of at least CFG_NAME_LEN characters where the
180*   section name is stored after successful invocation.
181* @param entries
182*   Pre-allocated array of at least max_entries entries where the section
183*   entries are stored as key-value pair after successful invocation
184* @param max_entries
185*   Maximum number of section entries to be stored in entries array
186* @return
187*   Number of entries populated on success, -1 otherwise
188*/
189int rte_cfgfile_section_entries_by_index(struct rte_cfgfile *cfg,
190	int index,
191	char *sectionname,
192	struct rte_cfgfile_entry *entries,
193	int max_entries);
194
195/**
196* Get value of the named entry in named config file section
197*
198* If multiple sections have the given name this function operates on the
199* first one.
200*
201* @param cfg
202*   Config file
203* @param sectionname
204*   Section name
205* @param entryname
206*   Entry name
207* @return
208*   Entry value on success, NULL otherwise
209*/
210const char *rte_cfgfile_get_entry(struct rte_cfgfile *cfg,
211	const char *sectionname,
212	const char *entryname);
213
214/**
215* Check if given entry exists in named config file section
216*
217* If multiple sections have the given name this function operates on the
218* first one.
219*
220* @param cfg
221*   Config file
222* @param sectionname
223*   Section name
224* @param entryname
225*   Entry name
226* @return
227*   TRUE (value different than 0) if entry exists, FALSE (value 0) otherwise
228*/
229int rte_cfgfile_has_entry(struct rte_cfgfile *cfg, const char *sectionname,
230	const char *entryname);
231
232/**
233* Close config file
234*
235* @param cfg
236*   Config file
237* @return
238*   0 on success, -1 otherwise
239*/
240int rte_cfgfile_close(struct rte_cfgfile *cfg);
241
242#ifdef __cplusplus
243}
244#endif
245
246#endif
247