Utility Functions

Utility Functions — Various utility functions that do not fit elsewhere.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <apt.h>

gboolean            (*AptUtilsForeachInDirFunc)         (gpointer user_data,
                                                         const gchar *file,
                                                         GError **error);
gboolean            apt_utils_foreach_in_dir            (const gchar *dirname,
                                                         const gchar *suffix,
                                                         AptUtilsForeachInDirFunc callback,
                                                         gpointer user_data,
                                                         GError **error);
gint                apt_utils_lock_file                 (const gchar *file,
                                                         GError **error);
gboolean            apt_utils_match                     (const gchar *pattern,
                                                         const gchar *string);
gboolean            apt_utils_str_case_equal            (gconstpointer s1,
                                                         gconstpointer s2);
guint               apt_utils_str_case_hash             (gconstpointer v);
gchar *             apt_utils_uri_to_filename           (const gchar *uri);

Description

This section documents various utility functions that are needed for APT2 and may also be useful to applications using APT2.

Details

AptUtilsForeachInDirFunc ()

gboolean            (*AptUtilsForeachInDirFunc)         (gpointer user_data,
                                                         const gchar *file,
                                                         GError **error);

The type of the callback function passed to apt_utils_foreach_in_dir().

`user_data` :	The user data passed to `apt_utils_foreach_in_dir()`.
`file` :	The path to the file.
`error` :	The location to store an error.
Returns :	`TRUE` if no error occured, `FALSE` otherwise. Returning `FALSE` will cancel `apt_utils_foreach_in_dir()`.

apt_utils_foreach_in_dir ()

gboolean            apt_utils_foreach_in_dir            (const gchar *dirname,
                                                         const gchar *suffix,
                                                         AptUtilsForeachInDirFunc callback,
                                                         gpointer user_data,
                                                         GError **error);

Calls the function callback for each file in the directory (given the complete path to the file) that ends with suffix or consists only of alphanumeric, hyphen-minus (-), underscore (_) and period characters.

If callback encounters an error, it should return FALSE and set its error pointer. In such a case, this function exits immediately with the value FALSE and propagates the error of callback to the caller.

`dirname` :	The path to the directory that shall be read.
`suffix` :	The suffix the files should have (including .)
`callback` :	The AptUtilsForeachInDirFunc to be called for each file in the directory.
`user_data` :	The pointer that will be passed to `callback` as its first argument.
`error` :	The location to store an error.
Returns :	`TRUE` if everything is OK, `FALSE` if this function or `callback` encountered an error.

apt_utils_lock_file ()

gint                apt_utils_lock_file                 (const gchar *file,
                                                         GError **error);

Acquires an advisory POSIX write lock for the file file. If any other process already holds a lock on file or if the file can not be locked due to other reasons, the return value is -1 and error is set to an error describing the reason why the lock could not be acquired.

Since this uses POSIX locking, calling close() on any file descriptor for the file file will release all locks on this file.

`file` :	The path to the file that shall be locked.
`error` :	Location to store a GFileError.
Returns :	The file descriptor of the lock file, or -1 on failure.

apt_utils_match ()

gboolean            apt_utils_match                     (const gchar *pattern,
                                                         const gchar *string);

Checks whether pattern matches string.

`pattern` :	A regular expression if it starts with a forward slash and ends with one, otherwise a `glob()` like pattern.
`string` :	The string `pattern` should be matched again.
Returns :	`TRUE` if `pattern` matches `string`, `FALSE` otherwise. If `string` is `NULL`, the result is always `FALSE`.

apt_utils_str_case_equal ()

gboolean            apt_utils_str_case_equal            (gconstpointer s1,
                                                         gconstpointer s2);

Checks whether the two strings s1 and s2 are equal, ignoring differing cases of ASCII characters.

`s1` :	The first string
`s2` :	The second string
Returns :	`TRUE` if `s1` matches `s2`, `FALSE` otherwise.

apt_utils_str_case_hash ()

guint               apt_utils_str_case_hash             (gconstpointer v);

Converts a string to a hash value, ignoring the case of ASCII characters.

`v` :	a string key
Returns :	a hash value corresponding to the key

apt_utils_uri_to_filename ()

gchar *             apt_utils_uri_to_filename           (const gchar *uri);

Converts uri, excluding scheme and userinfo, into a string that can be used as a local filename. For this, forward slashes are replaced by underscores; the other remaining reserved characters, excluding the colon but including the tilde character, are replaced using their percent-encoded form.

`uri` :	A valid Uniform Resource Identifier (URI) as specified in RFC 3986
Returns :	A newly allocated, escaped version of `uri`. The returned string should be freed when no longer needed.

			APT2 Reference Manual
Top \| Description