<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<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>

<refsect1 id="glib-Miscellaneous-Utility-Functions.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-application-name">g_get_application_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-set-application-name">g_set_application_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-prgname">g_get_prgname</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-set-prgname">g_set_prgname</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-get-environ">g_get_environ</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-environ-getenv">g_environ_getenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-environ-setenv">g_environ_setenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-environ-unsetenv">g_environ_unsetenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-getenv">g_getenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-setenv">g_setenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-unsetenv">g_unsetenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="g-listenv">g_listenv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-name">g_get_user_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-real-name">g_get_real_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-cache-dir">g_get_user_cache_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-data-dir">g_get_user_data_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-config-dir">g_get_user_config_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-runtime-dir">g_get_user_runtime_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-user-special-dir">g_get_user_special_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;* const *
</entry><entry role="function_name"><link linkend="g-get-system-data-dirs">g_get_system_data_dirs</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;* const *
</entry><entry role="function_name"><link linkend="g-get-system-config-dirs">g_get_system_config_dirs</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-reload-user-special-dirs-cache">g_reload_user_special_dirs_cache</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-host-name">g_get_host_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-home-dir">g_get_home_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-tmp-dir">g_get_tmp_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-get-current-dir">g_get_current_dir</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-basename">g_basename</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-canonicalize-filename">g_canonicalize_filename</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-path-is-absolute">g_path_is_absolute</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-path-skip-root">g_path_skip_root</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-path-get-basename">g_path_get_basename</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-path-get-dirname">g_path_get_dirname</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-build-filename">g_build_filename</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-build-filenamev">g_build_filenamev</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-build-filename-valist">g_build_filename_valist</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-build-path">g_build_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-build-pathv">g_build_pathv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-format-size">g_format_size</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-format-size-full">g_format_size_full</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-format-size-for-display">g_format_size_for_display</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-find-program-in-path">g_find_program_in_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-bit-nth-lsf">g_bit_nth_lsf</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-bit-nth-msf">g_bit_nth_msf</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-bit-storage">g_bit_storage</link><phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-spaced-primes-closest">g_spaced_primes_closest</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atexit">g_atexit</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-abort">g_abort</link></entry></row>

<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-parse-debug-string">g_parse_debug_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GVoidFunc">*GVoidFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GFreeFunc">*GFreeFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-qsort-with-data">g_qsort_with_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-nullify-pointer">g_nullify_pointer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Miscellaneous-Utility-Functions.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GUserDirectory">GUserDirectory</link></entry></row>

<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-dirname">g_dirname</link></entry></row>

<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GFormatSizeFlags">GFormatSizeFlags</link></entry></row>





<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GDebugKey">GDebugKey</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Miscellaneous-Utility-Functions.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
#include &lt;glib/gprintf.h&gt;
</synopsis></refsect1>

