Resource Config File Support: libxfce4util Reference Manual

## Resource Config File Support Resource Config File Support — functions for reading and writing resource config files. |

## Functions

XfceRc * | xfce_rc_simple_open ()
XfceRc * | xfce_rc_config_open ()
void | xfce_rc_close ()
void | xfce_rc_flush ()
gboolean | xfce_rc_is_dirty ()
gboolean | xfce_rc_is_readonly ()
const gchar * | xfce_rc_get_locale ()
gchar ** | xfce_rc_get_groups ()
gchar ** | xfce_rc_get_entries ()
void | xfce_rc_delete_group ()
const gchar * | xfce_rc_get_group ()
gboolean | xfce_rc_has_group ()
void | xfce_rc_set_group ()
void | xfce_rc_delete_entry ()
gboolean | xfce_rc_has_entry ()
const gchar * | xfce_rc_read_entry ()
const gchar * | xfce_rc_read_entry_untranslated ()
gboolean | xfce_rc_read_bool_entry ()
gint | xfce_rc_read_int_entry ()
gchar ** | xfce_rc_read_list_entry ()
void | xfce_rc_rollback ()
void | xfce_rc_write_entry ()
void | xfce_rc_write_bool_entry ()
void | xfce_rc_write_int_entry ()
void | xfce_rc_write_list_entry ()

## Types and Values

| XfceRc

## Object Hierarchy

        GBoxed
        ╰── XfceRc

## Includes

    #include <libxfce4util/libxfce4util.h>

## Description

Provides support for parsing INI-style resource config files like used by for example KDE and some Xfce components (like xfwm4, who uses rc files for the themes).

The parser itself is optimized for high-performance using memory and string chunks to reduce the time spent looking for heap memory (a nice side effect of this is the reduced heap corruption). But due to this fact, an XfceRc object might consume quite a lot of memory after some time of usage. Therefore you should close an XfceRc object as soon as possible after loading configuration data from the object.

## Functions

### xfce_rc_simple_open ()

    XfceRc *
    xfce_rc_simple_open (const gchar *filename,
                         gboolean readonly);

Parses the resource config file specified by `filename` .

If `readonly` is `TRUE` parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass `TRUE` for `readonly` , xfce_rc_simple_open will fail if `filename` does not reference a regular file.

It is no error if `readonly` is `FALSE` and the file referenced by `filename` does not exists. In this case you'll start with a fresh config, which contains only the default group and no entries.

#### Parameters

filename | name of the filename to open. |
readonly | whether to open `filename` readonly. |

#### Returns

the newly created XfceRc object, or `NULL` on error.

[transfer full]

Since: 4.2

### xfce_rc_config_open ()

    XfceRc *
    xfce_rc_config_open (XfceResourceType type,
                         const gchar *resource,
                         gboolean readonly);

If `readonly` is `TRUE` parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass `TRUE` for `readonly` , xfce_rc_config will fail if `resource` does not reference a regular file.

It is no error if `readonly` is `FALSE` and the file referenced by `resource` does not exists. In this case you'll start with a fresh config, which contains only the default group and no entries.

#### Parameters

type | The resource type being opened |
resource | The resource name to open |
readonly | whether to open `resource` readonly. |

#### Returns

the newly created XfceRc object, or `NULL` on error.

[transfer full]

Since: 4.2

### xfce_rc_close ()

    void
    xfce_rc_close (XfceRc *rc);

Destructs `rc` .

If `rc` was opened read-write and contains dirty (modified) entries, these will be flushed to permanent storage first.

#### Parameters

rc | an XfceRc object. |

Since: 4.2

### xfce_rc_flush ()

    void
    xfce_rc_flush (XfceRc *rc);

Flushes all changes that currently reside only in memory back to permanent storage. Dirty configuration entries are written in the most specific file available.

#### Parameters

rc | an XfceRc object. |

Since: 4.2

### xfce_rc_is_dirty ()

    gboolean
    xfce_rc_is_dirty (const XfceRc *rc);

Checks whether `rc` has any dirty (modified) entries.

#### Parameters

rc | an XfceRc object. |

#### Returns

`TRUE` if `rc` has any dirty (modified) entries.

Since: 4.2

### xfce_rc_is_readonly ()

    gboolean
    xfce_rc_is_readonly (const XfceRc *rc);

Returns the read-only status of `rc` .

#### Parameters

rc | an XfceRc object. |

