Class (GI Struct)

GLib-2.0 ▶ GLib ▶ KeyFile

GLib.KeyFile parses .ini-like config files.

GLib.KeyFile lets you parse, edit or create files containing groups of key-value pairs, which we call ‘key files’ for lack of a better name. Several freedesktop.org specifications use key files. For example, the Desktop Entry Specification and the Icon Theme Specification.

The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments.

# this is just an example
# there can be comments before the first group

[First Group]

Name=Key File Example\tthis value shows\nescaping

# localized strings are stored in multiple key-value pairs
Welcome=Hello
Welcome[de]=Hallo
Welcome[fr_FR]=Bonjour
Welcome[it]=Ciao

[Another Group]

Numbers=2;20;-200;0

Booleans=true;false;true;true

Lines beginning with a # and blank lines are considered comments.

Groups are started by a header line containing the group name enclosed in [ and ], and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group.

Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form key[locale]=value, with a locale identifier of the form lang_COUNTRY@MODIFIER where COUNTRY and MODIFIER are optional. As a special case, the locale C is associated with the untranslated pair key=value (since GLib 2.84). Space before and after the = character is ignored. Newline, tab, carriage return and backslash characters in value are escaped as \n, \t, \r, and \\\\, respectively. To preserve leading spaces in values, these can also be escaped as \s.

Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically ; or ,. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash.

This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important differences:

  • .ini files use the ; character to begin comments, key files use the # character.

  • Key files do not allow for ungrouped keys meaning only comments can precede the first group.

  • Key files are always encoded in UTF-8.

  • Key and Group names are case-sensitive. For example, a group called [GROUP] is a different from [group].

  • .ini files don’t have a strongly typed boolean entry type, they only have GetProfileInt(). In key files, only true and false (in lower case) are allowed.

Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged together. Another difference is that keys and group names in key files are not restricted to ASCII characters.

Here is an example of loading a key file and reading a value:

g_autoptr(GError) error = NULL;
g_autoptr(GKeyFile) key_file = g_key_file_new ();

if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
  {
    if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
      g_warning ("Error loading key file: %s", error->message);
    return;
  }

