Skip to main content.
IBAN   NL79 ABNA 0477 3565 08
EU-VAT NL170160656B01
Chamber of Commerce 32041148
http://www.compuphase.com
Eerste Industriestraat 19-21
1401VL  Bussum
tel. +31 35 693 9261
info@compuphase.com
CompuPhase

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.8).

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, a liberal license that permits use in commercial projects.

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.1, 25 April 2008
Initial release
Version 0.2, 28 April 2008
Example glue files for EFSL and FatFs.
Improved portability.
Version 0.3, 19 May 2008
Corrected issue #1 (does not compile with Linux because string comparison function must be called strncasecmp() instead of strnicmp()).
Minor reformatting of the documentation (no new contents).
Version 0.4, 28 July 2008
Support for values (in name/value pairs) that are between double quotes.
Private implementation of strnicmp() for those platforms that lack the function.
Version 0.5, 30 September 2008
Section and key enumeration.
General improvements of the documentation (index, internal links).
Version 0.6, 2 March 2009
The functions for writing a value or string into an INI file now first check whether that setting is already present. If it is present and the setting already has the correct (new) value, the functions just return (with a "success" code). This skips the normal "copy-on-modify" routine, which is redundant if there is, in fact, no modification.
Switch to the Apache License 2.0.
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).
Correction for issue #3 (getkey() returns the whole line instead of just the key).
Improved portability. Reduced compiler warnings (on GNU GCC in the highest warning level); issues #5 and #6.
Improved the sections on configuration and building minIni in the documentation.
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.

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.