1 /* 2 INI LIBRARY 3 4 Header file for the ini configuration interface. 5 THIS IS THE PREFERRED INTERFACE TO USE. 6 7 Copyright (C) Dmitri Pal <dpal@redhat.com> 2010 - 2012 8 9 INI Library is free software: you can redistribute it and/or modify 10 it under the terms of the GNU Lesser General Public License as published by 11 the Free Software Foundation, either version 3 of the License, or 12 (at your option) any later version. 13 14 INI Library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public License 20 along with INI Library. If not, see <http://www.gnu.org/licenses/>. 21 */ 22 23 24 #ifndef INI_CONFIGOBJ_H 25 #define INI_CONFIGOBJ_H 26 27 #include <sys/types.h> 28 #include <sys/stat.h> 29 #include <unistd.h> 30 #include <limits.h> 31 #include <stdio.h> 32 #include "simplebuffer.h" 33 #include "ini_valueobj.h" 34 35 #ifndef DING_ATTR_FORMAT 36 # if ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 3))) 37 # define DING_ATTR_FORMAT(fmt, args) __attribute__((__format__(__printf__, fmt, args))) 38 # else 39 # define DING_ATTR_FORMAT(fmt, args) 40 # endif 41 #endif 42 43 /** @mainpage The INI configuration interface 44 * 45 * The goal of the this interface is to allow applications 46 * to read configuration from an INI file. 47 * 48 * So why yet another library to read data from an INI file? 49 * As we started the SSSD project we looked around for a 50 * open source library that would meet the following 51 * requirements: 52 * - Is written in C (not C++) 53 * - Is lightweight. 54 * - Has an live community. 55 * - Supported on multiple platforms . 56 * - Can evolve as we build SSSD solution. 57 * - Can deal with different types of values including arrays. 58 * - Can deal with sections that are related to each other 59 * and can form a hierarchy of sections. 60 * - Has a compatible license we can use. 61 * 62 * We have seen several solutions but none was able to fully address 63 * our requirements. As a result we started developing our own 64 * INI parsing library. 65 * 66 * Currently INI parser allows reading and merging INI files 67 * and getting a resulting configuration in one object. 68 * 69 * One of the main advantages of this interface is that 70 * the library is created with the idea of reading the configuration 71 * data, not managing it. Thus currently you will not find 72 * any function that alters the configuration data read from the files. 73 * There is a set of proposed enhancements to be able to manipulate 74 * the configuration data and save it back but there has been no real 75 * driver for it. This API is focused on letting applications read data 76 * from a file (or files) and interpret it, not to generate configuration 77 * files. There are all sorts of different tools that already do that. 78 * 79 * The INI configuration interface uses COLLECTION (see libcollection 80 * interface) to store data internally. 81 * 82 * Concepts: 83 * - INI file consists of the key value pairs. 84 * - Keys and values are separated by the equal sign. 85 * Spaces around equal sign are trimmed. Everything before the equal 86 * sign is the key, everything after is the value. 87 * - Comments are the lines that start with ";" or "#" in the first 88 * position of the line. 89 * - Library now supports multi-line values. Values that span across multiple 90 * lines should start with a single space on every new line. 91 * - After being read both keys and values are stored in the internal 92 * objects. 93 * - Application configuration can consist from multiple files. 94 * For example, there can be a generic file in /etc containing 95 * configuration for all applications of a particular class running 96 * on a box and then there might be a special file 97 * with parameters specific for each application in the 98 * /etc/whatever.d directory. Interface does not allow reading 99 * multiple files in one call. Instead files need to be read separately 100 * and then merged together. A helper function to do so might be added 101 * later. 102 * - If there is no section in the file or there are key value pairs 103 * declared before the first section, those pairs will be placed into 104 * the default section with the name "default". 105 * - All values are treated as strings. Spaces are trimmed at the beginning 106 * and the end of the value. The value ends at the end of the line. 107 * If values is too long, an error will be returned. 108 * - Parsing of a value happens when a caller tries to interpret 109 * the value. The caller can use different functions to do this. 110 * The value can be treated as numeric, logical, string, binary, 111 * array of strings or array of numbers. In case of arrays parsing functions 112 * accept separators that will be used to slice the value into the array 113 * of elements. 114 * - If there is any error parsing section and key values it can be 115 * intercepted by the caller. There are different modes that the library 116 * supports regarding error handling. See details in the description 117 * of individual functions. 118 * - The library allows ini files with fragmented sections. This means that 119 * a section can be scattered across the file. Flags control what to 120 * do in such situation. 121 * - The library allows storing and retrieving multiple key value pairs with 122 * the same key in one section. 123 * 124 * <i>There is a deprecated interface that can be found in ini_config.h. 125 * This interface is supported only for backwards compatibility and should 126 * not be used.</i> 127 */ 128 129 /** 130 * @defgroup structures Structures 131 * 132 * All structures used in the interface should be treated as internal opaque objects. 133 * 134 * @{ 135 * 136 * @} 137 */ 138 139 140 /** 141 * @defgroup bomType Types of configutration file encodings 142 * 143 * Constants that define how configuration file is encoded. 144 * 145 * @{ 146 */ 147 /** Enumeration of the encoding types. */ 148 149 enum index_utf_t { 150 INDEX_UTF32BE = 0, /**< The file is encoded in 'big-endian' 32-bit */ 151 INDEX_UTF32LE = 1, /**< The file is encoded in 'little-endian' 32-bit */ 152 INDEX_UTF16BE = 2, /**< The file is encoded in 'big-endian' 16-bit */ 153 INDEX_UTF16LE = 3, /**< The file is encoded in 'little-endian' 16-bit */ 154 INDEX_UTF8 = 4, /**< The file is encoded in standard UTF8 but has BOM */ 155 INDEX_UTF8NOBOM = 5 /**< The file is encoded in standard UTF8 without BOM */ 156 }; 157 158 /** 159 * @} 160 */ 161 162 163 /** 164 * @defgroup errorlevel Error tolerance constants 165 * 166 * Constants in this section define what to do if 167 * error or warning encountered while parsing the INI file. 168 * 169 * @{ 170 */ 171 /** Enumeration of error levels. */ 172 enum ERR_LEVEL { 173 INI_STOP_ON_ANY = 0, /**< Fail if any problem is detected. */ 174 INI_STOP_ON_NONE = 1, /**< Best effort - do not fail. */ 175 INI_STOP_ON_ERROR = 2 /**< Fail on errors only. */ 176 }; 177 178 /** 179 * @} 180 */ 181 182 /** 183 * @defgroup parseerr Parsing errors and warnings 184 * 185 * Parsing errors and warnings 186 * 187 * @{ 188 */ 189 /** Enumeration of parsing errors. */ 190 enum ERR_PARSE { 191 ERR_LONGDATA = 1, /**< Line is too long (Error). */ 192 ERR_NOCLOSESEC, /**< No closing bracket in section 193 definition (Error). */ 194 ERR_NOSECTION, /**< Section name is missing (Error). */ 195 ERR_SECTIONLONG, /**< Section name too long (Error). */ 196 ERR_NOEQUAL, /**< No equal sign (Error). */ 197 ERR_NOKEY, /**< No key before equal sign (Error). */ 198 ERR_LONGKEY, /**< Key is too long (Error). */ 199 ERR_READ, /**< Failed to read line (Error). */ 200 ERR_SPACE, /**< Line starts with space when it 201 should not (Error). */ 202 ERR_DUPKEY, /**< Duplicate key is not allowed (Error). */ 203 ERR_DUPKEYSEC, /**< Duplicate key is detected while merging 204 sections (Error). */ 205 ERR_DUPSECTION, /**< Duplicate section is not allowed (Error). */ 206 ERR_SPECIAL, /**< Line contains invalid characters (Error). */ 207 ERR_TAB, /**< Line starts with tab when it 208 should not (Error). */ 209 ERR_BADCOMMENT, /**< End of file while processing comment (Error). */ 210 ERR_MAXPARSE = ERR_BADCOMMENT /**< Special value. Size of the error array. */ 211 }; 212 213 /** 214 * @} 215 */ 216 217 /** 218 * @defgroup metacollect Constants that define what meta data to collect 219 * 220 * Constants in this section define what meta data to collect 221 * 222 * 223 * @{ 224 */ 225 /** @brief Do not collect any data. */ 226 #define INI_META_NONE 0 227 /** @brief Collect file stats. */ 228 #define INI_META_STATS 1 229 230 /** 231 * @} 232 */ 233 234 /** 235 * @defgroup accesscheck Access control check flags 236 * 237 * @{ 238 */ 239 240 /** 241 * @brief Validate access mode 242 * 243 * If this flag is specified the mode parameter 244 * will be matched against the permissions set on the file 245 * using the provided mask. 246 */ 247 #define INI_ACCESS_CHECK_MODE 0x00000001 248 249 /** 250 * @brief Validate uid 251 * 252 * Provided uid will be checked against uid 253 * of the file. 254 */ 255 #define INI_ACCESS_CHECK_UID 0x00000002 256 257 /** 258 * @brief Validate gid 259 * 260 * Provided gid will be checked against gid 261 * of the file. 262 */ 263 #define INI_ACCESS_CHECK_GID 0x00000004 264 265 /** 266 * @} 267 */ 268 269 /** 270 * @defgroup collisionflags Flags that define collision resolution logic. 271 * 272 * @{ 273 */ 274 275 /** 276 * @defgroup onesecvalue Colliding values come from one section 277 * 278 * Flags that define collision resolution logic for values in 279 * the same section. 280 * These flags should be used during parsing to handle duplicate 281 * keys in the same section of the ini file. 282 * 283 * @{ 284 */ 285 286 /** @brief Value with same key is overwritten */ 287 #define INI_MV1S_OVERWRITE 0x0000 288 /** @brief Collision causes error */ 289 #define INI_MV1S_ERROR 0x0001 290 /** @brief Second value is discarded */ 291 #define INI_MV1S_PRESERVE 0x0002 292 /** @brief Duplicates are allowed */ 293 #define INI_MV1S_ALLOW 0x0003 294 /** @brief Duplicates are allowed but errors are logged */ 295 #define INI_MV1S_DETECT 0x0004 296 297 /** 298 * @} 299 */ 300 301 /** 302 * @defgroup twosecvalue Colliding values come from two sections 303 * 304 * Flags that define collision resolution logic between two values 305 * that come from two sections with the same name. 306 * These flags should be used during parsing to handle duplicate 307 * keys coming from the same section scattered across the ini file. 308 * These flags also can be used to specify the rules of merging 309 * values that come from two different configuration files. 310 * 311 * @{ 312 */ 313 /** @brief Value with same key is overwritten */ 314 #define INI_MV2S_OVERWRITE 0x0000 315 /** @brief Collision causes error */ 316 #define INI_MV2S_ERROR 0x0010 317 /** @brief Second value is discarded */ 318 #define INI_MV2S_PRESERVE 0x0020 319 /** @brief Duplicates are allowed */ 320 #define INI_MV2S_ALLOW 0x0030 321 /** @brief Duplicates are allowed but errors are logged */ 322 #define INI_MV2S_DETECT 0x0040 323 324 /** 325 * @} 326 */ 327 328 /** 329 * @defgroup mergesec Collision in two sections 330 * 331 * Flags that define collision resolution logic between two sections. 332 * These flags should be used during parsing to handle duplicate 333 * sections scattered across the ini file. 334 * These flags also can be used to specify the rules of merging 335 * sections that come from two different configuration files. 336 * 337 * @{ 338 */ 339 /** @brief Sections are merged */ 340 #define INI_MS_MERGE 0x0000 341 /** @brief Collision causes error */ 342 #define INI_MS_ERROR 0x0100 343 /** @brief First section is discarded */ 344 #define INI_MS_OVERWRITE 0x0200 345 /** @brief Second section is discarded */ 346 #define INI_MS_PRESERVE 0x0300 347 /** @brief Log errors if duplicate sections are detected; non-exclusive */ 348 /** This defaults to MERGE, but can be used with OVERWRITE and PRESERVE **/ 349 #define INI_MS_DETECT 0x0400 350 351 /** 352 * @} 353 */ 354 355 /** 356 * @} 357 */ 358 359 /** 360 * @defgroup parseflags Flags that define parsing rules 361 * 362 * Flags that define how the file should be parsed. 363 * 364 * @{ 365 */ 366 367 /** @brief Suppress multi line value wrapping */ 368 #define INI_PARSE_NOWRAP 0x0001 369 /** @brief No spaces are allowed to the left of the key */ 370 #define INI_PARSE_NOSPACE 0x0002 371 /** @brief No tabs are allowed to the left of the key */ 372 #define INI_PARSE_NOTAB 0x0004 373 /** @brief Do not allow C-style comments */ 374 #define INI_PARSE_NO_C_COMMENTS 0x0008 375 /** @brief Skip lines that are not KVPs */ 376 #define INI_PARSE_IGNORE_NON_KVP 0x0010 377 378 /** 379 * @} 380 */ 381 382 /** 383 * @defgroup searchmode Constants that define how to look for a value 384 * 385 * Configuration file can allow several keys with the same name 386 * in one section. Use the constants below to define which 387 * value you are looking for. 388 * You can search for the next value only if you are looking 389 * for the same section and key as in the previous search. If you 390 * specify INI_GET_NEXT_VALUE but the section or key is 391 * different from the values that were used in the previous search 392 * the value will be ignored and the function will act as if 393 * INI_GET_FIRST_VALUE is specified. 394 * This functionality allows creating an attribute list and 395 * actually fetching every value including duplicate values 396 * in a single loop. 397 * 398 * @{ 399 */ 400 /** Enumeration of parsing errors. */ 401 enum INI_GET { 402 INI_GET_FIRST_VALUE, /**< Get the first value (default). */ 403 INI_GET_NEXT_VALUE, /**< Look for the next value in the section */ 404 INI_GET_LAST_VALUE /**< Look for the last value in the section */ 405 }; 406 407 /** 408 * @} 409 */ 410 411 412 /** 413 * @defgroup augment Constants and structures related to augmentation. 414 * 415 * @{ 416 */ 417 418 /** Structure to pass access check parameters to augmentation function. 419 * 420 */ 421 struct access_check { 422 uint32_t flags; /**< Define what to check. 423 * One can check file 424 * permissions with mask, 425 * uid, and gid of the file. 426 * See \ref accesscheck constants. 427 */ 428 uid_t uid; /**< Expected uid of the file. */ 429 gid_t gid; /**< Expected gid of the file.*/ 430 mode_t mode; /**< Expected mode of the file. */ 431 mode_t mask; /**< Mask to use in the mode check. 432 * Mask is always adjusted to 433 * include at least S_IRWXU, 434 * S_IRWXG and S_IRWXO. 435 */ 436 }; 437 438 /** Enumeration of augmentation modes. */ 439 enum augmode { 440 INI_AUG_ANY = 0, /**< Allow any augmentation. */ 441 INI_AUG_ADD = 1, /**< Allow only new sections. */ 442 INI_AUG_OVER = 2 /**< Allow section updates. */ 443 }; 444 445 /** 446 * @} 447 */ 448 449 /** 450 * @brief Name of the default section. 451 * 452 * This is the name of the implied section where orphan key-value 453 * pairs will be put. 454 */ 455 #define INI_DEFAULT_SECTION "default" 456 457 /** 458 * @defgroup structures Structures 459 * @{ 460 */ 461 462 463 struct ini_cfgobj; 464 struct ini_cfgfile; 465 466 /** @brief Structure that holds error number and 467 * line number for the encountered error. 468 */ 469 struct ini_parse_error; 470 471 472 /** 473 * @} 474 */ 475 476 477 /** 478 * @defgroup ini_core Core interface functions 479 * 480 * Functions in this section allow manipulation with the configuration file, 481 * parsing data from the configuration file and storing it in a configuration 482 * object, merging configuration objects and other operations. 483 * 484 * For functions to create or alter configuration object in memory 485 * see \ref ini_mod. 486 * 487 * @{ 488 * 489 */ 490 491 /** 492 * @brief Create a configuration object. 493 * 494 * Allocates an object that will store configuration data. 495 * Configuration object is populated by parsing a file. 496 * 497 * @param[out] ini_config Configuration object. 498 * 499 * @return 0 - Success. 500 * @return EINVAL - Invalid parameter. 501 * @return ENOMEM - No memory. 502 */ 503 int ini_config_create(struct ini_cfgobj **ini_config); 504 505 /** 506 * @brief Destroy a configuration object. 507 * 508 * Frees configuration data. 509 * 510 * @param[in] ini_config Configuration object. 511 * 512 */ 513 void ini_config_destroy(struct ini_cfgobj *ini_config); 514 515 /** 516 * @brief Flush cached search data. 517 * 518 * Frees cached search data. This will cause 519 * any iteration over the same keys to start over. 520 * 521 * @param[in] ini_config Configuration object. 522 * 523 */ 524 void ini_config_clean_state(struct ini_cfgobj *ini_config); 525 526 /** 527 * @brief Create a configuration file object. 528 * 529 * Create a file object for parsing a configuration file. 530 * 531 * A "configuration file object" is different from 532 * a "configuration object". The former stores metadata 533 * about a file the configuration data is read from, 534 * while the latter holds the configuration itself. 535 * 536 * @param[in] filename Name or path to the ini file. 537 * This argument can contain 538 * a short or a fully qualified 539 * file name. If a short name is 540 * specified the full path 541 * will be resolved internally. 542 * @param[in] metadata_flags Flags that specify what additional 543 * data if any needs to be collected 544 * about the ini file. 545 * @param[out] file_ctx Configuration file object. 546 * 547 * @return 0 - Success. 548 * @return EINVAL - Invalid parameter. 549 * @return ENOMEM - No memory. 550 */ 551 int ini_config_file_open(const char *filename, 552 uint32_t metadata_flags, 553 struct ini_cfgfile **file_ctx); 554 555 /** 556 * @brief Create a configuration file object using memory buffer. 557 * 558 * Create a file object for parsing a configuration file. 559 * Configuration will use provided memory instead of the actual file. 560 * 561 * A "configuration file object" is different from 562 * a "configuration object". The former stores metadata 563 * about a file the configuration data is read from, 564 * while the latter holds the configuration itself. 565 * 566 * @param[in] data_buf In memory configuration data. 567 * Needs to be NULL terminated. 568 * @param[in] data_len Length of memory data 569 * not including terminating NULL. 570 * @param[out] file_ctx Configuration file object. 571 * 572 * @return 0 - Success. 573 * @return EINVAL - Invalid parameter. 574 * @return ENOMEM - No memory. 575 */ 576 int ini_config_file_from_mem(void *data_buf, 577 uint32_t data_len, 578 struct ini_cfgfile **file_ctx); 579 580 /** 581 * @brief Close configuration file after parsing 582 * 583 * Closes file but keeps the context. File can be reopened 584 * and reread using \ref ini_config_file_reopen function. 585 * 586 * @param[in] file_ctx Configuration file object. 587 * 588 */ 589 void ini_config_file_close(struct ini_cfgfile *file_ctx); 590 591 592 /** 593 * @brief Reopen the configuration file 594 * 595 * Creates a new file object from the original one. 596 * The file configuration objects then can be compared 597 * to determine whether the file actually changed. 598 * 599 * @param[in] file_ctx_in Original configuration file object. 600 * @param[out] file_ctx_out A new configuration file object. 601 * 602 * @return 0 - Success. 603 * @return EINVAL - Invalid parameter. 604 * @return ENOMEM - No memory. 605 */ 606 int ini_config_file_reopen(struct ini_cfgfile *file_ctx_in, 607 struct ini_cfgfile **file_ctx_out); 608 609 610 /** 611 * @brief Close configuration file and free all data 612 * 613 * Closes file and frees the context. 614 * 615 * @param[in] file_ctx Configuration file object. 616 * 617 */ 618 void ini_config_file_destroy(struct ini_cfgfile *file_ctx); 619 620 /** 621 * @brief Save configuration in a backup configuration file 622 * 623 * Creates a backup version of the data in a given configuration file. 624 * It is expected that file context was created by some open or reopen 625 * function first. Then the caller can make this call to save the data 626 * aside before parsing the configuration file and making changes to it. 627 * 628 * The caller can specify a backup directory to save the file in. 629 * If directory is not specified then a current working directory will 630 * be used. If the directory is invalid or caller does not have access to it 631 * an error will be returned. 632 * 633 *>The template specifies the file name to use for the backup. 634 *>For example: 635 *> my_file.conf.%d.save 636 *> my_file%d.conf.bak 637 *>The template can contain only one '%d' placeholder. This placeholder 638 * will be replaced by a number. If previously created backup files 639 * are found in the given directory. The function will start with 1 and will 640 * try to find an available unused file name in the given directory 641 * up until it reaches the limit specified in the max_num argument. 642 * Function will return EEXIST if it runs out of attempts to save the file. 643 * 644 * The caller can optionally pass an access structure. The access structure 645 * would specify what mode and ownership to use for the newly created file. 646 * If the access structure is not specified the access data of the original 647 * file context will be used. If file object does not have stats explicitly 648 * read at the time when the object is created then the stats will be collected 649 * but not saved. If the file was a memory mapped file and no access 650 * structure is passed in, the function will use effective UID and GID of the 651 * running process and mode will be set to: S_IFREG | S_IRUSR | S_IWUSR 652 * 653 * @param[in] file_ctx File context of the file to backup. 654 * @param[in] backup_dir Path to backup directory. Can be NULL. 655 * @param[in] backup_tpl File name template with %d placeholder. 656 * @param[in] backup_access Optional access overwrite structure. 657 * See \ref access_check for more details. 658 * @param[in] max_num Maximum number of retries to try to create 659 * a specific backup file. 660 * 661 * @return 0 - Success. 662 * @return EINVAL - Invalid parameter. 663 * @return EIXIST - All possible backup file names are already taken. 664 * @return ENOMEM - No memory. 665 * 666 * Function can return other errors that standard libc functions line open, 667 * chmod, and chown return. 668 */ 669 int ini_config_file_backup(struct ini_cfgfile *file_ctx, 670 const char *backup_dir, 671 const char *backup_tpl, 672 struct access_check *backup_access, 673 unsigned max_num); 674 675 /** 676 * @brief Change permissions and ownership of the file 677 * 678 * Function changes access mode and permissions of the file associated 679 * with the given context. If there is no file associated with the context 680 * because the context is created using a memory buffer, then the function 681 * will return an error EINVAL. 682 * 683 * @param[in] file_ctx File context of the file to change access. 684 * @param[in] new_access Structure that defines what access should 685 * be set on the file. 686 * See \ref access_check for more details. 687 * 688 * @return 0 - Success. 689 * @return EINVAL - Invalid parameter. 690 * 691 * Function can return other errors that standard chmod and chown 692 * functions return. 693 */ 694 int ini_config_change_access(struct ini_cfgfile *file_ctx, 695 struct access_check *new_access); 696 697 /** 698 * @brief Save configuration in a file 699 * 700 * Function is a wrapper around \ref ini_config_save_as with 701 * argument filename as NULL. 702 * 703 * For more information see \ref ini_config_save_as. 704 */ 705 int ini_config_save(struct ini_cfgfile *file_ctx, 706 struct access_check *new_access, 707 struct ini_cfgobj *ini_config); 708 709 710 /* Save configuration in a file using existing context but with a new name */ 711 /** 712 * @brief Save configuration with a new name. 713 * 714 * Function uses an existing file context but a new file name. 715 * The file context will be used to perform operation to save file. 716 * By default the ownership, mode and BOM of the new file will be derived 717 * from the existing context. The rest of the context will be reinitialized. 718 * Configuration will be serialized and saved in the file using encoding 719 * specified by BOM type. The BOM prefix will also be added if needed. 720 * After saving the file the function initializes the context and reads the 721 * file back. At this moment the file context is ready for the parsing 722 * again. 723 * 724 * @param[in] file_ctx File context to use for saving. 725 * @param[in] filename Name of the file to save into. If NULL 726 * the file name of the context will be used. 727 * If the context was originally created 728 * as a memory mapped configuration buffer 729 * and filename is NULL the function will 730 * return error EINVAL. 731 * @param[in] new_access Structure that defines what access should 732 * be set on the file. 733 * See \ref access_check for more details. 734 * @param[in] ini_config Configuration to save. 735 * 736 * @return 0 - Success. 737 * @return EINVAL - Invalid parameter. 738 * 739 * Function can return other errors that standard open, chmod and chown 740 * functions return. 741 */ 742 int ini_config_save_as(struct ini_cfgfile *file_ctx, 743 const char *filename, 744 struct access_check *new_access, 745 struct ini_cfgobj *ini_config); 746 747 748 749 /** 750 * @brief Return the encoding indicator. 751 * 752 * When the file object is created the configuration data is inspected for 753 * encoding indicator called BOM. This function returns a constant that 754 * indicates what type of BOM was detected. 755 * 756 * @param[in] file_ctx File context. 757 * 758 * Function returns the constant of type enum index_utf_t. 759 */ 760 enum index_utf_t ini_config_get_bom(struct ini_cfgfile *file_ctx); 761 762 /** 763 * @brief Set the encoding indicator. 764 * 765 * When the file object is created the configuration data is inspected for 766 * encoding indicator called BOM. The BOM indicator is recorded in the file 767 * object and used when the file is saved. If the caller wants to change 768 * the encoding before saving he can use this function to alter the BOM type. 769 * 770 * @param[in] file_ctx File context. 771 * @param[in] bom BOM type indicator to set. 772 * 773 * 774 * @return 0 - Success. 775 * @return EINVAL - Invalid parameter. 776 */ 777 int ini_config_set_bom(struct ini_cfgfile *file_ctx, enum index_utf_t bom); 778 779 780 /** 781 * @brief Check parsing errors count 782 * 783 * Query the configuration file object about 784 * how many parsing errors were found during last 785 * parsing operation. 786 * 787 * @param[in] ini_config Configuration object. 788 * 789 * @return Number of errors. 790 */ 791 unsigned ini_config_error_count(struct ini_cfgobj *ini_config); 792 793 /** 794 * @brief Get array of parsing errors 795 * 796 * Function returns a newly allocated array of strings 797 * that should be later freed by the \ref ini_config_free_errors 798 * function. 799 * Array can be referenced as a normal array of strings. 800 * The NULL entry indicates the end of the array. 801 * 802 * @param[in] ini_config Configuration object. 803 * @param[out] errors Array of error strings. 804 * 805 * @return 0 - Success. 806 * @return EINVAL - Invalid parameter. 807 * @return ENOMEM - No memory. 808 */ 809 int ini_config_get_errors(struct ini_cfgobj *ini_config, 810 char ***errors); 811 812 /** 813 * @brief Free array of parsing errors 814 * 815 * Free array of parsing errors previously allocated 816 * by using \ref ini_config_get_errors function. 817 * 818 * @param[in] errors Array of error strings. 819 * 820 */ 821 void ini_config_free_errors(char **errors); 822 823 /** 824 * @brief Print errors to a file 825 * 826 * Prints array of parsing errors previously allocated 827 * by using \ref ini_config_get_errors function into 828 * a provided file. 829 * 830 * @param[in] file File or stream to send errors to. 831 * @param[in] error_list Array of error strings. 832 * 833 */ 834 void ini_config_print_errors(FILE *file, char **error_list); 835 836 /** 837 * @brief Get the fully resolved file name 838 * 839 * Returns the full name to the configuration file 840 * that was resolved by the library. 841 * 842 * @param[in] file_ctx Configuration file object. 843 * 844 * @return Full file name. 845 */ 846 const char *ini_config_get_filename(struct ini_cfgfile *file_ctx); 847 848 /** 849 * @brief Get pointer to collected stat data 850 * 851 * Returns the pointer to the internal stat structure. 852 * If stat data was not collected when the file was open 853 * function would return NULL. 854 * 855 * @param[in] file_ctx Configuration file object. 856 * 857 * @return Pointer to the stat structure. 858 */ 859 const struct stat *ini_config_get_stat(struct ini_cfgfile *file_ctx); 860 861 862 863 /** 864 * @brief Print file context 865 * 866 * Function is useful for debugging purposes only. 867 * 868 * @param[in] file_ctx Configuration file object. 869 * 870 */ 871 void ini_config_file_print(struct ini_cfgfile *file_ctx); 872 873 /** 874 * @brief Check file properties 875 * 876 * Before parsing it makes sense to make sure 877 * that the file you are trying to read is properly 878 * owned and has proper permissions. 879 * 880 * @param[in] file_ctx Configuration file object. 881 * @param[in] flags Define what to check. 882 * One can check file 883 * permissions with mask, 884 * uid, and gid of the file. 885 * @param[in] uid Expected uid of the file. 886 * @param[in] gid Expected gid of the file. 887 * @param[in] mode Expected mode of the file. 888 * @param[in] mask Mask to use in the mode check. 889 * Mask is always adjusted to 890 * include at least S_IRWXU, 891 * S_IRWXG and S_IRWXO 892 * 893 * @return 0 - Success. 894 * @return EINVAL - Invalid parameter. 895 * @return EACCES - File attributes do no match expectations. 896 */ 897 int ini_config_access_check(struct ini_cfgfile *file_ctx, 898 uint32_t flags, 899 uid_t uid, 900 gid_t gid, 901 mode_t mode, 902 mode_t mask); 903 904 /** 905 * @brief Check if file has changed 906 * 907 * Compares two configuration file objects. 908 * Determines if two objects are different 909 * by comparing: 910 * - time stamp 911 * - device ID 912 * - i-node 913 * 914 * Function can be used to check if the file 915 * has changed since last time the it was read. 916 * 917 * <i> Note:</i> If the file was deleted and quickly 918 * re-created the kernel seems to restore the same i-node. 919 * The stat structure keeps time granularity of seconds. 920 * As a result if the file is quickly recreated 921 * with the same contents like in the unit test the check 922 * would assume that file did not change. 923 * This is why the unit test has a one second delay. 924 * 925 * @param[in] file_ctx1 First configuration file object. 926 * @param[in] file_ctx2 Second configuration file object. 927 * @param[out] changed A value will be set to 0 if 928 * the objects are same and to 1 929 * if they are different. 930 * 931 * @return 0 - Success. 932 * @return EINVAL - Invalid parameter. 933 * @return EACCES - File attributes do no match expectations. 934 */ 935 int ini_config_changed(struct ini_cfgfile *file_ctx1, 936 struct ini_cfgfile *file_ctx2, 937 int *changed); 938 939 /** 940 * @brief Parse the file and populate a configuration object 941 * 942 * Function parses the file. It is assumed that 943 * the configuration object was just created. 944 * Using a non empty configuration object in 945 * a parsing operation would fail with EINVAL. 946 * 947 * @param[in] file_ctx Configuration file object. 948 * @param[in] error_level Flags that control actions 949 * in case of parsing error. 950 * @param[in] collision_flags Flags that control handling 951 * of the duplicate sections or keys. 952 * @param[in] parse_flags Flags that control parsing process, 953 * for example how to handle spaces at 954 * the beginning of the line. 955 * @param[out] ini_config Configuration object. 956 * 957 * @return 0 - Success. 958 * @return EINVAL - Invalid parameter. 959 * @return ENOMEM - No memory. 960 */ 961 int ini_config_parse(struct ini_cfgfile *file_ctx, 962 int error_level, 963 uint32_t collision_flags, 964 uint32_t parse_flags, 965 struct ini_cfgobj *ini_config); 966 967 /** 968 * @brief Create a copy of the configuration object 969 * 970 * Function creates a deep copy of all the configuration data. 971 * Error list created during parsing is not copied over. 972 * 973 * @param[in] ini_config Original configuration object. 974 * @param[out] ini_new A new configuration object. 975 * 976 * @return 0 - Success. 977 * @return EINVAL - Invalid parameter. 978 * @return ENOMEM - No memory. 979 */ 980 int ini_config_copy(struct ini_cfgobj *ini_config, 981 struct ini_cfgobj **ini_new); 982 983 /** 984 * @brief Merge two configuration objects 985 * 986 * Function merges configuration objects and creates 987 * a new resulting object out of the two. 988 * IMPORTANT: Use same collision flags for reading 989 * of the files and then merging. 990 * Mixing the flags would lead to strange results 991 * that would be hard to debug. 992 * 993 * 994 * @param[in] first A base object 995 * the other object will 996 * be merged with. 997 * @param[in] second The object that will 998 * be merged to the first one. 999 * @param[in] collision_flags Flags that control handling 1000 * of the duplicate sections or keys. 1001 * @param[out] result A new configuration object, 1002 * the result of the merge. 1003 * 1004 * @return 0 - Success. 1005 * @return EINVAL - Invalid parameter. 1006 * @return ENOMEM - No memory. 1007 */ 1008 int ini_config_merge(struct ini_cfgobj *first, 1009 struct ini_cfgobj *second, 1010 uint32_t collision_flags, 1011 struct ini_cfgobj **result); 1012 1013 1014 /** 1015 * @brief Augment configuration 1016 * 1017 * Function merges the main configuration file 1018 * with the configuration file snippets 1019 * read from a specified directory 1020 * ordered according to the locale setting. 1021 * 1022 * @param[in] base_cfg A configuration object 1023 * that will be augmented. 1024 * @param[in] path Path to a directory where 1025 * configuration snippets 1026 * will be read from. 1027 * @param[in] patterns List of regular expressions 1028 * that the name of a snippet file 1029 * has to match to be considered 1030 * for merge. These use POSIX Basic Regular 1031 * Expressions. 1032 * @param[in] sections List of regular expressions 1033 * that the section names in the snippet 1034 * file need to match. If file contains 1035 * sections that do not match any patterns 1036 * the file is skipped and error is recorded. 1037 * These use POSIX Basic Regular Expressions. 1038 * @param[in] check_perm Pointer to structure that 1039 * holds criteria for the 1040 * access check. 1041 * @param[in] error_level Flags that control actions 1042 * in case of parsing error in a snippet file. 1043 * @param[in] collision_flags These flags control how the potential 1044 * collisions between keys and sections 1045 * within the snippet file will be handled. 1046 * For more information 1047 * see collision flag definitions. 1048 * @param[in] parse_flags Flags that control parsing process, 1049 * for example how to handle spaces at 1050 * the beginning of the line. 1051 * @param[in] merge_flags Flags that control handling 1052 * of the duplicate sections or keys 1053 * during merging of the snippets. 1054 * They are different from the collision flags 1055 * because duplicate sections and keys inside 1056 * are snippets most likely will be handled as 1057 * 'last value wins' while during merge 1058 * the attempt to overwrite 1059 * a specific section might be treated as 1060 * an error. 1061 * @param[out] result_cfg A new configuration object, 1062 * the result of the merge. 1063 * @param[out] error_list List of strings that 1064 * contains all encountered 1065 * errors. 1066 * It can be NULL, in this case list of errors 1067 * is not populated. 1068 * @param[out] success_list List of strings that 1069 * contains file names of snippets that were 1070 * successfully merged. 1071 * It can be NULL, in this case list of files 1072 * is not populated. 1073 * 1074 * @return 0 - Success. 1075 * @return EINVAL - Invalid parameter. 1076 * @return ENOMEM - No memory. 1077 */ 1078 int ini_config_augment(struct ini_cfgobj *base_cfg, 1079 const char *path, 1080 const char *patterns[], 1081 const char *sections[], 1082 struct access_check *check_perm, 1083 int error_level, 1084 uint32_t collision_flags, 1085 uint32_t parse_flags, 1086 uint32_t merge_flags, 1087 struct ini_cfgobj **result_cfg, 1088 struct ref_array **error_list, 1089 struct ref_array **success_list); 1090 1091 /** 1092 * @brief Set the folding boundary 1093 * 1094 * Set the folding boundary for multiline values. 1095 * Use before serializing and saving to a file if the 1096 * default boundary of 80 characters does not work for you. 1097 * 1098 * @param[in] ini_config Configuration object. 1099 * @param[in] boundary Wrapping boundary. 1100 * 1101 * @return 0 - Success. 1102 * @return EINVAL - Invalid parameter. 1103 */ 1104 int ini_config_set_wrap(struct ini_cfgobj *ini_config, 1105 uint32_t boundary); 1106 1107 /** 1108 * @brief Serialize configuration object 1109 * 1110 * Serialize configuration object into provided buffer. 1111 * Use buffer object functions to manipulate or save 1112 * the buffer to a file/stream. 1113 * 1114 * @param[in] ini_config Configuration object. 1115 * @param[out] sbobj Serialized configuration. 1116 * 1117 * @return 0 - Success. 1118 * @return EINVAL - Invalid parameter. 1119 * @return ENOMEM - No memory. 1120 */ 1121 int ini_config_serialize(struct ini_cfgobj *ini_config, 1122 struct simplebuffer *sbobj); 1123 1124 1125 /* Functions that add, modify or delete sections and values in 1126 * the configuration object can be found in section \ref ini_mod. 1127 */ 1128 1129 /** 1130 * @} 1131 */ 1132 1133 1134 /** 1135 * @defgroup ini_section_and_attr Section and attribute management 1136 * 1137 * Functions in this section allow getting the lists of 1138 * sections in the configuration file and keys in a section 1139 * as arrays of strings. 1140 * 1141 * @{ 1142 * 1143 */ 1144 1145 /** 1146 * @brief Get list of sections. 1147 * 1148 * Get list of sections from the configuration object 1149 * as an array of strings. 1150 * Function allocates memory for the array of the sections. 1151 * Use \ref ini_free_section_list() to free allocated memory. 1152 * 1153 * @param[in] ini_config Configuration object. 1154 * @param[out] size If not NULL parameter will 1155 * receive number of sections 1156 * in the configuration. 1157 * @param[out] error If not NULL parameter will 1158 * receive the error code. 1159 * 0 - Success. 1160 * EINVAL - Invalid parameter. 1161 * ENOMEM - No memory. 1162 * 1163 * @return Array of strings. 1164 */ 1165 char **ini_get_section_list(struct ini_cfgobj *ini_config, 1166 int *size, 1167 int *error); 1168 1169 /** 1170 * @brief Free list of sections. 1171 * 1172 * The section array created by \ref ini_get_section_list() 1173 * should be freed using this function. 1174 * 1175 * @param[in] section_list Array of strings returned by 1176 * \ref ini_get_section_list() function. 1177 */ 1178 void ini_free_section_list(char **section_list); 1179 1180 /** 1181 * @brief Get list of attributes. 1182 * 1183 * Get list of attributes in a section as an array of strings. 1184 * Function allocates memory for the array of attributes. 1185 * Use \ref ini_free_attribute_list() to free allocated memory. 1186 * 1187 * @param[in] ini_config Configuration object. 1188 * @param[in] section Section name. 1189 * @param[out] size If not NULL parameter will 1190 * receive number of attributes 1191 * in the section. 1192 * @param[out] error If not NULL parameter will 1193 * receive the error code. 1194 * 0 - Success. 1195 * EINVAL - Invalid parameter. 1196 * ENOMEM - No memory. 1197 * 1198 * @return Array of strings. 1199 */ 1200 char **ini_get_attribute_list(struct ini_cfgobj *ini_config, 1201 const char *section, 1202 int *size, 1203 int *error); 1204 1205 /** 1206 * @brief Free list of attributes. 1207 * 1208 * The attribute array created by \ref ini_get_attribute_list() 1209 * should be freed using this function. 1210 * 1211 * @param[in] attr_list Array of strings returned by 1212 * \ref ini_get_attribute_list() function. 1213 */ 1214 void ini_free_attribute_list(char **attr_list); 1215 1216 /** 1217 * @} 1218 */ 1219 1220 /** 1221 * @defgroup ini_value Value management 1222 * 1223 * This section contains value management functions. These functions 1224 * can be used to interpret values that are stored in the configuration 1225 * object in memory. 1226 * 1227 * @{ 1228 * 1229 */ 1230 1231 1232 /** 1233 * @brief Retrieve a value object form the configuration. 1234 * 1235 * Check return error code first. If the function returns 1236 * an error there is a serious problem. 1237 * Then check if object is found. Function will set 1238 * vo parameter to NULL if no attribute with 1239 * provided name is found in the collection. 1240 * 1241 * @param[in] section Section name. 1242 * If NULL assumed default. 1243 * @param[in] name Attribute name to find. 1244 * @param[in] ini_config Configuration object to search. 1245 * @param[in] mode See \ref searchmode "search mode" 1246 * section for more info. 1247 * @param[out] vo Value object. 1248 * Will be set to NULL if 1249 * element with the given name 1250 * is not found. 1251 * @return 0 - Success. 1252 * @return EINVAL - Invalid parameter. 1253 * @return ENOMEM - No memory. 1254 * 1255 */ 1256 1257 int ini_get_config_valueobj(const char *section, 1258 const char *name, 1259 struct ini_cfgobj *ini_config, 1260 int mode, 1261 struct value_obj **vo); 1262 1263 1264 1265 /** 1266 * @brief Convert value to integer number. 1267 * 1268 * This is a conversion function. 1269 * It converts the value read from the INI file 1270 * and stored in the configuration element 1271 * into an int number. Any of the conversion 1272 * functions can be used to try to convert the value 1273 * stored as a string inside the value object. 1274 * The result can be different depending upon 1275 * how the caller tries to interpret the value. 1276 * If "strict" parameter is non zero the function will fail 1277 * if there are more characters after the last digit. 1278 * The value range is from INT_MIN to INT_MAX. 1279 * 1280 * @param[in] vo Value object to interpret. 1281 * It must be retrieved using 1282 * \ref ini_get_config_valueobj(). 1283 * @param[in] strict Fail the function if 1284 * the symbol after last digit 1285 * is not valid. 1286 * @param[in] def Default value to use if 1287 * conversion failed. 1288 * @param[out] error Variable will get the value 1289 * of the error code if 1290 * error happened. 1291 * Can be NULL. In this case 1292 * function does not set 1293 * the code. 1294 * Codes: 1295 * - 0 - Success. 1296 * - EINVAL - Argument is invalid. 1297 * - EIO - Conversion failed due 1298 * invalid characters. 1299 * - ERANGE - Value is out of range. 1300 * 1301 * @return Converted value. 1302 * In case of failure the function returns default value and 1303 * sets error code into the provided variable. 1304 */ 1305 int ini_get_int_config_value(struct value_obj *vo, 1306 int strict, 1307 int def, 1308 int *error); 1309 1310 /** 1311 * @brief Convert value object to a unsigned number. 1312 * 1313 * This is a conversion function. 1314 * It converts the value read from the INI file 1315 * and stored in the configuration element 1316 * into an unsigned number. Any of the conversion 1317 * functions can be used to try to convert the value 1318 * stored as a string inside the value object. 1319 * The result can be different depending upon 1320 * how the caller tries to interpret the value. 1321 * If "strict" parameter is non zero the function will fail 1322 * if there are more characters after the last digit. 1323 * The value range is from 0 to UINT_MAX. 1324 * 1325 * @param[in] vo Value object to interpret. 1326 * It must be retrieved using 1327 * \ref ini_get_config_valueobj(). 1328 * @param[in] strict Fail the function if 1329 * the symbol after last digit 1330 * is not valid. 1331 * @param[in] def Default value to use if 1332 * conversion failed. 1333 * @param[out] error Variable will get the value 1334 * of the error code if 1335 * error happened. 1336 * Can be NULL. In this case 1337 * function does not set 1338 * the code. 1339 * Codes: 1340 * - 0 - Success. 1341 * - EINVAL - Argument is invalid. 1342 * - EIO - Conversion failed due 1343 * invalid characters. 1344 * - ERANGE - Value is out of range. 1345 * 1346 * @return Converted value. 1347 * In case of failure the function returns default value and 1348 * sets error code into the provided variable. 1349 */ 1350 1351 unsigned ini_get_unsigned_config_value(struct value_obj *vo, 1352 int strict, 1353 unsigned def, 1354 int *error); 1355 1356 /** 1357 * @brief Convert value to long number. 1358 * 1359 * This is a conversion function. 1360 * It converts the value read from the INI file 1361 * and stored in the configuration element 1362 * into a long number. Any of the conversion 1363 * functions can be used to try to convert the value 1364 * stored as a string inside the value object. 1365 * The result can be different depending upon 1366 * how the caller tries to interpret the value. 1367 * If "strict" parameter is non zero the function will fail 1368 * if there are more characters after the last digit. 1369 * The value range is from LONG_MIN to LONG_MAX. 1370 * 1371 * @param[in] vo Value object to interpret. 1372 * It must be retrieved using 1373 * \ref ini_get_config_valueobj(). 1374 * @param[in] strict Fail the function if 1375 * the symbol after last digit 1376 * is not valid. 1377 * @param[in] def Default value to use if 1378 * conversion failed. 1379 * @param[out] error Variable will get the value 1380 * of the error code if 1381 * error happened. 1382 * Can be NULL. In this case 1383 * function does not set 1384 * the code. 1385 * Codes: 1386 * - 0 - Success. 1387 * - EINVAL - Argument is invalid. 1388 * - EIO - Conversion failed due 1389 * invalid characters. 1390 * - ERANGE - Value is out of range. 1391 * 1392 * @return Converted value. 1393 * In case of failure the function returns default value and 1394 * sets error code into the provided variable. 1395 */ 1396 1397 long ini_get_long_config_value(struct value_obj *vo, 1398 int strict, 1399 long def, 1400 int *error); 1401 1402 /** 1403 * @brief Convert value to unsigned long number. 1404 * 1405 * This is a conversion function. 1406 * It converts the value read from the INI file 1407 * and stored in the configuration element 1408 * into an unsigned long number. Any of the conversion 1409 * functions can be used to try to convert the value 1410 * stored as a string inside the value object. 1411 * The result can be different depending upon 1412 * how the caller tries to interpret the value. 1413 * If "strict" parameter is non zero the function will fail 1414 * if there are more characters after the last digit. 1415 * The value range is from 0 to ULONG_MAX. 1416 * 1417 * @param[in] vo Value object to interpret. 1418 * It must be retrieved using 1419 * \ref ini_get_config_valueobj(). 1420 * @param[in] strict Fail the function if 1421 * the symbol after last digit 1422 * is not valid. 1423 * @param[in] def Default value to use if 1424 * conversion failed. 1425 * @param[out] error Variable will get the value 1426 * of the error code if 1427 * error happened. 1428 * Can be NULL. In this case 1429 * function does not set 1430 * the code. 1431 * Codes: 1432 * - 0 - Success. 1433 * - EINVAL - Argument is invalid. 1434 * - EIO - Conversion failed due 1435 * invalid characters. 1436 * - ERANGE - Value is out of range. 1437 * 1438 * @return Converted value. 1439 * In case of failure the function returns default value and 1440 * sets error code into the provided variable. 1441 */ 1442 1443 unsigned long ini_get_ulong_config_value(struct value_obj *vo, 1444 int strict, 1445 unsigned long def, 1446 int *error); 1447 1448 1449 /** 1450 * @brief Convert value to int32_t number. 1451 * 1452 * This is a conversion function. 1453 * It converts the value read from the INI file 1454 * and stored in the configuration element 1455 * into an int32_t number. Any of the conversion 1456 * functions can be used to try to convert the value 1457 * stored as a string inside the value object. 1458 * The result can be different depending upon 1459 * how the caller tries to interpret the value. 1460 * If "strict" parameter is non zero the function will fail 1461 * if there are more characters after the last digit. 1462 * The value range is from INT_MIN to INT_MAX. 1463 * 1464 * @param[in] vo Value object to interpret. 1465 * It must be retrieved using 1466 * \ref ini_get_config_valueobj(). 1467 * @param[in] strict Fail the function if 1468 * the symbol after last digit 1469 * is not valid. 1470 * @param[in] def Default value to use if 1471 * conversion failed. 1472 * @param[out] error Variable will get the value 1473 * of the error code if 1474 * error happened. 1475 * Can be NULL. In this case 1476 * function does not set 1477 * the code. 1478 * Codes: 1479 * - 0 - Success. 1480 * - EINVAL - Argument is invalid. 1481 * - EIO - Conversion failed due 1482 * invalid characters. 1483 * - ERANGE - Value is out of range. 1484 * 1485 * @return Converted value. 1486 * In case of failure the function returns default value and 1487 * sets error code into the provided variable. 1488 */ 1489 int32_t ini_get_int32_config_value(struct value_obj *vo, 1490 int strict, 1491 int32_t def, 1492 int *error); 1493 1494 /** 1495 * @brief Convert value to uint32_t number. 1496 * 1497 * This is a conversion function. 1498 * It converts the value read from the INI file 1499 * and stored in the configuration value 1500 * into an uint32_t number. Any of the conversion 1501 * functions can be used to try to convert the value 1502 * stored as a string inside the value object. 1503 * The result can be different depending upon 1504 * how the caller tries to interpret the value. 1505 * If "strict" parameter is non zero the function will fail 1506 * if there are more characters after the last digit. 1507 * The value range is from 0 to ULONG_MAX. 1508 * 1509 * @param[in] vo Value object to interpret. 1510 * It must be retrieved using 1511 * \ref ini_get_config_valueobj(). 1512 * @param[in] strict Fail the function if 1513 * the symbol after last digit 1514 * is not valid. 1515 * @param[in] def Default value to use if 1516 * conversion failed. 1517 * @param[out] error Variable will get the value 1518 * of the error code if 1519 * error happened. 1520 * Can be NULL. In this case 1521 * function does not set 1522 * the code. 1523 * Codes: 1524 * - 0 - Success. 1525 * - EINVAL - Argument is invalid. 1526 * - EIO - Conversion failed due 1527 * invalid characters. 1528 * - ERANGE - Value is out of range. 1529 * 1530 * @return Converted value. 1531 * In case of failure the function returns default value and 1532 * sets error code into the provided variable. 1533 */ 1534 uint32_t ini_get_uint32_config_value(struct value_obj *vo, 1535 int strict, 1536 uint32_t def, 1537 int *error); 1538 1539 /** 1540 * @brief Convert value to integer number. 1541 * 1542 * This is a conversion function. 1543 * It converts the value read from the INI file 1544 * and stored in the configuration element 1545 * into an int64_t number. Any of the conversion 1546 * functions can be used to try to convert the value 1547 * stored as a string inside the value object. 1548 * The result can be different depending upon 1549 * how the caller tries to interpret the value. 1550 * If "strict" parameter is non zero the function will fail 1551 * if there are more characters after the last digit. 1552 * The value range is from LLONG_MIN to LLONG_MAX. 1553 * 1554 * @param[in] vo Value object to interpret. 1555 * It must be retrieved using 1556 * \ref ini_get_config_valueobj(). 1557 * @param[in] strict Fail the function if 1558 * the symbol after last digit 1559 * is not valid. 1560 * @param[in] def Default value to use if 1561 * conversion failed. 1562 * @param[out] error Variable will get the value 1563 * of the error code if 1564 * error happened. 1565 * Can be NULL. In this case 1566 * function does not set 1567 * the code. 1568 * Codes: 1569 * - 0 - Success. 1570 * - EINVAL - Argument is invalid. 1571 * - EIO - Conversion failed due 1572 * invalid characters. 1573 * - ERANGE - Value is out of range. 1574 * 1575 * @return Converted value. 1576 * In case of failure the function returns default value and 1577 * sets error code into the provided variable. 1578 */ 1579 int64_t ini_get_int64_config_value(struct value_obj *vo, 1580 int strict, 1581 int64_t def, 1582 int *error); 1583 1584 /** 1585 * @brief Convert value to integer number. 1586 * 1587 * This is a conversion function. 1588 * It converts the value read from the INI file 1589 * and stored in the configuration element 1590 * into an uint64_t number. Any of the conversion 1591 * functions can be used to try to convert the value 1592 * stored as a string inside the value object. 1593 * The result can be different depending upon 1594 * how the caller tries to interpret the value. 1595 * If "strict" parameter is non zero the function will fail 1596 * if there are more characters after the last digit. 1597 * The value range is from 0 to ULLONG_MAX. 1598 * 1599 * @param[in] vo Value object to interpret. 1600 * It must be retrieved using 1601 * \ref ini_get_config_valueobj(). 1602 * @param[in] strict Fail the function if 1603 * the symbol after last digit 1604 * is not valid. 1605 * @param[in] def Default value to use if 1606 * conversion failed. 1607 * @param[out] error Variable will get the value 1608 * of the error code if 1609 * error happened. 1610 * Can be NULL. In this case 1611 * function does not set 1612 * the code. 1613 * Codes: 1614 * - 0 - Success. 1615 * - EINVAL - Argument is invalid. 1616 * - EIO - Conversion failed due 1617 * invalid characters. 1618 * - ERANGE - Value is out of range. 1619 * 1620 * @return Converted value. 1621 * In case of failure the function returns default value and 1622 * sets error code into the provided variable. 1623 */ 1624 uint64_t ini_get_uint64_config_value(struct value_obj *vo, 1625 int strict, 1626 uint64_t def, 1627 int *error); 1628 1629 /** 1630 * @brief Convert value to floating point number. 1631 * 1632 * This is a conversion function. 1633 * It converts the value read from the INI file 1634 * and stored in the configuration element 1635 * into a floating point number. Any of the conversion 1636 * functions can be used to try to convert the value 1637 * stored as a string inside the value object. 1638 * The result can be different depending upon 1639 * how the caller tries to interpret the value. 1640 * If "strict" parameter is non zero the function will fail 1641 * if there are more characters after the last digit. 1642 * 1643 * @param[in] vo Value object to interpret. 1644 * It must be retrieved using 1645 * \ref ini_get_config_valueobj(). 1646 * @param[in] strict Fail the function if 1647 * the symbol after last digit 1648 * is not valid. 1649 * @param[in] def Default value to use if 1650 * conversion failed. 1651 * @param[out] error Variable will get the value 1652 * of the error code if 1653 * error happened. 1654 * Can be NULL. In this case 1655 * function does not set 1656 * the code. 1657 * Codes: 1658 * - 0 - Success. 1659 * - EINVAL - Argument is invalid. 1660 * - EIO - Conversion failed due 1661 * invalid characters. 1662 * 1663 * @return Converted value. 1664 * In case of failure the function returns default value and 1665 * sets error code into the provided variable. 1666 */ 1667 double ini_get_double_config_value(struct value_obj *vo, 1668 int strict, 1669 double def, 1670 int *error); 1671 1672 /** 1673 * @brief Convert value into a logical value. 1674 * 1675 * This is a conversion function. 1676 * It converts the value read from the INI file 1677 * and stored in the configuration element 1678 * into a Boolean. Any of the conversion 1679 * functions can be used to try to convert the value 1680 * stored as a string inside the value object. 1681 * The result can be different depending upon 1682 * how the caller tries to interpret the value. 1683 * 1684 * @param[in] vo Value object to interpret. 1685 * It must be retrieved using 1686 * \ref ini_get_config_valueobj(). 1687 * @param[in] def Default value to use if 1688 * conversion failed. 1689 * @param[out] error Variable will get the value 1690 * of the error code if 1691 * error happened. 1692 * Can be NULL. In this case 1693 * function does not set 1694 * the code. 1695 * Codes: 1696 * - 0 - Success. 1697 * - EINVAL - Argument is invalid. 1698 * - EIO - Conversion failed due 1699 * invalid characters. 1700 * 1701 * @return Converted value. 1702 * In case of failure the function returns default value and 1703 * sets error code into the provided variable. 1704 */ 1705 unsigned char ini_get_bool_config_value(struct value_obj *vo, 1706 unsigned char def, 1707 int *error); 1708 1709 /** 1710 * @brief Get the copy of string stored in the configuration value 1711 * 1712 * Function creates a copy of the string value stored in 1713 * the configuration element. 1714 * Returned value needs to be freed after use. 1715 * If error occurred the returned value will be NULL. 1716 * 1717 * @param[in] vo Value object to use. 1718 * It must be retrieved using 1719 * \ref ini_get_config_valueobj(). 1720 * @param[out] error Variable will get the value 1721 * of the error code if 1722 * error happened. 1723 * Can be NULL. In this case 1724 * function does not set 1725 * the code. 1726 * Codes: 1727 * - 0 - Success. 1728 * - EINVAL - Argument is invalid. 1729 * - ENOMEM - No memory. 1730 * 1731 * @return Copy of the string or NULL. 1732 */ 1733 char *ini_get_string_config_value(struct value_obj *vo, 1734 int *error); 1735 /** 1736 * @brief Get the string stored in the configuration value 1737 * 1738 * Function returns a reference to the string value 1739 * stored inside the configuration element. This string can't be altered. 1740 * The string will go out of scope if the value object is deleted. 1741 * 1742 * @param[in] vo Value object to use. 1743 * It must be retrieved using 1744 * \ref ini_get_config_valueobj(). 1745 * @param[out] error Variable will get the value 1746 * of the error code if 1747 * error happened. 1748 * Can be NULL. In this case 1749 * function does not set 1750 * the code. 1751 * Codes: 1752 * - 0 - Success. 1753 * - EINVAL - Argument is invalid. 1754 * 1755 * @return String from the value object. 1756 */ 1757 const char *ini_get_const_string_config_value(struct value_obj *vo, 1758 int *error); 1759 1760 /** 1761 * @brief Convert value into a binary sequence. 1762 * 1763 * This is a conversion function. 1764 * It converts the value read from the INI file 1765 * and stored in the configuration element 1766 * into a sequence of bytes. 1767 * Any of the conversion functions 1768 * can be used to try to convert the value 1769 * stored as a string inside the value object. 1770 * The result can be different depending upon 1771 * how the caller tries to interpret the value. 1772 * 1773 * The function allocates memory. 1774 * It is the responsibility of the caller to free it after use. 1775 * Use \ref ini_free_bin_config_value() for this purpose. 1776 * Functions will return NULL if conversion failed. 1777 * 1778 * Function assumes that the value being interpreted 1779 * has a special format. 1780 * The string should be taken in single quotes 1781 * and consist of hex encoded value represented by 1782 * two hex digits per byte. 1783 * Case does not matter. 1784 * 1785 * Example: '0a2BFeCc' 1786 * 1787 * @param[in] vo Value object to interpret. 1788 * It must be retrieved using 1789 * \ref ini_get_config_valueobj(). 1790 * @param[out] length Variable that optionally receives 1791 * the length of the binary 1792 * sequence. 1793 * @param[out] error Variable will get the value 1794 * of the error code if 1795 * error happened. 1796 * Can be NULL. In this case 1797 * function does not set 1798 * the code. 1799 * Codes: 1800 * - 0 - Success. 1801 * - EINVAL - Argument is invalid. 1802 * - EIO - Conversion failed due 1803 * invalid characters. 1804 * - ENOMEM - No memory. 1805 * 1806 * @return Converted value. 1807 * In case of failure the function returns NULL. 1808 */ 1809 char *ini_get_bin_config_value(struct value_obj *vo, 1810 int *length, 1811 int *error); 1812 1813 /** 1814 * @brief Free binary buffer 1815 * 1816 * Free binary value returned by \ref ini_get_bin_config_value(). 1817 * 1818 * @param[in] bin Binary buffer to free. 1819 * 1820 */ 1821 void ini_free_bin_config_value(char *bin); 1822 1823 /** 1824 * @brief Convert value to an array of strings. 1825 * 1826 * This is a conversion function. 1827 * It converts the value read from the INI file 1828 * and stored in the configuration value object 1829 * into an array of strings. Any of the conversion 1830 * functions can be used to try to convert the value 1831 * stored as a string inside the value object. 1832 * The result can be different depending upon 1833 * how the caller tries to interpret the value. 1834 * 1835 * Separator string includes up to three different separators. 1836 * If separator NULL, comma is assumed. 1837 * The spaces are trimmed automatically around separators 1838 * in the string. 1839 * The function drops empty tokens from the list. 1840 * This means that the string like this: "apple, ,banana, ,orange ," 1841 * will be translated into the list of three items: 1842 * "apple","banana" and "orange". 1843 * 1844 * The length of the allocated array is returned in "size". 1845 * Size and error parameters can be NULL. 1846 * Use \ref ini_free_string_config_array() to free the array after use. 1847 * 1848 * The array is always NULL terminated so 1849 * it is safe not to get size and just loop until 1850 * array element is NULL. 1851 * 1852 * @param[in] vo Value object to interpret. 1853 * It must be retrieved using 1854 * \ref ini_get_config_valueobj(). 1855 * @param[in] sep String cosisting of separator 1856 * symbols. For example: ",.;" would mean 1857 * that comma, dot and semicolon 1858 * should be treated as separators 1859 * in the value. 1860 * @param[out] size Variable that optionally receives 1861 * the size of the array. 1862 * @param[out] error Variable will get the value 1863 * of the error code if 1864 * error happened. 1865 * Can be NULL. In this case 1866 * function does not set 1867 * the code. 1868 * Codes: 1869 * - 0 - Success. 1870 * - EINVAL - Argument is invalid. 1871 * - EIO - Conversion failed. 1872 * - ENOMEM - No memory. 1873 * 1874 * @return Array of strings. 1875 * In case of failure the function returns NULL. 1876 */ 1877 char **ini_get_string_config_array(struct value_obj *vo, 1878 const char *sep, 1879 int *size, 1880 int *error); 1881 1882 /** 1883 * @brief Convert value to an array of strings. 1884 * 1885 * This is a conversion function. 1886 * It converts the value read from the INI file 1887 * and stored in the configuration element 1888 * into an array of strings. Any of the conversion 1889 * functions can be used to try to convert the value 1890 * stored as a string inside the value object. 1891 * The result can be different depending upon 1892 * how the caller tries to interpret the value. 1893 * 1894 * Separator string includes up to three different separators. 1895 * If separator NULL, comma is assumed. 1896 * The spaces are trimmed automatically around separators 1897 * in the string. 1898 * The function does not drop empty tokens from the list. 1899 * This means that the string like this: "apple, ,banana, ,orange ," 1900 * will be translated into the list of five items: 1901 * "apple", "", "banana", "" and "orange". 1902 * 1903 * The length of the allocated array is returned in "size". 1904 * Size and error parameters can be NULL. 1905 * Use \ref ini_free_string_config_array() to free the array after use. 1906 * 1907 * The array is always NULL terminated so 1908 * it is safe not to get size and just loop until 1909 * array element is NULL. 1910 * 1911 * @param[in] vo Value object to interpret. 1912 * It must be retrieved using 1913 * \ref ini_get_config_valueobj(). 1914 * @param[in] sep String cosisting of separator 1915 * symbols. For example: ",.;" would mean 1916 * that comma, dot and semicolon 1917 * should be treated as separators 1918 * in the value. 1919 * @param[out] size Variable that optionally receives 1920 * the size of the array. 1921 * @param[out] error Variable will get the value 1922 * of the error code if 1923 * error happened. 1924 * Can be NULL. In this case 1925 * function does not set 1926 * the code. 1927 * Codes: 1928 * - 0 - Success. 1929 * - EINVAL - Argument is invalid. 1930 * - EIO - Conversion failed. 1931 * - ENOMEM - No memory. 1932 * 1933 * @return Array of strings. 1934 * In case of failure the function returns NULL. 1935 */ 1936 char **ini_get_raw_string_config_array(struct value_obj *vo, 1937 const char *sep, 1938 int *size, 1939 int *error); 1940 1941 /** 1942 * @brief Convert value to an array of long values. 1943 * 1944 * This is a conversion function. 1945 * It converts the value read from the INI file 1946 * and stored in the configuration element 1947 * into an array of long values. Any of the conversion 1948 * functions can be used to try to convert the value 1949 * stored as a string inside the value object. 1950 * The result can be different depending upon 1951 * how the caller tries to interpret the value. 1952 * 1953 * Separators inside the string are detected automatically. 1954 * The spaces are trimmed automatically around separators 1955 * in the string. 1956 * 1957 * The length of the allocated array is returned in "size". 1958 * Size parameter can't be NULL. 1959 * 1960 * Use \ref ini_free_long_config_array() to free the array after use. 1961 * 1962 * @param[in] vo Value object to interpret. 1963 * It must be retrieved using 1964 * \ref ini_get_config_valueobj(). 1965 * @param[out] size Variable that receives 1966 * the size of the array. 1967 * @param[out] error Variable will get the value 1968 * of the error code if 1969 * error happened. 1970 * Can be NULL. In this case 1971 * function does not set 1972 * the code. 1973 * Codes: 1974 * - 0 - Success. 1975 * - EINVAL - Argument is invalid. 1976 * - EIO - Conversion failed. 1977 * - ERANGE - Value is out of range. 1978 * - ENOMEM - No memory. 1979 * 1980 * @return Array of long values. 1981 * In case of failure the function returns NULL. 1982 */ 1983 long *ini_get_long_config_array(struct value_obj *vo, 1984 int *size, 1985 int *error); 1986 1987 /** 1988 * @brief Convert value to an array of floating point values. 1989 * 1990 * This is a conversion function. 1991 * It converts the value read from the INI file 1992 * and stored in the configuration element 1993 * into an array of floating point values. Any of the conversion 1994 * functions can be used to try to convert the value 1995 * stored as a string inside the value object. 1996 * The result can be different depending upon 1997 * how the caller tries to interpret the value. 1998 * 1999 * Separators inside the string are detected automatically. 2000 * The spaces are trimmed automatically around separators 2001 * in the string. 2002 * 2003 * The length of the allocated array is returned in "size". 2004 * Size parameter can't be NULL. 2005 * 2006 * Use \ref ini_free_double_config_array() to free the array after use. 2007 * 2008 * @param[in] vo Value object to interpret. 2009 * It must be retrieved using 2010 * \ref ini_get_config_valueobj(). 2011 * @param[out] size Variable that receives 2012 * the size of the array. 2013 * @param[out] error Variable will get the value 2014 * of the error code if 2015 * error happened. 2016 * Can be NULL. In this case 2017 * function does not set 2018 * the code. 2019 * Codes: 2020 * - 0 - Success. 2021 * - EINVAL - Argument is invalid. 2022 * - EIO - Conversion failed. 2023 * - ENOMEM - No memory. 2024 * 2025 * @return Array of floating point values. 2026 * In case of failure the function returns NULL. 2027 */ 2028 double *ini_get_double_config_array(struct value_obj *vo, 2029 int *size, 2030 int *error); 2031 2032 /** 2033 * @brief Free array of string values. 2034 * 2035 * Use this function to free the array returned by 2036 * \ref ini_get_string_config_array() or by 2037 * \ref ini_get_raw_string_config_array(). 2038 * 2039 * @param[in] str_config Array of string values. 2040 */ 2041 void ini_free_string_config_array(char **str_config); 2042 2043 /** 2044 * @brief Free array of long values. 2045 * 2046 * Use this function to free the array returned by 2047 * \ref ini_get_long_config_array(). 2048 * 2049 * @param[in] array Array of long values. 2050 */ 2051 void ini_free_long_config_array(long *array); 2052 /** 2053 * @brief Free array of floating pointer values. 2054 * 2055 * Use this function to free the array returned by 2056 * \ref ini_get_double_config_array(). 2057 * 2058 * @param[in] array Array of floating pointer values. 2059 */ 2060 void ini_free_double_config_array(double *array); 2061 2062 /** @brief Structure that holds error messages 2063 * generated by validators. 2064 */ 2065 struct ini_errobj; 2066 2067 /** 2068 * @brief Create structure to hold error messages. 2069 * 2070 * This function initiates structure that can be used to 2071 * hold error messages from generators. To add messages to 2072 * the structure use \ref ini_errobj_add_msg. 2073 * 2074 * @param[out] _errobj container for errors. 2075 * 2076 * @return Zero on success, nonzero value in case of error. 2077 */ 2078 int ini_errobj_create(struct ini_errobj **_errobj); 2079 2080 /** 2081 * @brief Free structure that holds error messages. 2082 * 2083 * This function is used to free structure 2084 * previously created by \ref ini_errobj_create. 2085 * 2086 * @param[in] errobj container for errors. 2087 */ 2088 void ini_errobj_destroy(struct ini_errobj **errobj); 2089 2090 /** 2091 * @brief Add new printf formated message to errobj. 2092 * 2093 * This function initiates structure that can be used to 2094 * hold error messages from generators. To add messages to 2095 * the structure use \ref ini_errobj_add_msg. 2096 * 2097 * @param[in] errobj container for errors previously 2098 * created by \ref ini_errobj_create. 2099 * @param[in] format printf format string 2100 * 2101 * @return Zero on success, nonzero value in case of error. 2102 */ 2103 int ini_errobj_add_msg(struct ini_errobj *errobj, 2104 const char *format, ...) 2105 DING_ATTR_FORMAT(2, 3); 2106 2107 /** 2108 * @brief Reset iterator in errobj. 2109 * 2110 * After calling this function, the iterator in errobj 2111 * will point to the first error message. Use this if 2112 * you need to accesss the list multiple times in a loop. 2113 * 2114 * @param[in] errobj container for errors previously 2115 * created by \ref ini_errobj_create. 2116 */ 2117 void ini_errobj_reset(struct ini_errobj *errobj); 2118 2119 /** 2120 * @brief Get pointer to current message in errobj. 2121 * 2122 * This function returns pointer to current message 2123 * pointed by the internal iterator. The returned string can 2124 * not be changed and will point to valid data only 2125 * until \ref ini_errobj_destroy is called. 2126 * 2127 * @param[in] errobj container for errors previously 2128 * created by \ref ini_errobj_create. 2129 * @return String inside the errobj structure. String 2130 * is valid until errobj is destroyed. 2131 */ 2132 const char *ini_errobj_get_msg(struct ini_errobj *errobj); 2133 2134 /** 2135 * @brief Move to the next message in errobj. 2136 * 2137 * This function moves the internal iterator of errobj 2138 * to the next message in list. 2139 * 2140 * @param[in] errobj container for errors previously 2141 * created by \ref ini_errobj_create. 2142 */ 2143 void ini_errobj_next(struct ini_errobj *errobj); 2144 2145 /** 2146 * @brief Check if errobj has more messages. 2147 * 2148 * This function returns true if errobj's internal iterator 2149 * reached end of list and no longer points to a message 2150 * 2151 * @param[in] errobj container for errors previously 2152 * created by \ref ini_errobj_create. 2153 * @return True if internal iterator reached end of list. 2154 */ 2155 int ini_errobj_no_more_msgs(struct ini_errobj *errobj); 2156 2157 /** 2158 * @brief Return number of messages in errobj 2159 * 2160 * This function returns number of messages inside errobj 2161 * 2162 * @param[in] errobj container for errors previously 2163 * created by \ref ini_errobj_create. 2164 * @return Number of messages stored in errobj. 2165 */ 2166 size_t ini_errobj_count(struct ini_errobj *errobj); 2167 2168 typedef int (ini_validator_func)(const char *rule_name, 2169 struct ini_cfgobj *rules_obj, 2170 struct ini_cfgobj *config_obj, 2171 struct ini_errobj *errobj, 2172 void **data); 2173 2174 typedef int (ini_schema_validator_func)(const char *rule_name, 2175 struct ini_cfgobj *rules_obj, 2176 struct ini_errobj *errobj, 2177 void **data); 2178 2179 /** @brief Structure used to define application specific 2180 * (external to libini) validator 2181 */ 2182 struct ini_validator { 2183 const char *name; 2184 ini_validator_func *func; 2185 /* currently unused, for future expansion */ 2186 ini_schema_validator_func *schema_validator; 2187 }; 2188 2189 /** 2190 * @brief Read rules from INI file 2191 * 2192 * This function is used to read rules from INI file 2193 * and store them in config object. This special 2194 * config object is passed to \ref ini_rules_check 2195 * together with config object representing the 2196 * configuration that will be checked. 2197 * 2198 * @param[in] filename Name of file with rules 2199 * @param[out] _rules_obj config object representing the rules 2200 * @return Zero on success. Non zero value on error. 2201 */ 2202 int ini_rules_read_from_file(const char *filename, 2203 struct ini_cfgobj **_rules_obj); 2204 2205 /** 2206 * @brief Check configuration file using rules 2207 * 2208 * This function is used to check if configuration 2209 * file applies to rules previously loaded by 2210 * \ref ini_rules_read_from_file. Any errors 2211 * detected in the configuration are stored in the 2212 * errobj structure. Error code returned by this 2213 * function indicates some internal error with 2214 * validators or memory allocation error (not 2215 * rule violation). 2216 * 2217 * @param[in] rules_obj config object representing the rules 2218 * @param[in] config_obj config object representing the 2219 * configuration 2220 * @param[in] extra_validators NULL terminated array of external 2221 * validators. Can be NULL if no external 2222 * validators are used. 2223 * 2224 * @param[in] errobj errobj to store generated errors 2225 * from validators. 2226 * 2227 * @return Zero on success. Non zero value on error. 2228 */ 2229 int ini_rules_check(struct ini_cfgobj *rules_obj, 2230 struct ini_cfgobj *config_obj, 2231 struct ini_validator **extra_validators, 2232 struct ini_errobj *errobj); 2233 2234 /** 2235 * @brief Free the rules 2236 * 2237 * This function is just wrapper around ini_config_destroy 2238 */ 2239 void ini_rules_destroy(struct ini_cfgobj *ini_config); 2240 2241 /** 2242 * @} 2243 */ 2244 2245 #endif 2246