<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.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-get-application-name" role="function" condition="since:2.2">
<title>g_get_application_name&#160;()</title>
<indexterm zone="g-get-application-name" role="2.2"><primary sortas="get_application_name">g_get_application_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_application_name (<parameter><type>void</type></parameter>);</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>
<refsect3 id="g-get-application-name.returns" role="returns">
<title>Returns</title>
<para> human-readable application name. may return <link linkend="NULL:CAPS"><literal>NULL</literal></link></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-set-application-name" role="function" condition="since:2.2">
<title>g_set_application_name&#160;()</title>
<indexterm zone="g-set-application-name" role="2.2"><primary sortas="set_application_name">g_set_application_name</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_set_application_name (<parameter>const <link linkend="gchar"><type>gchar</type></link> *application_name</parameter>);</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>
<refsect3 id="g-set-application-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>application_name</para></entry>
<entry role="parameter_description"><para>localized name of the application</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.2">2.2</link></para></refsect2>
<refsect2 id="g-get-prgname" role="function">
<title>g_get_prgname&#160;()</title>
<indexterm zone="g-get-prgname"><primary sortas="get_prgname">g_get_prgname</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_prgname (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the name of the program. This name should not be localized,
in contrast to <link linkend="g-get-application-name"><function>g_get_application_name()</function></link>.</para>
<para>If you are using <link linkend="GApplication"><type>GApplication</type></link> the program name is set in
<link linkend="g-application-run"><function>g_application_run()</function></link>. In case of GDK or GTK+ it 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> and the
<link linkend="GtkApplication-startup"><type>“startup”</type></link> handler. The program name is found by
taking the last component of <parameter>argv</parameter>
[0].</para>
<refsect3 id="g-get-prgname.returns" role="returns">
<title>Returns</title>
<para>the name of the program, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if it has not been
set yet. The returned string belongs
to GLib and must not be modified or freed. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-set-prgname" role="function">
<title>g_set_prgname&#160;()</title>
<indexterm zone="g-set-prgname"><primary sortas="set_prgname">g_set_prgname</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_set_prgname (<parameter>const <link linkend="gchar"><type>gchar</type></link> *prgname</parameter>);</programlisting>
<para>Sets the name of the program. This name should not be localized,
in contrast to <link linkend="g-set-application-name"><function>g_set_application_name()</function></link>.</para>
<para>If you are using <link linkend="GApplication"><type>GApplication</type></link> the program name is set in
<link linkend="g-application-run"><function>g_application_run()</function></link>. In case of GDK or GTK+ it 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> and the
<link linkend="GtkApplication-startup"><type>“startup”</type></link> handler. The program name is found by
taking the last component of <parameter>argv</parameter>
[0].</para>
<para>Note that for thread-safety reasons this function can only be called once.</para>
<refsect3 id="g-set-prgname.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>prgname</para></entry>
<entry role="parameter_description"><para>the name of the program.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-get-environ" role="function" condition="since:2.28">
<title>g_get_environ&#160;()</title>
<indexterm zone="g-get-environ" role="2.28"><primary sortas="get_environ">g_get_environ</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_get_environ (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the list of environment variables for the current process.</para>
<para>The list is <link linkend="NULL:CAPS"><literal>NULL</literal></link> terminated and each item in the list is of the
form 'NAME=VALUE'.</para>
<para>This is equivalent to direct access to the 'environ' global variable,
except portable.</para>
<para>The return value is freshly allocated and it should be freed with
<link linkend="g-strfreev"><function>g_strfreev()</function></link> when it is no longer needed.</para>
<refsect3 id="g-get-environ.returns" role="returns">
<title>Returns</title>
<para>the list of environment variables. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-environ-getenv" role="function" condition="since:2.32">
<title>g_environ_getenv&#160;()</title>
<indexterm zone="g-environ-getenv" role="2.32"><primary sortas="environ_getenv">g_environ_getenv</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_environ_getenv (<parameter><link linkend="gchar"><type>gchar</type></link> **envp</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>);</programlisting>
<para>Returns the value of the environment variable <parameter>variable</parameter>
 in the
provided list <parameter>envp</parameter>
.</para>
<refsect3 id="g-environ-getenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>envp</para></entry>
<entry role="parameter_description"><para>an environment list (eg, as returned from <link linkend="g-get-environ"><function>g_get_environ()</function></link>), or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
for an empty environment list. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>array</acronym> zero-terminated=1][<acronym>transfer none</acronym>][<acronym>element-type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to get. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-environ-getenv.returns" role="returns">
<title>Returns</title>
<para>the value of the environment variable, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
the environment variable is not set in <parameter>envp</parameter>
. The returned
string is owned by <parameter>envp</parameter>
, and will be freed if <parameter>variable</parameter>
is
set or unset again. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="g-environ-setenv" role="function" condition="since:2.32">
<title>g_environ_setenv&#160;()</title>
<indexterm zone="g-environ-setenv" role="2.32"><primary sortas="environ_setenv">g_environ_setenv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_environ_setenv (<parameter><link linkend="gchar"><type>gchar</type></link> **envp</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>,
                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
                  <parameter><link linkend="gboolean"><type>gboolean</type></link> overwrite</parameter>);</programlisting>
<para>Sets the environment variable <parameter>variable</parameter>
 in the provided list
<parameter>envp</parameter>
 to <parameter>value</parameter>
.</para>
<refsect3 id="g-environ-setenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>envp</para></entry>
<entry role="parameter_description"><para>an environment list that can be freed using <link linkend="g-strfreev"><function>g_strfreev()</function></link> (e.g., as
returned from <link linkend="g-get-environ"><function>g_get_environ()</function></link>), or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for an empty
environment list. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to set, must not
contain '='. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>the value for to set the variable to. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>overwrite</para></entry>
<entry role="parameter_description"><para>whether to change the variable if it already exists</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-environ-setenv.returns" role="returns">
<title>Returns</title>
<para>the updated environment list. Free it using <link linkend="g-strfreev"><function>g_strfreev()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="g-environ-unsetenv" role="function" condition="since:2.32">
<title>g_environ_unsetenv&#160;()</title>
<indexterm zone="g-environ-unsetenv" role="2.32"><primary sortas="environ_unsetenv">g_environ_unsetenv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_environ_unsetenv (<parameter><link linkend="gchar"><type>gchar</type></link> **envp</parameter>,
                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>);</programlisting>
<para>Removes the environment variable <parameter>variable</parameter>
 from the provided
environment <parameter>envp</parameter>
.</para>
<refsect3 id="g-environ-unsetenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>envp</para></entry>
<entry role="parameter_description"><para>an environment list that can be freed using <link linkend="g-strfreev"><function>g_strfreev()</function></link> (e.g., as
returned from <link linkend="g-get-environ"><function>g_get_environ()</function></link>), or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for an empty environment list. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to remove, must not
contain '='. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-environ-unsetenv.returns" role="returns">
<title>Returns</title>
<para>the updated environment list. Free it using <link linkend="g-strfreev"><function>g_strfreev()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="g-getenv" role="function">
<title>g_getenv&#160;()</title>
<indexterm zone="g-getenv"><primary sortas="getenv">g_getenv</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_getenv (<parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>);</programlisting>
<para>Returns the value of an environment variable.</para>
<para>On UNIX, the name and value are byte strings which might or might not
be in some consistent character set and encoding. On Windows, they are
in UTF-8.
On Windows, in case the environment variable's value contains
references to other environment variables, they are expanded.</para>
<refsect3 id="g-getenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to get. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-getenv.returns" role="returns">
<title>Returns</title>
<para>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>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-setenv" role="function" condition="since:2.4">
<title>g_setenv&#160;()</title>
<indexterm zone="g-setenv" role="2.4"><primary sortas="setenv">g_setenv</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_setenv (<parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>,
          <parameter>const <link linkend="gchar"><type>gchar</type></link> *value</parameter>,
          <parameter><link linkend="gboolean"><type>gboolean</type></link> overwrite</parameter>);</programlisting>
<para>Sets an environment variable. On UNIX, both the variable's name and
value can be arbitrary byte strings, except that the variable's name
cannot contain '='. 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>You should be mindful of the fact that environment variable handling
in UNIX is not thread-safe, and your program may crash if one thread
calls <link linkend="g-setenv"><function>g_setenv()</function></link> while another thread is calling <link linkend="getenv"><function>getenv()</function></link>. (And note
that many functions, such as <link linkend="gettext"><function>gettext()</function></link>, call <link linkend="getenv"><function>getenv()</function></link> internally.)
This function is only safe to use at the very start of your program,
before creating any other threads (or creating objects that create
worker threads of their own).</para>
<para>If you need to set up the environment for a child process, you can
use <link linkend="g-get-environ"><function>g_get_environ()</function></link> to get an environment array, modify that with
<link linkend="g-environ-setenv"><function>g_environ_setenv()</function></link> and <link linkend="g-environ-unsetenv"><function>g_environ_unsetenv()</function></link>, and then pass that
array directly to <link linkend="execvpe"><function>execvpe()</function></link>, <link linkend="g-spawn-async"><function>g_spawn_async()</function></link>, or the like.</para>
<refsect3 id="g-setenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to set, must not
contain '='. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>the value for to set the variable to. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>overwrite</para></entry>
<entry role="parameter_description"><para>whether to change the variable if it already exists.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-setenv.returns" role="returns">
<title>Returns</title>
<para> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the environment variable couldn't be set.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-unsetenv" role="function" condition="since:2.4">
<title>g_unsetenv&#160;()</title>
<indexterm zone="g-unsetenv" role="2.4"><primary sortas="unsetenv">g_unsetenv</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_unsetenv (<parameter>const <link linkend="gchar"><type>gchar</type></link> *variable</parameter>);</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.</para>
<para>You should be mindful of the fact that environment variable handling
in UNIX is not thread-safe, and your program may crash if one thread
calls <link linkend="g-unsetenv"><function>g_unsetenv()</function></link> while another thread is calling <link linkend="getenv"><function>getenv()</function></link>. (And note
that many functions, such as <link linkend="gettext"><function>gettext()</function></link>, call <link linkend="getenv"><function>getenv()</function></link> internally.) This
function is only safe to use at the very start of your program, before
creating any other threads (or creating objects that create worker
threads of their own).</para>
<para>If you need to set up the environment for a child process, you can
use <link linkend="g-get-environ"><function>g_get_environ()</function></link> to get an environment array, modify that with
<link linkend="g-environ-setenv"><function>g_environ_setenv()</function></link> and <link linkend="g-environ-unsetenv"><function>g_environ_unsetenv()</function></link>, and then pass that
array directly to <link linkend="execvpe"><function>execvpe()</function></link>, <link linkend="g-spawn-async"><function>g_spawn_async()</function></link>, or the like.</para>
<refsect3 id="g-unsetenv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>variable</para></entry>
<entry role="parameter_description"><para>the environment variable to remove, must
not contain '='. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-listenv" role="function" condition="since:2.8">
<title>g_listenv&#160;()</title>
<indexterm zone="g-listenv" role="2.8"><primary sortas="listenv">g_listenv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
g_listenv (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the names of all variables set in the environment.</para>
<para>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.</para>
<refsect3 id="g-listenv.returns" role="returns">
<title>Returns</title>
<para>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>. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-get-user-name" role="function">
<title>g_get_user_name&#160;()</title>
<indexterm zone="g-get-user-name"><primary sortas="get_user_name">g_get_user_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_name (<parameter><type>void</type></parameter>);</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>
<refsect3 id="g-get-user-name.returns" role="returns">
<title>Returns</title>
<para>the user name of the current user. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-get-real-name" role="function">
<title>g_get_real_name&#160;()</title>
<indexterm zone="g-get-real-name"><primary sortas="get_real_name">g_get_real_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_real_name (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the real name of the user. This usually comes from the user's
entry in the <literal>passwd</literal> 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>
<refsect3 id="g-get-real-name.returns" role="returns">
<title>Returns</title>
<para>the user's real name. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-get-user-cache-dir" role="function" condition="since:2.6">
<title>g_get_user_cache_dir&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_cache_dir (<parameter><type>void</type></parameter>);</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>.
In this case the directory retrieved will be <literal>XDG_CACHE_HOME</literal>.</para>
<para>On Windows it follows XDG Base Directory Specification if <literal>XDG_CACHE_HOME</literal> is defined.
If <literal>XDG_CACHE_HOME</literal> is undefined, the directory that serves as a common
repository for temporary Internet files is used instead. A typical path is
<literal>C:\Documents and Settings\username\Local Settings\Temporary Internet Files</literal>.
See the <ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache">documentation for <literal>CSIDL_INTERNET_CACHE</literal></ulink>.</para>
<refsect3 id="g-get-user-cache-dir.returns" role="returns">
<title>Returns</title>
<para>a string owned by GLib that must not be modified
or freed. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-get-user-data-dir" role="function" condition="since:2.6">
<title>g_get_user_data_dir&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_data_dir (<parameter><type>void</type></parameter>);</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>.
In this case the directory retrieved will be <literal>XDG_DATA_HOME</literal>.</para>
<para>On Windows it follows XDG Base Directory Specification if <literal>XDG_DATA_HOME</literal>
is defined. If <literal>XDG_DATA_HOME</literal> is undefined, the folder to use for local (as
opposed to roaming) application data is used instead. See the
<ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata">documentation for <literal>CSIDL_LOCAL_APPDATA</literal></ulink>.
Note that in this case on Windows it will be the same
as what <link linkend="g-get-user-config-dir"><function>g_get_user_config_dir()</function></link> returns.</para>
<refsect3 id="g-get-user-data-dir.returns" role="returns">
<title>Returns</title>
<para>a string owned by GLib that must not be modified
or freed. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-get-user-config-dir" role="function" condition="since:2.6">
<title>g_get_user_config_dir&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_config_dir (<parameter><type>void</type></parameter>);</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>.
In this case the directory retrieved will be <literal>XDG_CONFIG_HOME</literal>.</para>
<para>On Windows it follows XDG Base Directory Specification if <literal>XDG_CONFIG_HOME</literal> is defined.
If <literal>XDG_CONFIG_HOME</literal> is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
<ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata">documentation for <literal>CSIDL_LOCAL_APPDATA</literal></ulink>.
Note that in this case on Windows it will be  the same
as what <link linkend="g-get-user-data-dir"><function>g_get_user_data_dir()</function></link> returns.</para>
<refsect3 id="g-get-user-config-dir.returns" role="returns">
<title>Returns</title>
<para>a string owned by GLib that must not be modified
or freed. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-get-user-runtime-dir" role="function" condition="since:2.28">
<title>g_get_user_runtime_dir&#160;()</title>
<indexterm zone="g-get-user-runtime-dir" role="2.28"><primary sortas="get_user_runtime_dir">g_get_user_runtime_dir</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_runtime_dir (<parameter><type>void</type></parameter>);</programlisting>
<para>Returns a directory that is unique to the current user on the local
system.</para>
<para>This is determined using the mechanisms described
in the 
<ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG Base Directory Specification</ulink>.
This is the directory
specified in the <literal>XDG_RUNTIME_DIR</literal> environment variable.
In the case that this variable is not set, we return the value of
<link linkend="g-get-user-cache-dir"><function>g_get_user_cache_dir()</function></link>, after verifying that it exists.</para>
<refsect3 id="g-get-user-runtime-dir.returns" role="returns">
<title>Returns</title>
<para>a string owned by GLib that must not be
modified or freed. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.28">2.28</link></para></refsect2>
<refsect2 id="g-get-user-special-dir" role="function" condition="since:2.14">
<title>g_get_user_special_dir&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_user_special_dir (<parameter><link linkend="GUserDirectory"><type>GUserDirectory</type></link> directory</parameter>);</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 <literal>$HOME/Desktop</literal> 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>
<refsect3 id="g-get-user-special-dir.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>directory</para></entry>
<entry role="parameter_description"><para>the logical id of special directory</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-get-user-special-dir.returns" role="returns">
<title>Returns</title>
<para>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. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-get-system-data-dirs" role="function" condition="since:2.6">
<title>g_get_system_data_dirs&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;* const *
g_get_system_data_dirs (<parameter><type>void</type></parameter>);</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>
In this case the list of directories retrieved will be <literal>XDG_DATA_DIRS</literal>.</para>
<para>On Windows it follows XDG Base Directory Specification if <literal>XDG_DATA_DIRS</literal> is defined.
If <literal>XDG_DATA_DIRS</literal> is undefined,
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>
<refsect3 id="g-get-system-data-dirs.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings owned by GLib that must not be
modified or freed. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-get-system-config-dirs" role="function" condition="since:2.6">
<title>g_get_system_config_dirs&#160;()</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 language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;* const *
g_get_system_config_dirs (<parameter><type>void</type></parameter>);</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>.
In this case the list of directories retrieved will be <literal>XDG_CONFIG_DIRS</literal>.</para>
<para>On Windows it follows XDG Base Directory Specification if <literal>XDG_CONFIG_DIRS</literal> is defined.
If <literal>XDG_CONFIG_DIRS</literal> is undefined, the directory that contains application
data for all users is used instead. A typical path is
<literal>C:\Documents and Settings\All Users\Application Data</literal>.
This folder is used for application data
that is not user specific. For example, an application can store
a spell-check dictionary, a database of clip art, or a log file in the
CSIDL_COMMON_APPDATA folder. This information will not roam and is available
to anyone using the computer.</para>
<refsect3 id="g-get-system-config-dirs.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of strings owned by GLib that must not be
modified or freed. </para>
<para><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.6">2.6</link></para></refsect2>
<refsect2 id="g-reload-user-special-dirs-cache" role="function" condition="since:2.22">
<title>g_reload_user_special_dirs_cache&#160;()</title>
<indexterm zone="g-reload-user-special-dirs-cache" role="2.22"><primary sortas="reload_user_special_dirs_cache">g_reload_user_special_dirs_cache</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_reload_user_special_dirs_cache (<parameter><type>void</type></parameter>);</programlisting>
<para>Resets the cache used for <link linkend="g-get-user-special-dir"><function>g_get_user_special_dir()</function></link>, so
that the latest on-disk version is used. Call this only
if you just changed the data on disk yourself.</para>
<para>Due to thread safety issues this may cause leaking of strings
that were previously returned from <link linkend="g-get-user-special-dir"><function>g_get_user_special_dir()</function></link>
that can't be freed. We ensure to only leak the data for
the directories that actually changed value though.</para>
<para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-get-host-name" role="function" condition="since:2.8">
<title>g_get_host_name&#160;()</title>
<indexterm zone="g-get-host-name" role="2.8"><primary sortas="get_host_name">g_get_host_name</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_host_name (<parameter><type>void</type></parameter>);</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>The encoding of the returned string is UTF-8.</para>
<refsect3 id="g-get-host-name.returns" role="returns">
<title>Returns</title>
<para> the host name of the machine.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-get-home-dir" role="function">
<title>g_get_home_dir&#160;()</title>
<indexterm zone="g-get-home-dir"><primary sortas="get_home_dir">g_get_home_dir</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_home_dir (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the current user's home directory.</para>
<para>As with most UNIX tools, this function will return the value of the
<literal>HOME</literal> environment variable if it is set to an existing absolute path
name, falling back to the <literal>passwd</literal> file in the case that it is unset.</para>
<para>If the path given in <literal>HOME</literal> is non-absolute, does not exist, or is
not a directory, the result is undefined.</para>
<para>Before version 2.36 this function would ignore the <literal>HOME</literal> environment
variable, taking the value from the <literal>passwd</literal> database instead. This was
changed to increase the compatibility of GLib with other programs (and
the XDG basedir specification) and to increase testability of programs
based on GLib (by making it easier to run them from test frameworks).</para>
<para>If your program has a strong requirement for either the new or the
old behaviour (and if you don't wish to increase your GLib
dependency to ensure that the new behaviour is in effect) then you
should either directly check the <literal>HOME</literal> environment variable yourself
or unset it before calling any functions in GLib.</para>
<refsect3 id="g-get-home-dir.returns" role="returns">
<title>Returns</title>
<para>the current user's home directory. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-get-tmp-dir" role="function">
<title>g_get_tmp_dir&#160;()</title>
<indexterm zone="g-get-tmp-dir"><primary sortas="get_tmp_dir">g_get_tmp_dir</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_tmp_dir (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the directory to use for temporary files.</para>
<para>On UNIX, this is taken from the <literal>TMPDIR</literal> environment variable.
If the variable is not set, <literal>P_tmpdir</literal> is
used, as defined by the system C library. Failing that, a
hard-coded default of "/tmp" is returned.</para>
<para>On Windows, the <literal>TEMP</literal> environment variable is used, with the
root directory of the Windows installation (eg: "C:\") used
as a default.</para>
<para>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> or the empty
string.</para>
<refsect3 id="g-get-tmp-dir.returns" role="returns">
<title>Returns</title>
<para>the directory to use for temporary files. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-get-current-dir" role="function">
<title>g_get_current_dir&#160;()</title>
<indexterm zone="g-get-current-dir"><primary sortas="get_current_dir">g_get_current_dir</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_get_current_dir (<parameter><type>void</type></parameter>);</programlisting>
<para>Gets the current directory.</para>
<para>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>Since GLib 2.40, this function will return the value of the "PWD"
environment variable if it is set and it happens to be the same as
the current directory.  This can make a difference in the case that
the current directory is the target of a symbolic link.</para>
<refsect3 id="g-get-current-dir.returns" role="returns">
<title>Returns</title>
<para>the current directory. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-basename" role="function" condition="deprecated">
<title>g_basename&#160;()</title>
<indexterm zone="g-basename" role="deprecated"><primary sortas="basename">g_basename</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_basename (<parameter>const <link linkend="gchar"><type>gchar</type></link> *file_name</parameter>);</programlisting>
<warning><para><literal>g_basename</literal> has been deprecated since version 2.2 and should not be used in newly-written code.</para> <para>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>
<refsect3 id="g-basename.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>the name of the file. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-basename.returns" role="returns">
<title>Returns</title>
<para>the name of the file without any leading
directory components. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-canonicalize-filename" role="function" condition="since:2.58">
<title>g_canonicalize_filename&#160;()</title>
<indexterm zone="g-canonicalize-filename" role="2.58"><primary sortas="canonicalize_filename">g_canonicalize_filename</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_canonicalize_filename (<parameter>const <link linkend="gchar"><type>gchar</type></link> *filename</parameter>,
                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *relative_to</parameter>);</programlisting>
<para>Gets the canonical file name from <parameter>filename</parameter>
. All triple slashes are turned into
single slashes, and all <literal>..</literal> and <literal>.</literal>s resolved against <parameter>relative_to</parameter>
.</para>
<para>Symlinks are not followed, and the returned path is guaranteed to be absolute.</para>
<para>If <parameter>filename</parameter>
 is an absolute path, <parameter>relative_to</parameter>
 is ignored. Otherwise,
<parameter>relative_to</parameter>
 will be prepended to <parameter>filename</parameter>
 to make it absolute. <parameter>relative_to</parameter>

must be an absolute path, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. If <parameter>relative_to</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, it'll fallback
to <link linkend="g-get-current-dir"><function>g_get_current_dir()</function></link>.</para>
<para>This function never fails, and will canonicalize file paths even if they don't
exist.</para>
<para>No file system I/O is done.</para>
<refsect3 id="g-canonicalize-filename.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filename</para></entry>
<entry role="parameter_description"><para>the name of the file. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>relative_to</para></entry>
<entry role="parameter_description"><para>the relative directory, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
to use the current working directory. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename][<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-canonicalize-filename.returns" role="returns">
<title>Returns</title>
<para>a newly allocated string with the
canonical file path. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.58">2.58</link></para></refsect2>
<refsect2 id="g-path-is-absolute" role="function">
<title>g_path_is_absolute&#160;()</title>
<indexterm zone="g-path-is-absolute"><primary sortas="path_is_absolute">g_path_is_absolute</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_path_is_absolute (<parameter>const <link linkend="gchar"><type>gchar</type></link> *file_name</parameter>);</programlisting>
<para>Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the given <parameter>file_name</parameter>
 is an absolute file name.
Note that this is a somewhat vague concept on Windows.</para>
<para>On POSIX systems, an absolute file name is well-defined. It always
starts from the single root directory. For example "/usr/local".</para>
<para>On Windows, the concepts of current drive and drive-specific
current directory introduce vagueness. This function interprets as
an absolute file name one that either begins with a directory
separator such as "\Users\tml" or begins with the root on a drive,
for example "C:\Windows". The first case also includes UNC paths
such as "\\myserver\docs\foo". In all cases, either slashes or
backslashes are accepted.</para>
<para>Note that a file name relative to the current drive root does not
truly specify a file uniquely over time and across processes, as
the current drive is a per-process value and can be changed.</para>
<para>File names relative the current directory on some specific drive,
such as "D:foo/bar", are not interpreted as absolute by this
function, but they obviously are not relative to the normal current
directory as returned by <link linkend="getcwd"><function>getcwd()</function></link> or <link linkend="g-get-current-dir"><function>g_get_current_dir()</function></link>
either. Such paths should be avoided, or need to be handled using
Windows-specific code.</para>
<refsect3 id="g-path-is-absolute.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>a file name. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-path-is-absolute.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>file_name</parameter>
is absolute</para>
</refsect3></refsect2>
<refsect2 id="g-path-skip-root" role="function">
<title>g_path_skip_root&#160;()</title>
<indexterm zone="g-path-skip-root"><primary sortas="path_skip_root">g_path_skip_root</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_path_skip_root (<parameter>const <link linkend="gchar"><type>gchar</type></link> *file_name</parameter>);</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>
<refsect3 id="g-path-skip-root.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>a file name. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-path-skip-root.returns" role="returns">
<title>Returns</title>
<para>a pointer into <parameter>file_name</parameter>
after the
root component. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-path-get-basename" role="function">
<title>g_path_get_basename&#160;()</title>
<indexterm zone="g-path-get-basename"><primary sortas="path_get_basename">g_path_get_basename</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_path_get_basename (<parameter>const <link linkend="gchar"><type>gchar</type></link> *file_name</parameter>);</programlisting>
<para>Gets the last component of the filename.</para>
<para>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>
<refsect3 id="g-path-get-basename.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>the name of the file. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-path-get-basename.returns" role="returns">
<title>Returns</title>
<para>a newly allocated string containing the last
component of the filename. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-path-get-dirname" role="function">
<title>g_path_get_dirname&#160;()</title>
<indexterm zone="g-path-get-dirname"><primary sortas="path_get_dirname">g_path_get_dirname</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_path_get_dirname (<parameter>const <link linkend="gchar"><type>gchar</type></link> *file_name</parameter>);</programlisting>
<para>Gets the directory components of a file name. For example, the directory
component of <literal>/usr/bin/test</literal> is <literal>/usr/bin</literal>. The directory component of <literal>/</literal>
is <literal>/</literal>.</para>
<para>If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.</para>
<refsect3 id="g-path-get-dirname.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>the name of the file. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-path-get-dirname.returns" role="returns">
<title>Returns</title>
<para>the directory components of the file. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-build-filename" role="function">
<title>g_build_filename&#160;()</title>
<indexterm zone="g-build-filename"><primary sortas="build_filename">g_build_filename</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_build_filename (<parameter>const <link linkend="gchar"><type>gchar</type></link> *first_element</parameter>,
                  <parameter>...</parameter>);</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>
<refsect3 id="g-build-filename.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>first_element</para></entry>
<entry role="parameter_description"><para>the first element in the path. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>remaining elements in path, terminated by <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-build-filename.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string that must be freed with
<link linkend="g-free"><function>g_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-build-filenamev" role="function" condition="since:2.8">
<title>g_build_filenamev&#160;()</title>
<indexterm zone="g-build-filenamev" role="2.8"><primary sortas="build_filenamev">g_build_filenamev</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_build_filenamev (<parameter><link linkend="gchar"><type>gchar</type></link> **args</parameter>);</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>
<refsect3 id="g-build-filenamev.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para><link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated
array of strings containing the path elements. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-build-filenamev.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string that must be freed
with <link linkend="g-free"><function>g_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-build-filename-valist" role="function" condition="since:2.56">
<title>g_build_filename_valist&#160;()</title>
<indexterm zone="g-build-filename-valist" role="2.56"><primary sortas="build_filename_valist">g_build_filename_valist</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_build_filename_valist (<parameter>const <link linkend="gchar"><type>gchar</type></link> *first_element</parameter>,
                         <parameter><link linkend="va-list"><type>va_list</type></link> *args</parameter>);</programlisting>
<para>Behaves exactly like <link linkend="g-build-filename"><function>g_build_filename()</function></link>, but takes the path elements
as a va_list. This function is mainly meant for language bindings.</para>
<refsect3 id="g-build-filename-valist.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>first_element</para></entry>
<entry role="parameter_description"><para>the first element in the path. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para>va_list of remaining elements in path</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-build-filename-valist.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string that must be freed
with <link linkend="g-free"><function>g_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.56">2.56</link></para></refsect2>
<refsect2 id="g-build-path" role="function">
<title>g_build_path&#160;()</title>
<indexterm zone="g-build-path"><primary sortas="build_path">g_build_path</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_build_path (<parameter>const <link linkend="gchar"><type>gchar</type></link> *separator</parameter>,
              <parameter>const <link linkend="gchar"><type>gchar</type></link> *first_element</parameter>,
              <parameter>...</parameter>);</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>, then <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>
<refsect3 id="g-build-path.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>separator</para></entry>
<entry role="parameter_description"><para>a string used to separator the elements of the path. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>first_element</para></entry>
<entry role="parameter_description"><para>the first element in the path. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>remaining elements in path, terminated by <link linkend="NULL:CAPS"><literal>NULL</literal></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-build-path.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string that must be freed with
<link linkend="g-free"><function>g_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-build-pathv" role="function" condition="since:2.8">
<title>g_build_pathv&#160;()</title>
<indexterm zone="g-build-pathv" role="2.8"><primary sortas="build_pathv">g_build_pathv</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_build_pathv (<parameter>const <link linkend="gchar"><type>gchar</type></link> *separator</parameter>,
               <parameter><link linkend="gchar"><type>gchar</type></link> **args</parameter>);</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>
<refsect3 id="g-build-pathv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>separator</para></entry>
<entry role="parameter_description"><para>a string used to separator the elements of the path.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>args</para></entry>
<entry role="parameter_description"><para><link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated
array of strings containing the path elements. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-build-pathv.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string that must be freed
with <link linkend="g-free"><function>g_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.8">2.8</link></para></refsect2>
<refsect2 id="g-format-size" role="function" condition="since:2.30">
<title>g_format_size&#160;()</title>
<indexterm zone="g-format-size" role="2.30"><primary sortas="format_size">g_format_size</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_format_size (<parameter><link linkend="guint64"><type>guint64</type></link> size</parameter>);</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.2 MB". The returned string
is UTF-8, and may use a non-breaking space to separate the number and units,
to ensure they aren’t separated when line wrapped.</para>
<para>The prefix units base is 1000 (i.e. 1 kB is 1000 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>See <link linkend="g-format-size-full"><function>g_format_size_full()</function></link> for more options about how the size might be
formatted.</para>
<refsect3 id="g-format-size.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>size</para></entry>
<entry role="parameter_description"><para>a size in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-format-size.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated formatted string containing a human readable
file size</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-format-size-full" role="function" condition="since:2.30">
<title>g_format_size_full&#160;()</title>
<indexterm zone="g-format-size-full" role="2.30"><primary sortas="format_size_full">g_format_size_full</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_format_size_full (<parameter><link linkend="guint64"><type>guint64</type></link> size</parameter>,
                    <parameter><link linkend="GFormatSizeFlags"><type>GFormatSizeFlags</type></link> flags</parameter>);</programlisting>
<para>Formats a size.</para>
<para>This function is similar to <link linkend="g-format-size"><function>g_format_size()</function></link> but allows for flags
that modify the output. See <link linkend="GFormatSizeFlags"><type>GFormatSizeFlags</type></link>.</para>
<refsect3 id="g-format-size-full.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>size</para></entry>
<entry role="parameter_description"><para>a size in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para><link linkend="GFormatSizeFlags"><type>GFormatSizeFlags</type></link> to modify the output</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-format-size-full.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated formatted string containing a human
readable file size</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-format-size-for-display" role="function" condition="deprecated|since:2.16">
<title>g_format_size_for_display&#160;()</title>
<indexterm zone="g-format-size-for-display" role="deprecated"><primary sortas="format_size_for_display">g_format_size_for_display</primary></indexterm><indexterm zone="g-format-size-for-display" role="2.16"><primary sortas="format_size_for_display">g_format_size_for_display</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_format_size_for_display (<parameter><link linkend="goffset"><type>goffset</type></link> size</parameter>);</programlisting>
<warning><para><literal>g_format_size_for_display</literal> has been deprecated since version 2.30 and should not be used in newly-written code.</para> <para>This function is broken due to its use of SI
    suffixes to denote IEC units. Use <link linkend="g-format-size"><function>g_format_size()</function></link> instead.</para>
</warning>
<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>
<refsect3 id="g-format-size-for-display.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>size</para></entry>
<entry role="parameter_description"><para>a size in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-format-size-for-display.returns" role="returns">
<title>Returns</title>
<para> a newly-allocated formatted string containing a human
readable file size</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.16">2.16</link></para></refsect2>
<refsect2 id="g-find-program-in-path" role="function">
<title>g_find_program_in_path&#160;()</title>
<indexterm zone="g-find-program-in-path"><primary sortas="find_program_in_path">g_find_program_in_path</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_find_program_in_path (<parameter>const <link linkend="gchar"><type>gchar</type></link> *program</parameter>);</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.</para>
<para>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 <literal>PATHEXT</literal> 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 <literal>PATH</literal> environment variable. If
the program is found, the return value contains the full name
including the type suffix.</para>
<refsect3 id="g-find-program-in-path.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>program</para></entry>
<entry role="parameter_description"><para>a program name in the GLib file name encoding. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-find-program-in-path.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated string with the absolute path,
or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-bit-nth-lsf" role="macro">
<title>g_bit_nth_lsf()</title>
<indexterm zone="g-bit-nth-lsf"><primary sortas="bit_nth_lsf">g_bit_nth_lsf</primary></indexterm>
<programlisting language="C">#define             g_bit_nth_lsf(mask, 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>
<refsect3 id="g-bit-nth-lsf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>mask</para></entry>
<entry role="parameter_description"><para>a <link linkend="gulong"><type>gulong</type></link> containing flags</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>nth_bit</para></entry>
<entry role="parameter_description"><para>the index of the bit to start the search from</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-bit-nth-lsf.returns" role="returns">
<title>Returns</title>
<para> the index of the first bit set which is higher than <parameter>nth_bit</parameter>
, or -1
if no higher bits are set</para>
</refsect3></refsect2>
<refsect2 id="g-bit-nth-msf" role="macro">
<title>g_bit_nth_msf()</title>
<indexterm zone="g-bit-nth-msf"><primary sortas="bit_nth_msf">g_bit_nth_msf</primary></indexterm>
<programlisting language="C">#define             g_bit_nth_msf(mask, 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>
<refsect3 id="g-bit-nth-msf.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>mask</para></entry>
<entry role="parameter_description"><para>a <link linkend="gulong"><type>gulong</type></link> containing flags</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>nth_bit</para></entry>
<entry role="parameter_description"><para>the index of the bit to start the search from</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-bit-nth-msf.returns" role="returns">
<title>Returns</title>
<para> the index of the first bit set which is lower than <parameter>nth_bit</parameter>
, or -1
if no lower bits are set</para>
</refsect3></refsect2>
<refsect2 id="g-bit-storage" role="macro">
<title>g_bit_storage()</title>
<indexterm zone="g-bit-storage"><primary sortas="bit_storage">g_bit_storage</primary></indexterm>
<programlisting language="C">#define             g_bit_storage(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>
<refsect3 id="g-bit-storage.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>number</para></entry>
<entry role="parameter_description"><para>a <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-bit-storage.returns" role="returns">
<title>Returns</title>
<para> the number of bits used to hold <parameter>number</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-spaced-primes-closest" role="function">
<title>g_spaced_primes_closest&#160;()</title>
<indexterm zone="g-spaced-primes-closest"><primary sortas="spaced_primes_closest">g_spaced_primes_closest</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_spaced_primes_closest (<parameter><link linkend="guint"><type>guint</type></link> num</parameter>);</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>
<refsect3 id="g-spaced-primes-closest.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>num</para></entry>
<entry role="parameter_description"><para>a <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-spaced-primes-closest.returns" role="returns">
<title>Returns</title>
<para> the smallest prime number from a built-in array of primes
which is larger than <parameter>num</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-atexit" role="function" condition="deprecated:2.32: It is best to avoid g_atexit().">
<title>g_atexit&#160;()</title>
<indexterm zone="g-atexit" role="deprecated"><primary sortas="atexit">g_atexit</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_atexit (<parameter><link linkend="GVoidFunc"><type>GVoidFunc</type></link> func</parameter>);</programlisting>
<warning><para><literal>g_atexit</literal> has been deprecated since version 2.32 and should not be used in newly-written code.</para> <para>It is best to avoid <link linkend="g-atexit"><function>g_atexit()</function></link>.</para>
</warning>
<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>
<refsect3 id="g-atexit.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>func</para></entry>
<entry role="parameter_description"><para>the function to call on normal program termination. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>scope async</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-abort" role="macro" condition="since:2.50">
<title>g_abort</title>
<indexterm zone="g-abort" role="2.50"><primary sortas="abort">g_abort</primary></indexterm>
<programlisting language="C">#define             g_abort()</programlisting>
<para>A wrapper for the POSIX <link linkend="abort"><function>abort()</function></link> function.</para>
<para>On Windows it is a function that makes extra effort (including a call
to <link linkend="abort"><function>abort()</function></link>) to ensure that a debugger-catchable exception is thrown
before the program terminates.</para>
<para>See your C library manual for more details about <link linkend="abort"><function>abort()</function></link>.</para>
<para role="since">Since: <link linkend="api-index-2.50">2.50</link></para></refsect2>
<refsect2 id="g-parse-debug-string" role="function">
<title>g_parse_debug_string&#160;()</title>
<indexterm zone="g-parse-debug-string"><primary sortas="parse_debug_string">g_parse_debug_string</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_parse_debug_string (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                      <parameter>const <link linkend="GDebugKey"><type>GDebugKey</type></link> *keys</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> nkeys</parameter>);</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. Any flags
specified along with "all" in <parameter>string</parameter>
 are inverted; thus,
"all,foo,bar" or "foo,bar,all" sets all flags except those
corresponding to "foo" and "bar".</para>
<para>If <parameter>string</parameter>
 is equal to "help", all the available keys in <parameter>keys</parameter>

are printed out to standard error.</para>
<refsect3 id="g-parse-debug-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a list of debug options separated by colons, spaces, or
commas, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>keys</para></entry>
<entry role="parameter_description"><para>pointer to an array of <link linkend="GDebugKey"><type>GDebugKey</type></link> which associate
strings with bit flags. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=nkeys]</emphasis></entry></row>
<row><entry role="parameter_name"><para>nkeys</para></entry>
<entry role="parameter_description"><para>the number of <link linkend="GDebugKeys"><type>GDebugKeys</type></link> in the array.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-parse-debug-string.returns" role="returns">
<title>Returns</title>
<para> the combined set of bit flags.</para>
</refsect3></refsect2>
<refsect2 id="GVoidFunc" role="function" condition="deprecated:">
<title>GVoidFunc&#160;()</title>
<indexterm zone="GVoidFunc" role="deprecated"><primary sortas="VoidFunc">GVoidFunc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GVoidFunc<phrase role="c_punctuation">)</phrase> (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>GVoidFunc</literal> is deprecated and should not be used in newly-written code.</para></warning>
<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&#160;()</title>
<indexterm zone="GFreeFunc"><primary sortas="FreeFunc">GFreeFunc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GFreeFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="gpointer"><type>gpointer</type></link> data</parameter>);</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>
<refsect3 id="GFreeFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>a data pointer</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-qsort-with-data" role="function">
<title>g_qsort_with_data&#160;()</title>
<indexterm zone="g-qsort-with-data"><primary sortas="qsort_with_data">g_qsort_with_data</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_qsort_with_data (<parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> pbase</parameter>,
                   <parameter><link linkend="gint"><type>gint</type></link> total_elems</parameter>,
                   <parameter><link linkend="gsize"><type>gsize</type></link> size</parameter>,
                   <parameter><link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> compare_func</parameter>,
                   <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>This is guaranteed to be a stable sort since version 2.32.</para>
<refsect3 id="g-qsort-with-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>pbase</para></entry>
<entry role="parameter_description"><para>start of array to sort. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>total_elems</para></entry>
<entry role="parameter_description"><para>elements in the array</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>size</para></entry>
<entry role="parameter_description"><para>size of each element</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>compare_func</para></entry>
<entry role="parameter_description"><para>function to compare elements</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>compare_func</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-nullify-pointer" role="function">
<title>g_nullify_pointer&#160;()</title>
<indexterm zone="g-nullify-pointer"><primary sortas="nullify_pointer">g_nullify_pointer</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_nullify_pointer (<parameter><link linkend="gpointer"><type>gpointer</type></link> *nullify_location</parameter>);</programlisting>
<para>Set the pointer at the specified location to <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="g-nullify-pointer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>nullify_location</para></entry>
<entry role="parameter_description"><para>the memory address of the pointer. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="glib-Miscellaneous-Utility-Functions.other_details" role="details">
<title role="details.title">Types and Values</title>
<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>
<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>
<refsect3 id="GUserDirectory.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-DESKTOP:CAPS">G_USER_DIRECTORY_DESKTOP</para></entry>
<entry role="enum_member_description"><para>the user's Desktop directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-DOCUMENTS:CAPS">G_USER_DIRECTORY_DOCUMENTS</para></entry>
<entry role="enum_member_description"><para>the user's Documents directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-DOWNLOAD:CAPS">G_USER_DIRECTORY_DOWNLOAD</para></entry>
<entry role="enum_member_description"><para>the user's Downloads directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-MUSIC:CAPS">G_USER_DIRECTORY_MUSIC</para></entry>
<entry role="enum_member_description"><para>the user's Music directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-PICTURES:CAPS">G_USER_DIRECTORY_PICTURES</para></entry>
<entry role="enum_member_description"><para>the user's Pictures directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-PUBLIC-SHARE:CAPS">G_USER_DIRECTORY_PUBLIC_SHARE</para></entry>
<entry role="enum_member_description"><para>the user's shared directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-TEMPLATES:CAPS">G_USER_DIRECTORY_TEMPLATES</para></entry>
<entry role="enum_member_description"><para>the user's Templates directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-DIRECTORY-VIDEOS:CAPS">G_USER_DIRECTORY_VIDEOS</para></entry>
<entry role="enum_member_description"><para>the user's Movies directory</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-USER-N-DIRECTORIES:CAPS">G_USER_N_DIRECTORIES</para></entry>
<entry role="enum_member_description"><para>the number of enum values</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.14">2.14</link></para></refsect2>
<refsect2 id="g-dirname" role="macro" condition="deprecated:use g_path_get_dirname() instead">
<title>g_dirname</title>
<indexterm zone="g-dirname" role="deprecated"><primary sortas="dirname">g_dirname</primary></indexterm>
<programlisting language="C">#define             g_dirname</programlisting>
<warning><para><literal>g_dirname</literal> is deprecated and should not be used in newly-written code.</para> <para>use <link linkend="g-path-get-dirname"><function>g_path_get_dirname()</function></link> instead</para>
</warning>
<para>Gets the directory components of a file name.</para>
<para>If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.</para>
<refsect3 id="g-dirname.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>file_name</para></entry>
<entry role="parameter_description"><para>the name of the file. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-dirname.returns" role="returns">
<title>Returns</title>
<para>the directory components of the file. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> filename]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="GFormatSizeFlags" role="enum">
<title>enum GFormatSizeFlags</title>
<indexterm zone="GFormatSizeFlags"><primary sortas="FormatSizeFlags">GFormatSizeFlags</primary></indexterm>
<para>Flags to modify the format of the string returned by <link linkend="g-format-size-full"><function>g_format_size_full()</function></link>.</para>
<refsect3 id="GFormatSizeFlags.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="G-FORMAT-SIZE-DEFAULT:CAPS">G_FORMAT_SIZE_DEFAULT</para></entry>
<entry role="enum_member_description"><para>behave the same as <link linkend="g-format-size"><function>g_format_size()</function></link></para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-FORMAT-SIZE-LONG-FORMAT:CAPS">G_FORMAT_SIZE_LONG_FORMAT</para></entry>
<entry role="enum_member_description"><para>include the exact number of bytes as part
of the returned string.  For example, "45.6 kB (45,612 bytes)".</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-FORMAT-SIZE-IEC-UNITS:CAPS">G_FORMAT_SIZE_IEC_UNITS</para></entry>
<entry role="enum_member_description"><para>use IEC (base 1024) units with "KiB"-style
suffixes. IEC units should only be used for reporting things with
a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
Network and storage sizes should be reported in the normal SI units.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="G-FORMAT-SIZE-BITS:CAPS">G_FORMAT_SIZE_BITS</para></entry>
<entry role="enum_member_description"><para>set the size as a quantity in bits, rather than
bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GDebugKey" role="struct">
<title>struct GDebugKey</title>
<indexterm zone="GDebugKey"><primary sortas="DebugKey">GDebugKey</primary></indexterm>
<programlisting language="C">struct GDebugKey {
  const gchar *key;
  guint	       value;
};
</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>
<refsect3 id="GDebugKey.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para>const&#160;<link linkend="gchar"><type>gchar</type></link>&#160;*<structfield id="GDebugKey.key">key</structfield>;</para></entry>
<entry role="struct_member_description"><para>the string</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="GDebugKey.value">value</structfield>;</para></entry>
<entry role="struct_member_description"><para>the flag</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>

</refentry>
