<refentry id="glib-Miscellaneous-Utility-Functions">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Miscellaneous-Utility-Functions.top_of_page">Miscellaneous Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Miscellaneous Utility Functions</refname>
<refpurpose>a selection of portable utility functions</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Miscellaneous-Utility-Functions.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

const <link linkend="gchar">gchar</link>*        <link linkend="g-get-application-name">g_get_application_name</link>              (void);
<link linkend="void">void</link>                <link linkend="g-set-application-name">g_set_application_name</link>              (const <link linkend="gchar">gchar</link> *application_name);
<link linkend="gchar">gchar</link>*              <link linkend="g-get-prgname">g_get_prgname</link>                       (void);
<link linkend="void">void</link>                <link linkend="g-set-prgname">g_set_prgname</link>                       (const <link linkend="gchar">gchar</link> *prgname);
const <link linkend="gchar">gchar</link>*        <link linkend="g-getenv">g_getenv</link>                            (const <link linkend="gchar">gchar</link> *variable);
<link linkend="gboolean">gboolean</link>            <link linkend="g-setenv">g_setenv</link>                            (const <link linkend="gchar">gchar</link> *variable,
                                                         const <link linkend="gchar">gchar</link> *value,
                                                         <link linkend="gboolean">gboolean</link> overwrite);
