AptConfiguration

AptConfiguration — Reading APT configuration files.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <apt.h>

#define             APT_CONFIGURATION_ERROR
enum                AptConfigurationError;

                    AptConfiguration;
AptConfiguration *  apt_configuration_new               (void);
AptConfiguration *  apt_configuration_ref               (AptConfiguration *configuration);
void                apt_configuration_unref             (AptConfiguration *configuration);

GOptionGroup *      apt_configuration_get_option_group  (AptConfiguration *configuration);
gboolean            apt_configuration_init_defaults     (AptConfiguration *configuration,
                                                         GError **error);

const gchar *       apt_configuration_get               (AptConfiguration *configuration,
                                                         const gchar *name);
void                apt_configuration_set               (AptConfiguration *configuration,
                                                         const gchar *name,
                                                         const gchar *value);

gboolean            apt_configuration_get_boolean       (AptConfiguration *configuration,
                                                         const gchar *name);
gchar *             apt_configuration_get_file          (AptConfiguration *configuration,
                                                         const gchar *name);
gint                apt_configuration_get_int           (AptConfiguration *configuration,
                                                         const gchar *name);
const gchar **      apt_configuration_get_list          (AptConfiguration *configuration,
                                                         const gchar *name,
                                                         gsize *length);

gboolean            apt_configuration_parse_file        (AptConfiguration *configuration,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            apt_configuration_parse_dir         (AptConfiguration *configuration,
                                                         const gchar *dirname,
                                                         GError **error);
gboolean            apt_configuration_parse_text        (AptConfiguration *configuration,
                                                         const gchar *text,
                                                         GError **error);
gchar *             apt_configuration_dumps             (AptConfiguration *configuration);

Description

The APT configuration system is basically a tree of options. Each option can have zero or more sub-options and these suboptions can either all have a name or no name (which makes them list elements). The levels of the tree are seperated by two colons, like C++.

Details

APT_CONFIGURATION_ERROR

#define APT_CONFIGURATION_ERROR apt_configuration_error_quark()

The error domain for configuration parsing.

enum AptConfigurationError

typedef enum {
    APT_CONFIGURATION_ERROR_FAILED
} AptConfigurationError;

Error values for the configuration subsystem.

APT_CONFIGURATION_ERROR_FAILED

 Something failed.

AptConfiguration

typedef struct _AptConfiguration AptConfiguration;

AptConfiguration is an opaque data type which may only be accessed using the following functions.

apt_configuration_new ()

AptConfiguration *  apt_configuration_new               (void);

Creates a new AptConfiguration.

Returns :

 A newly allocated AptConfiguration with reference count 1.

apt_configuration_ref ()

AptConfiguration *  apt_configuration_ref               (AptConfiguration *configuration);

Increments the reference count of configuration.

configuration :

 An AptConfiguration

Returns :

 configuration

apt_configuration_unref ()

void                apt_configuration_unref             (AptConfiguration *configuration);

Decrements the reference count of configuration. If the reference count drops to 0, the memory pointed to by configuration will be freed.

configuration :

 An AptConfiguration

apt_configuration_get_option_group ()

GOptionGroup *      apt_configuration_get_option_group  (AptConfiguration *configuration);

Gets a new GOptionGroup for configuration containing the options 'config-file' (-c) and 'option' (-o).

configuration :

 An AptConfiguration

Returns :

 A newly allocated GOptionGroup for configuration. It holds its own reference to configuration.

apt_configuration_init_defaults ()

gboolean            apt_configuration_init_defaults     (AptConfiguration *configuration,
                                                         GError **error);

Initializes configuration using default values and by reading the configuration file specified by the environment variable APT_CONFIG and then the file specified by the option Dir::Etc::main and the files in the directory specified by the option Dir::Etc::parts.

configuration :

 An AptConfiguration

error :

 Return location to store a GError.

Returns :

 TRUE if everything succeded, FALSE otherwise.

apt_configuration_get ()

const gchar *       apt_configuration_get               (AptConfiguration *configuration,
                                                         const gchar *name);

Gets the value of the option name and returns it as a constant string. Please note that the returned string may be freed at any time a new value for this option is set. Thus, if you want to keep the value around, call g_strdup() on it. If the requested option is not set, NULL is returned.

configuration :

 An AptConfiguration.

name :

 The name of the option that shall be retrieved.

Returns :

 A constant string containing the value or NULL if the option is not set.

apt_configuration_set ()

void                apt_configuration_set               (AptConfiguration *configuration,
                                                         const gchar *name,
                                                         const gchar *value);

Sets the configuration option name to value. The parameter name is pushed to lower-case before insertion, and both parameters are duplicated before they are inserted into the hashtable.

configuration :

 An AptConfiguration

name :

 The name of the option that should be set.

value :

 The value that the option should be set to.

apt_configuration_get_boolean ()

gboolean            apt_configuration_get_boolean       (AptConfiguration *configuration,
                                                         const gchar *name);

Calls apt_configuration_get() and converts the result into a gboolean. Valid boolean values are "no", "false", "off", "disable", "without", and "0" for FALSE; and "yes", "true", "on", "enable", "with", and 1 for TRUE. If the value of the option name is not one of those strings or if the option name is not set, FALSE is returned.

configuration :

 An AptConfiguration.

name :

 The name of the option that shall be retrieved.

Returns :

 The boolean value stored at name or FALSE if name is not set or is not a valid boolean value.

apt_configuration_get_file ()

gchar *             apt_configuration_get_file          (AptConfiguration *configuration,
                                                         const gchar *name);

Lookup a file in the configuration space. This lookups the value at name and goes upwards in the configuration tree, prepending every value found until the path is absolute or a relative path starting with "./" or "../". If a special configuration option named "rootdir" exists, its value is prepended to the string.

configuration :

 An AptConfiguration

name :

 The name of the option to be looked up

Returns :

 A string which contains the path to the file and must be freed using g_free() when no longer required.

apt_configuration_get_int ()

gint                apt_configuration_get_int           (AptConfiguration *configuration,
                                                         const gchar *name);

Calls apt_configuration_get() and converts the result into an integer.

configuration :

 An AptConfiguration.

name :

 The name of the option that shall be retrieved.

Returns :

 The integer stored at name, or 0 if the option does not exist or is no integer.

apt_configuration_get_list ()

const gchar **      apt_configuration_get_list          (AptConfiguration *configuration,
                                                         const gchar *name,
                                                         gsize *length);

Gets the list stored at the given option.

configuration :

 An AptConfiguration

name :

 The name of the list option, including the :: suffix.

length :

 Location to store the length of the list.

Returns :

 A list of strings of the values at the given option.

apt_configuration_parse_file ()

gboolean            apt_configuration_parse_file        (AptConfiguration *configuration,
                                                         const gchar *filename,
                                                         GError **error);

Parses the configuration file located at filename and inserts the option it defines into configuration.

configuration :

 An AptConfiguration.

filename :

 The name of the file which shall be parsed.

error :

 Location to store an error.

Returns :

 TRUE if the file could be parsed, FALSE otherwise.

apt_configuration_parse_dir ()

gboolean            apt_configuration_parse_dir         (AptConfiguration *configuration,
                                                         const gchar *dirname,
                                                         GError **error);

Parses the configuration files located in the directory dirname and insert the options they define into configuration.

configuration :

 An AptConfiguration.

dirname :

 The name of the directory containing the files to be parsed.

error :

 Location to store an error.

Returns :

 TRUE if all files could be parsed, FALSE otherwise.

apt_configuration_parse_text ()

gboolean            apt_configuration_parse_text        (AptConfiguration *configuration,
                                                         const gchar *text,
                                                         GError **error);

Parses text which must be a string in the format of APT configuration files and inserts the options it defines into configuration.

configuration :

 An AptConfiguration.

text :

 The text that shall be parsed.

error :

 Location to store an error.

Returns :

 TRUE if the text could be parsed, FALSE otherwise.

apt_configuration_dumps ()

gchar *             apt_configuration_dumps             (AptConfiguration *configuration);

Gets a string describing the options held in configuration that can be parsed by apt_configuration_parse_text().

configuration :

 An AptConfiguration.
Generated by GTK-Doc V1.17