
   [support.jpg] [1]cloanto.com [default-1-sep.gif] [2]Products
   [default-1-sep.gif] [3]Download [default-1-sep.gif] [4]Shop
   [support-1-sep.gif] [5]Support [support-1-sep.gif] [6]Contact
   [default-1-sep.gif] [1x1-00.gif]
   [support-0-130x5.gif]
   Specs
   [7]Previous Page 
   [support-0-104x14.gif] [8]End of Page 

Cloanto Implementation of INI File Format

Abstract

   This document specifies a text-based file format for representing
   software configuration data in a format which is easily editable by
   humans and unambiguously readable by a simple automatic parser.

Introduction

   The format described here is an implementation of the ".INI File
   Format", as defined in the Microsoft Windows for Workgroups Resource
   Kit. Since the original Microsoft specification is generic, and
   implementations vary widely, we decided to document how the INI files
   and parsers used in Cloanto applications works. As far as possible,
   existing specifications and practices for character encoding and
   programming have been retained.

   Where this document says that an application "should" implement a
   certain feature in a certain way, it means that the Cloanto INI parser
   supports this feature as recommended here. Where this document says
   that a certain style "should" be avoided, but parsers "should" support
   it or ignore it, it means that authors of INI files should not use
   that style (the risk being incompatibility with slightly different INI
   parsers), but authors of parser software should support it or ignore
   it as indicated, rather than generate an error condition. In the
   following, "INI" refers to the file format as specified here.

Character Set

   The entire INI file, including section names, key names and data
   values is encoded using 8-bit characters in the ISO 8859-1 character
   set (of which 7-bit ASCII is a subset). Application-specific string
   values may store data using other character sets, and even binary
   data, as long as they are encoded as either ASCII or ISO 8859-1 text.
   ANSI C Escape sequences are used for the encoding of special
   characters in strings.

