This is libconfig.info, produced by makeinfo version 4.13 from

libconfig.texi.

INFO-DIR-SECTION Software libraries

START-INFO-DIR-ENTRY

* libconfig: (libconfig).       A Library For Processing Structured Configuration Files

END-INFO-DIR-ENTRY

File: libconfig.info,  Node: Top,  Next: Introduction,  Up: (dir)

libconfig

*********

* Menu:

* Introduction::

* Configuration Files::

* The C API::

* The C++ API::

* Example Programs::

* Configuration File Grammar::

* License::

* Function Index::

* Type Index::

* Concept Index::

File: libconfig.info,  Node: Introduction,  Next: Configuration Files,  Prev: Top,  Up: Top

* Menu:

* Why Another Configuration File Library?::

* Using the Library from a C Program::

* Using the Library from a C++ Program::

* Multithreading Issues::

* Internationalization Issues::

* Compiling Using pkg-config::

* Version Test Macros::

1 Introduction

**************

Libconfig is a library for reading, manipulating, and writing

structured configuration files. The library features a fully reentrant

parser and includes bindings for both the C and C++ programming

languages.

   The library runs on modern POSIX-compilant systems, such as Linux,

Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows 2000/XP

and later (with either Microsoft Visual Studio 2005 or later, or the

GNU toolchain via the MinGW environment).

File: libconfig.info,  Node: Why Another Configuration File Library?,  Next: Using the Library from a C Program,  Up: Introduction

1.1 Why Another Configuration File Library?

===========================================

There are several open-source configuration file libraries available as

of this writing. This library was written because each of those

libraries falls short in one or more ways. The main features of

libconfig that set it apart from the other libraries are:

   * A fully reentrant parser. Independent configurations can be parsed

     in concurrent threads at the same time.

   * Both C and C++ bindings, as well as hooks to allow for the

     creation of wrappers in other languages.

   * A simple, structured configuration file format that is more

     readable and compact than XML and more flexible than the obsolete

     but prevalent Windows "INI" file format.

   * A low-footprint implementation (just 37K for the C library and 76K

     for the C++ library) that is suitable for memory-constrained

     systems.

   * Proper documentation.

File: libconfig.info,  Node: Using the Library from a C Program,  Next: Using the Library from a C++ Program,  Prev: Why Another Configuration File Library?,  Up: Introduction

1.2 Using the Library from a C Program

======================================

To use the library from C code, include the following preprocessor

directive in your source files:

     #include <libconfig.h>

   To link with the library, specify `-lconfig' as an argument to the

linker.

File: libconfig.info,  Node: Using the Library from a C++ Program,  Next: Multithreading Issues,  Prev: Using the Library from a C Program,  Up: Introduction

1.3 Using the Library from a C++ Program

========================================

To use the library from C++, include the following preprocessor

directive in your source files:

     #include <libconfig.h++>

   Or, alternatively:

     #include <libconfig.hh>

   The C++ API classes are defined in the namespace `libconfig', hence

the following statement may optionally be used:

     using namespace libconfig;

   To link with the library, specify `-lconfig++' as an argument to the

linker.

File: libconfig.info,  Node: Multithreading Issues,  Next: Internationalization Issues,  Prev: Using the Library from a C++ Program,  Up: Introduction

1.4 Multithreading Issues

=========================

Libconfig is fully "reentrant"; the functions in the library do not

make use of global variables and do not maintain state between

successive calls. Therefore two independent configurations may be safely

manipulated concurrently by two distinct threads.

   Libconfig is not "thread-safe". The library is not aware of the

presence of threads and knows nothing about the host system's threading

model. Therefore, if an instance of a configuration is to be accessed

from multiple threads, it must be suitably protected by synchronization

mechanisms like read-write locks or mutexes; the standard rules for

safe multithreaded access to shared data must be observed.

   Libconfig is not "async-safe". Calls should not be made into the

library from signal handlers, because some of the C library routines

that it uses may not be async-safe.

   Libconfig is not guaranteed to be "cancel-safe". Since it is not

aware of the host system's threading model, the library does not

contain any thread cancellation points. In most cases this will not be

an issue for multithreaded programs. However, be aware that some of the

routines in the library (namely those that read/write configurations

from/to files or streams) perform I/O using C library routines which

may potentially block; whether or not these C library routines are

cancel-safe depends on the host system.

File: libconfig.info,  Node: Internationalization Issues,  Next: Compiling Using pkg-config,  Prev: Multithreading Issues,  Up: Introduction

1.5 Internationalization Issues

===============================

Libconfig does not natively support Unicode configuration files, but

string values may contain Unicode text encoded in UTF-8; such strings

will be treated as ordinary 8-bit ASCII text by the library. It is the

responsibility of the calling program to perform the necessary

conversions to/from wide (wchar_t) strings using the wide string

conversion functions such as mbsrtowcs() and wcsrtombs() or the iconv()

function of the libiconv library.

   The textual representation of a floating point value varies by

locale. However, the libconfig grammar specifies that floating point

values are represented using a period (`.') as the radix symbol; this

