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