\input texinfo.tex    @c -*-texinfo-*-

@c

@c %**start of header

@c All text is ignored before the setfilename.

@setfilename libconfig.info

@settitle libconfig

@set edition 1.4.9

@set update-date 28 September 2012

@set subtitle-text A Library For Processing Structured Configuration Files

@set author-text Mark A.@: Lindner

@comment %**end of header

@dircategory Software libraries

@direntry

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

@end direntry

@tex

\global\emergencystretch = .3\hsize

@end tex

@setchapternewpage odd

@titlepage

@title libconfig

@subtitle @value{subtitle-text}

@subtitle Version @value{edition}

@subtitle @value{update-date}

@author @value{author-text}

@page

@vskip 0pt plus 1filll

Copyright @copyright{} 2005-2012  Mark A Lindner

Permission is granted to make and distribute verbatim copies of

this manual provided the copyright notice and this permission notice

are preserved on all copies.

Permission is granted to copy and distribute modified versions of this

manual under the conditions for verbatim copying, provided that the entire

resulting derived work is distributed under the terms of a permission

notice identical to this one.

@end titlepage

@c Give the HTML output a title page that somewhat resembles the printed one

@ifhtml

@html

<hr noshade size=6 color="black">

<div align=right>@value{subtitle-text}<br>

Version @value{edition}<br>

@value{update-date}</div>

<br><br><br><br>

<font size=+1>@value{author-text}</font>

<hr size=3 noshade color="black">

<br><br>

@end html

@end ifhtml

@contents

@ifnottex

@node Top

@comment  node-name,  next,  previous,  up

@top libconfig

@end ifnottex

@menu

* Introduction::

* Configuration Files::

* The C API::

* The C++ API::

* Example Programs::

* Configuration File Grammar::

* License::

* Function Index::

* Type Index::

* Concept Index::

@end menu

@node Introduction, Configuration Files, Top, Top

@comment  node-name,  next,  previous,  up

@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::

@end menu

@chapter Introduction

@i{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).

@node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction

@comment  node-name,  next,  previous,  up

@section 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

@i{libconfig} that set it apart from the other libraries are:

@itemize @bullet

@item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.

@item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.

@item 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.

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

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

@item Proper documentation.

@end itemize

@node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction

@comment  node-name,  next,  previous,  up

@section Using the Library from a C Program

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

directive in your source files:

@sp 1

@smallexample

#include <libconfig.h>

@end smallexample

@sp 1

To link with the library, specify @samp{-lconfig} as an argument to the

linker.

@node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction

@comment  node-name,  next,  previous,  up

@section Using the Library from a C++ Program

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

directive in your source files:

@sp 1

@smallexample

#include <libconfig.h++>

@end smallexample

@sp 1

Or, alternatively:

@sp 1

@smallexample

#include <libconfig.hh>

@end smallexample

@sp 1

@page

The C++ API classes are defined in the namespace @samp{libconfig}, hence the

following statement may optionally be used:

@sp 1

@smallexample

using namespace libconfig;

@end smallexample

@sp 1

To link with the library, specify @samp{-lconfig++} as an argument to

the linker.

@node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction

@comment  node-name,  next,  previous,  up

@section Multithreading Issues

