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