INI file

An INI file is a configuration file for computer software that consists of a text-based content with a structure and syntax comprising key–value pairs for properties, and sections that organize the properties.[1] The name of these configuration files comes from the filename extension INI, for initialization, used in the MS-DOS operating system which popularized this method of software configuration. The format has become an informal standard in many contexts of configuration, but many applications on other operating systems use different file name extensions, such as conf and cfg.[2]

INI
Filename extension
.ini
Internet media type
text/plain, application/textedit, zz-application/zz-winassoc-ini
Type of formatInitialization/Configuration File

History

The primary mechanism of software configuration in Windows was originally a text file format that comprised text lines with one key–value pair per line, organized into sections. This format was used for operating system components, such as device drivers, fonts, and startup launchers. INI files were also generally used by applications to store individual settings.[3]

The format was maintained in 16-bit Microsoft Windows platforms up through Windows 3.1x. Starting with Windows 95 Microsoft favored the use of the Windows Registry and began to steer developers away from using INI files for configuration. All subsequent versions of Windows have used the Windows Registry for system configuration, but applications built on the .NET Framework use special XML .config files. The initialization-file functions are still available in Windows and developers may still use them.

Besides Windows software, platform-agnostic software may use this file format for configuration. Some Unix-like config files also use a similar format. INI is human-readable and simple to parse, so it is a usable format for configuration files that do not require much greater complexity.

Examples of use

Desktop.ini files determine the display of directories in Windows, e.g., the icons for a directory.[4]

  • Git configuration files are similar to INI files.[5]
  • The freedesktop.org .desktop format, which provides a link to an application, uses a similar format.[6] Other examples with Unix-like system software include systemd service files[7] and pacman.conf.[8]
  • PHP uses the INI format for its "php.ini" configuration file in both Windows and Linux systems.[9][10]

Example

The following example file has two sections: one for the owner of the software, and one for a payroll database connection. Comments record the last person who modified the file and the reason for modification.

; 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"

Format

INI is an informal format, with features that vary from parser to parser (INI dialects). Some features are more shared across different parsers than others and can be considered as the hard core of the format (e.g. square brackets for sections, newlines for delimiting different nodes, etc.). Attempts to create parsers able to support as many dialects as possible exist,[11] and in its most advanced form the INI format is able to express a tree object with a power comparable to that of other structured formats (JSON, XML) using a more relaxed syntax.

Keys (properties)

The basic element contained in an INI file is the key or property. Every key has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign. In the Windows implementation the equal sign and the semicolon are reserved characters and cannot appear in the key. The value can contain any character. 

name = value

Leading and trailing whitespaces around the outside of the property name are ignored.

Sections

Keys may, but need not, be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All keys 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 at the end of the file. Sections cannot be nested.

[section]
key1 = a
key2 = b

Case sensitivity

Section and property names are case insensitive.[12]

Comments

Semicolons (;) at the beginning of the line indicate a comment. Comment lines are ignored.

; comment text

Order of sections and properties

The order of properties in a section and the order of sections in a file is irrelevant.

Varying features

As the INI file format is not rigidly defined, many parsers support features beyond the basics already described. The following is a list of some common features, which may or may not be implemented in any given program.

Global properties

Optional "global" properties may also be allowed, that are declared before any section is declared.[13]

Name/value delimiter

Some implementations allow a colon (:) as the name/value delimiter (instead of the equals sign). Whitespace is occasionally used in the GNU world.[11]

Hierarchy (section nesting)

Some parsers allow section nesting, using dots as path delimiters:

[section]
domain = example.com

[section.subsection]
foo = bar

In some cases relative nesting is supported too, where a leading dot expresses nesting to the previous section:[11]

[section]
domain = example.com

[.subsection]
foo = bar

Historically, ways for expressing nesting alternative to the dot have existed too (for example, IBM's driver file for Microsoft Windows devlist.ini, in which the backslash was used as nesting delimiter in the form of [A\B\C]; or Microsoft Visual Studio's AEMANAGR.INI file, which used a completely different syntax in the form of [A] and B,C,P = V). Some parsers did not offer nesting support at all and were hierarchy-blind, but nesting could still be partially emulated by exploiting the fact that [A.B.C] constitutes a unique identifier.

Comments