is consistent with the grammar of most programming languages. When a

configuration is read in or written out, libconfig temporarily changes

the LC_NUMERIC category of the locale of the calling thread to the "C"

locale to ensure consistent handling of floating point values

regardless of the locale(s) in use by the calling program.

   Note that the MinGW environment does not (as of this writing) provide

functions for changing the locale of the calling thread. Therefore,

when using libconfig in that environment, the calling program is

responsible for changing the LC_NUMERIC category of the locale to the

"C" locale before reading or writing a configuration.

File: libconfig.info,  Node: Compiling Using pkg-config,  Next: Version Test Macros,  Prev: Internationalization Issues,  Up: Introduction

1.6 Compiling Using pkg-config

==============================

On UNIX systems you can use the pkg-config utility (version 0.20 or

later) to automatically select the appropriate compiler and linker

switches for libconfig. Ensure that the environment variable

`PKG_CONFIG_PATH' contains the absolute path to the `lib/pkgconfig'

subdirectory of the libconfig installation. Then, you can compile and

link C programs with libconfig as follows:

     gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \

         `pkg-config --libs libconfig`

   And similarly, for C++ programs:

     g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \

         `pkg-config --libs libconfig++`

   Note the backticks in the above examples.

   When using autoconf, the `PKG_CHECK_MODULES' m4 macro may be used to

check for the presence of a given version of libconfig, and set the

appropriate Makefile variables automatically. For example:

     PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],,

       AC_MSG_ERROR([libconfig++ 1.4 or newer not found.])

     )

   In the above example, if libconfig++ version 1.4 or newer is found,

the Makefile variables `LIBCONFIGXX_LIBS' and `LIBCONFIGXX_CFLAGS' will

be set to the appropriate compiler and linker flags for compiling with

libconfig, and if it is not found, the configure script will abort with

an error to that effect.

File: libconfig.info,  Node: Version Test Macros,  Prev: Compiling Using pkg-config,  Up: Introduction

1.7 Version Test Macros

=======================

The `libconfig.h' header declares the following macros:

 -- Macro: LIBCONFIG_VER_MAJOR

 -- Macro: LIBCONFIG_VER_MINOR

 -- Macro: LIBCONFIG_VER_REVISION

     These macros represent the major version, minor version, and

     revision of the libconfig library. For example, in libconfig 1.4

     these are defined as `1', `4', and `0', respectively. These macros

     can be used in preprocessor directives to determine which

     libconfig features and/or APIs are present. For example:

          #if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \

               || (LIBCONFIG_VER_MAJOR > 1))

            /* use features present in libconfig 1.4 and later */

          #endif

     These macros were introduced in libconfig 1.4.

   Similarly, the `libconfig.h++' header declares the following macros:

 -- Macro: LIBCONFIGXX_VER_MAJOR

 -- Macro: LIBCONFIGXX_VER_MINOR

 -- Macro: LIBCONFIGXX_VER_REVISION

     These macros represent the major version, minor version, and

     revision of the libconfig++ library.

File: libconfig.info,  Node: Configuration Files,  Next: The C API,  Prev: Introduction,  Up: Top

* Menu:

* Settings::

* Groups::

* Arrays::

* Lists::

* Integer Values::

* 64-bit Integer Values::

* Floating Point Values::

* Boolean Values::

* String Values::

* Comments::

* Include Directives::

2 Configuration Files

*********************

Libconfig supports structured, hierarchical configurations. These

configurations can be read from and written to files and manipulated in

memory.

   A "configuration" consists of a group of "settings", which associate

