GLib Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Miscellaneous Utility Functions

## Name

Miscellaneous Utility Functions -- a selection of portable utility functions.

## Synopsis

    #include <glib.h>

    gchar*      g_get_prgname                   (void);
    void        g_set_prgname                   (const gchar *prgname);
    G_CONST_RETURN gchar* g_getenv              (const gchar *variable);
    G_CONST_RETURN gchar* g_get_user_name       (void);
    G_CONST_RETURN gchar* g_get_real_name       (void);

    G_CONST_RETURN gchar* g_get_home_dir        (void);
    G_CONST_RETURN gchar* g_get_tmp_dir         (void);
    gchar*      g_get_current_dir               (void);
    G_CONST_RETURN gchar* g_basename            (const gchar *file_name);
    #define     g_dirname
    gboolean    g_path_is_absolute              (const gchar *file_name);
    G_CONST_RETURN 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);
    struct      GDebugKey;

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

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

    void        g_nullify_pointer               (gpointer *nullify_location);

## Description

These are portable utility functions.

## Details

### g_get_prgname ()

    gchar*      g_get_prgname                   (void);

Gets the name of the program. (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.

### g_set_prgname ()

    void        g_set_prgname                   (const gchar *prgname);

Sets the name of the program.

`prgname` : | the name of the program.

### g_getenv ()

    G_CONST_RETURN gchar* g_getenv              (const gchar *variable);

Returns an environment variable.

`variable` : | the environment variable to get.
Returns : | the value of the environment variable, or `NULL` if the environment variable is not found.

### g_get_user_name ()

    G_CONST_RETURN gchar* g_get_user_name       (void);

Gets the user name of the current user.

Returns : | the user name of the current user.

### g_get_real_name ()

    G_CONST_RETURN 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.

Returns : | the user's real name.

### g_get_home_dir ()

    G_CONST_RETURN gchar* g_get_home_dir        (void);

Gets the current user's home directory.

Returns : | the current user's home directory.

### g_get_tmp_dir ()

    G_CONST_RETURN 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.

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.

Returns : | the current directory.

### g_basename ()

    G_CONST_RETURN gchar* g_basename            (const gchar *file_name);

Warning
`g_basename` 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_basename() instead.

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 ()

    G_CONST_RETURN 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 name of the file without any leading directory components. The returned string should be freed when no longer needed.

> Note: This function allocates new memory for the returned string. This is different from the old g_basename() function, which returned a pointer into the argument.

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

### 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. This function behaves identically to `g_build_path (G_DIR_SEPARATOR_S, first_element, ....)`.

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
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.

`separator` : | a string used to separator the elements of the path.
`first_element` : | the first element in the path
`...` : | remaining elements in path
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 to append the suffixes in the PATHEXT environment variable (if that doesn't exists, the suffixes .com, .exe, and .bat) in turn, and then look for the resulting file name in the same way as CreateProcess() would. This means first in the directory where the 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
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 31. To start searching from the 0th bit, set `nth_bit` to -1.

`mask` : | a guint32 containing up to 32 bit 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 31. To start searching from the 31st bit, set `nth_bit` to 32 or -1.

`mask` : | a guint32 containing up to 32 bit 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.

### struct GDebugKey

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

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,
                                                 size_t 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.

<<< Previous Page | Home | Up | Next Page >>>
Hook Functions | Lexical Scanner