@i{Libconfig} is fully @dfn{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.

@i{Libconfig} is not @dfn{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.

@i{Libconfig} is not @dfn{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.

@i{Libconfig} is not guaranteed to be @dfn{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.

@node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction

@comment  node-name,  next,  previous,  up

@section Internationalization Issues

@cindex Unicode

@cindex UTF-8

@i{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 (@t{wchar_t}) strings using the

wide string conversion functions such as @t{mbsrtowcs()} and

@t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv}

library.

@cindex locale

The textual representation of a floating point value varies by

locale. However, the @i{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,

@i{libconfig} temporarily changes the @t{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 @i{libconfig} in that environment, the calling program is

responsible for changing the @t{LC_NUMERIC} category of the locale to

the "C" locale before reading or writing a configuration.

@node Compiling Using pkg-config, Version Test Macros, Internationalization Issues, Introduction

@comment  node-name,  next,  previous,  up

@section Compiling Using pkg-config

On UNIX systems you can use the @i{pkg-config} utility (version 0.20

or later) to automatically select the appropriate compiler and linker

switches for @i{libconfig}. Ensure that the environment variable

@code{PKG_CONFIG_PATH} contains the absolute path to the

@file{lib/pkgconfig} subdirectory of the @i{libconfig} installation. Then,

you can compile and link C programs with @i{libconfig} as follows:

@smallexample

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

    `pkg-config --libs libconfig`

@end smallexample

@sp 1

And similarly, for C++ programs:

@smallexample

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

    `pkg-config --libs libconfig++`

@end smallexample

@sp 1

Note the backticks in the above examples.

When using @b{autoconf}, the @code{PKG_CHECK_MODULES} m4 macro may be used to check for the presence of a given version of @i{libconfig}, and set the appropriate Makefile variables automatically. For example:

@smallexample

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

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

)

@end smallexample

In the above example, if @i{libconfig++} version 1.4 or newer is found,

the Makefile variables @code{LIBCONFIGXX_LIBS} and @code{LIBCONFIGXX_CFLAGS} will be

set to the appropriate compiler and linker flags for compiling with

@i{libconfig}, and if it is not found, the configure script will abort

with an error to that effect.

@node Version Test Macros, , Compiling Using pkg-config, Introduction

@comment  node-name,  next,  previous,  up

@section Version Test Macros

The @file{libconfig.h} header declares the following macros:

@defmac LIBCONFIG_VER_MAJOR

@defmacx LIBCONFIG_VER_MINOR

@defmacx LIBCONFIG_VER_REVISION

These macros represent the major version, minor version, and revision

of the @i{libconfig} library. For example, in @i{libconfig} 1.4 these

are defined as @samp{1}, @samp{4}, and @samp{0}, respectively. These

macros can be used in preprocessor directives to determine which

@i{libconfig} features and/or APIs are present. For example:

@smallexample

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

     || (LIBCONFIG_VER_MAJOR > 1))

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

#endif

@end smallexample

These macros were introduced in @i{libconfig} 1.4.

@end defmac

Similarly, the @file{libconfig.h++} header declares the following macros:

@defmac LIBCONFIGXX_VER_MAJOR

@defmacx LIBCONFIGXX_VER_MINOR

@defmacx LIBCONFIGXX_VER_REVISION

These macros represent the major version, minor version, and revision

of the @i{libconfig++} library.

@end defmac

@node Configuration Files, The C API, Introduction, Top

@comment  node-name,  next,  previous,  up

@menu

* Settings::

* Groups::

* Arrays::

* Lists::

* Integer Values::

* 64-bit Integer Values::

* Floating Point Values::

* Boolean Values::

* String Values::

* Comments::

* Include Directives::

@end menu

@chapter Configuration Files

@i{Libconfig} supports structured, hierarchical configurations. These

configurations can be read from and written to files and manipulated

in memory.

@cindex setting

@cindex value

@cindex scalar value

@cindex array

@cindex group

@cindex list

@cindex configuration

A @dfn{configuration} consists of a group of @dfn{settings}, which

associate names with values. A @dfn{value} can be one of the

following:

@itemize @bullet

@item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean,

or string

@item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type

@item A @dfn{group}, which is a collection of settings

@item A @dfn{list}, which is a sequence of values of any type, including other lists

@end itemize

Consider the following configuration file for a hypothetical GUI

application, which illustrates all of the elements of the configuration

file grammar.

@sp 1

@cartouche

@smallexample

# 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;

  @};

@};

@end smallexample

@end cartouche

@sp 1

@cindex path

Settings can be uniquely identified within the configuration by a

@dfn{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

@code{x} setting is @code{application.window.pos.x}; the path to the

@code{version} setting is simply @code{version}; and the path to the

@code{title} setting of the second book in the @code{books} list is

@code{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 @code{TRUE}, @code{true},

@code{FALSE}, or @code{false} (or any other mixed-case version of

those tokens, e.g., @code{True} or @code{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 (@samp{-}), underscores (@samp{_}), and asterisks

(@samp{*}), 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 @code{int}, @code{long long},

@code{double}, and @code{const char *}, respectively. The boolean type

is mapped to @code{int} in C and @code{bool} in C++.

The following sections describe the elements of the configuration file

grammar in additional detail.

@node Settings, Groups, , Configuration Files

@comment  node-name,  next,  previous,  up

@section Settings

A setting has the form:

@i{name} @b{=} @i{value} @b{;}

or:

@i{name} @b{:} @i{value} @b{;}

The trailing semicolon is optional. Whitespace is not significant.

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

@node Groups, Arrays, Settings, Configuration Files

@comment  node-name,  next,  previous,  up

@section Groups

A group has the form:

@b{@{}

   @i{settings ...}

@b{@}}

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

a unique name within the group.

@node Arrays, Lists, Groups, Configuration Files

@comment  node-name,  next,  previous,  up

@section Arrays

An array has the form:

@b{[} @i{value}@b{,} @i{value ...} @b{]}

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

scalar values of the same type.

@node Lists, Integer Values, Arrays, Configuration Files

@comment  node-name,  next,  previous,  up

@section Lists

A list has the form:

@b{(} @i{value}@b{,} @i{value ...} @b{)}

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

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

@node Integer Values, 64-bit Integer Values, Lists, Configuration Files

@comment  node-name,  next,  previous,  up

@section Integer Values

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

more decimal digits (@samp{0} - @samp{9}), with an optional leading

sign character (@samp{+} or @samp{-}); or as a hexadecimal value

consisting of the characters @samp{0x} followed by a series of one or

more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F},

@samp{a} - @samp{f}).

@node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files

@comment  node-name,  next,  previous,  up

@section 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, @samp{0L} indicates a 64-bit integer value 0.

@node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files

@comment  node-name,  next,  previous,  up

@section Floating Point Values

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

decimal point, an optional leading sign character (@samp{+} or

@samp{-}), and an optional exponent. An exponent consists of the

letter @samp{E} or @samp{e}, an optional sign character, and a series

of one or more digits.

@node Boolean Values, String Values, Floating Point Values, Configuration Files

@comment  node-name,  next,  previous,  up

@section Boolean Values

Boolean values may have one of the following values: @samp{true},

@samp{false}, or any mixed-case variation thereof.

@node String Values, Comments, Boolean Values, Configuration Files

@comment  node-name,  next,  previous,  up

@section String Values

@cindex escape sequence

String values consist of arbitrary text delimited by double

quotes. Literal double quotes can be escaped by preceding them with a

backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f},

@samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the

usual meaning.

In addition, the @samp{\x} escape sequence is supported; this sequence

must be followed by @i{exactly two} hexadecimal digits, which represent an

8-bit ASCII value. For example, @samp{\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:

@itemize @bullet

@item

@code{"The quick brown fox jumped over the lazy dog."}

@item

@code{"The quick brown fox"} @*

@code{" jumped over the lazy dog."}

@item

@code{"The quick" /* comment */ " brown fox " // another comment} @*

@code{"jumped over the lazy dog."}

@end itemize

@page

@node Comments, Include Directives, String Values, Configuration Files

@comment  node-name,  next,  previous,  up

@section Comments

@cindex comment

Three types of comments are allowed within a configuration:

@itemize @bullet

@item Script-style comments. All text beginning with a @samp{#} character

to the end of the line is ignored.

@item C-style comments. All text, including line breaks, between a starting

@samp{/*} sequence and an ending @samp{*/} sequence is ignored.

@item C++-style comments. All text beginning with a @samp{//} sequence to the

end of the line is ignored.

@end itemize

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.

@node Include Directives, , Comments, Configuration Files

@comment  node-name,  next,  previous,  up

@section Include Directives

@cindex include directive

A configuration file may ``include'' the contents of another file

using an @i{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:

@b{@@include "}@i{filename}@b{"}

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

@samp{\\} and @samp{\"}, respectively.

For example, consider the following two configuration files:

@cartouche

@smallexample

# 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";

@end smallexample

@end cartouche

@cartouche

@smallexample

# file: test.cfg

info: @{

  name = "Winston Churchill";

  @@include "quote.cfg"

  country = "UK";

@};

@end smallexample

@end cartouche

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.

@node The C API, The C++ API, Configuration Files, Top

@comment  node-name,  next,  previous,  up

@chapter The C API

@tindex config_t

@tindex config_setting_t

This chapter describes the C library API. The type @i{config_t}

represents a configuration, and the type @i{config_setting_t} represents

a configuration setting.

The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are

macros defined as @code{(1)} and @code{(0)}, respectively.

@deftypefun void config_init (@w{config_t * @var{config}})

@deftypefunx void config_destroy (@w{config_t * @var{config}})

These functions initialize and destroy the configuration object @var{config}.

@code{config_init()} initializes the @i{config_t} structure pointed to by

@var{config} as a new, empty configuration.

@code{config_destroy()} destroys the configuration @var{config},

deallocating all memory associated with the configuration, but does not

attempt to deallocate the @i{config_t} structure itself.

@end deftypefun

@deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}})

This function reads and parses a configuration from the given

@var{stream} into the configuration object @var{config}. It returns

@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the

@code{config_error_text()}, @code{config_error_file()},

@code{config_error_line()}, and @code{config_error_type()} functions,

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

@end deftypefun

@deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})

This function reads and parses a configuration from the file named

@var{filename} into the configuration object @var{config}. It returns

@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the

@code{config_error_text()} and @code{config_error_line()} functions,

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

@end deftypefun

@deftypefun int config_read_string (@w{config_t * @var{config}}, @w{const char * @var{str}})

This function reads and parses a configuration from the string

@var{str} into the configuration object @var{config}. It returns

@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the

@code{config_error_text()} and @code{config_error_line()} functions,

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

@end deftypefun

@deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}})

This function writes the configuration @var{config} to the given

@var{stream}.

@end deftypefun

@deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})

