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 * Get number of sections in config file
 125 *
 126 * @param cfg
 127 *   Config file
 128 * @param sec_name
 129 *   Section name
 130 * @param length
 131 *   Maximum section name length
 132 * @return
 133 *   Number of sections
 134 */
 135 int rte_cfgfile_num_sections(struct rte_cfgfile *cfg, const char *sec_name,
 136         size_t length);
 137
 138 /**
 139 * Get name of all config file sections.
 140 *
 141 * Fills in the array sections with the name of all the sections in the file
 142 * (up to the number of max_sections sections).
 143 *
 144 * @param cfg
 145 *   Config file
 146 * @param sections
 147 *   Array containing section names after successful invocation. Each element
 148 *   of this array should be preallocated by the user with at least
 149 *   CFG_NAME_LEN characters.
 150 * @param max_sections
 151 *   Maximum number of section names to be stored in sections array
 152 * @return
 153 *   Number of populated sections names
 154 */
 155 int rte_cfgfile_sections(struct rte_cfgfile *cfg, char *sections[],
 156         int max_sections);
 157
 158 /**
 159 * Check if given section exists in config file
 160 *
 161 * @param cfg
 162 *   Config file
 163 * @param sectionname
 164 *   Section name
 165 * @return
 166 *   TRUE (value different than 0) if section exists, FALSE (value 0) otherwise
 167 */
 168 int rte_cfgfile_has_section(struct rte_cfgfile *cfg, const char *sectionname);
 169
 170 /**
 171 * Get number of entries in given config file section
 172 *
 173 * If multiple sections have the given name this function operates on the
 174 * first one.
 175 *
 176 * @param cfg
 177 *   Config file
 178 * @param sectionname
 179 *   Section name
 180 * @return
 181 *   Number of entries in section on success, -1 otherwise
 182 */
 183 int rte_cfgfile_section_num_entries(struct rte_cfgfile *cfg,
 184         const char *sectionname);
 185
 186 /**
 187 * Get section entries as key-value pairs
 188 *
 189 * If multiple sections have the given name this function operates on the
 190 * first one.
 191 *
 192 * @param cfg
 193 *   Config file
 194 * @param sectionname
 195 *   Section name
 196 * @param entries
 197 *   Pre-allocated array of at least max_entries entries where the section
 198 *   entries are stored as key-value pair after successful invocation
 199 * @param max_entries
 200 *   Maximum number of section entries to be stored in entries array
 201 * @return
 202 *   Number of entries populated on success, -1 otherwise
 203 */
 204 int rte_cfgfile_section_entries(struct rte_cfgfile *cfg,
 205         const char *sectionname,
 206         struct rte_cfgfile_entry *entries,
 207         int max_entries);
 208
 209 /**
 210 * Get section entries as key-value pairs
 211 *
 212 * The index of a section is the same as the index of its name in the
 213 * result of rte_cfgfile_sections. This API can be used when there are
 214 * multiple sections with the same name.
 215 *
 216 * @param cfg
 217 *   Config file
 218 * @param index
 219 *   Section index
 220 * @param sectionname
 221 *   Pre-allocated string of at least CFG_NAME_LEN characters where the
 222 *   section name is stored after successful invocation.
 223 * @param entries
 224 *   Pre-allocated array of at least max_entries entries where the section
 225 *   entries are stored as key-value pair after successful invocation
 226 * @param max_entries
 227 *   Maximum number of section entries to be stored in entries array
 228 * @return
 229 *   Number of entries populated on success, -1 otherwise
 230 */
 231 int rte_cfgfile_section_entries_by_index(struct rte_cfgfile *cfg,
 232         int index,
 233         char *sectionname,
 234         struct rte_cfgfile_entry *entries,
 235         int max_entries);
 236
 237 /**
 238 * Get value of the named entry in named config file section
 239 *
 240 * If multiple sections have the given name this function operates on the
 241 * first one.
 242 *
 243 * @param cfg
 244 *   Config file
 245 * @param sectionname
 246 *   Section name
 247 * @param entryname
 248 *   Entry name
 249 * @return
 250 *   Entry value on success, NULL otherwise
 251 */
 252 const char *rte_cfgfile_get_entry(struct rte_cfgfile *cfg,
 253         const char *sectionname,
 254         const char *entryname);
 255
 256 /**
 257 * Check if given entry exists in named config file section
 258 *
 259 * If multiple sections have the given name this function operates on the
 260 * first one.
 261 *
 262 * @param cfg
 263 *   Config file
 264 * @param sectionname
 265 *   Section name
 266 * @param entryname
 267 *   Entry name
 268 * @return
 269 *   TRUE (value different than 0) if entry exists, FALSE (value 0) otherwise
 270 */
 271 int rte_cfgfile_has_entry(struct rte_cfgfile *cfg, const char *sectionname,
 272         const char *entryname);
 273
 274 /**
 275 * Close config file
 276 *
 277 * @param cfg
 278 *   Config file
 279 * @return
 280 *   0 on success, -1 otherwise
 281 */
 282 int rte_cfgfile_close(struct rte_cfgfile *cfg);
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif