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);
    gchar*      g_getenv                        (const gchar *variable);
    gchar*      g_get_user_name                 (void);
    gchar*      g_get_real_name                 (void);

    gchar*      g_get_home_dir                  (void);
    gchar*      g_get_tmp_dir                   (void);
    gchar*      g_get_current_dir               (void);
    gchar*      g_basename                      (const gchar *file_name);
    gchar*      g_dirname                       (const gchar *file_name);
    gboolean    g_path_is_absolute              (const gchar *file_name);
    gchar*      g_path_skip_root                (gchar *file_name);

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

    guint       g_spaced_primes_closest         (guint num);

    void        g_atexit                        (GVoidFunc func);

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

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

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

    gchar*      g_getenv                        (const gchar *variable);

Returns an environment variable. On windows systems the returned value is only valid until the next call to g_getenv().

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

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

    gchar*      g_get_real_name                 (void);

Gets the real name of the user. This comes from the user's entry in the passwd file.

Returns : | the user's real name.

### g_get_home_dir ()

    gchar*      g_get_home_dir                  (void);

Gets the current user's home directory.

Returns : | the current user's home directory.

### g_get_tmp_dir ()

    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.

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

    gchar*      g_basename                      (const gchar *file_name);

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

    gchar*      g_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_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' or 'C:/windows' on windows systems.

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

### g_path_skip_root ()

    gchar*      g_path_skip_root                (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_bit_nth_lsf ()

    gint        g_bit_nth_lsf                   (guint32 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                   (guint32 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                   (guint 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,
                                                 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` : |

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