This function writes the configuration @var{config} to the file named

@var{filename}. It returns @code{CONFIG_TRUE} on success, or

@code{CONFIG_FALSE} on failure.

@end deftypefun

@deftypefun {const char *} config_error_text (@w{const config_t * @var{config}})

@deftypefunx {const char *} config_error_file (@w{const config_t * @var{config}})

@deftypefunx int config_error_line (@w{const config_t * @var{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 @code{config_read()}, @code{config_read_string()}, or

@code{config_read_file()}. Storage for the strings returned by

@code{config_error_text()} and @code{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,

@code{config_error_file()} will return NULL.

@end deftypefun

@deftypefun config_error_t config_error_type (@w{const config_t * @var{config}})

@tindex config_error_t

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 @var{config_error_t} type is an enumeration with the

following values: @code{CONFIG_ERR_NONE}, @code{CONFIG_ERR_FILE_IO},

@code{CONFIG_ERR_PARSE}. These represent success, a file I/O error,

and a parsing error, respectively.

@end deftypefun

@deftypefun void config_set_include_dir (@w{config_t *@var{config}}, @w{const char *@var{include_dir}})

@deftypefunx {const char *} config_get_include_dir (@w{const config_t *@var{config}})

@code{config_set_include_dir()} specifies the include directory,

@var{include_dir}, relative to which the files specified in

@samp{@@include} directives will be located for the configuration

@var{config}. By default, there is no include directory, and all

include files are expected to be relative to the current working

directory. If @var{include_dir} is @code{NULL}, the default behavior

is reinstated.

For example, if the include directory is set to @file{/usr/local/etc},

the include directive @samp{@@include "configs/extra.cfg"} would include the

file @file{/usr/local/etc/configs/extra.cfg}.

@code{config_get_include_dir()} returns the current include directory for the

configuration @var{config}, or @code{NULL} if none is set.

@end deftypefun

@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}})

@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}})

