mtconnect_adapter.zip

minIni

Version 0.7

May 2009

minIni is a programmer’s library to read and write “INI” files in embedded systems. minIni

takes little reso urces and can be configured for various kinds of file I/O libra ries.

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 i t does not require that this file I/O system is compatible with

the standard C/C

library —indeed, the standard library is of ten too big and resource-hungry

Using minIni . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

The “glue” file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Multi-tasking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Key and section enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Function reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

A: Example glue files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

B: License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

ITB CompuPhase

 Copyright 2008–2009, ITB CompuPhase; Eerste Industriestraat 19–21 Bussum, The Netherlands (Pays Bas);

voice: (+31)-(0)35 6939 261; fax: (+31)-(0)35 6939 293

e-mail: info@compuphase.com; homepage: http://www.compuphase.com

The minIni library was derived in part from the article “Multiplatform .INI Files” by Joseph J. Graf in the March

1994 issue of Dr. Dobb’s Journal.

The examples and programs in this manual have been included for their instructional value. They have been tested

with care, but are not guaranteed for any particular purpose.

Although the main feature of minIni is that it is small and minim al, it has a few other features:

⋄ minIni supports reading keys that are outside a s ection, and it thereby supports configuration

⋄ You may use a colo n to separate key and value; the colon is equivalent to the equal sign. That

⋄ The hash character (“#”) is an alternative for the semicol on to start a com ment line.

⋄ Leading and trailing white space around key names and values is ignored.

⋄ Section and key name co mparisons are ca s e insensitive (similar to Microsoft Windows).

⋄ Section and key enumeration are supported.

⋄ You can optionally s et t he line terminati on (fo r text files) that minIni will use. (This is a

Listing: Example INI file

In t he 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 lea ding

and/or trailing spaces in a value, put the value between double quotes. The ini gets function

The first step in using minIni is making sure that it compiles. The library consists of only one

C file and two header files, so the amount of configuration to do is minimal. If you cannot

use the standard C/C

++

library, there is, however, a configuration file (or “glue” file) that you

must make or customize. This file is explained in t he next section. The minIni distribution

comes with a default configuration file that maps to the standard C library (specifically the file

I/O functions from the “stdio” package) and example glue files for two embedded file system

libaries for embedded systems —see appendix A of this ma nual.

Once you have a good glue file, you can add the source file of minIni to your project and include

the header file “minIni.h” in your source code files. In your source code, you can then use the

four functions tha t the minIni library provides to read text and values from ini files and to write

minIni uses string functions from the standard C/C

++

library, including one function that is

A notabl e limitation of minIni is that there i s a (fixed) maximum length of a line that can be

read from an ini file. This maximum length is configurable (at compile-time, not at run-time)

and it may be short on embedded systems —see page 3.

When running in an Unicode environment or when moving the ini file across platfo rms, there

may be other considerations concerning the use of minIni –see the relevant sections in this

chapter, specifically page 4.

The “glue” file

The minIni library must be configured for a platform wit h the help o f a so-called “glue file”. This

glue file contains macros (and possibly functions) that map file rea ding and writing functions

used by the minIni library to those provided by the operating system. The glue file must be

The minIni source code requires f unctions from a file I/O library to perform the actual reading

and writing. This can be any li brary; minIni does not rely on the availability of a standard C

full operating systems, separating the file I/O from the ini format parsing carries advantages,

because it allows you to cache the ini file and t hereby enhance performance.

The functions that you need to implement, or map to standard file I/O functions are:

Listing: Functions to map in the “glue file”

All functions should return zero on fail ure and a non-zero value on success. For examples of

“implementations” for the above functions, see the appendix A.

If you are not using the standard C/C

file I/O library, chances are that you need a different

handle or “structure” to identify the storeage than the ubiquitous “FILE*” type. If this is t he

case, you must define the type that minIni uses in the glue file.

The minIni functions will declare variables of this type and pass these variables to sub-functions

(including the glue interface functions) by reference.

The above macro limit s the line length of the ini files supported by minIni to 512 characters.

The temporary file is onl y used when w riting to ini files. The minIni routines copy/change

the ini file to a temporary file and then rename that temporary file to the original file. This

approach uses the least amount of memory. The path name of the temporary file is the same as

the input file, but with the last character set to a tilde (“~”).