Some software supports the use of the number sign (#) as an alternative to the semicolon for indicating comments, especially under Unix, where it mirrors shell comments. The number sign might be included in the key name in other dialects and ignored as such. For instance, the following line may be interpreted as a comment in one dialect, but create a variable named "#var" in another dialect. If the "#var" value is ignored, it would form a pseudo-implementation of a comment.

#var = a

In some implementations, a comment may begin anywhere on a line after a space (inline comments), including on the same line after properties or section declarations.

var = a       ; This is an inline comment
foo = bar     # This is another inline comment

In others, including the WinAPI function GetPrivateProfileString, comments must occur on lines by themselves.

Duplicate names

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, it may be ignored (and the value discarded), or it may override the first occurrence (with the first value discarded). 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, as if they occurred contiguously. Others may abort, or ignore some aspect of the INI file.

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.

Escape characters

Some implementations offer varying support for an escape character, typically with the backslash (\) following the C syntax. 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 escape sequences is also seen.[14]

Common escape sequences
Sequence Meaning
\\ \ (a single backslash, escaping the escape character)
\' Apostrophe
\" Double quotes
\0 Null character
\a Bell/Alert/Audible
\b Backspace, Bell character for some applications
\t Tab character
\r Carriage return
\n Line feed
\; Semicolon
\# Number sign
\= Equals sign
\: Colon
\x???? Unicode character with hexadecimal code point corresponding to ????

Accessing INI files

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 "private" profile is contrasted with GetProfileString, which fetches from WIN.INI.)

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, sizeof(dbserver) / sizeof(dbserver[0]), ".\\dbsettings.ini");
  dbport = GetPrivateProfileInt("database", "port", 143, ".\\dbsettings.ini");
  // N.B. WritePrivateProfileInt() does not exist, only WritePrivateProfileString()
  return 0;
}

The third parameter of the GetPrivateProfileString function is the default value, which are "127.0.0.1" and 143 respectively in the two function calls above. If the argument supplied for this parameter is NULL, the default is an empty string, "".

Under Unix, many different configuration libraries exist to access INI files. They are often already included in frameworks and toolkits. Examples of INI parsers for Unix include GLib, iniparser and libconfini.

Comparison of INI parsers
Name Sections support Section nesting support Disabled entry recognition[15] Multi-line support[16] Value types Read/Write support Platform License Programming language Latest release version
Python ConfigParser[17][18] Yes Yes No Non-standard[19] Boolean, Number, String Read + Write *BSD, Linux, macOS, Windows PSFL C (implementation), Python (usage) 3.9.7[20]
GLib[21] Yes Yes No No Boolean, Number, String, Array Read + Write *BSD, Linux, macOS, Windows LGPL C 2.66.7 (February 11, 2021 (2021-02-11)) [±][22]

[23]

inifile[24] Yes No No No Boolean, Number, String Read + Write *BSD, Linux, macOS, Windows Apache Go 1.2.0[25]
inih[26] Yes No No Non-standard[27] Boolean, Number, String Read *BSD, Linux, macOS, Windows BSD C 53[28]
iniparser[29] Yes No No Yes Boolean, Number, String Read + Write *BSD, Linux, macOS, Windows MIT C 4.1[30]
Java (via java.util.Properties)[31] No No No Yes String Read + Write Platform-agnostic Dual-license: GPL version 2 with classpath exception,[32] and a proprietary license.[33] C (implementation), Java (usage) 21.0.0 LTS (September 19, 2023 (2023-09-19)) [±]

17.0.6 LTS (February 18, 2023 (2023-02-18)) [±]
11.0.17 LTS (October 18, 2022 (2022-10-18)[34]) [±]
8u351 LTS (October 18, 2022 (2022-10-18)[35]) [±]

libconfini[36] Yes Yes Yes Yes Boolean, Number, String, Array Read *BSD, Linux, macOS, Windows GPL C 1.16.2[37]
PHP (via parse_ini_file())[38] Yes Yes Yes No Number, String, Null Read Linux, macOS, Windows PHP License v3.01[39] C (implementation), PHP (usage) 8.2.11[40] Edit this on Wikidata (28 September 2023 (28 September 2023))
PyINI[41] Yes No Yes Yes Boolean, Number, String Read + Write Platform-agnostic GPL Python 1.0[42]
python-ini[43] Yes No No Yes Boolean, Number, String, Null Read + Write Platform-agnostic BSD Python 1.1.0
RudeConfig[44] Yes No No No Boolean, Number, String Read + Write Linux, Windows GPL C++ Discontinued – last version is 5.0.5, from November 2009[45]
Windows API Yes No No No Number, String, Struct Read + Write (non-destructive) Windows Proprietary C 22H2 (10.0.22621.2506) (October 26, 2023 (2023-10-26)[46]) [±]
Wine (implementation of Windows API) Yes No No No Number, String, Struct Read + Write (non-destructive) Linux, macOS, Windows LGPL C 8.0.2[47] Edit this on Wikidata 19 July 2023 (19 July 2023)
Rust configparser[48] Yes No No No Boolean, Number, String Read + Write *BSD, Linux, macOS, Windows MIT or LGPL v3.0+ Rust 3.0.2[48] 11 September 2022; 3 months ago
java-ini-parser[49] Yes No Yes Yes Boolean, Number, String Read + Write Platform-agnostic Apache Java 1.4[48] 29 December 2022; 3 days ago
Name Sections support Section nesting support Disabled entry recognition Multi-line support Value types Read/Write support Platform License Programming language Latest release version

File mapping

Initialization file mapping creates a mapping between an INI file and the Windows registry.[50][51] It was introduced with Windows NT and Windows 95 as a way to migrate from storing settings in classic .ini files to the new 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 below, 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 the directory:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

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
databaseUSR: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
nameJohn Doe
organizationAcme 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.

Alternatives