names with values. A "value" can be one of the following:

   * A "scalar value": integer, 64-bit integer, floating-point number,

     boolean, or string

   * An "array", which is a sequence of scalar values, all of which

     must have the same type

   * A "group", which is a collection of settings

   * A "list", which is a sequence of values of any type, including

     other lists

   Consider the following configuration file for a hypothetical GUI

application, which illustrates all of the elements of the configuration

file grammar.

     # Example application configuration file

     version = "1.0";

     application:

     {

       window:

       {

         title = "My Application";

         size = { w = 640; h = 480; };

         pos = { x = 350; y = 250; };

       };

       list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */) );

       books = ( { title  = "Treasure Island";

                   author = "Robert Louis Stevenson";

                   price  = 29.95;

                   qty    = 5; },

                 { title  = "Snow Crash";

                   author = "Neal Stephenson";

                   price  = 9.99;

                   qty    = 8; } );

       misc:

       {

         pi = 3.141592654;

         bigint = 9223372036854775807L;

         columns = [ "Last Name", "First Name", "MI" ];

         bitmask = 0x1FC3;

       };

     };

   Settings can be uniquely identified within the configuration by a

"path". The path is a dot-separated sequence of names, beginning at a

top-level group and ending at the setting itself. Each name in the path

is the name of a setting; if the setting has no name because it is an

element in a list or array, an integer index in square brackets can be

used as the name.

   For example, in our hypothetical configuration file, the path to the

`x' setting is `application.window.pos.x'; the path to the `version'

setting is simply `version'; and the path to the `title' setting of the

second book in the `books' list is `application.books.[1].title'.

   The datatype of a value is determined from the format of the value

itself. If the value is enclosed in double quotes, it is treated as a

string. If it looks like an integer or floating point number, it is

treated as such. If it is one of the values `TRUE', `true', `FALSE', or

`false' (or any other mixed-case version of those tokens, e.g., `True'

or `FaLsE'), it is treated as a boolean. If it consists of a

comma-separated list of values enclosed in square brackets, it is

treated as an array. And if it consists of a comma-separated list of

values enclosed in parentheses, it is treated as a list. Any value

which does not meet any of these criteria is considered invalid and

results in a parse error.

   All names are case-sensitive. They may consist only of alphanumeric

characters, dashes (`-'), underscores (`_'), and asterisks (`*'), and

must begin with a letter or asterisk. No other characters are allowed.

   In C and C++, integer, 64-bit integer, floating point, and string

values are mapped to the types `int', `long long', `double', and `const

char *', respectively. The boolean type is mapped to `int' in C and

`bool' in C++.

   The following sections describe the elements of the configuration

file grammar in additional detail.

File: libconfig.info,  Node: Settings,  Next: Groups,  Up: Configuration Files

2.1 Settings

============

A setting has the form:

   name = value ;

   or:

   name : value ;

   The trailing semicolon is optional. Whitespace is not significant.

   The value may be a scalar value, an array, a group, or a list.

File: libconfig.info,  Node: Groups,  Next: Arrays,  Prev: Settings,  Up: Configuration Files

2.2 Groups

==========

A group has the form:

   {    settings ...  }

   Groups can contain any number of settings, but each setting must have

a unique name within the group.

File: libconfig.info,  Node: Arrays,  Next: Lists,  Prev: Groups,  Up: Configuration Files

2.3 Arrays

==========

An array has the form:

   [ value, value ... ]

   An array may have zero or more elements, but the elements must all be

scalar values of the same type.

File: libconfig.info,  Node: Lists,  Next: Integer Values,  Prev: Arrays,  Up: Configuration Files

2.4 Lists

=========

A list has the form:

   ( value, value ... )

   A list may have zero or more elements, each of which can be a scalar

value, an array, a group, or another list.

File: libconfig.info,  Node: Integer Values,  Next: 64-bit Integer Values,  Prev: Lists,  Up: Configuration Files

2.5 Integer Values

==================

Integers can be represented in one of two ways: as a series of one or

more decimal digits (`0' - `9'), with an optional leading sign

