The INI file format is a standard for configuration files for some platforms or software. INI files are simple text files with a basic structure composed of "sections" and "properties".
They are a deprecated standard on the Windows operating system. The use of the "INI file" has been changed in Windows in favor of the registry, and deprecated in .NET in favor of XML .config files. The name "INI file" comes from the filename extension usually used, ".INI", that stands for "initialization". Sometimes a different file extension will be used instead of .ini, such as ".CFG", ".conf", or ".TXT".
Contents |
The basic element contained in an INI file is the property. Every property has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign.
name=value
Properties may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All properties 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]
Semicolons (;) at the beginning of the line indicate a comment. Comment lines are ignored.
; comment text
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.
Some rudimentary programs do not allow blank lines. Every line must therefore be a section head, a property, or a comment.
Interpretation of whitespace varies. Most implementations ignore leading and trailing whitespace around the outside of the property name. Some even ignore whitespace within values (for example, making "host name" and "hostname" equivalent). Some implementations also ignore leading and trailing whitespace around the property value; others consider all characters following the equals sign (including whitespace) to be part of the value.
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.
Some software supports the use of the pound 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 properties or section declarations. In others, including MS Windows' GetPrivateProfileString function, comments must occur on lines by themselves.
Most implementations only support having one property with a given name in a section. The second occurrence of a property 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 property names to implement multi-valued properties.
Interpretation of multiple section declarations with the same name also varies. In some implementations, duplicate sections simply merge their properties together, as if they occurred contiguously. Others may abort, or ignore some aspect of the INI file.
In most cases the order of properties in a section and the order of sections in a file is irrelevant, but implementations may vary.
Some implementations allow a colon (:) as the name/value delimiter (instead of the equals sign).
Most commonly, INI files have no hierarchy of sections within sections. Some files appear to have a hierarchical naming convention, however. For section A, subsection B, sub-subsection C, property P and value V, they may accept entries such as [A.B.C] and P=V (Windows' xstart.ini), [A\B\C] and P=V (the IBM Windows driver file devlist.ini), or [A] and B,C,P = V (Microsoft Visual Studio file AEMANAGR.INI).
It is unclear whether these are simply naming conventions that an application happens to use in order to give the appearance of a hierarchy, or whether the file is being read by a module that actually presents this hierarchy to the application programmer.
Optional "global" properties may also be allowed, that are declared before any section is declared.[1]
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 |
| \a | Bell/Alert/Audible |
| \b | Backspace, Bell character for some applications |
| \t | Tab character |
| \r | Carriage return |
| \n | Newline |
| \; | Semicolon |
| \# | Number sign |
| \= | Equals sign |
| \: | Colon |
| \x???? | Unicode character with hexadecimal codepoint corresponding to ???? |
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 Widgets Inc. [database] ; use IP address in case network name resolution is not working server=192.0.2.62 port=143 file = "payroll.dat"
Under Windows, the Profile API is the programming interface used to read and write settings from classic Windows .ini files. For example, the GetPrivateProfileString function retrieves a string from the specified section in an initialization file.
The following sample C program demonstrates reading property values from the above sample INI file (Let the name of configuration file be dbsettings.ini)
#include <Windows.h> int main(int argc, _TCHAR *argv[]) { _TCHAR dbserver[1000]; int dbport; GetPrivateProfileString("database", "server", "127.0.0.1", dbserver, 1000, "dbsettings.ini"); dbport = GetPrivateProfileInt("database", "port", 143, "dbsettings.ini"); return 0; }
Initialization File Mapping[2][3] creates a mapping between an INI file and the Registry. It was introduced with Windows NT and Windows 95 as a way to migrate from storing settings in classic .ini files to the new Windows Registry. File mapping traps the Profile API calls and, using settings from the IniFileMapping Registry section, directs reads and writes to appropriate places in the Registry.
Using the Example above, a string call could be made to fetch the name key from the owner section from a settings file called, say, dbsettings.ini. The returned value should be the string "John Doe":
GetPrivateProfileString("owner", "name", ... , "c:\\programs\\oldprogram\\dbsettings.ini");
INI mapping takes this Profile API call, ignores any path in the given filename and checks to see if there is a Registry key matching the filename under:
If this exists, it looks for an entry name matching the requested section. If an entry is found, INI mapping uses its value as a pointer to another part of the Registry. It then looks up the requested INI setting in that part of the Registry.
If no matching entry name is found and there is an entry under the (Default) entry name, INI mapping uses that instead. Thus each section name does not need its own entry.
| HKEY_LOCAL_MACHINE\Software\...\IniFileMapping\dbsettings.ini | |
|---|---|
| (Default) | @USR:Software\oldprogs\inisettings\all |
| database | USR:Software\oldprogs\inisettings\db |
So, in this case the profile call for the [owner] section is mapped through to:
| HKEY_CURRENT_USER\Software\oldprogs\inisettings\all | |
|---|---|
| name | John Doe |
| organization | Acme Products |
where the "name" Registry entry name is found to match the requested INI key. The value of "John Doe" is then returned to the Profile call. In this case, the @ prefix on the default prevents any reads from going to the dbsettings.ini file on disk. The result is that any settings not found in the Registry are not looked for in the INI file.
The "database" Registry entry does not have the @ prefix on the value; thus, for the [database] section only, settings in the Registry are taken first followed by settings in the dbsettings.ini file on disk.
Starting with Windows 95, Microsoft began strongly promoting the use of Windows registry over the INI file.
More recently, XML-based configuration files have become 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 typically limited to two levels (sections and properties) and do not handle binary data well. Additionally, data serialization formats, such as JSON and YAML can serve as configuration formats. These three alternative formats can nest arbitrarily, but have a more heavyweight syntax than the INI file.