minIni - a minimal INI file parser

Skip to main content (skip navigation menu)






minIni - a minimal INI file parser

 

minIni is a programmer's library to read and write "INI" files in embedded systems. minIni takes little resources and can be configured for various kinds of file I/O libraries. minIni provides functionality for reading, writing and deleting keys from an INI file, all in 650 lines of (commented) source code (version 0.9).

The principal purpose for minIni is to be used on embedded systems that run on an RTOS (or even without any operating system). minIni requires that such a system provides a kind of storeage and file I/O system, but it does not require that this file I/O system is compatible with the standard C/C++ library --indeed, the standard library is often too big and resource-hungry for embedded systems.

If you wish to know more about minIni, please see the manual that is in the source code archive.

Downloads & license

The minIni library is distributed under the Apache License, version 2.0, plus an exception clause to explicitly permit static linking of the library to commercial applications.

INI file syntax

INI files have a simple syntax with name/value pairs in a plain text file. The name must be unique (per section) and the value must fit on a single line. INI files are commonly separated into sections --in minIni, this is optional. A section is a name between square brackets, like "[Network]" in the example below. 

[Network]
hostname=My Computer
address=dhcp
dns = 192.168.1.1

In the API and in this documentation, the "name" for a setting is denoted as the key for the setting. The key and the value are separated by an equal sign ("="). minIni supports the colon (":") as an alternative to the equal sign for the key/value delimiter.

Leading a trailing spaces around values or key names are removed. If you need to include leading and/or trailing spaces in a value, put the value between double quotes. The ini_gets function (from the minIni library, see the minIni manual) strips off the double quotes from the returned value. Function ini_puts() adds double quotes if the value to write contains trailing white space (or special characters).

minIni ignores spaces around the "=" or ":" delimiters, but it does not ignore spaces between the brackets in a section name. In other words, it is best not to put spaces behind the opening bracket "[" or before the closing bracket "]" of a section name.

Comments in the INI must start with a semicolon (";") or a hash character ("#"), and run to the end of the line. A comment can be a line of its own, or it may follow a key/value pair (the "#" character and trailing comments are extensions of minIni).

Adapting minIni to a file system

The minIni library must be configured for a platform with the help of a so-called "glue file". This glue file contains macros (and possibly functions) that map file reading and writing functions used by the minIni library to those provided by the operating system. The glue file must be called "minGlue.h".

To get you started, the minIni distribution comes with the following example glue files:

Multi-tasking

The minIni library does not have any global variables and it does not use any dynamically allocated memory. Yet, the library should not be considered "thread-safe" or re-entrant, because it implicitly uses a particular shared resource: the file system.

Multiple tasks reading from an INI file do not pose a problem. However, when one task is writing to an INI file, no other tasks should access this INI file --neither for reading, nor for writing. It might be easier, in the implementation, to serialize all accesses of the INI file.

The first advise in protecting resources from concurrent access in a multi-tasking environment is to avoid sharing resources between tasks. If only a single task uses a resource, no semaphore protection is necessary and no priority inversion or deadlock problems can occur. This advise also applies to the minIni library. If possible, make a single task the "owner" of the INI file and create a client/server architecture for other tasks to query and adjust settings.

If the INI file must be shared between tasks (and at least one of the tasks writes to the INI file), you need to write wrappers around the functions of the minIni library that block on a mutex or binary semaphore.

History

Version 0.9, 6 July 2010
Minor corrections, notably regarding the C++ interface (with thanks to Lieven de Cock) and the FatFS / Tiny-FatFS glue file (with thanks to Andreas Wetzel).
C++ methods to delete a section or key from an INI file, because "references" cannot be NULL.
The documentation is updated, especially regarding the C++ interface.
Nota Bene: some macros (for configuring the minIni library) were renamed; please see the updated manual for details.
Version 0.8, 27 October 2009
Corrected updating of a key when the existing key has space characters around the "="; issue #9.
Trailing comments (behind a section) are now allowed; issue #8.
When comment characters or trailing white space exists in a value, that value is now automatically put between quotes (when reading, the quotes are automatically removed). Double quotes in a string are now escaped (when writing) and restored when reading.
Version 0.7, 6 May 2009
Added a C++ class (contributed by Steven Van Ingelgem; issue #2).
Added a read-only capability (contributed by Luca Bassanello).
Corrections, improved portability.
Version 0.6, 2 March 2009
Reduce (redundant) writes (when writing unmodified settings back).
Version 0.5, 30 September 2008
Section and key enumeration.
Version 0.4, 28 July 2008
Support for values (in name/value pairs) that are between double quotes.
Version 0.3, 19 May 2008
Bug fix release.
Version 0.2, 28 April 2008
Example glue files for EFSL and FatFs; improved portability.
Version 0.1, 25 April 2008
Initial release

Acknowledgement

Back in 2003 I was maintaining an IDE (for the authoring language EGO), which stores project information in INI files. Some projects grew large and crossed the 32 kiB limit that Microsoft Windows 95 and Windows 98 (and Windows ME) imposed on INI files (and back then, we were not prepared to drop support for Windows 98 yet). So I picked up the source code from the article "Multiplatform .INI Files" by Joseph J. Graf in the March 1994 issue of Dr. Dobb's Journal.

The comment at the start of my implementation of the code from Joseph Graf's article contains the note "This release comes close to a complete re-write". There were quite a few bugs in the original code. We also needed extensions such as deleting keys, and enumerating keys and sections, that the original code lacked.

In turn, minIni is derived from my re-write of the Joseph Graf's code --this time reducing the size and memory requirements of the library, plus changes to increase the portability.

Exception clause to the Apache License version 2.0

As a special exception to the Apache License 2.0 (and referring to the definitions in Section 1 of that license), you may link, statically or dynamically, the "Work" to other modules to produce an executable file containing portions of the "Work", and distribute that executable file in "Object" form under the terms of your choice, without any of the additional requirements listed in Section 4 of the Apache License 2.0. This exception applies only to redistributions in "Object" form (not "Source" form) and only if no modifications have been made to the "Work".