![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
Miscellaneous Utility FunctionsMiscellaneous Utility Functions — a selection of portable utility functions |
#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); gchar** g_listenv (void); 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); enum GUserDirectory; const gchar* g_get_user_special_dir (GUserDirectory directory); const gchar* const * g_get_system_data_dirs (void); const gchar* const * g_get_system_config_dirs (void); const gchar* g_get_host_name (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_filenamev (gchar **args); gchar * g_build_path (const gchar *separator, const gchar *first_element, ...); gchar * g_build_pathv (const gchar *separator, gchar **args); char * g_format_size_for_display (goffset size); 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);
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
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.
|
localized name of the application |
Since 2.2
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. |
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.
|
the name of the program. |
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.
|
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() .
|
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.
|
the environment variable to set, must not contain '='. |
|
the value for to set the variable to. |
|
whether to change the variable if it already exists. |
Returns : |
FALSE if the environment variable couldn't be set.
|
Since 2.4
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.
|
the environment variable to remove, must not contain '='. |
Since 2.4
gchar** g_listenv (void);
Gets the names of all variables set in the environment.
Returns : |
a NULL -terminated list of strings which must be freed
with g_strfreev() .
Programs that want to be portable to Windows should typically use
this function and g_getenv() instead of using the environ array
from the C library directly. On Windows, the strings in the environ
array are in system codepage encoding, while in most of the typical
use cases for environment variables in GLib-using programs you want
the UTF-8 encoding that this function and g_getenv() provide.
|
Since 2.8
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. |
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. |
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
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
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
typedef enum { G_USER_DIRECTORY_DESKTOP, G_USER_DIRECTORY_DOCUMENTS, G_USER_DIRECTORY_DOWNLOAD, G_USER_DIRECTORY_MUSIC, G_USER_DIRECTORY_PICTURES, G_USER_DIRECTORY_PUBLIC_SHARE, G_USER_DIRECTORY_TEMPLATES, G_USER_DIRECTORY_VIDEOS, G_USER_N_DIRECTORIES } GUserDirectory;
These are logical ids for special directories which are defined
depending on the platform used. You should use g_get_user_special_dir()
to retrieve the full path associated to the logical id.
The GUserDirectory enumeration can be extended at later date. Not every platform has a directory for every logical id in this enumeration.
the user's Desktop directory | |
the user's Documents directory | |
the user's Downloads directory | |
the user's Music directory | |
the user's Pictures directory | |
the user's shared directory | |
the user's Templates directory | |
the user's Movies directory | |
the number of enum values |
Since 2.14
const gchar* g_get_user_special_dir (GUserDirectory directory);
Returns the full path of a special directory using its logical id.
On Unix this is done using the XDG special user directories.
For compatibility with existing practise, G_USER_DIRECTORY_DESKTOP
falls back to $HOME/Desktop
when XDG special
user directories have not been set up.
Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded.
|
the logical id of special directory |
Returns : |
the path to the specified special directory, or NULL
if the logical id was not found. The returned string is owned by
GLib and should not be modified or freed.
|
Since 2.14
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
On Windows the first elements in the list are the Application Data and Documents folders for All Users. (These can be determined only on Windows 2000 or later and are not present in the list on other Windows versions.) See documentation for CSIDL_COMMON_APPDATA and CSIDL_COMMON_DOCUMENTS.
Then follows the "share" subfolder in the installation folder for the package containing the DLL that calls this function, if it can be determined.
Finally the list contains the "share" subfolder in the installation folder for GLib, and in the installation folder for the package the application's .exe file belongs to.
The installation folders above are determined by looking up the folder where the module (DLL or EXE) in question is located. If the folder's name is "bin", its parent is used, otherwise the folder itself.
Note that on Windows the returned list can vary depending on where this function is called.
Returns : |
a NULL -terminated array of strings owned by GLib that must
not be modified or freed.
|
Since 2.6
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
const gchar* g_get_host_name (void);
Return a name for the machine.
The returned name is not necessarily a fully-qualified domain name, or even present in DNS or some other name service at all. It need not even be unique on your local network or site, but usually it is. Callers should not rely on the return value having any specific properties like uniqueness for security purposes. Even if the name of the machine is changed while an application is running, the return value from this function does not change. The returned string is owned by GLib and should not be modified or freed. If no name can be determined, a default fixed string "localhost" is returned.
Returns : |
the host name of the machine. |
Since 2.8
const gchar* g_get_home_dir (void);
Gets the current user's home directory as defined in the password database.
Note that in contrast to traditional UNIX tools, this function
prefers passwd
entries over the HOME
environment variable.
One of the reasons for this decision is that applications in many
cases need special handling to deal with the case where
HOME
is
Not owned by the user |
Not writeable |
Not even readable |
Since applications are in general not written
to deal with these situations it was considered better to make
g_get_home_dir()
not pay attention to HOME
and to
return the real home directory for the user. If applications
want to pay attention to HOME
, they can do:
const char *homedir = g_getenv ("HOME"); if (!homedir) homedir = g_get_home_dir ();
Returns : |
the current user's home directory |
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. |
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. |
const gchar* g_basename (const gchar *file_name);
g_basename
has been deprecated since version 2.2 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.
|
the name of the file. |
Returns : |
the name of the file without any leading directory components. |
#define g_dirname
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. |
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.
|
a file name. |
Returns : |
TRUE if file_name is an absolute path.
|
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
.
|
a file name. |
Returns : |
a pointer into file_name after the root component.
|
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 ".".
|
the name of the file. |
Returns : |
a newly allocated string containing the last component of the filename. |
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.
|
the name of the file. |
Returns : |
the directory components of the file. |
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.
gchar * g_build_filenamev (gchar **args);
Behaves exactly like g_build_filename()
, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.
|
NULL -terminated array of strings containing the path elements.
|
Returns : |
a newly-allocated string that must be freed with g_free() .
|
Since 2.8
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.
gchar * g_build_pathv (const gchar *separator, gchar **args);
Behaves exactly like g_build_path()
, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.
|
a string used to separator the elements of the path. |
|
NULL -terminated array of strings containing the path elements.
|
Returns : |
a newly-allocated string that must be freed with g_free() .
|
Since 2.8
char * g_format_size_for_display (goffset size);
Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (KB, MB, GB) and are displayed rounded to the nearest tenth. E.g. the file size 3292528 bytes will be converted into the string "3.1 MB".
The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
This string should be freed with g_free()
when not needed any longer.
|
a size in bytes. |
Returns : |
a newly-allocated formatted string containing a human readable file size. |
Since 2.16
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.
On Windows, 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.
|
a program name in the GLib file name encoding |
Returns : |
absolute path, or NULL
|
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.
|
a gulong containing flags. |
|
the index of the bit to start the search from. |
Returns : |
the index of the first bit set which is higher than nth_bit .
|
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.
|
a gulong containing flags. |
|
the index of the bit to start the search from. |
Returns : |
the index of the first bit set which is lower than nth_bit .
|
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.
|
a guint. |
Returns : |
the number of bits used to hold number .
|
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.
|
a guint. |
Returns : |
the smallest prime number from a built-in array of primes which is
larger than num .
|
void g_atexit (GVoidFunc func);
Specifies a function to be called at normal program termination.
Since GLib 2.8.2, on Windows g_atexit()
actually is a preprocessor
macro that maps to a call to the atexit()
function in the C
library. This means that in case the code that calls g_atexit()
,
i.e. atexit()
, is in a DLL, the function will be called when the
DLL is detached from the program. This typically makes more sense
than that the function is called when the GLib DLL is detached,
which happened earlier when g_atexit()
was a function in the GLib
DLL.
The behaviour of atexit()
in the context of dynamically loaded
modules is not formally specified and varies wildly.
On POSIX systems, calling g_atexit()
(or atexit()
) in a dynamically
loaded module which is unloaded before the program terminates might
well cause a crash at program exit.
Some POSIX systems implement atexit()
like Windows, and have each
dynamically loaded module maintain an own atexit chain that is
called when the module is unloaded.
On other POSIX systems, before a dynamically loaded module is unloaded, the registered atexit functions (if any) residing in that module are called, regardless where the code that registered them resided. This is presumably the most robust approach.
As can be seen from the above, for portability it's best to avoid
calling g_atexit()
(or atexit()
) except in the main executable of a
program.
|
the function to call on normal program termination. |
guint g_parse_debug_string (const gchar *string, const GDebugKey *keys, guint nkeys);
Parses a string containing debugging options
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.
If string
is equal to "all", all flags are set. If string
is equal to "help", all the available keys in keys
are printed
out to standard error.
typedef struct { const gchar *key; guint value; } GDebugKey;
Associates a string with a bit flag.
Used in g_parse_debug_string()
.
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()
.
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+.
|
a data pointer. |
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.
|
start of array to sort |
|
elements in the array |
|
size of each element |
|
function to compare elements |
|
data to pass to compare_func
|