#### Returns

the read-only status.

Since: 4.2

### xfce_rc_get_locale ()

    const gchar *
    xfce_rc_get_locale (const XfceRc *rc);

Returns current locale used by `rc` to lookup translated entries.

#### Parameters

rc | an XfceRc object. |

#### Returns

a string representing the current locale.

Since: 4.2

### xfce_rc_get_groups ()

    gchar **
    xfce_rc_get_groups (const XfceRc *rc);

Returns the names of all known groups in `rc` .

Since the default groups (the "NULL group") name is `NULL`, it will not be returned with this functions. But it does not matter at all, since the default group is known to always exist.

#### Parameters

rc | an XfceRc object. |

#### Returns

a NULL-terminated string array will the names of all groups in `rc` . Should be freed using `g_strfreev()` when no longer needed.

[transfer full]

Since: 4.2

### xfce_rc_get_entries ()

    gchar **
    xfce_rc_get_entries (const XfceRc *rc,
                         const gchar *group);

Returns the names of all entries in `group` if any.

`NULL` is a valid input value for `group` . xfce_rc_get_entries will then return all entries in the so called "NULL group". Though this "NULL group" should only be used for backward compatibility with old applications. You should not use it in newly written code.

#### Parameters

rc | an XfceRc object. |
group | the name of the group to get entries from. |

#### Returns

a NULL-terminated string array with all entries in `group` . Has to be freed using `g_strfreev()` if no longer needed. If the specified `group` does not exists, `NULL` is returned. If the `group` has no entries, an empty string array is returned.

[transfer full]

Since: 4.2

### xfce_rc_delete_group ()

    void
    xfce_rc_delete_group (XfceRc *rc,
                          const gchar *group,
                          gboolean global);

If `rc` is a simple config object and `group` exists, it is deleted. All entries within `group` will be deleted. For simple config objects, `global` is ignored.

If `rc` is a complex config object and `group` exists, it will be deleted will all entries. If `global` is `TRUE`, the entry will be marked as deleted globally, therefore all calls to xfce_rc_read_entry and related functions will return the fallback values. If `global` is `FALSE`, the `group` will be deleted in the per-user config file, and further calls to xfce_rc_read_entry will most probably return the system-wide config entries.

#### Parameters

rc | an XfceRc object. |
group | name of the group to delete. |
global | whether to delete the group globally. |

Since: 4.2

### xfce_rc_get_group ()

    const gchar *
    xfce_rc_get_group (const XfceRc *rc);

Returns the name of the group in which we are searching for keys and from which we are retrieving entries. If the currently active group is the default group (the so called "NULL group"), `NULL` will be returned.

#### Parameters

rc | an XfceRc object. |

#### Returns

the name of the current group.

Since: 4.2

### xfce_rc_has_group ()

    gboolean
    xfce_rc_has_group (const XfceRc *rc,
                       const gchar *group);

Returns `TRUE` if the specified `group` is known about.

#### Parameters

rc | an XfceRc object. |
group | the group to search for. |

#### Returns

`TRUE` if the `group` exists.

Since: 4.2

### xfce_rc_set_group ()

    void
    xfce_rc_set_group (XfceRc *rc,
                       const gchar *group);

Specifies the group in which keys will be read and written. Subsequent calls to xfce_rc_read_entry and xfce_rc_write_entry will be applied only in the active group.

If `group` references a group that does not exists, it will be created for you. But note, that empty groups will not be synced to permanent storage.

#### Parameters

rc | an XfceRc object. |
group | the name of the new group or `NULL` to to switch back to the default group. |

Since: 4.2

### xfce_rc_delete_entry ()

    void
    xfce_rc_delete_entry (XfceRc *rc,
                          const gchar *key,
                          gboolean global);

Similar to xfce_rc_delete_group, but works on an entry in the current group.

#### Parameters

rc | an XfceRc object. |
key | the key to delete. |
global | whether to delete `key` globally. |

Since: 4.2

### xfce_rc_has_entry ()

    gboolean
    xfce_rc_has_entry (const XfceRc *rc,
                       const gchar *key);

Checks whether the `key` has an entry in the current group.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |

#### Returns

`TRUE` if the `key` is available, else `FALSE`.

Since: 4.2

### xfce_rc_read_entry ()

    const gchar *
    xfce_rc_read_entry (const XfceRc *rc,
                        const gchar *key,
                        const gchar *fallback);

