C++ libconfig

C++ libconfig


Libconfig is a simple library for processing structured configuration files.

It is used for reading, manipulating, and writing structured configuration files

It is more compact and more readable than XML. And unlike XML, it is type-aware, so it is not necessary to do string parsing in application code.

The library includes bindings for both the C and C++ languages.

The library features a fully reentrant parser and includes bindings for both the C and C++ programming languages.

It works on POSIX-compliant UNIX and UNIX-like systems (GNU/Linux, Mac OS X, FreeBSD), Android, and Windows (2000, XP and later).



Libconfig is distributed under the terms of the GNU Lesser General Public License. This license was chosen over the standard GNU license to allow libconfig to be used with non-free programs.


  • It is a fully re-entrant parser. Independent configurations can be parsed in concurrent threads at the same time.
  • It includes both C and C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.
  • It is 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.
  • It is a low-footprint implementation (just 37K for the C library and 76K for the C++ library) that is suitable for memory-constrained systems.


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.



Libconfig supports structured, hierarchical configurations. These configurations can be read from and written to files and manipulated in memory.

configuration consists of a group of settings, which associate names with values. A value can be one of the following:

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.

group, which is a collection of settings.

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.

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.


The class Config represents a configuration, and the class Setting represents a configuration setting. Note that by design, neither of these classes provides a public copy constructor or assignment operator. Therefore, instances of these classes may only be passed between functions via references or pointers.

The library defines a group of exceptions, all of which extend the common base exception ConfigException.

SettingTypeException is thrown when the type of a setting's value does not match the type requested.

The following example presents a concise way to look up three values at once and perform error handling if any of them are not found or are of the wrong type:


 Likewise, there are various other methods which can be studied in depth.


The functions in the library do not make use of global variables and do not maintain state between successive calls.

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.

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.

Libconfig does not natively support Unicode configuration files.