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 :