lib/librte_cfgfile/rte_cfgfile.h

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