character (`+' or `-'); or as a hexadecimal value consisting of the

characters `0x' followed by a series of one or more hexadecimal digits

(`0' - `9', `A' - `F', `a' - `f').

File: libconfig.info,  Node: 64-bit Integer Values,  Next: Floating Point Values,  Prev: Integer Values,  Up: Configuration Files

2.6 64-bit Integer Values

=========================

Long long (64-bit) integers are represented identically to integers,

except that an 'L' character is appended to indicate a 64-bit value.

For example, `0L' indicates a 64-bit integer value 0.

File: libconfig.info,  Node: Floating Point Values,  Next: Boolean Values,  Prev: 64-bit Integer Values,  Up: Configuration Files

2.7 Floating Point Values

=========================

Floating point values consist of a series of one or more digits, one

decimal point, an optional leading sign character (`+' or `-'), and an

optional exponent. An exponent consists of the letter `E' or `e', an

optional sign character, and a series of one or more digits.

File: libconfig.info,  Node: Boolean Values,  Next: String Values,  Prev: Floating Point Values,  Up: Configuration Files

2.8 Boolean Values

==================

Boolean values may have one of the following values: `true', `false',

or any mixed-case variation thereof.

File: libconfig.info,  Node: String Values,  Next: Comments,  Prev: Boolean Values,  Up: Configuration Files

2.9 String Values

=================

String values consist of arbitrary text delimited by double quotes.

Literal double quotes can be escaped by preceding them with a

backslash: `\"'. The escape sequences `\\', `\f', `\n', `\r', and `\t'

are also recognized, and have the usual meaning.

   In addition, the `\x' escape sequence is supported; this sequence

must be followed by exactly two hexadecimal digits, which represent an

8-bit ASCII value. For example, `\xFF' represents the character with

ASCII code 0xFF.

   No other escape sequences are currently supported.

   Adjacent strings are automatically concatenated, as in C/C++ source

code. This is useful for formatting very long strings as sequences of

shorter strings. For example, the following constructs are equivalent:

   * `"The quick brown fox jumped over the lazy dog."'

   * `"The quick brown fox"'

     `" jumped over the lazy dog."'

   * `"The quick" /* comment */ " brown fox " // another comment'

     `"jumped over the lazy dog."'

File: libconfig.info,  Node: Comments,  Next: Include Directives,  Prev: String Values,  Up: Configuration Files

2.10 Comments

=============

Three types of comments are allowed within a configuration:

   * Script-style comments. All text beginning with a `#' character to

     the end of the line is ignored.

   * C-style comments. All text, including line breaks, between a

     starting `/*' sequence and an ending `*/' sequence is ignored.

   * C++-style comments. All text beginning with a `//' sequence to the

     end of the line is ignored.

   As expected, comment delimiters appearing within quoted strings are

treated as literal text.

   Comments are ignored when the configuration is read in, so they are

not treated as part of the configuration. Therefore if the

configuration is written back out to a stream, any comments that were

present in the original configuration will be lost.

File: libconfig.info,  Node: Include Directives,  Prev: Comments,  Up: Configuration Files

2.11 Include Directives

=======================

A configuration file may "include" the contents of another file using

an include directive. This directive has the effect of inlining the

contents of the named file at the point of inclusion.

   An include directive must appear on its own line in the input. It has

the form:

   @include "filename"

   Any backslashes or double quotes in the filename must be escaped as

`\\' and `\"', respectively.

   For example, consider the following two configuration files:

     # file: quote.cfg

     quote = "Criticism may not be agreeable, but it is necessary."

             " It fulfils the same function as pain in the human"

             " body. It calls attention to an unhealthy state of"

             " things.\n"

             "\t--Winston Churchill";

     # file: test.cfg

     info: {

       name = "Winston Churchill";

       @include "quote.cfg"

       country = "UK";

     };

   Include files may be nested to a maximum of 10 levels; exceeding this

limit results in a parse error.

   Like comments, include directives are not part of the configuration

file syntax. They are processed before the configuration itself is

parsed. Therefore, they are not preserved when the configuration is

written back out to a stream. There is presently no support for

programmatically inserting include directives into a configuration.

File: libconfig.info,  Node: The C API,  Next: The C++ API,  Prev: Configuration Files,  Up: Top

3 The C API

***********

This chapter describes the C library API. The type config_t represents

a configuration, and the type config_setting_t represents a

configuration setting.

   The boolean values `CONFIG_TRUE' and `CONFIG_FALSE' are macros

defined as `(1)' and `(0)', respectively.

 -- Function: void config_init (config_t * CONFIG)

 -- Function: void config_destroy (config_t * CONFIG)

     These functions initialize and destroy the configuration object

     CONFIG.

     `config_init()' initializes the config_t structure pointed to by

     CONFIG as a new, empty configuration.

     `config_destroy()' destroys the configuration CONFIG, deallocating

     all memory associated with the configuration, but does not attempt

     to deallocate the config_t structure itself.

 -- Function: int config_read (config_t * CONFIG, FILE * STREAM)

     This function reads and parses a configuration from the given

     STREAM into the configuration object CONFIG. It returns

     `CONFIG_TRUE' on success, or `CONFIG_FALSE' on failure; the

     `config_error_text()', `config_error_file()',

     `config_error_line()', and `config_error_type()' functions,

     described below, can be used to obtain information about the error.

 -- Function: int config_read_file (config_t * CONFIG,

          const char * FILENAME)

     This function reads and parses a configuration from the file named

     FILENAME into the configuration object CONFIG. It returns

     `CONFIG_TRUE' on success, or `CONFIG_FALSE' on failure; the

     `config_error_text()' and `config_error_line()' functions,

     described below, can be used to obtain information about the error.

 -- Function: int config_read_string (config_t * CONFIG,

          const char * STR)

     This function reads and parses a configuration from the string STR

     into the configuration object CONFIG. It returns `CONFIG_TRUE' on

     success, or `CONFIG_FALSE' on failure; the `config_error_text()'

     and `config_error_line()' functions, described below, can be used

     to obtain information about the error.

 -- Function: void config_write (const config_t * CONFIG, FILE * STREAM)

     This function writes the configuration CONFIG to the given STREAM.

 -- Function: int config_write_file (config_t * CONFIG,

          const char * FILENAME)

     This function writes the configuration CONFIG to the file named

     FILENAME. It returns `CONFIG_TRUE' on success, or `CONFIG_FALSE'

     on failure.

 -- Function: const char * config_error_text (const config_t * CONFIG)

 -- Function: const char * config_error_file (const config_t * CONFIG)

 -- Function: int config_error_line (const config_t * CONFIG)

     These functions, which are implemented as macros, return the text,

     filename, and line number of the parse error, if one occurred

     during a call to `config_read()', `config_read_string()', or

     `config_read_file()'. Storage for the strings returned by

     `config_error_text()' and `config_error_file()' are managed by the

     library and released automatically when the configuration is

     destroyed; these strings must not be freed by the caller. If the

     error occurred in text that was read from a string or stream,

     `config_error_file()' will return NULL.

 -- Function: config_error_t config_error_type (const config_t * CONFIG)

     This function, which is implemented as a macro, returns the type of

     error that occurred during the last call to one of the read or

     write functions. The CONFIG_ERROR_T type is an enumeration with the

     following values: `CONFIG_ERR_NONE', `CONFIG_ERR_FILE_IO',

     `CONFIG_ERR_PARSE'. These represent success, a file I/O error, and

     a parsing error, respectively.

 -- Function: void config_set_include_dir (config_t *CONFIG,

          const char *INCLUDE_DIR)

 -- Function: const char * config_get_include_dir

          (const config_t *CONFIG)

     `config_set_include_dir()' specifies the include directory,

     INCLUDE_DIR, relative to which the files specified in `@include'

     directives will be located for the configuration CONFIG. By

     default, there is no include directory, and all include files are

     expected to be relative to the current working directory. If

     INCLUDE_DIR is `NULL', the default behavior is reinstated.

     For example, if the include directory is set to `/usr/local/etc',

     the include directive `@include "configs/extra.cfg"' would include

     the file `/usr/local/etc/configs/extra.cfg'.

     `config_get_include_dir()' returns the current include directory

     for the configuration CONFIG, or `NULL' if none is set.

 -- Function: void config_set_auto_convert (config_t *CONFIG, int FLAG)

 -- Function: int config_get_auto_convert (const config_t *CONFIG)

     `config_set_auto_convert()' enables number auto-conversion for the

     configuration CONFIG if FLAG is non-zero, and disables it

     otherwise. When this feature is enabled, an attempt to retrieve a

     floating point setting's value into an integer (or vice versa), or

     store an integer to a floating point setting's value (or vice

     versa) will cause the library to silently perform the necessary

     conversion (possibly leading to loss of data), rather than

     reporting failure. By default this feature is disabled.

     `config_get_auto_convert()' returns `CONFIG_TRUE' if number

     auto-conversion is currently enabled for CONFIG; otherwise it

     returns `CONFIG_FALSE'.

 -- Function: void config_set_default_format (config_t * CONFIG,

          short FORMAT)

 -- Function: short config_get_default_format (config_t * CONFIG)

     These functions, which are implemented as macros, set and get the

     default external format for settings in the configuration CONFIG.

     If a non-default format has not been set for a setting with

     `config_setting_set_format()', this configuration-wide default

     format will be used instead when that setting is written to a file

     or stream.

 -- Function: void config_set_tab_width (config_t * CONFIG,

          unsigned short WIDTH)

 -- Function: unsigned short config_get_tab_width

          (const config_t * CONFIG)

     These functions, which are implemented as macros, set and get the

     tab width for the configuration CONFIG. The tab width affects the

     formatting of the configuration when it is written to a file or

     stream: each level of nesting is indented by WIDTH spaces, or by a

     single tab character if WIDTH is 0. The tab width has no effect on

     parsing.

     Valid tab widths range from 0 to 15. The default tab width is 2.

 -- Function: int config_lookup_int (const config_t * CONFIG,

          const char * PATH, int * VALUE)

 -- Function: int config_lookup_int64 (const config_t * CONFIG,

          const char * PATH, long long * VALUE)

 -- Function: int config_lookup_float (const config_t * CONFIG,

          const char * PATH, double * VALUE)

 -- Function: int config_lookup_bool (const config_t * CONFIG,

          const char * PATH, int * VALUE)

 -- Function: int config_lookup_string (const config_t * CONFIG,

          const char * PATH, const char ** VALUE)

     These functions look up the value of the setting in the

     configuration CONFIG specified by the path PATH. They store the

     value of the setting at VALUE and return `CONFIG_TRUE' on success.

     If the setting was not found or if the type of the value did not

     match the type requested, they leave the data pointed to by VALUE

     unmodified and return `CONFIG_FALSE'.

     Storage for the string returned by `config_lookup_string()' is

     managed by the library and released automatically when the setting

     is destroyed or when the setting's value is changed; the string

     must not be freed by the caller.

 -- Function: config_setting_t * config_lookup

          (const config_t * CONFIG, const char * PATH)

     This function locates the setting in the configuration CONFIG

     specified by the path PATH. It returns a pointer to the

     `config_setting_t' structure on success, or `NULL' if the setting

     was not found.

 -- Function: int config_setting_get_int

          (const config_setting_t * SETTING)

 -- Function: long long config_setting_get_int64

          (const config_setting_t * SETTING)

 -- Function: double config_setting_get_float

          (const config_setting_t * SETTING)

 -- Function: int config_setting_get_bool

          (const config_setting_t * SETTING)

 -- Function: const char * config_setting_get_string

          (const config_setting_t * SETTING)

     These functions return the value of the given SETTING. If the type

     of the setting does not match the type requested, a 0 or `NULL'

     value is returned. Storage for the string returned by

     `config_setting_get_string()' is managed by the library and

     released automatically when the setting is destroyed or when the

     setting's value is changed; the string must not be freed by the

     caller.

 -- Function: int config_setting_set_int (config_setting_t * SETTING,

          int VALUE)

 -- Function: int config_setting_set_int64 (config_setting_t * SETTING,

          long long VALUE)

 -- Function: int config_setting_set_float (config_setting_t * SETTING,

          double VALUE)

 -- Function: int config_setting_set_bool (config_setting_t * SETTING,

          int VALUE)

 -- Function: int config_setting_set_string

          (config_setting_t * SETTING, const char * VALUE)

     These functions set the value of the given SETTING to VALUE. On

     success, they return `CONFIG_TRUE'. If the setting does not match

     the type of the value, they return `CONFIG_FALSE'.

     `config_setting_set_string()' makes a copy of the passed string

     VALUE, so it may be subsequently freed or modified by the caller

     without affecting the value of the setting.

 -- Function: int config_setting_lookup_int

          (const config_setting_t * SETTING, const char * NAME,

          int * VALUE)

 -- Function: int config_setting_lookup_int64

          (const config_setting_t * SETTING, const char * NAME,

          long long * VALUE)

 -- Function: int config_setting_lookup_float

          (const config_setting_t * SETTING, const char * NAME,

          double * VALUE)

 -- Function: int config_setting_lookup_bool

          (const config_setting_t * SETTING, const char * NAME,

          int * VALUE)

 -- Function: int config_setting_lookup_string

          (const config_setting_t * SETTING, const char * NAME,

          const char ** VALUE)

     These functions look up the value of the child setting named NAME

     of the setting SETTING. They store the value at VALUE and return

     `CONFIG_TRUE' on success. If the setting was not found or if the

     type of the value did not match the type requested, they leave the

     data pointed to by VALUE unmodified and return `CONFIG_FALSE'.

     Storage for the string returned by

     `config_setting_lookup_string()' is managed by the library and

     released automatically when the setting is destroyed or when the

     setting's value is changed; the string must not be freed by the

     caller.

 -- Function: short config_setting_get_format

          (config_setting_t * SETTING)

 -- Function: int config_setting_set_format

          (config_setting_t * SETTING, short FORMAT)

     These functions get and set the external format for the setting

     SETTING.

     The FORMAT must be one of the constants `CONFIG_FORMAT_DEFAULT' or

     `CONFIG_FORMAT_HEX'. All settings support the

     `CONFIG_FORMAT_DEFAULT' format. The `CONFIG_FORMAT_HEX' format

     specifies hexadecimal formatting for integer values, and hence

     only applies to settings of type `CONFIG_TYPE_INT' and

     `CONFIG_TYPE_INT64'.  If FORMAT is invalid for the given setting,

     it is ignored.

     If a non-default format has not been set for the setting,

     `config_setting_get_format()' returns the default format for the

     configuration, as set by `config_set_default_format()'.

     `config_setting_set_format()' returns `CONFIG_TRUE' on success and

     `CONFIG_FALSE' on failure.

 -- Function: config_setting_t * config_setting_get_member

          (config_setting_t * SETTING, const char * NAME)

     This function fetches the child setting named NAME from the group

     SETTING. It returns the requested setting on success, or `NULL' if

     the setting was not found or if SETTING is not a group.

 -- Function: config_setting_t * config_setting_get_elem

          (const config_setting_t * SETTING, unsigned int INDEX)

     This function fetches the element at the given index INDEX in the

     setting SETTING, which must be an array, list, or group. It

     returns the requested setting on success, or `NULL' if INDEX is

     out of range or if SETTING is not an array, list, or group.

 -- Function: int config_setting_get_int_elem

          (const config_setting_t * SETTING, int INDEX)

 -- Function: long long config_setting_get_int64_elem

          (const config_setting_t * SETTING, int INDEX)

 -- Function: double config_setting_get_float_elem

          (const config_setting_t * SETTING, int INDEX)

 -- Function: int config_setting_get_bool_elem

          (const config_setting_t * SETTING, int INDEX)

 -- Function: const char * config_setting_get_string_elem

          (const config_setting_t * SETTING, int INDEX)

     These functions return the value at the specified index INDEX in

     the setting SETTING. If the setting is not an array or list, or if

     the type of the element does not match the type requested, or if

     INDEX is out of range, they return 0 or `NULL'. Storage for the

     string returned by `config_setting_get_string_elem()' is managed

     by the library and released automatically when the setting is

     destroyed or when its value is changed; the string must not be

     freed by the caller.

 -- Function: config_setting_t * config_setting_set_int_elem

          (config_setting_t * SETTING, int INDEX, int VALUE)

 -- Function: config_setting_t * config_setting_set_int64_elem

          (config_setting_t * SETTING, int INDEX, long long VALUE)

 -- Function: config_setting_t * config_setting_set_float_elem

          (config_setting_t * SETTING, int INDEX, double VALUE)

 -- Function: config_setting_t * config_setting_set_bool_elem

          (config_setting_t * SETTING, int INDEX, int VALUE)

 -- Function: config_setting_t * config_setting_set_string_elem

          (config_setting_t * SETTING, int INDEX, const char * VALUE)

     These functions set the value at the specified index INDEX in the

     setting SETTING to VALUE. If INDEX is negative, a new element is

     added to the end of the array or list. On success, these functions