Miscellaneous Utility Functions

Miscellaneous Utility Functions — a selection of portable utility functions.

Synopsis


#include <glib.h>


const gchar* g_get_application_name         (void);
void        g_set_application_name          (const gchar *application_name);
gchar*      g_get_prgname                   (void);
void        g_set_prgname                   (const gchar *prgname);
const gchar* g_getenv                       (const gchar *variable);
gboolean    g_setenv                        (const gchar *variable,
                                             const gchar *value,
                                             gboolean overwrite);
void        g_unsetenv                      (const gchar *variable);
const gchar* g_get_user_name                (void);
const gchar* g_get_real_name                (void);
const gchar* g_get_user_cache_dir           (void);
const gchar* g_get_user_data_dir            (void);
const gchar* g_get_user_config_dir          (void);
const gchar* const * g_get_system_data_dirs (void);
const gchar* const * g_get_system_config_dirs
                                            (void);

const gchar* g_get_home_dir                 (void);
const gchar* g_get_tmp_dir                  (void);
gchar*      g_get_current_dir               (void);
const gchar* g_basename                     (const gchar *file_name);
#define     g_dirname
gboolean    g_path_is_absolute              (const gchar *file_name);
const gchar* g_path_skip_root               (const gchar *file_name);
gchar*      g_path_get_basename             (const gchar *file_name);
gchar*      g_path_get_dirname              (const gchar *file_name);
gchar*      g_build_filename                (const gchar *first_element,
                                             ...);
gchar*      g_build_path                    (const gchar *separator,
                                             const gchar *first_element,
                                             ...);

gchar*      g_find_program_in_path          (const gchar *program);

gint        g_bit_nth_lsf                   (gulong mask,
                                             gint nth_bit);
gint        g_bit_nth_msf                   (gulong mask,
                                             gint nth_bit);
guint       g_bit_storage                   (gulong number);

guint       g_spaced_primes_closest         (guint num);

void        g_atexit                        (GVoidFunc func);

guint       g_parse_debug_string            (const gchar *string,
                                             const GDebugKey *keys,
                                             guint nkeys);
            GDebugKey;

void        (*GVoidFunc)                    (void);
void        (*GFreeFunc)                    (gpointer data);