Starting with Windows 95, Microsoft began strongly promoting the use of the Windows registry over INI files.[52] INI files are typically limited to two levels (sections and properties) and do not handle binary data well. This decision however has not been immune to critiques, due to the fact that the registry is monolithic, opaque and binary, must be in sync with the filesystem, and represents a single point of failure for the operating system.[53]

Later XML-based configuration files 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.

More recently, data serialization formats, such as JSON, TOML, and YAML can serve as configuration formats. These three alternative formats can nest arbitrarily, but have a different syntax than the INI file. Among them, TOML most closely resembles INI, but the idea to make TOML deliberately compatible with a large subset of INI was rejected.[54]

The newest INI parsers however allow the same arbitrary level of nesting of XML, JSON, TOML, and YAML, offer equivalent support of typed values and Unicode, although keep the "informal status" of INI files by allowing multiple syntaxes for expressing the same thing.[55]

See also

References
  1. Microsoft TechNet: Configure an Ini File Item
  2. .conf initialization files
  3. Microsoft: Windows NT Workstation Resource Kit
  4. Codrut Neagu, "Why Are There Two Desktop.ini Files On My Desktop & What Do They Do?".
  5. "git-config CONFIGURATION FILE".
  6. "Basic format of the file". specifications.freedesktop.org.
  7. "systemd.service". www.freedesktop.org.
  8. "pacman.conf(5)". archlinux.org.
  9. Rasmus Lerdorf, Kevin Tatroe, Peter MacIntyre. "Programming PHP". Sections "parse_ini_file", "Extension INI Entries", etc.
  10. Christian Wenz. "PHP and MySQL Phrasebook". section "Parsing INI Files". quote: "... the INI file format ... was very widely used in the Windows world, but today also drives the configuration of software products like PHP. For instance, ... php.ini"
  11. libconfini's Library Function Manual
  12. This includes the Windows implementation. See "GetPrivateProfileString function". Microsoft Developer Network. Microsoft. Retrieved 2012-06-02.
  13. Apache Documentation for org.apache.commons.configuration2.INIConfiguration, The Apache Software Foundation
  14. Cloanto Implementation
  15. It is a common practice among authors of INI files to "comment out" unwanted entries in order to disable them, instead of removing them completely. See the key a in the following example:
    [section]<br />#a=a<br />b=b
  16. The standard syntax for line continuation refers here to the sequence of a backslash followed by line break, as implemented by iniparser, libconfini and java.util.Properties
  17. Fredrik Lundh. "Python Standard Library". 2001. Section "The ConfigParser Module". p. 143
  18. "ConfigParser - Configuration file parser".
  19. Following the syntax of the language it is designed to work with (Python), to span a node over multiple lines ConfigParser requires a deeper indentation in the lines that follow, instead of the more common backslash + line break (see: configparser — Configuration file parser)
  20. Python Documentation by Version
  21. GLib Key–value file parser
  22. Withnall, Philip (11 Feb 2021). "glib 2.66.7". GNOME ftp-release (Mailing list). Retrieved 12 February 2021.
  23. Releases · GNOME/glib
  24. inifile documentation
  25. Releases · inifile
  26. inih README
  27. Using indentation, explicitly following ConfigParser's approach (see the project's documentation for more information)
  28. Releases · benhoyt/inih
  29. iniparser documentation
  30. Releases · ndevilla/iniparser
  31. Properties (Java Platform SE 8)
  32. "OpenJDK: GPLv2 + Classpath Exception". Openjdk.java.net. 1989-04-01. Retrieved 2016-02-09.
  33. "BCL For Java SE". Oracle.com. 2013-04-02. Retrieved 2016-02-09.
  34. "JDK Releases". Oracle Corporation. Retrieved 2022-12-09.
  35. "JDK Releases". Oracle Corporation. Retrieved 2022-12-09.
  36. libconfini documentation
  37. Releases · madmurphy/libconfini
  38. PHP. "parse_ini_file() — Parse a configuration file". Official PHP documentation. Retrieved 2022-07-19.
  39. PHP License v3.01
  40. "Version 8.2.11".
  41. PyINI
  42. Tags · whoatemybutter / PyINI
  43. python-ini
  44. RudeConfig documentation
  45. Releases · RudeConfig
  46. "October 26, 2023—KB5031455 (OS Build 22621.2506) Preview". Microsoft Support. Microsoft.
  47. "Wine 8.0.2 Released". 19 July 2023. Retrieved 20 July 2023.
  48. "configparser on crates.io". crates.io. 2022-12-12. Archived from the original on 2022-12-12. Retrieved 2022-12-12.
  49. java-ini-parser github page
  50. Initialization Files and the Registry, Windows NT Workstation Resource Kit, Microsoft TechNet
  51. Administering the NT Registry, Managing the Windows NT Registry, Paul Robichaux, O'Reilly Media
  52. The System Registry
  53. Was The Windows Registry a Good Idea? – Coding Horror
  54. "Comment on ".INI compatibility is a worthy goal" issue on GitHub". GitHub.
  55. libconfini/README
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.