<link linkend="void">void</link>                <link linkend="g-unsetenv">g_unsetenv</link>                          (const <link linkend="gchar">gchar</link> *variable);
<link linkend="gchar">gchar</link>**             <link linkend="g-listenv">g_listenv</link>                           (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-user-name">g_get_user_name</link>                     (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-real-name">g_get_real_name</link>                     (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-user-cache-dir">g_get_user_cache_dir</link>                (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-user-data-dir">g_get_user_data_dir</link>                 (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-user-config-dir">g_get_user_config_dir</link>               (void);
enum                <link linkend="GUserDirectory">GUserDirectory</link>;
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-user-special-dir">g_get_user_special_dir</link>              (<link linkend="GUserDirectory">GUserDirectory</link> directory);
const <link linkend="gchar">gchar</link>* const * <link linkend="g-get-system-data-dirs">g_get_system_data_dirs</link>             (void);
const <link linkend="gchar">gchar</link>* const * <link linkend="g-get-system-config-dirs">g_get_system_config_dirs</link>           (void);

const <link linkend="gchar">gchar</link>*        <link linkend="g-get-host-name">g_get_host_name</link>                     (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-home-dir">g_get_home_dir</link>                      (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-get-tmp-dir">g_get_tmp_dir</link>                       (void);
<link linkend="gchar">gchar</link>*              <link linkend="g-get-current-dir">g_get_current_dir</link>                   (void);
const <link linkend="gchar">gchar</link>*        <link linkend="g-basename">g_basename</link>                          (const <link linkend="gchar">gchar</link> *file_name);
#define             <link linkend="g-dirname">g_dirname</link>
<link linkend="gboolean">gboolean</link>            <link linkend="g-path-is-absolute">g_path_is_absolute</link>                  (const <link linkend="gchar">gchar</link> *file_name);
const <link linkend="gchar">gchar</link>*        <link linkend="g-path-skip-root">g_path_skip_root</link>                    (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link>*              <link linkend="g-path-get-basename">g_path_get_basename</link>                 (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link>*              <link linkend="g-path-get-dirname">g_path_get_dirname</link>                  (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link> *             <link linkend="g-build-filename">g_build_filename</link>                    (const <link linkend="gchar">gchar</link> *first_element,
                                                         ...);
<link linkend="gchar">gchar</link> *             <link linkend="g-build-filenamev">g_build_filenamev</link>                   (<link linkend="gchar">gchar</link> **args);
<link linkend="gchar">gchar</link> *             <link linkend="g-build-path">g_build_path</link>                        (const <link linkend="gchar">gchar</link> *separator,
                                                         const <link linkend="gchar">gchar</link> *first_element,
                                                         ...);
<link linkend="gchar">gchar</link> *             <link linkend="g-build-pathv">g_build_pathv</link>                       (const <link linkend="gchar">gchar</link> *separator,
                                                         <link linkend="gchar">gchar</link> **args);
<link linkend="char">char</link> *              <link linkend="g-format-size-for-display">g_format_size_for_display</link>           (<link linkend="goffset">goffset</link> size);

<link linkend="gchar">gchar</link>*              <link linkend="g-find-program-in-path">g_find_program_in_path</link>              (const <link linkend="gchar">gchar</link> *program);

<link linkend="gint">gint</link>                <link linkend="g-bit-nth-lsf">g_bit_nth_lsf</link>                       (<link linkend="gulong">gulong</link> mask,
                                                         <link linkend="gint">gint</link> nth_bit);
<link linkend="gint">gint</link>                <link linkend="g-bit-nth-msf">g_bit_nth_msf</link>                       (<link linkend="gulong">gulong</link> mask,
                                                         <link linkend="gint">gint</link> nth_bit);
<link linkend="guint">guint</link>               <link linkend="g-bit-storage">g_bit_storage</link>                       (<link linkend="gulong">gulong</link> number);

<link linkend="guint">guint</link>               <link linkend="g-spaced-primes-closest">g_spaced_primes_closest</link>             (<link linkend="guint">guint</link> num);

<link linkend="void">void</link>                <link linkend="g-atexit">g_atexit</link>                            (<link linkend="GVoidFunc">GVoidFunc</link> func);

<link linkend="guint">guint</link>               <link linkend="g-parse-debug-string">g_parse_debug_string</link>                (const <link linkend="gchar">gchar</link> *string,
                                                         const <link linkend="GDebugKey">GDebugKey</link> *keys,
                                                         <link linkend="guint">guint</link> nkeys);
                    <link linkend="GDebugKey">GDebugKey</link>;

<link linkend="void">void</link>                (<link linkend="GVoidFunc">*GVoidFunc</link>)                        (void);
<link linkend="void">void</link>                (<link linkend="GFreeFunc">*GFreeFunc</link>)                        (<link linkend="gpointer">gpointer</link> data);

<link linkend="void">void</link>                <link linkend="g-qsort-with-data">g_qsort_with_data</link>                   (<link linkend="gconstpointer">gconstpointer</link> pbase,
                                                         <link linkend="gint">gint</link> total_elems,
                                                         <link linkend="gsize">gsize</link> size,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);

<link linkend="void">void</link>                <link linkend="g-nullify-pointer">g_nullify_pointer</link>                   (<link linkend="gpointer">gpointer</link> *nullify_location);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Miscellaneous-Utility-Functions.description" role="desc">
<title role="desc.title">Description</title>
<para>
These are portable utility functions.
</para>
</refsect1>

<refsect1 id="glib-Miscellaneous-Utility-Functions.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-get-application-name" role="function" condition="since:2.2">
<title>g_get_application_name ()</title>
<indexterm zone="g-get-application-name" role="2.2"><primary sortas="get_application_name">g_get_application_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_application_name              (void);</programlisting>
<para>
Gets a human-readable name for the application, as set by
<link linkend="g-set-application-name"><function>g_set_application_name()</function></link>. This name should be localized if
possible, and is intended for display to the user.  Contrast with
<link linkend="g-get-prgname"><function>g_get_prgname()</function></link>, which gets a non-localized name. If
<link linkend="g-set-application-name"><function>g_set_application_name()</function></link> has not been called, returns the result of
<link linkend="g-get-prgname"><function>g_get_prgname()</function></link> (which may be <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <link linkend="g-set-prgname"><function>g_set_prgname()</function></link> has also not
been called).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> human-readable application name. may return <link linkend="NULL--CAPS"><literal>NULL</literal></link>

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-set-application-name" role="function" condition="since:2.2">
<title>g_set_application_name ()</title>
<indexterm zone="g-set-application-name" role="2.2"><primary sortas="set_application_name">g_set_application_name</primary></indexterm><programlisting><link linkend="void">void</link>                g_set_application_name              (const <link linkend="gchar">gchar</link> *application_name);</programlisting>
<para>
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 <link linkend="g-set-prgname"><function>g_set_prgname()</function></link>, which sets a non-localized name.
<link linkend="g-set-prgname"><function>g_set_prgname()</function></link> will be called automatically by <link linkend="gtk-init"><function>gtk_init()</function></link>,
but <link linkend="g-set-application-name"><function>g_set_application_name()</function></link> will not.
</para>
<para>
Note that for thread safety reasons, this function can only
be called once.
</para>
<para>
The application name will be used in contexts such as error messages,
or when displaying an application's name in the task list.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>application_name</parameter>&#160;:</term>
<listitem><simpara> localized name of the application
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.2</para></refsect2>
<refsect2 id="g-get-prgname" role="function">
<title>g_get_prgname ()</title>
<indexterm zone="g-get-prgname"><primary sortas="get_prgname">g_get_prgname</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_get_prgname                       (void);</programlisting>
<para>
Gets the name of the program. This name should <emphasis>not</emphasis> 
be localized, contrast with <link linkend="g-get-application-name"><function>g_get_application_name()</function></link>.
(If you are using GDK or GTK+ the program name is set in <link linkend="gdk-init"><function>gdk_init()</function></link>, 
which is called by <link linkend="gtk-init"><function>gtk_init()</function></link>. The program name is found by taking 
the last component of <literal>argv[0]</literal>.)</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the name of the program. The returned string belongs 
to GLib and must not be modified or freed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-set-prgname" role="function">
<title>g_set_prgname ()</title>
<indexterm zone="g-set-prgname"><primary sortas="set_prgname">g_set_prgname</primary></indexterm><programlisting><link linkend="void">void</link>                g_set_prgname                       (const <link linkend="gchar">gchar</link> *prgname);</programlisting>
<para>
Sets the name of the program. This name should <emphasis>not</emphasis> 
be localized, contrast with <link linkend="g-set-application-name"><function>g_set_application_name()</function></link>. Note that for 
thread-safety reasons this function can only be called once.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>prgname</parameter>&#160;:</term>
<listitem><simpara> the name of the program.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-getenv" role="function">
<title>g_getenv ()</title>
<indexterm zone="g-getenv"><primary sortas="getenv">g_getenv</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_getenv                            (const <link linkend="gchar">gchar</link> *variable);</programlisting>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>variable</parameter>&#160;:</term>
<listitem><simpara> the environment variable to get, in the GLib file name encoding.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the value of the environment variable, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
the environment variable is not found. The returned string may be
overwritten by the next call to <link linkend="g-getenv"><function>g_getenv()</function></link>, <link linkend="g-setenv"><function>g_setenv()</function></link> or
<link linkend="g-unsetenv"><function>g_unsetenv()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-setenv" role="function" condition="since:2.4">
<title>g_setenv ()</title>
<indexterm zone="g-setenv" role="2.4"><primary sortas="setenv">g_setenv</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_setenv                            (const <link linkend="gchar">gchar</link> *variable,
                                                         const <link linkend="gchar">gchar</link> *value,
                                                         <link linkend="gboolean">gboolean</link> overwrite);</programlisting>
<para>
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.
</para>
<para>
Note that on some systems, when variables are overwritten, the memory 
used for the previous variables and its value isn't reclaimed.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>variable</parameter>&#160;:</term>
<listitem><simpara> the environment variable to set, must not contain '='.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> the value for to set the variable to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>overwrite</parameter>&#160;:</term>
<listitem><simpara> whether to change the variable if it already exists.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the environment variable couldn't be set.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-unsetenv" role="function" condition="since:2.4">
<title>g_unsetenv ()</title>
<indexterm zone="g-unsetenv" role="2.4"><primary sortas="unsetenv">g_unsetenv</primary></indexterm><programlisting><link linkend="void">void</link>                g_unsetenv                          (const <link linkend="gchar">gchar</link> *variable);</programlisting>
<para>
Removes an environment variable from the environment.
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>variable</parameter>&#160;:</term>
<listitem><simpara> the environment variable to remove, must not contain '='.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-listenv" role="function" condition="since:2.8">
<title>g_listenv ()</title>
<indexterm zone="g-listenv" role="2.8"><primary sortas="listenv">g_listenv</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             g_listenv                           (void);</programlisting>
<para>
Gets the names of all variables set in the environment.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated list of strings which must be freed
with <link linkend="g-strfreev"><function>g_strfreev()</function></link>.

Programs that want to be portable to Windows should typically use
this function and <link linkend="g-getenv"><function>g_getenv()</function></link> 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 <link linkend="g-getenv"><function>g_getenv()</function></link> provide.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-get-user-name" role="function">
<title>g_get_user_name ()</title>
<indexterm zone="g-get-user-name"><primary sortas="get_user_name">g_get_user_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_user_name                     (void);</programlisting>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user name of the current user.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-get-real-name" role="function">
<title>g_get_real_name ()</title>
<indexterm zone="g-get-real-name"><primary sortas="get_real_name">g_get_real_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_real_name                     (void);</programlisting>
<para>
Gets the real name of the user. This usually comes from the user's entry 
in the <filename>passwd</filename> 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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user's real name.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-get-user-cache-dir" role="function" condition="since:2.6">
<title>g_get_user_cache_dir ()</title>
<indexterm zone="g-get-user-cache-dir" role="2.6"><primary sortas="get_user_cache_dir">g_get_user_cache_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_user_cache_dir                (void);</programlisting>
<para>
Returns a base directory in which to store non-essential, cached
data specific to particular user.
</para>
<para>
On UNIX platforms this is determined using the mechanisms described in
the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
XDG Base Directory Specification</ulink></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string owned by GLib that must not be modified 
              or freed.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="g-get-user-data-dir" role="function" condition="since:2.6">
<title>g_get_user_data_dir ()</title>
<indexterm zone="g-get-user-data-dir" role="2.6"><primary sortas="get_user_data_dir">g_get_user_data_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_user_data_dir                 (void);</programlisting>
<para>
Returns a base directory in which to access application data such
as icons that is customized for a particular user.  
</para>
<para>
On UNIX platforms this is determined using the mechanisms described in
the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
XDG Base Directory Specification</ulink></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string owned by GLib that must not be modified 
              or freed.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="g-get-user-config-dir" role="function" condition="since:2.6">
<title>g_get_user_config_dir ()</title>
<indexterm zone="g-get-user-config-dir" role="2.6"><primary sortas="get_user_config_dir">g_get_user_config_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_user_config_dir               (void);</programlisting>
<para>
Returns a base directory in which to store user-specific application 
configuration information such as user preferences and settings. 
</para>
<para>
On UNIX platforms this is determined using the mechanisms described in
the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
XDG Base Directory Specification</ulink></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string owned by GLib that must not be modified 
              or freed.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="GUserDirectory" role="enum" condition="since:2.14">
<title>enum GUserDirectory</title>
<indexterm zone="GUserDirectory" role="2.14"><primary sortas="UserDirectory">GUserDirectory</primary></indexterm><programlisting>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;
</programlisting>
<para>
These are logical ids for special directories which are defined
depending on the platform used. You should use <link linkend="g-get-user-special-dir"><function>g_get_user_special_dir()</function></link>
to retrieve the full path associated to the logical id.
</para>
<para>
The <link linkend="GUserDirectory"><type>GUserDirectory</type></link> enumeration can be extended at later date. Not
every platform has a directory for every logical id in this
enumeration.</para>
<para>
</para><variablelist role="enum">
<varlistentry id="G-USER-DIRECTORY-DESKTOP--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_DESKTOP</literal></term>
<listitem><simpara> the user's Desktop directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-DOCUMENTS--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_DOCUMENTS</literal></term>
<listitem><simpara> the user's Documents directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-DOWNLOAD--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_DOWNLOAD</literal></term>
<listitem><simpara> the user's Downloads directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-MUSIC--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_MUSIC</literal></term>
<listitem><simpara> the user's Music directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-PICTURES--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_PICTURES</literal></term>
<listitem><simpara> the user's Pictures directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-PUBLIC-SHARE--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_PUBLIC_SHARE</literal></term>
<listitem><simpara> the user's shared directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-TEMPLATES--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_TEMPLATES</literal></term>
<listitem><simpara> the user's Templates directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-DIRECTORY-VIDEOS--CAPS" role="constant">
<term><literal>G_USER_DIRECTORY_VIDEOS</literal></term>
<listitem><simpara> the user's Movies directory
</simpara></listitem>
</varlistentry>
<varlistentry id="G-USER-N-DIRECTORIES--CAPS" role="constant">
<term><literal>G_USER_N_DIRECTORIES</literal></term>
<listitem><simpara> the number of enum values
</simpara></listitem>
</varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="g-get-user-special-dir" role="function" condition="since:2.14">
<title>g_get_user_special_dir ()</title>
<indexterm zone="g-get-user-special-dir" role="2.14"><primary sortas="get_user_special_dir">g_get_user_special_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_user_special_dir              (<link linkend="GUserDirectory">GUserDirectory</link> directory);</programlisting>
<para>
Returns the full path of a special directory using its logical id.
</para>
<para>
On Unix this is done using the XDG special user directories.
For compatibility with existing practise, <link linkend="G-USER-DIRECTORY-DESKTOP--CAPS"><literal>G_USER_DIRECTORY_DESKTOP</literal></link>
falls back to <filename>$HOME/Desktop</filename> when XDG special
user directories have not been set up. 
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>directory</parameter>&#160;:</term>
<listitem><simpara> the logical id of special directory
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the path to the specified special directory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
  if the logical id was not found. The returned string is owned by
  GLib and should not be modified or freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.14</para></refsect2>
<refsect2 id="g-get-system-data-dirs" role="function" condition="since:2.6">
<title>g_get_system_data_dirs ()</title>
<indexterm zone="g-get-system-data-dirs" role="2.6"><primary sortas="get_system_data_dirs">g_get_system_data_dirs</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* const * g_get_system_data_dirs             (void);</programlisting>
<para>
Returns an ordered list of base directories in which to access 
system-wide application data.
</para>
<para>
On UNIX platforms this is determined using the mechanisms described in
the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
XDG Base Directory Specification</ulink>
</para>
<para>
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.
</para>
<para>
Then follows the "share" subfolder in the installation folder for
the package containing the DLL that calls this function, if it can
be determined.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
Note that on Windows the returned list can vary depending on where
this function is called.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings owned by GLib that must 
              not be modified or freed.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="g-get-system-config-dirs" role="function" condition="since:2.6">
<title>g_get_system_config_dirs ()</title>
<indexterm zone="g-get-system-config-dirs" role="2.6"><primary sortas="get_system_config_dirs">g_get_system_config_dirs</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* const * g_get_system_config_dirs           (void);</programlisting>
<para>
Returns an ordered list of base directories in which to access 
system-wide configuration information.
</para>
<para>
On UNIX platforms this is determined using the mechanisms described in
the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
XDG Base Directory Specification</ulink></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings owned by GLib that must 
              not be modified or freed.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.6</para></refsect2>
<refsect2 id="g-get-host-name" role="function" condition="since:2.8">
<title>g_get_host_name ()</title>
<indexterm zone="g-get-host-name" role="2.8"><primary sortas="get_host_name">g_get_host_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_host_name                     (void);</programlisting>
<para>
Return a name for the machine. 
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the host name of the machine.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-get-home-dir" role="function">
<title>g_get_home_dir ()</title>
<indexterm zone="g-get-home-dir"><primary sortas="get_home_dir">g_get_home_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_home_dir                      (void);</programlisting>
<para>
Gets the current user's home directory as defined in the 
password database.
</para>
<para>
Note that in contrast to traditional UNIX tools, this function 
prefers <filename>passwd</filename> entries over the <envar>HOME</envar> 
environment variable. 
</para>
<para>
One of the reasons for this decision is that applications in many 
cases need special handling to deal with the case where 
<envar>HOME</envar> is
<simplelist>
  <member>Not owned by the user</member>
  <member>Not writeable</member>
  <member>Not even readable</member>
</simplelist>
Since applications are in general <emphasis>not</emphasis> written 
to deal with these situations it was considered better to make 
<link linkend="g-get-home-dir"><function>g_get_home_dir()</function></link> not pay attention to <envar>HOME</envar> and to 
return the real home directory for the user. If applications
want to pay attention to <envar>HOME</envar>, they can do:
<informalexample><programlisting>
 const char *homedir = g_getenv ("HOME");
  if (!homedir)
     homedir = g_get_home_dir (<!-- -->);
</programlisting></informalexample></para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the current user's home directory
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-get-tmp-dir" role="function">
<title>g_get_tmp_dir ()</title>
<indexterm zone="g-get-tmp-dir"><primary sortas="get_tmp_dir">g_get_tmp_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_get_tmp_dir                       (void);</programlisting>
<para>
Gets the directory to use for temporary files. This is found from 
inspecting the environment variables <envar>TMPDIR</envar>, 
<envar>TMP</envar>, and <envar>TEMP</envar> 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 <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the directory to use for temporary files.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-get-current-dir" role="function">
<title>g_get_current_dir ()</title>
<indexterm zone="g-get-current-dir"><primary sortas="get_current_dir">g_get_current_dir</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_get_current_dir                   (void);</programlisting>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the current directory.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-basename" role="function" condition="deprecated">
<title>g_basename ()</title>
<indexterm zone="g-basename" role="deprecated"><primary sortas="basename">g_basename</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_basename                          (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<warning><para><literal>g_basename</literal> has been deprecated since version 2.2 and should not be used in newly-written code. Use <link linkend="g-path-get-basename"><function>g_path_get_basename()</function></link> instead, but notice that
<link linkend="g-path-get-basename"><function>g_path_get_basename()</function></link> allocates new memory for the returned string, unlike
this function which returns a pointer into the argument.</para></warning>
<para>
Gets the name of the file without any leading directory components.  
It returns a pointer into the given file name string.</para>
<variablelist role="params">
<varlistentry><term><parameter>file_name</parameter>&#160;:</term>
<listitem><simpara> the name of the file.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the name of the file without any leading directory components.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-dirname" role="macro" condition="deprecated:">
<title>g_dirname</title>
<indexterm zone="g-dirname" role="deprecated"><primary sortas="dirname">g_dirname</primary></indexterm><programlisting>#define             g_dirname</programlisting>
<warning><para><literal>g_dirname</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
This function is deprecated and will be removed in the next major
release of GLib. Use <link linkend="g-path-get-dirname"><function>g_path_get_dirname()</function></link> instead.
</para>
<para>
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.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the directory components of the file.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-path-is-absolute" role="function">
<title>g_path_is_absolute ()</title>
<indexterm zone="g-path-is-absolute"><primary sortas="path_is_absolute">g_path_is_absolute</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_path_is_absolute                  (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the given <parameter>file_name</parameter> 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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file_name</parameter>&#160;:</term>
<listitem><simpara> a file name.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>file_name</parameter> is an absolute path. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-path-skip-root" role="function">
<title>g_path_skip_root ()</title>
<indexterm zone="g-path-skip-root"><primary sortas="path_skip_root">g_path_skip_root</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_path_skip_root                    (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
Returns a pointer into <parameter>file_name</parameter> after the root component, i.e. after
the "/" in UNIX or "C:\" under Windows. If <parameter>file_name</parameter> is not an absolute
path it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file_name</parameter>&#160;:</term>
<listitem><simpara> a file name.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer into <parameter>file_name</parameter> after the root component.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-path-get-basename" role="function">
<title>g_path_get_basename ()</title>
<indexterm zone="g-path-get-basename"><primary sortas="path_get_basename">g_path_get_basename</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_path_get_basename                 (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
Gets the last component of the filename. If <parameter>file_name</parameter> ends with a 
directory separator it gets the component before the last slash. If 
<parameter>file_name</parameter> consists only of directory separators (and on Windows, 
possibly a drive letter), a single separator is returned. If
<parameter>file_name</parameter> is empty, it gets ".".</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file_name</parameter>&#160;:</term>
<listitem><simpara> the name of the file.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string containing the last component of 
  the filename.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-path-get-dirname" role="function">
<title>g_path_get_dirname ()</title>
<indexterm zone="g-path-get-dirname"><primary sortas="path_get_dirname">g_path_get_dirname</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_path_get_dirname                  (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>file_name</parameter>&#160;:</term>
<listitem><simpara> the name of the file.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the directory components of the file.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-build-filename" role="function">
<title>g_build_filename ()</title>
<indexterm zone="g-build-filename"><primary sortas="build_filename">g_build_filename</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_build_filename                    (const <link linkend="gchar">gchar</link> *first_element,
                                                         ...);</programlisting>
<para>
Creates a filename from a series of elements using the correct
separator for filenames.
</para>
<para>
On Unix, this function behaves identically to <literal>g_build_path
(G_DIR_SEPARATOR_S, first_element, ....)</literal>.
</para>
<para>
On Windows, it takes into account that either the backslash
(<literal>\</literal> or slash (<literal>/</literal>) 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.
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>first_element</parameter>&#160;:</term>
<listitem><simpara> the first element in the path
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> remaining elements in path, terminated by <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-build-filenamev" role="function" condition="since:2.8">
<title>g_build_filenamev ()</title>
<indexterm zone="g-build-filenamev" role="2.8"><primary sortas="build_filenamev">g_build_filenamev</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_build_filenamev                   (<link linkend="gchar">gchar</link> **args);</programlisting>
<para>
Behaves exactly like <link linkend="g-build-filename"><function>g_build_filename()</function></link>, but takes the path elements 
as a string array, instead of varargs. This function is mainly
meant for language bindings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara> <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings containing the path elements.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-build-path" role="function">
<title>g_build_path ()</title>
<indexterm zone="g-build-path"><primary sortas="build_path">g_build_path</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_build_path                        (const <link linkend="gchar">gchar</link> *separator,
                                                         const <link linkend="gchar">gchar</link> *first_element,
                                                         ...);</programlisting>
<para>
Creates a path from a series of elements using <parameter>separator</parameter> 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.
</para>
<para>
Empty elements are ignored.
</para>
<para>
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.
</para>
<para>
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 <literal>ABA</literal>, <literal>ABABA</literal>
has 1 trailing copy.)
</para>
<para>
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.
</para>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter>&#160;:</term>
<listitem><simpara> a string used to separator the elements of the path.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_element</parameter>&#160;:</term>
<listitem><simpara> the first element in the path
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara> remaining elements in path, terminated by <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-build-pathv" role="function" condition="since:2.8">
<title>g_build_pathv ()</title>
<indexterm zone="g-build-pathv" role="2.8"><primary sortas="build_pathv">g_build_pathv</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_build_pathv                       (const <link linkend="gchar">gchar</link> *separator,
                                                         <link linkend="gchar">gchar</link> **args);</programlisting>
<para>
Behaves exactly like <link linkend="g-build-path"><function>g_build_path()</function></link>, but takes the path elements 
as a string array, instead of varargs. This function is mainly
meant for language bindings.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>separator</parameter>&#160;:</term>
<listitem><simpara> a string used to separator the elements of the path.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara> <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of strings containing the path elements.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-format-size-for-display" role="function" condition="since:2.16">
<title>g_format_size_for_display ()</title>
<indexterm zone="g-format-size-for-display" role="2.16"><primary sortas="format_size_for_display">g_format_size_for_display</primary></indexterm><programlisting><link linkend="char">char</link> *              g_format_size_for_display           (<link linkend="goffset">goffset</link> size);</programlisting>
<para>
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".
</para>
<para>
The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
</para>
<para>
This string should be freed with <link linkend="g-free"><function>g_free()</function></link> when not needed any longer.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara> a size in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated formatted string containing a human readable
         file size.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-find-program-in-path" role="function">
<title>g_find_program_in_path ()</title>
<indexterm zone="g-find-program-in-path"><primary sortas="find_program_in_path">g_find_program_in_path</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_find_program_in_path              (const <link linkend="gchar">gchar</link> *program);</programlisting>
<para>
Locates the first executable named <parameter>program</parameter> in the user's path, in the
same way that <link linkend="execvp"><function>execvp()</function></link> would locate it. Returns an allocated string
with the absolute path name, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the program is not found in
the path. If <parameter>program</parameter> is already an absolute path, returns a copy of
<parameter>program</parameter> if <parameter>program</parameter> exists and is executable, and <link linkend="NULL--CAPS"><literal>NULL</literal></link> otherwise.
 
On Windows, if <parameter>program</parameter> does not have a file type suffix, tries
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
the <envar>PATHEXT</envar> environment variable. 
</para>
<para>
On Windows, it looks for the file in the same way as <link linkend="CreateProcess"><function>CreateProcess()</function></link> 
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 <envar>PATH</envar> environment 
variable. If the program is found, the return value contains the 
full name including the type suffix.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>program</parameter>&#160;:</term>
<listitem><simpara> a program name in the GLib file name encoding
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> absolute path, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-bit-nth-lsf" role="function">
<title>g_bit_nth_lsf ()</title>
<indexterm zone="g-bit-nth-lsf"><primary sortas="bit_nth_lsf">g_bit_nth_lsf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_bit_nth_lsf                       (<link linkend="gulong">gulong</link> mask,
                                                         <link linkend="gint">gint</link> nth_bit);</programlisting>
<para>
Find the position of the first bit set in <parameter>mask</parameter>, searching from (but not
including) <parameter>nth_bit</parameter> upwards. Bits are numbered from 0 (least significant)
to sizeof(<link linkend="gulong"><type>gulong</type></link>) * 8 - 1 (31 or 63, usually). To start searching from the
0th bit, set <parameter>nth_bit</parameter> to -1.
</para><variablelist role="params">
<varlistentry><term><parameter>mask</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="gulong"><type>gulong</type></link> containing flags.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nth_bit</parameter>&#160;:</term>
<listitem><simpara>the index of the bit to start the search from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the index of the first bit set which is higher than <parameter>nth_bit</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-bit-nth-msf" role="function">
<title>g_bit_nth_msf ()</title>
<indexterm zone="g-bit-nth-msf"><primary sortas="bit_nth_msf">g_bit_nth_msf</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_bit_nth_msf                       (<link linkend="gulong">gulong</link> mask,
                                                         <link linkend="gint">gint</link> nth_bit);</programlisting>
<para>
Find the position of the first bit set in <parameter>mask</parameter>, searching from (but not
including) <parameter>nth_bit</parameter> downwards. Bits are numbered from 0 (least significant)
to sizeof(<link linkend="gulong"><type>gulong</type></link>) * 8 - 1 (31 or 63, usually). To start searching from the
last bit, set <parameter>nth_bit</parameter> to -1 or GLIB_SIZEOF_LONG * 8.
</para><variablelist role="params">
<varlistentry><term><parameter>mask</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="gulong"><type>gulong</type></link> containing flags.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nth_bit</parameter>&#160;:</term>
<listitem><simpara>the index of the bit to start the search from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the index of the first bit set which is lower than <parameter>nth_bit</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-bit-storage" role="function">
<title>g_bit_storage ()</title>
<indexterm zone="g-bit-storage"><primary sortas="bit_storage">g_bit_storage</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_bit_storage                       (<link linkend="gulong">gulong</link> number);</programlisting>
<para>
Gets the number of bits used to hold <parameter>number</parameter>,
e.g. if <parameter>number</parameter> is 4, 3 bits are needed.
</para><variablelist role="params">
<varlistentry><term><parameter>number</parameter>&#160;:</term>
<listitem><simpara>a guint.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the number of bits used to hold <parameter>number</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-spaced-primes-closest" role="function">
<title>g_spaced_primes_closest ()</title>
<indexterm zone="g-spaced-primes-closest"><primary sortas="spaced_primes_closest">g_spaced_primes_closest</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_spaced_primes_closest             (<link linkend="guint">guint</link> num);</programlisting>
<para>
Gets the smallest prime number from a built-in array of primes which
is larger than <parameter>num</parameter>. This is used within GLib to calculate the optimum
size of a <link linkend="GHashTable"><type>GHashTable</type></link>.
</para>
<para>
The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.
</para><variablelist role="params">
<varlistentry><term><parameter>num</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="guint"><type>guint</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the smallest prime number from a built-in array of primes which is
larger than <parameter>num</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-atexit" role="function">
<title>g_atexit ()</title>
<indexterm zone="g-atexit"><primary sortas="atexit">g_atexit</primary></indexterm><programlisting><link linkend="void">void</link>                g_atexit                            (<link linkend="GVoidFunc">GVoidFunc</link> func);</programlisting>
<para>
Specifies a function to be called at normal program termination.
</para>
<para>
Since GLib 2.8.2, on Windows <link linkend="g-atexit"><function>g_atexit()</function></link> actually is a preprocessor
macro that maps to a call to the <link linkend="atexit"><function>atexit()</function></link> function in the C
library. This means that in case the code that calls <link linkend="g-atexit"><function>g_atexit()</function></link>,
i.e. <link linkend="atexit"><function>atexit()</function></link>, 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 <link linkend="g-atexit"><function>g_atexit()</function></link> was a function in the GLib
DLL.
</para>
<para>
The behaviour of <link linkend="atexit"><function>atexit()</function></link> in the context of dynamically loaded
modules is not formally specified and varies wildly.
</para>
<para>
On POSIX systems, calling <link linkend="g-atexit"><function>g_atexit()</function></link> (or <link linkend="atexit"><function>atexit()</function></link>) in a dynamically
loaded module which is unloaded before the program terminates might
well cause a crash at program exit.
</para>
<para>
Some POSIX systems implement <link linkend="atexit"><function>atexit()</function></link> like Windows, and have each
dynamically loaded module maintain an own atexit chain that is
called when the module is unloaded.
</para>
<para>
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.
</para>
<para>
As can be seen from the above, for portability it's best to avoid
calling <link linkend="g-atexit"><function>g_atexit()</function></link> (or <link linkend="atexit"><function>atexit()</function></link>) except in the main executable of a
program.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call on normal program termination.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-parse-debug-string" role="function">
<title>g_parse_debug_string ()</title>
<indexterm zone="g-parse-debug-string"><primary sortas="parse_debug_string">g_parse_debug_string</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_parse_debug_string                (const <link linkend="gchar">gchar</link> *string,
                                                         const <link linkend="GDebugKey">GDebugKey</link> *keys,
                                                         <link linkend="guint">guint</link> nkeys);</programlisting>
<para>
Parses a string containing debugging options
into a <link linkend="guint"><literal>guint</literal></link> containing bit flags. This is used 
within GDK and GTK+ to parse the debug options passed on the
command line or through environment variables.
</para>
<para>
If <parameter>string</parameter> is equal to "all", all flags are set.  If <parameter>string</parameter>
is equal to "help", all the available keys in <parameter>keys</parameter> are printed
out to standard error.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara> a list of debug options separated by colons, spaces, or
commas, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>keys</parameter>&#160;:</term>
<listitem><simpara> pointer to an array of <link linkend="GDebugKey"><type>GDebugKey</type></link> which associate 
    strings with bit flags.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nkeys</parameter>&#160;:</term>
<listitem><simpara> the number of <link linkend="GDebugKey"><type>GDebugKey</type></link><!-- -->s in the array.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the combined set of bit flags.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GDebugKey" role="struct">
<title>GDebugKey</title>
<indexterm zone="GDebugKey"><primary sortas="DebugKey">GDebugKey</primary></indexterm><programlisting>typedef struct {
  const gchar *key;
  guint	       value;
} GDebugKey;
</programlisting>
<para>
Associates a string with a bit flag.
Used in <link linkend="g-parse-debug-string"><function>g_parse_debug_string()</function></link>.
</para><variablelist role="struct">
<varlistentry>
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>key</structfield>;</term>
<listitem><simpara>the string
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="guint">guint</link>&#160;<structfield>value</structfield>;</term>
<listitem><simpara>the flag
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="GVoidFunc" role="function">
<title>GVoidFunc ()</title>
<indexterm zone="GVoidFunc"><primary sortas="VoidFunc">GVoidFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GVoidFunc)                        (void);</programlisting>
<para>
Declares a type of function which takes no arguments and has no return value.
It is used to specify the type function passed to <link linkend="g-atexit"><function>g_atexit()</function></link>.
</para></refsect2>
<refsect2 id="GFreeFunc" role="function">
<title>GFreeFunc ()</title>
<indexterm zone="GFreeFunc"><primary sortas="FreeFunc">GFreeFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GFreeFunc)                        (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
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+.
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>a data pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-qsort-with-data" role="function">
<title>g_qsort_with_data ()</title>
<indexterm zone="g-qsort-with-data"><primary sortas="qsort_with_data">g_qsort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>                g_qsort_with_data                   (<link linkend="gconstpointer">gconstpointer</link> pbase,
                                                         <link linkend="gint">gint</link> total_elems,
                                                         <link linkend="gsize">gsize</link> size,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
This is just like the standard C <link linkend="qsort"><function>qsort()</function></link> function, but
the comparison routine accepts a user data argument.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>pbase</parameter>&#160;:</term>
<listitem><simpara> start of array to sort
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>total_elems</parameter>&#160;:</term>
<listitem><simpara> elements in the array
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara> size of each element
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara> function to compare elements
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> data to pass to <parameter>compare_func</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-nullify-pointer" role="function">
<title>g_nullify_pointer ()</title>
<indexterm zone="g-nullify-pointer"><primary sortas="nullify_pointer">g_nullify_pointer</primary></indexterm><programlisting><link linkend="void">void</link>                g_nullify_pointer                   (<link linkend="gpointer">gpointer</link> *nullify_location);</programlisting>
<para>
Set the pointer at the specified location to <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>nullify_location</parameter>&#160;:</term>
<listitem><simpara> the memory address of the pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