@code{config_set_auto_convert()} enables number auto-conversion for

the configuration @var{config} if @var{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.

@code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number

auto-conversion is currently enabled for @var{config}; otherwise it

returns @code{CONFIG_FALSE}.

@end deftypefun

@deftypefun void config_set_default_format (@w{config_t * @var{config}}, @w{short @var{format}})

@deftypefunx short config_get_default_format (@w{config_t * @var{config}})

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

default external format for settings in the configuration

@var{config}. If a non-default format has not been set for a setting

with @code{config_setting_set_format()}, this configuration-wide

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

file or stream.

@end deftypefun

@deftypefun void config_set_tab_width (@w{config_t * @var{config}}, @w{unsigned short @var{width}})

@deftypefunx {unsigned short} config_get_tab_width (@w{const config_t * @var{config}})

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

width for the configuration @var{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 @var{width} spaces, or

by a single tab character if @var{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.

@end deftypefun

@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}})

@deftypefunx int config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long long * @var{value}})

@deftypefunx int config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{double * @var{value}})

@deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}})

@deftypefunx int config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{const char ** @var{value}})

These functions look up the value of the setting in the configuration

@var{config} specified by the path @var{path}. They store the value of

the setting at @var{value} and return @code{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

@var{value} unmodified and return @code{CONFIG_FALSE}.

Storage for the string returned by @code{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.

@end deftypefun

@deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}})

This function locates the setting in the configuration @var{config}

specified by the path @var{path}. It returns a pointer to the

@code{config_setting_t} structure on success, or @code{NULL} if the

setting was not found.

@end deftypefun

@deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}})

@deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}})

@deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}})

@deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}})

@deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}})

These functions return the value of the given @var{setting}. If the

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

@code{NULL} value is returned. Storage for the string returned by

@code{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.

@end deftypefun

@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{int @var{value}})

@deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}})

@deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}})

@deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}})

@deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}})

These functions set the value of the given @var{setting} to

@var{value}. On success, they return @code{CONFIG_TRUE}. If

the setting does not match the type of the value, they return

@code{CONFIG_FALSE}. @code{config_setting_set_string()} makes a copy

of the passed string @var{value}, so it may be subsequently freed or

modified by the caller without affecting the value of the setting.

@end deftypefun

@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}})

@deftypefunx int config_setting_lookup_int64 (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long long * @var{value}})

@deftypefunx int config_setting_lookup_float (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{double * @var{value}})

@deftypefunx int config_setting_lookup_bool (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}})

@deftypefunx int config_setting_lookup_string (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{const char ** @var{value}})

These functions look up the value of the child setting named

@var{name} of the setting @var{setting}. They store the value at

@var{value} and return @code{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 @var{value} unmodified

and return @code{CONFIG_FALSE}.