g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
if (val == NULL &&
    !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
  {
    g_warning ("Error finding key in key file: %s", error->message);
    return;
  }
else if (val == NULL)
  {
    // Fall back to a default value.
    val = g_strdup ("default-value");
  }

Here is an example of creating and saving a key file:

g_autoptr(GKeyFile) key_file = g_key_file_new ();
const gchar *val = …;
g_autoptr(GError) error = NULL;

g_key_file_set_string (key_file, "Group Name", "SomeKey", val);

// Save as a file.
if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
  {
    g_warning ("Error saving key file: %s", error->message);
    return;
  }

// Or store to a GBytes for use elsewhere.
gsize data_len;
g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
if (data == NULL)
  {
    g_warning ("Error saving key file: %s", error->message);
    return;
  }
g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
Index

Constructors

constructor

Properties

$gtype

Methods

get_boolean get_boolean_list get_comment get_double get_double_list get_groups get_int64 get_integer get_integer_list get_keys get_locale_for_key get_locale_string get_locale_string_list get_start_group get_string get_string_list get_uint64 get_value has_group load_from_bytes load_from_data load_from_data_dirs load_from_dirs load_from_file remove_comment remove_group remove_key save_to_file set_boolean set_boolean_list set_comment set_double set_double_list set_int64 set_integer set_integer_list set_list_separator set_locale_string set_locale_string_list set_string set_string_list set_uint64 set_value to_data unref error_quark new

Constructors

Properties

$gtype: GType<GLib.KeyFile>

Methods

  • Returns the value associated with key under group_name as a boolean.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as a boolean then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns boolean

    the value associated with the key as a boolean, or false if the key was not found or could not be parsed.

  • Returns the values associated with key under group_name as booleans.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as booleans then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns boolean[]

    the values associated with the key as a list of booleans, or NULL if the key was not found or could not be parsed. The returned list of booleans should be freed with GLib.free when no longer needed.

  • Retrieves a comment above key from group_name.

    If key is NULL then comment will be read from above group_name. If both key and group_name are NULL, then comment will be read from above the first group in the file.

    Note that the returned string does not include the # comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break.

    Parameters

    • Optionalgroup_name: string

      a group name, or NULL to get a top-level comment

    • Optionalkey: string

      a key, or NULL to get a group comment

    Returns string

    a comment that should be freed with GLib.free

  • Returns the value associated with key under group_name as a double.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as a double then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number

    the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed.

  • Returns the values associated with key under group_name as doubles.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as doubles then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number[]

    the values associated with the key as a list of doubles, or NULL if the key was not found or could not be parsed. The returned list of doubles should be freed with GLib.free when no longer needed.

  • Returns all groups in the key file loaded with key_file.

    The array of returned groups will be NULL-terminated, so length may optionally be NULL.

    Returns [string[], number]

    a newly-allocated NULL-terminated array of strings. Use GLib.strfreev to free it.

  • Returns the value associated with key under group_name as a signed 64-bit integer.

    This is similar to GLib.KeyFile.get_integer but can return 64-bit results without truncation.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number

    the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed.

  • Returns the value associated with key under group_name as an integer.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the value associated with key cannot be interpreted as an integer, or is out of range for a gint, then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number

    the value associated with the key as an integer, or 0 if the key was not found or could not be parsed.

  • Returns the values associated with key under group_name as integers.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. Likewise, if the values associated with key cannot be interpreted as integers, or are out of range for gint, then GLib.KeyFileError.INVALID_VALUE is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number[]

    the values associated with the key as a list of integers, or NULL if the key was not found or could not be parsed. The returned list of integers should be freed with GLib.free when no longer needed.

  • Returns all keys for the group name group_name.

    The array of returned keys will be NULL-terminated, so length may optionally be NULL. If the group_name cannot be found, GLib.KeyFileError.GROUP_NOT_FOUND is returned.

    Parameters

    • group_name: string

      a group name

    Returns [string[], number]

    a newly-allocated NULL-terminated array of strings. Use GLib.strfreev to free it.

  • Returns the value associated with key under group_name translated in the given locale if available.

    If locale is C then the untranslated value is returned (since GLib 2.84).

    If locale is NULL then the current locale is assumed.

    If locale is to be non-NULL, or if the current locale will change over the lifetime of the GLib.KeyFile, it must be loaded with GLib.KeyFileFlags.KEEP_TRANSLATIONS in order to load strings for all locales.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. If the value associated with key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • Optionallocale: string

      a locale identifier or NULL to use the current locale

    Returns string

    a newly allocated string or NULL if the specified key cannot be found.

  • Returns the values associated with key under group_name translated in the given locale if available.

    If locale is C then the untranslated value is returned (since GLib 2.84).

    If locale is NULL then the current locale is assumed.

    If locale is to be non-NULL, or if the current locale will change over the lifetime of the GLib.KeyFile, it must be loaded with GLib.KeyFileFlags.KEEP_TRANSLATIONS in order to load strings for all locales.

    If key cannot be found then GLib.KeyFileError.KEY_NOT_FOUND is returned. If the values associated with key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array is NULL-terminated, so length may optionally be NULL.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • Optionallocale: string

      a locale identifier or NULL to use the current locale

    Returns string[]

    a newly allocated NULL-terminated string array or NULL if the key isn’t found. The string array should be freed with GLib.strfreev.

  • Returns the name of the start group of the file.

    Returns string

    The start group of the key file.

  • Returns the value associated with key under group_name as an unsigned 64-bit integer.

    This is similar to GLib.KeyFile.get_integer but can return large positive results without truncation.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    Returns number

    the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed.

  • Looks whether the key file has the group group_name.

    Parameters

    • group_name: string

      a group name

    Returns boolean

    true if group_name is a part of key_file, false otherwise.

  • Loads a key file from memory into an empty GLib.KeyFile structure.

    If the object cannot be created then a [error@GLib.KeyFileError is returned.

    Parameters

    • data: string

      key file loaded in memory

    • length: number

      the length of data in bytes (or (gsize)-1 if data is nul-terminated)

    • flags: KeyFileFlags

      flags from GLib.KeyFileFlags

    Returns boolean

    true if a key file could be loaded, false otherwise

  • Looks for a key file named file in the paths specified in search_dirs, loads the file into key_file and returns the file’s full path in full_path.

    search_dirs are checked in the order listed in the array, with the highest priority directory listed first. Within each directory, file is looked for. If it’s not found, - characters in file are progressively replaced with directory separators to search subdirectories of the search directory. If the file has not been found after all - characters have been replaced, the next search directory in search_dirs is checked.

    If the file could not be found in any of the search_dirs, GLib.KeyFileError.NOT_FOUND is returned. If the file is found but the OS returns an error when opening or reading the file, a GLib.FileError is returned. If there is a problem parsing the file, a GLib.KeyFileError is returned.

    Parameters

    • file: string

      a relative path to a filename to open and parse

    • search_dirs: string[]

      NULL-terminated array of directories to search

    • flags: KeyFileFlags

      flags from GLib.KeyFileFlags

    Returns [boolean, string]

    true if a key file could be loaded, false otherwise

  • Removes a comment above key from group_name.

    If key is NULL then comment will be removed above group_name. If both key and group_name are NULL, then comment will be removed above the first group in the file.

    Parameters

    • Optionalgroup_name: string

      a group name, or NULL to get a top-level comment

    • Optionalkey: string

      a key, or NULL to get a group comment

    Returns boolean

    true if the comment was removed, false otherwise

  • Removes the specified group, group_name, from the key file.

    Parameters

    • group_name: string

      a group name

    Returns boolean

    true if the group was removed, false otherwise

  • Removes key in group_name from the key file.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key name to remove

    Returns boolean

    true if the key was removed, false otherwise

  • Associates a new boolean value with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: boolean

      true or false

    Returns void

  • Associates a list of boolean values with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • list: boolean[]

      an array of boolean values

    Returns void

  • Places a comment above key from group_name.

    If key is NULL then comment will be written above group_name. If both key and group_name are NULL, then comment will be written above the first group in the file.

    Passing a non-existent group_name or key to this function returns false and populates error. (In contrast, passing a non-existent group_name or key to GLib.KeyFile.set_string creates the associated group name and key.)

    Note that this function prepends a # comment marker to each line of comment.

    Parameters

    • group_name: string

      a group name, or NULL to write a top-level comment

    • key: string

      a key, or NULL to write a group comment

    • comment: string

      a comment

    Returns boolean

    true if the comment was written, false otherwise

  • Associates a new double value with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: number

      a double value

    Returns void

  • Associates a list of double values with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • list: number[]

      an array of double values

    Returns void

  • Associates a new integer value with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: number

      an integer value

    Returns void

  • Associates a new integer value with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: number

      an integer value

    Returns void

  • Associates a list of integer values with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • list: number[]

      an array of integer values

    Returns void

  • Sets the character which is used to separate values in lists.

    Typically ; or , are used as separators. The default list separator is ;.

    Parameters

    • separator: number

      the separator

    Returns void

  • Associates a string value for key and locale under group_name.

    If the translation for key cannot be found then it is created.

    If locale is C then the untranslated value is set (since GLib 2.84).

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • locale: string

      a locale identifier

    • string: string

      a string

    Returns void

  • Associates a list of string values for key and locale under group_name.

    If locale is C then the untranslated value is set (since GLib 2.84).

    If the translation for key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • locale: string

      a locale identifier

    • list: string[]

      a NULL-terminated array of locale string values

    Returns void

  • Associates a new string value with key under group_name.

    If key cannot be found then it is created. If group_name cannot be found then it is created. Unlike GLib.KeyFile.set_value, this function handles characters that need escaping, such as newlines.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • string: string

      a string

    Returns void

  • Associates a list of string values for key under group_name.

    If key cannot be found then it is created. If group_name cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • list: string[]

      an array of string values

    Returns void

  • Associates a new integer value with key under group_name.

    If key cannot be found then it is created.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: number

      an integer value

    Returns void

  • Associates a new value with key under group_name.

    If key cannot be found then it is created. If group_name cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use GLib.KeyFile.set_string.

    Parameters

    • group_name: string

      a group name

    • key: string

      a key

    • value: string

      a string

    Returns void

  • Outputs key_file as a string.

    Note that this function never reports an error.

    Returns [string, number]

    a newly allocated string holding the contents of the key file

  • Decreases the reference count of key_file by 1.

    If the reference count reaches zero, frees the key file and all its allocated memory.

    Returns void