void        g_qsort_with_data               (gconstpointer pbase,
                                             gint total_elems,
                                             gsize size,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

void        g_nullify_pointer               (gpointer *nullify_location);

Description

These are portable utility functions.

Details

g_get_application_name ()

const gchar* g_get_application_name         (void);

Gets a human-readable name for the application, as set by g_set_application_name(). This name should be localized if possible, and is intended for display to the user. Contrast with g_get_prgname(), which gets a non-localized name. If g_set_application_name() has not been called, returns the result of g_get_prgname() (which may be NULL if g_set_prgname() has also not been called).

Returns : human-readable application name. may return NULL

Since 2.2


g_set_application_name ()

void        g_set_application_name          (const gchar *application_name);

Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with g_set_prgname(), which sets a non-localized name. g_set_prgname() will be called automatically by gtk_init(), but g_set_application_name() will not.

Note that for thread safety reasons, this function can only be called once.

The application name will be used in contexts such as error messages, or when displaying an application's name in the task list.

application_name : localized name of the application

g_get_prgname ()

gchar*      g_get_prgname                   (void);

Gets the name of the program. This name should not be localized, contrast with g_get_application_name(). (If you are using GDK or GTK+ the program name is set in gdk_init(), which is called by gtk_init(). The program name is found by taking the last component of argv[0].)

Returns :the name of the program. The returned string belongs to GLib and must not be modified or freed.

g_set_prgname ()

void        g_set_prgname                   (const gchar *prgname);

Sets the name of the program. This name should not be localized, contrast with g_set_application_name(). Note that for thread-safety reasons this function can only be called once.

prgname :the name of the program.

g_getenv ()

const gchar* g_getenv                       (const gchar *variable);

Returns the value of an environment variable. The name and value are in the GLib file name encoding. On Unix, this means the actual bytes which might or might not be in some consistent character set and encoding. On Windows, it is in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded.

variable : the environment variable to get, in the GLib file name encoding.
Returns : the value of the environment variable, or NULL if the environment variable is not found. The returned string may be overwritten by the next call to g_getenv(), g_setenv() or g_unsetenv().

g_setenv ()

gboolean    g_setenv                        (const gchar *variable,
                                             const gchar *value,
                                             gboolean overwrite);

Sets an environment variable. Both the variable's name and value should be in the GLib file name encoding. On Unix, this means that they can be any sequence of bytes. On Windows, they should be in UTF-8.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed.

variable : the environment variable to set, must not contain '='.
value : the value for to set the variable to.
overwrite : whether to change the variable if it already exists.
Returns : FALSE if the environment variable couldn't be set.

Since 2.4


g_unsetenv ()

void        g_unsetenv                      (const gchar *variable);

Removes an environment variable from the environment.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. Furthermore, this function can't be guaranteed to operate in a threadsafe way.

variable : the environment variable to remove, must not contain '='.

Since 2.4


g_get_user_name ()

const gchar* g_get_user_name                (void);

Gets the user name of the current user. The encoding of the returned string is system defined. On Unix, it might be the preferred file name encoding, or something else, and there is no guarantee that it is even consistent on a machine. On Windows, it is always UTF-8.

Returns :the user name of the current user.

g_get_real_name ()

const gchar* g_get_real_name                (void);

Gets the real name of the user. This usually comes from the user's entry in the passwd file. The encoding of the returned string is system defined. (On Windows, it is, however, always UTF-8.) If the real user name cannot be determined, the string "Unknown" is returned.

Returns :the user's real name.

g_get_user_cache_dir ()

const gchar* g_get_user_cache_dir           (void);

Returns a base directory in which to store non-essential, cached data specific to particular user.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Returns : a string owned by GLib that must not be modified or freed.

Since 2.6


g_get_user_data_dir ()

const gchar* g_get_user_data_dir            (void);

Returns a base directory in which to access application data such as icons that is customized for a particular user.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Returns : a string owned by GLib that must not be modified or freed.

Since 2.6


g_get_user_config_dir ()

const gchar* g_get_user_config_dir          (void);

Returns a base directory in which to store user-specific application configuration information such as user preferences and settings.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Returns : a string owned by GLib that must not be modified or freed.

Since 2.6


g_get_system_data_dirs ()

const gchar* const * g_get_system_data_dirs (void);

Returns an ordered list of base directories in which to access system-wide application data.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Returns : a NULL-terminated array of strings owned by GLib that must not be modified or freed.

Since 2.6


g_get_system_config_dirs ()

const gchar* const * g_get_system_config_dirs
                                            (void);

Returns an ordered list of base directories in which to access system-wide configuration information.

On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification

Returns : a NULL-terminated array of strings owned by GLib that must not be modified or freed.

Since 2.6


g_get_home_dir ()

const gchar* g_get_home_dir                 (void);

Gets the current user's home directory.

Note that in contrast to traditional Unix tools, this function prefers passwd entries over the HOME environment variable.

Returns :the current user's home directory.

g_get_tmp_dir ()

const gchar* g_get_tmp_dir                  (void);

Gets the directory to use for temporary files. This is found from inspecting the environment variables TMPDIR, TMP, and TEMP in that order. If none of those are defined "/tmp" is returned on UNIX and "C:\" on Windows. The encoding of the returned string is system defined. On Windows, it is always UTF-8. The return value is never NULL.

Returns :the directory to use for temporary files.

g_get_current_dir ()

gchar*      g_get_current_dir               (void);

Gets the current directory. The returned string should be freed when no longer needed. The encoding of the returned string is system defined. On Windows, it is always UTF-8.

Returns :the current directory.

g_basename ()

const gchar* g_basename                     (const gchar *file_name);

Warning

g_basename is deprecated and should not be used in newly-written code. Use g_path_get_basename() instead, but notice that g_path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument.

Gets the name of the file without any leading directory components. It returns a pointer into the given file name string.

file_name : the name of the file.
Returns : the name of the file without any leading directory components.

g_dirname

#define     g_dirname

Warning

g_dirname is deprecated and should not be used in newly-written code.

This function is deprecated and will be removed in the next major release of GLib. Use g_path_get_dirname() instead.

Gets the directory components of a file name. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed.

Returns :the directory components of the file.

g_path_is_absolute ()

gboolean    g_path_is_absolute              (const gchar *file_name);

Returns TRUE if the given file_name is an absolute file name, i.e. it contains a full path from the root directory such as '/usr/local' on UNIX or 'C:\windows' on Windows systems.

file_name :a file name.
Returns :TRUE if file_name is an absolute path.

g_path_skip_root ()

const gchar* g_path_skip_root               (const gchar *file_name);

Returns a pointer into file_name after the root component, i.e. after the '/' in UNIX or 'C:\' under Windows. If file_name is not an absolute path it returns NULL.

file_name :a file name.
Returns :a pointer into file_name after the root component.

g_path_get_basename ()

gchar*      g_path_get_basename             (const gchar *file_name);

Gets the last component of the filename. If file_name ends with a directory separator it gets the component before the last slash. If file_name consists only of directory separators (and on Windows, possibly a drive letter), a single separator is returned. If file_name is empty, it gets ".".

file_name : the name of the file.
Returns : a newly allocated string containing the last component of the filename.

g_path_get_dirname ()

gchar*      g_path_get_dirname              (const gchar *file_name);

Gets the directory components of a file name. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed.

file_name :the name of the file.
Returns :the directory components of the file.

g_build_filename ()

gchar*      g_build_filename                (const gchar *first_element,
                                             ...);

Creates a filename from a series of elements using the correct separator for filenames.

On Unix, this function behaves identically to g_build_path (G_DIR_SEPARATOR_S, first_element, ....).

On Windows, it takes into account that either the backslash (\ or slash (/) can be used as separator in filenames, but otherwise behaves as on Unix. When file pathname separators need to be inserted, the one that last previously occurred in the parameters (reading from left to right) is used.

No attempt is made to force the resulting filename to be an absolute path. If the first element is a relative path, the result will be a relative path.

first_element : the first element in the path
... : remaining elements in path, terminated by NULL
Returns : a newly-allocated string that must be freed with g_free().

g_build_path ()

gchar*      g_build_path                    (const gchar *separator,
                                             const gchar *first_element,
                                             ...);

Creates a path from a series of elements using separator as the separator between elements. At the boundary between two elements, any trailing occurrences of separator in the first element, or leading occurrences of separator in the second element are removed and exactly one copy of the separator is inserted.

Empty elements are ignored.

The number of leading copies of the separator on the result is the same as the number of leading copies of the separator on the first non-empty element.

The number of trailing copies of the separator on the result is the same as the number of trailing copies of the separator on the last non-empty element. (Determination of the number of trailing copies is done without stripping leading copies, so if the separator is ABA, ABABA has 1 trailing copy.)

However, if there is only a single non-empty element, and there are no characters in that element not part of the leading or trailing separators, then the result is exactly the original value of that element.

Other than for determination of the number of leading and trailing copies of the separator, elements consisting only of copies of the separator are ignored.

separator : a string used to separator the elements of the path.
first_element : the first element in the path
... : remaining elements in path, terminated by NULL
Returns : a newly-allocated string that must be freed with g_free().

g_find_program_in_path ()

gchar*      g_find_program_in_path          (const gchar *program);

Locates the first executable named program in the user's path, in the same way that execvp() would locate it. Returns an allocated string with the absolute path name, or NULL if the program is not found in the path. If program is already an absolute path, returns a copy of program if program exists and is executable, and NULL otherwise. On Windows, if program does not have a file type suffix, tries with the suffixes .exe, .cmd, .bat and .com, and the suffixes in the PATHEXT environment variable.

It looks for the file in the same way as CreateProcess() would. This means first in the directory where the executing program was loaded from, then in the current directory, then in the Windows 32-bit system directory, then in the Windows directory, and finally in the directories in the PATH environment variable. If the program is found, the return value contains the full name including the type suffix.

program : a program name in the GLib file name encoding
Returns : absolute path, or NULL

g_bit_nth_lsf ()

gint        g_bit_nth_lsf                   (gulong mask,
                                             gint nth_bit);

Find the position of the first bit set in mask, searching from (but not including) nth_bit upwards. Bits are numbered from 0 (least significant) to sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set nth_bit to -1.

mask :a gulong containing flags.
nth_bit :the index of the bit to start the search from.
Returns :the index of the first bit set which is higher than nth_bit.

g_bit_nth_msf ()

gint        g_bit_nth_msf                   (gulong mask,
                                             gint nth_bit);

Find the position of the first bit set in mask, searching from (but not including) nth_bit downwards. Bits are numbered from 0 (least significant) to sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the last bit, set nth_bit to -1 or GLIB_SIZEOF_LONG * 8.

mask :a gulong containing flags.
nth_bit :the index of the bit to start the search from.
Returns :the index of the first bit set which is lower than nth_bit.

g_bit_storage ()

guint       g_bit_storage                   (gulong number);

Gets the number of bits used to hold number, e.g. if number is 4, 3 bits are needed.

number :a guint.
Returns :the number of bits used to hold number.

g_spaced_primes_closest ()

guint       g_spaced_primes_closest         (guint num);

Gets the smallest prime number from a built-in array of primes which is larger than num. This is used within GLib to calculate the optimum size of a GHashTable.

The built-in array of primes ranges from 11 to 13845163 such that each prime is approximately 1.5-2 times the previous prime.

num :a guint.
Returns :the smallest prime number from a built-in array of primes which is larger than num.

g_atexit ()

void        g_atexit                        (GVoidFunc func);

Specifies a function to be called at normal program termination.

func :the function to call on normal program termination.

g_parse_debug_string ()

guint       g_parse_debug_string            (const gchar *string,
                                             const GDebugKey *keys,
                                             guint nkeys);

Parses a string containing debugging options separated by ':' into a guint containing bit flags. This is used within GDK and GTK+ to parse the debug options passed on the command line or through environment variables.

string :a list of debug options separated by ':' or "all" to set all flags.
keys :pointer to an array of GDebugKey which associate strings with bit flags.
nkeys :the number of GDebugKey in the array.
Returns :the combined set of bit flags.

GDebugKey

typedef struct {
  gchar *key;
  guint	 value;
} GDebugKey;

Associates a string with a bit flag. Used in g_parse_debug_string().


GVoidFunc ()

void        (*GVoidFunc)                    (void);

Declares a type of function which takes no arguments and has no return value. It is used to specify the type function passed to g_atexit().


GFreeFunc ()

void        (*GFreeFunc)                    (gpointer data);

Declares a type of function which takes an arbitrary data pointer argument and has no return value. It is not currently used in GLib or GTK+.

data :a data pointer.

g_qsort_with_data ()

void        g_qsort_with_data               (gconstpointer pbase,
                                             gint total_elems,
                                             gsize size,
                                             GCompareDataFunc compare_func,
                                             gpointer user_data);

This is just like the standard C qsort() function, but the comparison routine accepts a user data argument.

pbase : start of array to sort
total_elems : elements in the array
size : size of each element
compare_func : function to compare elements
user_data : data to pass to compare_func

g_nullify_pointer ()

void        g_nullify_pointer               (gpointer *nullify_location);

Set the pointer at the specified location to NULL.

nullify_location : the memory address of the pointer.