The INI file format is a de facto standard for configuration files. INI files are simple text files with a basic structure. They are commonly associated with Microsoft Windows, but are also used on other platforms. The name "INI file" comes from the filename extension usually used, ".INI". Sometimes, files using the INI file format will use a different extension, such as ".CFG", ".conf", or ".TXT".
|
Format
- Parameters
The basic element contained in an INI file is the parameter. Every parameter has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign.
name = value
- Sections
Parameters may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All parameters after the section declaration are associated with that section. There is no explicit "end of section" delimiter; sections end at the next section declaration, or the end of the file. Sections may not be nested.
[section]
- Comments
Semicolons (;) indicate the start of a comment. Comments continue to the end of the line. Everything after the semicolon is ignored.
; comment text
Varying features
The INI file format is not well defined. Many programs support features beyond the basics described above. The following is a list of some common features, which may or may not be implemented in any given program.
- Whitespace
Interpretation of whitespace varies. Most implementations ignore leading and trailing whitespace around the outside of the parameter name. Some even ignore whitespace within value names (for example, making "host name" and "hostname" equivalent). Some implementations also ignore leading and trailing whitespace around the parameter value; others consider all characters following the equals sign (including whitespace) to be part of the value.
- Quoted values
Some implementations allow values to be quoted, typically using double quotes and/or apostrophes. This allows for explicit declaration of whitespace, and/or for quoting of special characters (equals, semicolon, etc.). The standard Windows function GetPrivateProfileString supports this, and will remove quotation marks that surround the values.
- Comments
Some software supports the use of the number sign (#) as an alternative to the semicolon for indicating comments. In some implementations, a comment may begin anywhere on a line, including on the same line after parameters or section declarations. In others, any comments must occur on lines by themselves.
- Backslashes and escapes
See "Escapes", in this article.
- Duplicate names
Most implementations only support having one parameter with a given name in a section. The second occurrence of a parameter name may cause an abort; the second occurrence may be ignored (and the value discarded); the second occurrence may override the first occurrence (discard the first value). Some programs use duplicate parameter names to implement multi-valued parameters. Interpretation of multiple section declarations with the same name also varies. In some implementations, duplicate sections simply merge their parameters together, as if they occurred contiguously. Others may abort or ignore some aspect of the INI file.
- Name/value delimiter
Some implementations allow a colon (:) as the name/value delimiter (instead of the equals sign).
Escapes
Some implementations also offer varying support for an escape character, typically with the backslash (\). Some support "line continuation", where a backslash followed immediately by EOL (end-of-line) causes the line break to be ignored, and the "logical line" to be continued on the next actual line from the INI file. Implementation of various "special characters" with sequences escapes is also seen.
| Sequence | Meaning |
|---|---|
| \\ | \ (a single backslash, escaping the escape character) |
| \0 | Null character |
| \t | Tab character |
| \r | Carriage return |
| \n | Newline |
| \; | Semicolon |
| \# | Number sign |
| \= | Equals sign |
| \: | Colon |
| \x???? | Unicode character with hexadecimal codepoint corresponding to ???? |
Example
Following is an example INI file for an imaginary program. It has two sections, one for the owner of the software, and one for a payroll database connection. Comments note who modified the file last, and why an IP address is used instead of a DNS name.
; last modified 1 April 2001 by John Doe
[owner]
name=John Doe
organization=Acme Products
[database]
server=192.0.2.42 ; use IP address in case network name resolution is not working
port=143
file = "acme payroll.dat"
Alternatives
Starting with Windows 95, Microsoft began strongly promoting the use of Windows registry over the INI file. More recently, XML-based configuration files have became a popular choice for encoding configuration in text files. XML allows arbitrarily complex levels and nesting, and has standard mechanisms for encoding binary data. INI files are limited to two levels (sections and parameters) and do not handle binary data well.
See also
External links
- http://www.cloanto.com/specs/ini.html Unofficial specification