Reads the value of an entry specified by `key` in the current group.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |
fallback | a default value returned if the `key` was not found. |

#### Returns

the value for this `key` , or `fallback` if `key` was not found.

Since: 4.2

### xfce_rc_read_entry_untranslated ()

    const gchar *
    xfce_rc_read_entry_untranslated (const XfceRc *rc,
                                     const gchar *key,
                                     const gchar *fallback);

Reads the value of an entry specified by `key` in the current group. The untranslated entry is returned. You normally do not need this.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |
fallback | a default value returned if the `key` was not found. |

#### Returns

the untranslated value for this `key` , or `fallback` if `key` was not found.

Since: 4.2

### xfce_rc_read_bool_entry ()

    gboolean
    xfce_rc_read_bool_entry (const XfceRc *rc,
                             const gchar *key,
                             gboolean fallback);

Reads the value of an entry specified by `key` in the current group and interpret it as a boolean value. Currently "on", "true" and "yes" are accepted as true, everything else is false.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |
fallback | a default value returned if the `key` was not found. |

#### Returns

the value for this `key` .

Since: 4.2

### xfce_rc_read_int_entry ()

    gint
    xfce_rc_read_int_entry (const XfceRc *rc,
                            const gchar *key,
                            gint fallback);

Reads the value of an entry specified by `key` in the current group and interprets it as an integer value.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |
fallback | a default value returned if the `key` was not found. |

#### Returns

the value for this `key` .

Since: 4.2

### xfce_rc_read_list_entry ()

    gchar **
    xfce_rc_read_list_entry (const XfceRc *rc,
                             const gchar *key,
                             const gchar *delimiter);

Reads a list of strings in the entry specified by key in the current group. The returned list has to be freed using `g_strfreev()` when no longer needed.

This does not support delimiter escaping. If you need this feature, use `g_key_file_get_string_list()` instead.

#### Parameters

rc | an XfceRc object. |
key | the key to search for. |
delimiter | a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings. If NULL, "," is used. |

#### Returns

the list or NULL if the entry does not exist.

[transfer full]

Since: 4.2

### xfce_rc_rollback ()

    void
    xfce_rc_rollback (XfceRc *rc);

Mark `rc` as "clean", i.e. don't write dirty entries at destruction time. If you then call xfce_rc_write_entry again, the dirty flag is set again and dirty entries will be written at a subsequent xfce_rc_flush call.

#### Parameters

rc | an XfceRc object. |

Since: 4.2

### xfce_rc_write_entry ()

    void
    xfce_rc_write_entry (XfceRc *rc,
                         const gchar *key,
                         const gchar *value);

Writes a `key` /`value` pair. This has no effect if the resource config was opened readonly, else the value will be written to permanent storage on the next call to xfce_rc_flush or when `rc` is destroyed using xfce_rc_close.

If `rc` was opened using xfce_rc_config_open, the value will be written to the most specific config file.

#### Parameters

rc | an XfceRc object. |
key | the key to write. |
value | the value to write. |

Since: 4.2

### xfce_rc_write_bool_entry ()

    void
    xfce_rc_write_bool_entry (XfceRc *rc,
                              const gchar *key,
                              gboolean value);

Wrapper for xfce_rc_write_entry, that stores a boolean `value` .

#### Parameters

rc | an XfceRc object. |
key | the key to write. |
value | the value to write. |

Since: 4.2

### xfce_rc_write_int_entry ()

    void
    xfce_rc_write_int_entry (XfceRc *rc,
                             const gchar *key,
                             gint value);

Wrapper for xfce_rc_write_entry, that stores an integer `value` .

#### Parameters

rc | an XfceRc object. |
key | the key to write. |
value | the value to write. |

Since: 4.2

### xfce_rc_write_list_entry ()

    void
    xfce_rc_write_list_entry (XfceRc *rc,
                              const gchar *key,
                              gchar **value,
                              const gchar *separator);

Wrapper for xfce_rc_write_entry, that stores a string list `value` .

This does not support delimiter escaping. If you need this feature, use `g_key_file_set_string_list()` instead.

#### Parameters

rc | an XfceRc object. |
key | the key to write. |
value | a `NULL` terminated list of strings to store in the entry specified by key. |
separator | the list separator. Defaults to "," if `NULL`. |

Since: 4.2

## Types and Values

### XfceRc

    typedef struct _XfceRc XfceRc;