File Names

   If the INI file is to be stored or used on a Microsoft Windows system,
   the following characters should not be used in the file name, as they
   are not supported by older filing systems: "\", "/", ":", "*", "?",
   """ (double quote character), "<", ">" and "|".

   Additionally, certain file names are supported at the filing system
   level, and can be accessed by programs, but they are not accessible
   from certain shells and file manipulation programs. These names
   include: "COMx", "AUX", "LPTx", "PRN", "NUL" and "CON", and all
   variants with a "dot suffix". File names entirely consisting of dots
   (".", "..", etc.) are also "problem files".

   Where compatibility with older filing systems is important, short
   names ("8+3") should be used for directory and file names.

File Structure

   An INI file is an 8-bit text file divided into sections, each
   containing zero or more keys. Each key contains zero or more values.

   Example:

   [SectionName]

   keyname=value

   ;comment

   keyname=value, value, value ;comment

   Section names are enclosed in square brackets, and must begin at the
   beginning of a line.

   Section and key names are case-insensitive. In consideration of
   possible future upgrades from INI to XML, authors of INI files may
   want to use consistent and case-exact section and key names, as if INI
   parsers were case-sensitive (XML parsers are case-sensitive).

   Section and key names cannot contain spacing characters. The key name
   is followed by an equal sign ("=", decimal code 61), optionally
   surrounded by spacing characters, which are ignored.

   If the same section appears more than once in the same file, or if the
   same key appears more than once in the same section, then the last
   occurrence prevails.

   Multiple values for a key are separated by a comma followed by at
   least one spacing character.

   When a parser encounters an unrecognized section name, the entire
   section (with all its keys) should be skipped. Within a known section,
   only unrecognized keys should be skipped.

Spacing, Line Terminators and Comments

   Both Space (decimal code 32) and Horizontal Tab (HT, decimal code 9)
   are acceptable spacing characters.

   Lines are terminated by a CR (decimal code 13) or LF (decimal code 10)
   character. If CR+LF or LF+CR appear consecutively, they count as a
   single line terminator, generating one line, not two lines. A sequence
   consisting of CR+LF+CR+LF would however result in two lines, not one
   line. Where implementation-specific considerations do not advise
   otherwise, the recommended line terminator is a LF character.

   Comments are introduced by a semicolon character (";", decimal code
   59). Comments must begin at the beginning of a line or after a spacing
   character. Comments terminate at the end of the line.

   Parsers should treat HT (decimal code 9) characters as space
   characters (decimal code 32). Comments, empty lines, and spaces at the
   beginning of a line should be ignored. Parsers should also ignore
   binary characters other than HT, LF and CR, and treat an end of file
   like an end of line before continuing with specific end-of-file
   processing.

   Parsers should be tolerant towards spacing variations, such as in:

   [section name]

   keyname=value

   ; comment

   keyname = value, value , value ;comment

String Values

   String values may optionally be enclosed in quote characters (""",
   decimal code 34). String values beginning or ending with spaces, or
   containing commas or semicolons, must be enclosed in quotes. Quote and
   backslash ("\", decimal code 92) characters, as well as binary
   characters (decimal ranges 0..31, 127..159) appearing inside strings
   must be encoded using the [9]escape sequences described in this
   document.

   The default character set for text appearing inside string values is
   ISO 8859-1. Applications may define certain sections and/or keys to
   store text which, from the application side, results as being encoded
   using different character sets, or even binary data. However, the
   string data appearing in the INI file must be encoded as ISO 8859-1
   text, using escape sequences as necessary, so as to be compatible with
   INI parsers.

Path Values

   Path values are identical to String values, with the exception that
   escape sequences introduced by the backslash character are not
   supported. Path values are used to represent filing system and
   registry paths, where for clarity it is not desirable to use double
   backslash characters ("\\") to indicate backslash characters inside
   paths. This means that a path like "C:\readme.txt" would remain
   unchanged (whereas it would have to be indicated as "C:\\readme.txt"
   in a String field).

Numerical Values

   In numerical values, the period (".", decimal code 46) is the only
   valid decimal separator. Leading zeros are optional (e.g. "0.5",
   "000.5" and ".5" are all valid representations for the same value,
   i.e. 0.5). For consistency, one leading zero (e.g. "0.5") is the
   preferred format to represent values smaller than 1.

   Trailing zeroes may be used on an application-dependent basis, for
   example to express precision (e.g. "0.50", opposed to "0.5", may
   indicate that the smallest currency unit is equal to fifty "cents", as
   opposed to five "tenths" of the full unit, and "1.234000" may indicate
   to use a precision of six decimal digits in partial or total results).

Escape Sequences

   Escape sequences, consisting of a backslash followed by a lower case
   letter or by a combination of digits, should be used to encode binary
   data and certain other special characters and character combinations.
   The result of each escape sequence is parsed as if it were a single
   character. Quote and backslash characters inside a string must always
   be preceded by a backslash character. Binary data in key values should
   be encoded using one of the octal or hexadecimal notations described
   below.

                              Escape Sequence

   Represents

   \a

   Bell (alert)

   \b

   Backspace

   \f

   Form feed

   \n

   New line

   \r

   Carriage return

   \t

   Horizontal tab

   \v

   Vertical tab

   \'

   Single quotation mark

   \"

   Double quotation mark

   \\

   Backslash

   \?

   Question mark

   \ooo

   ASCII character in octal notation

   \xhhh

   ASCII character in hexadecimal notation

   \ at end of line

   Continuation character

   The octal (ooo) and hexadecimal (hhh) streams can be of any length,
   and terminate as soon as the first non-octal or non-hexadecimal
   character is encountered. For example, the digit 8 would terminate an
   octal stream, and be interpreted as a separate character. Both
   uppercase and lowercase letters A..F are acceptable for hexadecimal.

   The use of "\'" and "\?" is entirely optional (unlike "\"", "\\" and
   binary characters), and implemented only for compatibility with ANSI
   C.

   Nonprinting sequences, such as "\a" and "\f", produce device-dependent
   results. Applications should ignore such codes if they are not
   applicable to the context. Applications should try to implement at
   least "\n" and "\t". A simple implementation for "\t" could be to
   replace it with eight space characters, or with one space character,
   depending on the intended use.

   All escape sequences consisting of a backslash character plus a
   character that does not appear in the table listed above are ignored.
   For example, "\A" or "\c" would simply be skipped by a parser.

   A backslash followed by any combination of CR and LF characters is
   considered a continuation character. In this case, the backslash is
   ignored, and the new line beginning after the sequence of CR and LF
   characters ends is treated as the continuation of the previous line.
   For line-counting purposes (e.g. to report an error in a certain
   line), however, the lines are treated as separate.

INI Files on Web Servers

   A few special considerations apply to INI files hosted on web servers.

   MIME Media types instruct web clients how to handle files received
   from a server. The HTTP protocol specification requires that the web
   server reports the MIME type for content. By default, servers like
   Internet Information Services 6.0 serve only files with extensions
   registered in their MIME type list. If the web server does not already
   have a MIME type entry for INI files, we recommend that it be added by
   setting the MIME type for extension ".ini" to
   "application/octet-stream".

   If a security filter such as Microsoft Urlscan is running on the web
   server to control client requests, it must be configured to allow the
   data files to be fetched (e.g. by adding .ini to the [AllowExtensions]
   section and removing it from [DenyExtensions] in
   %SystemRoot%\System32\Inetsrv\Urlscan\URLScan.ini). If it is not
   possible to change the security settings, the names of the data files
   should be changed (e.g. replacing ".ini" with ".txt").

INI in Autorun.inf Files

   AutoRun is a feature of the Microsoft Windows operating system which
   makes it possible to automatically run a program (e.g. a menu window,
   a setup procedure, etc.) when a medium is inserted in the drive. When
   a medium is inserted in an AutoRun-enabled drive, the system looks for
   a file named "autorun.inf". For maximum compatibility both with
   Windows (especially older versions) and with third-party parser
   applications, it is recommended that:
     * No comments should be used in the file
     * No space characters should be used around "="
     * No space characters should be used in Open and Icon paths (not
       even if the paths are quoted)
     * Line terminators should be CR+LF
     _________________________________________________________________

   Specification Information
   Home Page: [10]http://www.cloanto.com/specs/ini.html
   Version: 1.3 (2003-09-04)
   Status: Unmodified spec is free to distribute, free to implement
   Last Page Update: 2003-09-04
   Your [11]feedback is always appreciated. It is safe to link to this
   page.
   [12]Legal and Privacy Notes [13]Top of Page 
   [1x1-ff.gif] [1x1-ff.gif] [1x1-ff.gif]

References

   1. http://cloanto.com/
   2. http://cloanto.com/products/
   3. http://cloanto.com/download/
   4. http://cloanto.com/shop/
   5. http://cloanto.com/support/
   6. http://cloanto.com/contact/
   7. javascript:history.back(-1)
   8. http://cloanto.com/specs/ini.html#end
   9. http://cloanto.com/specs/ini.html#escapesequences
  10. http://www.cloanto.com/specs/ini.html
  11. http://cloanto.com/contact/
  12. http://cloanto.com/notes/
  13. http://cloanto.com/specs/ini.html#top
