docs/reference/glib/html/glib-Miscellaneous-Utility-Functions.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Miscellaneous Utility Functions</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-Hook-Functions.html" title="Hook Functions">
  10 <link rel="next" href="glib-Lexical-Scanner.html" title="Lexical Scanner">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Hook-Functions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Lexical-Scanner.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Miscellaneous-Utility-Functions.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Miscellaneous-Utility-Functions.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Miscellaneous-Utility-Functions"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Miscellaneous-Utility-Functions.top_of_page"></a>Miscellaneous Utility Functions</span></h2>
  34 <p>Miscellaneous Utility Functions — a selection of portable utility functions</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Miscellaneous-Utility-Functions.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-application-name" title="g_get_application_name ()">g_get_application_name</a>              (<em class="parameter"><code><span class="type">void</span></code></em>);
  44 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()">g_set_application_name</a>              (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *application_name</code></em>);
  45 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname" title="g_get_prgname ()">g_get_prgname</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);
  46 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-prgname" title="g_set_prgname ()">g_set_prgname</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *prgname</code></em>);
  47 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()">g_get_environ</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);
  48 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-getenv" title="g_environ_getenv ()">g_environ_getenv</a>                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
  49                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);
  50 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-setenv" title="g_environ_setenv ()">g_environ_setenv</a>                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
  51                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>,
  52                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *value</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> overwrite</code></em>);
  54 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-unsetenv" title="g_environ_unsetenv ()">g_environ_unsetenv</a>                  (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
  55                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);
  56 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()">g_getenv</a>                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);
  57 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-setenv" title="g_setenv ()">g_setenv</a>                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>,
  58                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *value</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> overwrite</code></em>);
  60 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()">g_unsetenv</a>                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);
  61 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-listenv" title="g_listenv ()">g_listenv</a>                           (<em class="parameter"><code><span class="type">void</span></code></em>);
  62 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-name" title="g_get_user_name ()">g_get_user_name</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
  63 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-real-name" title="g_get_real_name ()">g_get_real_name</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
  64 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-cache-dir" title="g_get_user_cache_dir ()">g_get_user_cache_dir</a>                (<em class="parameter"><code><span class="type">void</span></code></em>);
  65 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-data-dir" title="g_get_user_data_dir ()">g_get_user_data_dir</a>                 (<em class="parameter"><code><span class="type">void</span></code></em>);
  66 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-config-dir" title="g_get_user_config_dir ()">g_get_user_config_dir</a>               (<em class="parameter"><code><span class="type">void</span></code></em>);
  67 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-runtime-dir" title="g_get_user_runtime_dir ()">g_get_user_runtime_dir</a>              (<em class="parameter"><code><span class="type">void</span></code></em>);
  68 enum                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GUserDirectory" title="enum GUserDirectory">GUserDirectory</a>;
  69 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-special-dir" title="g_get_user_special_dir ()">g_get_user_special_dir</a>              (<em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GUserDirectory" title="enum GUserDirectory"><span class="type">GUserDirectory</span></a> directory</code></em>);
  70 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-system-data-dirs" title="g_get_system_data_dirs ()">g_get_system_data_dirs</a>            (<em class="parameter"><code><span class="type">void</span></code></em>);
  71 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-system-config-dirs" title="g_get_system_config_dirs ()">g_get_system_config_dirs</a>          (<em class="parameter"><code><span class="type">void</span></code></em>);
  72 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-reload-user-special-dirs-cache" title="g_reload_user_special_dirs_cache ()">g_reload_user_special_dirs_cache</a>    (<em class="parameter"><code><span class="type">void</span></code></em>);
  73
  74 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-host-name" title="g_get_host_name ()">g_get_host_name</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
  75 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-home-dir" title="g_get_home_dir ()">g_get_home_dir</a>                      (<em class="parameter"><code><span class="type">void</span></code></em>);
  76 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-tmp-dir" title="g_get_tmp_dir ()">g_get_tmp_dir</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);
  77 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-current-dir" title="g_get_current_dir ()">g_get_current_dir</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
  78 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-basename" title="g_basename ()">g_basename</a>                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);
  79 #define             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-dirname" title="g_dirname">g_dirname</a>
  80 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-is-absolute" title="g_path_is_absolute ()">g_path_is_absolute</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);
  81 const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-skip-root" title="g_path_skip_root ()">g_path_skip_root</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);
  82 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-basename" title="g_path_get_basename ()">g_path_get_basename</a>                 (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);
  83 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname" title="g_path_get_dirname ()">g_path_get_dirname</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);
  84 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-filename" title="g_build_filename ()">g_build_filename</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *first_element</code></em>,
  85                                                          <em class="parameter"><code>...</code></em>);
  86 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-filenamev" title="g_build_filenamev ()">g_build_filenamev</a>                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **args</code></em>);
  87 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-path" title="g_build_path ()">g_build_path</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
  88                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *first_element</code></em>,
  89                                                          <em class="parameter"><code>...</code></em>);
  90 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-pathv" title="g_build_pathv ()">g_build_pathv</a>                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
  91                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **args</code></em>);
  92
  93 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size" title="g_format_size ()">g_format_size</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> size</code></em>);
  94 enum                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags">GFormatSizeFlags</a>;
  95 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size-full" title="g_format_size_full ()">g_format_size_full</a>                  (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> size</code></em>,
  96                                                          <em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a> flags</code></em>);
  97 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size-for-display" title="g_format_size_for_display ()">g_format_size_for_display</a>           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#goffset" title="goffset"><span class="type">goffset</span></a> size</code></em>);
  98
  99 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-find-program-in-path" title="g_find_program_in_path ()">g_find_program_in_path</a>              (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *program</code></em>);
 100
 101 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-nth-lsf" title="g_bit_nth_lsf ()">g_bit_nth_lsf</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> mask</code></em>,
 102                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> nth_bit</code></em>);
 103 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-nth-msf" title="g_bit_nth_msf ()">g_bit_nth_msf</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> mask</code></em>,
 104                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> nth_bit</code></em>);
 105 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-storage" title="g_bit_storage ()">g_bit_storage</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> number</code></em>);
 106
 107 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-spaced-primes-closest" title="g_spaced_primes_closest ()">g_spaced_primes_closest</a>             (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> num</code></em>);
 108
 109 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()">g_atexit</a>                            (<em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GVoidFunc" title="GVoidFunc ()"><span class="type">GVoidFunc</span></a> func</code></em>);
 110
 111 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-parse-debug-string" title="g_parse_debug_string ()">g_parse_debug_string</a>                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
 112                                                          <em class="parameter"><code>const <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey"><span class="type">GDebugKey</span></a> *keys</code></em>,
 113                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> nkeys</code></em>);
 114 struct              <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey">GDebugKey</a>;
 115
 116 <span class="returnvalue">void</span>                (<a class="link" href="glib-Miscellaneous-Utility-Functions.html#GVoidFunc" title="GVoidFunc ()">*GVoidFunc</a>)                        (<em class="parameter"><code><span class="type">void</span></code></em>);
 117 <span class="returnvalue">void</span>                (<a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFreeFunc" title="GFreeFunc ()">*GFreeFunc</a>)                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
 118
 119 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-qsort-with-data" title="g_qsort_with_data ()">g_qsort_with_data</a>                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> pbase</code></em>,
 120                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> total_elems</code></em>,
 121                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> size</code></em>,
 122                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> compare_func</code></em>,
 123                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
 124
 125 <span class="returnvalue">void</span>                <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-nullify-pointer" title="g_nullify_pointer ()">g_nullify_pointer</a>                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> *nullify_location</code></em>);
 126 </pre>
 127 </div>
 128 <div class="refsect1">
 129 <a name="glib-Miscellaneous-Utility-Functions.description"></a><h2>Description</h2>
 130 <p>
 131 These are portable utility functions.
 132 </p>
 133 </div>
 134 <div class="refsect1">
 135 <a name="glib-Miscellaneous-Utility-Functions.details"></a><h2>Details</h2>
 136 <div class="refsect2">
 137 <a name="g-get-application-name"></a><h3>g_get_application_name ()</h3>
 138 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_application_name              (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 139 <p>
 140 Gets a human-readable name for the application, as set by
 141 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()"><code class="function">g_set_application_name()</code></a>. This name should be localized if
 142 possible, and is intended for display to the user.  Contrast with
 143 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname" title="g_get_prgname ()"><code class="function">g_get_prgname()</code></a>, which gets a non-localized name. If
 144 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()"><code class="function">g_set_application_name()</code></a> has not been called, returns the result of
 145 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname" title="g_get_prgname ()"><code class="function">g_get_prgname()</code></a> (which may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-prgname" title="g_set_prgname ()"><code class="function">g_set_prgname()</code></a> has also not
 146 been called).
 147 </p>
 148 <div class="variablelist"><table border="0">
 149 <col align="left" valign="top">
 150 <tbody><tr>
 151 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 152 <td>human-readable application name. may return <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 153 </td>
 154 </tr></tbody>
 155 </table></div>
 156 <p class="since">Since 2.2</p>
 157 </div>
 158 <hr>
 159 <div class="refsect2">
 160 <a name="g-set-application-name"></a><h3>g_set_application_name ()</h3>
 161 <pre class="programlisting"><span class="returnvalue">void</span>                g_set_application_name              (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *application_name</code></em>);</pre>
 162 <p>
 163 Sets a human-readable name for the application. This name should be
 164 localized if possible, and is intended for display to the user.
 165 Contrast with <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-prgname" title="g_set_prgname ()"><code class="function">g_set_prgname()</code></a>, which sets a non-localized name.
 166 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-prgname" title="g_set_prgname ()"><code class="function">g_set_prgname()</code></a> will be called automatically by <a href="http://library.gnome.org/devel/gtk/gtk3-General.html#gtk-init"><code class="function">gtk_init()</code></a>,
 167 but <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()"><code class="function">g_set_application_name()</code></a> will not.
 168 </p>
 169 <p>
 170 Note that for thread safety reasons, this function can only
 171 be called once.
 172 </p>
 173 <p>
 174 The application name will be used in contexts such as error messages,
 175 or when displaying an application's name in the task list.
 176 </p>
 177 <div class="variablelist"><table border="0">
 178 <col align="left" valign="top">
 179 <tbody><tr>
 180 <td><p><span class="term"><em class="parameter"><code>application_name</code></em> :</span></p></td>
 181 <td>localized name of the application</td>
 182 </tr></tbody>
 183 </table></div>
 184 <p class="since">Since 2.2</p>
 185 </div>
 186 <hr>
 187 <div class="refsect2">
 188 <a name="g-get-prgname"></a><h3>g_get_prgname ()</h3>
 189 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_get_prgname                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 190 <p>
 191 Gets the name of the program. This name should <span class="emphasis"><em>not</em></span>
 192 be localized, contrast with <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-application-name" title="g_get_application_name ()"><code class="function">g_get_application_name()</code></a>.
 193 (If you are using GDK or GTK+ the program name is set in <a href="http://library.gnome.org/devel/gdk/gdk3-General.html#gdk-init"><code class="function">gdk_init()</code></a>,
 194 which is called by <a href="http://library.gnome.org/devel/gtk/gtk3-General.html#gtk-init"><code class="function">gtk_init()</code></a>. The program name is found by taking
 195 the last component of <code class="literal">argv[0]</code>.)
 196 </p>
 197 <div class="variablelist"><table border="0">
 198 <col align="left" valign="top">
 199 <tbody><tr>
 200 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 201 <td>the name of the program. The returned string belongs
 202 to GLib and must not be modified or freed.</td>
 203 </tr></tbody>
 204 </table></div>
 205 </div>
 206 <hr>
 207 <div class="refsect2">
 208 <a name="g-set-prgname"></a><h3>g_set_prgname ()</h3>
 209 <pre class="programlisting"><span class="returnvalue">void</span>                g_set_prgname                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *prgname</code></em>);</pre>
 210 <p>
 211 Sets the name of the program. This name should <span class="emphasis"><em>not</em></span>
 212 be localized, contrast with <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()"><code class="function">g_set_application_name()</code></a>. Note that for
 213 thread-safety reasons this function can only be called once.
 214 </p>
 215 <div class="variablelist"><table border="0">
 216 <col align="left" valign="top">
 217 <tbody><tr>
 218 <td><p><span class="term"><em class="parameter"><code>prgname</code></em> :</span></p></td>
 219 <td>the name of the program.</td>
 220 </tr></tbody>
 221 </table></div>
 222 </div>
 223 <hr>
 224 <div class="refsect2">
 225 <a name="g-get-environ"></a><h3>g_get_environ ()</h3>
 226 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_get_environ                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 227 <p>
 228 Gets the list of environment variables for the current process.
 229 </p>
 230 <p>
 231 The list is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> terminated and each item in the list is of the
 232 form 'NAME=VALUE'.
 233 </p>
 234 <p>
 235 This is equivalent to direct access to the 'environ' global variable,
 236 except portable.
 237 </p>
 238 <p>
 239 The return value is freshly allocated and it should be freed with
 240 <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> when it is no longer needed.
 241 </p>
 242 <div class="variablelist"><table border="0">
 243 <col align="left" valign="top">
 244 <tbody><tr>
 245 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 246 <td>the list of
 247 environment variables. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 248 </td>
 249 </tr></tbody>
 250 </table></div>
 251 <p class="since">Since 2.28</p>
 252 </div>
 253 <hr>
 254 <div class="refsect2">
 255 <a name="g-environ-getenv"></a><h3>g_environ_getenv ()</h3>
 256 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_environ_getenv                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
 257                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);</pre>
 258 <p>
 259 Returns the value of the environment variable <em class="parameter"><code>variable</code></em> in the
 260 provided list <em class="parameter"><code>envp</code></em>.
 261 </p>
 262 <p>
 263 The name and value are in the GLib file name encoding.
 264 On UNIX, this means the actual bytes which might or might not
 265 be in some consistent character set and encoding. On Windows,
 266 it is in UTF-8. On Windows, in case the environment variable's
 267 value contains references to other environment variables, they
 268 are expanded.
 269 </p>
 270 <div class="variablelist"><table border="0">
 271 <col align="left" valign="top">
 272 <tbody>
 273 <tr>
 274 <td><p><span class="term"><em class="parameter"><code>envp</code></em> :</span></p></td>
 275 <td>an environment
 276 list (eg, as returned from <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()"><code class="function">g_get_environ()</code></a>). <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 277 </td>
 278 </tr>
 279 <tr>
 280 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 281 <td>the environment variable to get, in the GLib file name
 282 encoding</td>
 283 </tr>
 284 <tr>
 285 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 286 <td>the value of the environment variable, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if
 287 the environment variable is not set in <em class="parameter"><code>envp</code></em>. The returned
 288 string is owned by <em class="parameter"><code>envp</code></em>, and will be freed if <em class="parameter"><code>variable</code></em> is
 289 set or unset again.</td>
 290 </tr>
 291 </tbody>
 292 </table></div>
 293 <p class="since">Since 2.32</p>
 294 </div>
 295 <hr>
 296 <div class="refsect2">
 297 <a name="g-environ-setenv"></a><h3>g_environ_setenv ()</h3>
 298 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_environ_setenv                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
 299                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>,
 300                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *value</code></em>,
 301                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> overwrite</code></em>);</pre>
 302 <p>
 303 Sets the environment variable <em class="parameter"><code>variable</code></em> in the provided list
 304 <em class="parameter"><code>envp</code></em> to <em class="parameter"><code>value</code></em>.
 305 </p>
 306 <p>
 307 Both the variable's name and value should be in the GLib
 308 file name encoding. On UNIX, this means that they can be
 309 arbitrary byte strings. On Windows, they should be in UTF-8.
 310 </p>
 311 <div class="variablelist"><table border="0">
 312 <col align="left" valign="top">
 313 <tbody>
 314 <tr>
 315 <td><p><span class="term"><em class="parameter"><code>envp</code></em> :</span></p></td>
 316 <td>an environment
 317 list that can be freed using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> (e.g., as returned from <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()"><code class="function">g_get_environ()</code></a>). <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 318 </td>
 319 </tr>
 320 <tr>
 321 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 322 <td>the environment variable to set, must not contain '='</td>
 323 </tr>
 324 <tr>
 325 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 326 <td>the value for to set the variable to</td>
 327 </tr>
 328 <tr>
 329 <td><p><span class="term"><em class="parameter"><code>overwrite</code></em> :</span></p></td>
 330 <td>whether to change the variable if it already exists</td>
 331 </tr>
 332 <tr>
 333 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 334 <td>the
 335 updated environment list. Free it using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 336 </td>
 337 </tr>
 338 </tbody>
 339 </table></div>
 340 <p class="since">Since 2.32</p>
 341 </div>
 342 <hr>
 343 <div class="refsect2">
 344 <a name="g-environ-unsetenv"></a><h3>g_environ_unsetenv ()</h3>
 345 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_environ_unsetenv                  (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **envp</code></em>,
 346                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);</pre>
 347 <p>
 348 Removes the environment variable <em class="parameter"><code>variable</code></em> from the provided
 349 environment <em class="parameter"><code>envp</code></em>.
 350 </p>
 351 <div class="variablelist"><table border="0">
 352 <col align="left" valign="top">
 353 <tbody>
 354 <tr>
 355 <td><p><span class="term"><em class="parameter"><code>envp</code></em> :</span></p></td>
 356 <td>an environment
 357 list that can be freed using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a> (e.g., as returned from <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()"><code class="function">g_get_environ()</code></a>). <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 358 </td>
 359 </tr>
 360 <tr>
 361 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 362 <td>the environment variable to remove, must not contain '='</td>
 363 </tr>
 364 <tr>
 365 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 366 <td>the
 367 updated environment list. Free it using <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 368 </td>
 369 </tr>
 370 </tbody>
 371 </table></div>
 372 <p class="since">Since 2.32</p>
 373 </div>
 374 <hr>
 375 <div class="refsect2">
 376 <a name="g-getenv"></a><h3>g_getenv ()</h3>
 377 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_getenv                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);</pre>
 378 <p>
 379 Returns the value of an environment variable.
 380 </p>
 381 <p>
 382 The name and value are in the GLib file name encoding. On UNIX,
 383 this means the actual bytes which might or might not be in some
 384 consistent character set and encoding. On Windows, it is in UTF-8.
 385 On Windows, in case the environment variable's value contains
 386 references to other environment variables, they are expanded.
 387 </p>
 388 <div class="variablelist"><table border="0">
 389 <col align="left" valign="top">
 390 <tbody>
 391 <tr>
 392 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 393 <td>the environment variable to get, in the GLib file name
 394 encoding</td>
 395 </tr>
 396 <tr>
 397 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 398 <td>the value of the environment variable, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if
 399 the environment variable is not found. The returned string
 400 may be overwritten by the next call to <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()"><code class="function">g_getenv()</code></a>, <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-setenv" title="g_setenv ()"><code class="function">g_setenv()</code></a>
 401 or <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()"><code class="function">g_unsetenv()</code></a>.</td>
 402 </tr>
 403 </tbody>
 404 </table></div>
 405 </div>
 406 <hr>
 407 <div class="refsect2">
 408 <a name="g-setenv"></a><h3>g_setenv ()</h3>
 409 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_setenv                            (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>,
 410                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *value</code></em>,
 411                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> overwrite</code></em>);</pre>
 412 <p>
 413 Sets an environment variable. Both the variable's name and value
 414 should be in the GLib file name encoding. On UNIX, this means that
 415 they can be arbitrary byte strings. On Windows, they should be in
 416 UTF-8.
 417 </p>
 418 <p>
 419 Note that on some systems, when variables are overwritten, the memory
 420 used for the previous variables and its value isn't reclaimed.
 421 </p>
 422 <p>
 423 </p>
 424 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 425 <h3 class="title">Warning</h3>
 426 <p>
 427 Environment variable handling in UNIX is not thread-safe, and your
 428 program may crash if one thread calls <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-setenv" title="g_setenv ()"><code class="function">g_setenv()</code></a> while another
 429 thread is calling <code class="function">getenv()</code>. (And note that many functions, such as
 430 <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) This function is only safe to
 431 use at the very start of your program, before creating any other
 432 threads (or creating objects that create worker threads of their
 433 own).
 434 </p>
 435 <p>
 436 If you need to set up the environment for a child process, you can
 437 use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()"><code class="function">g_get_environ()</code></a> to get an environment array, modify that with
 438 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-setenv" title="g_environ_setenv ()"><code class="function">g_environ_setenv()</code></a> and <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-unsetenv" title="g_environ_unsetenv ()"><code class="function">g_environ_unsetenv()</code></a>, and then pass that
 439 array directly to <code class="function">execvpe()</code>, <a class="link" href="glib-Spawning-Processes.html#g-spawn-async" title="g_spawn_async ()"><code class="function">g_spawn_async()</code></a>, or the like.
 440 </p>
 441 </div>
 442 <p>
 443 </p>
 444 <div class="variablelist"><table border="0">
 445 <col align="left" valign="top">
 446 <tbody>
 447 <tr>
 448 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 449 <td>the environment variable to set, must not contain '='.</td>
 450 </tr>
 451 <tr>
 452 <td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
 453 <td>the value for to set the variable to.</td>
 454 </tr>
 455 <tr>
 456 <td><p><span class="term"><em class="parameter"><code>overwrite</code></em> :</span></p></td>
 457 <td>whether to change the variable if it already exists.</td>
 458 </tr>
 459 <tr>
 460 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 461 <td>
 462 <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the environment variable couldn't be set.</td>
 463 </tr>
 464 </tbody>
 465 </table></div>
 466 <p class="since">Since 2.4</p>
 467 </div>
 468 <hr>
 469 <div class="refsect2">
 470 <a name="g-unsetenv"></a><h3>g_unsetenv ()</h3>
 471 <pre class="programlisting"><span class="returnvalue">void</span>                g_unsetenv                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *variable</code></em>);</pre>
 472 <p>
 473 Removes an environment variable from the environment.
 474 </p>
 475 <p>
 476 Note that on some systems, when variables are overwritten, the
 477 memory used for the previous variables and its value isn't reclaimed.
 478 </p>
 479 <p>
 480 </p>
 481 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 482 <h3 class="title">Warning</h3>
 483 <p>
 484 Environment variable handling in UNIX is not thread-safe, and your
 485 program may crash if one thread calls <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()"><code class="function">g_unsetenv()</code></a> while another
 486 thread is calling <code class="function">getenv()</code>. (And note that many functions, such as
 487 <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) This function is only safe
 488 to use at the very start of your program, before creating any other
 489 threads (or creating objects that create worker threads of their
 490 own).
 491 </p>
 492 <p>
 493 If you need to set up the environment for a child process, you can
 494 use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()"><code class="function">g_get_environ()</code></a> to get an environment array, modify that with
 495 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-setenv" title="g_environ_setenv ()"><code class="function">g_environ_setenv()</code></a> and <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-unsetenv" title="g_environ_unsetenv ()"><code class="function">g_environ_unsetenv()</code></a>, and then pass that
 496 array directly to <code class="function">execvpe()</code>, <a class="link" href="glib-Spawning-Processes.html#g-spawn-async" title="g_spawn_async ()"><code class="function">g_spawn_async()</code></a>, or the like.
 497 </p>
 498 </div>
 499 <p>
 500 </p>
 501 <div class="variablelist"><table border="0">
 502 <col align="left" valign="top">
 503 <tbody><tr>
 504 <td><p><span class="term"><em class="parameter"><code>variable</code></em> :</span></p></td>
 505 <td>the environment variable to remove, must not contain '='</td>
 506 </tr></tbody>
 507 </table></div>
 508 <p class="since">Since 2.4</p>
 509 </div>
 510 <hr>
 511 <div class="refsect2">
 512 <a name="g-listenv"></a><h3>g_listenv ()</h3>
 513 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> **            g_listenv                           (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 514 <p>
 515 Gets the names of all variables set in the environment.
 516 </p>
 517 <p>
 518 Programs that want to be portable to Windows should typically use
 519 this function and <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()"><code class="function">g_getenv()</code></a> instead of using the environ array
 520 from the C library directly. On Windows, the strings in the environ
 521 array are in system codepage encoding, while in most of the typical
 522 use cases for environment variables in GLib-using programs you want
 523 the UTF-8 encoding that this function and <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()"><code class="function">g_getenv()</code></a> provide.
 524 </p>
 525 <div class="variablelist"><table border="0">
 526 <col align="left" valign="top">
 527 <tbody><tr>
 528 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 529 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated
 530 list of strings which must be freed with <a class="link" href="glib-String-Utility-Functions.html#g-strfreev" title="g_strfreev ()"><code class="function">g_strfreev()</code></a>. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 531 </td>
 532 </tr></tbody>
 533 </table></div>
 534 <p class="since">Since 2.8</p>
 535 </div>
 536 <hr>
 537 <div class="refsect2">
 538 <a name="g-get-user-name"></a><h3>g_get_user_name ()</h3>
 539 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_name                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 540 <p>
 541 Gets the user name of the current user. The encoding of the returned
 542 string is system-defined. On UNIX, it might be the preferred file name
 543 encoding, or something else, and there is no guarantee that it is even
 544 consistent on a machine. On Windows, it is always UTF-8.
 545 </p>
 546 <div class="variablelist"><table border="0">
 547 <col align="left" valign="top">
 548 <tbody><tr>
 549 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 550 <td>the user name of the current user.</td>
 551 </tr></tbody>
 552 </table></div>
 553 </div>
 554 <hr>
 555 <div class="refsect2">
 556 <a name="g-get-real-name"></a><h3>g_get_real_name ()</h3>
 557 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_real_name                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 558 <p>
 559 Gets the real name of the user. This usually comes from the user's entry
 560 in the <code class="filename">passwd</code> file. The encoding of the returned
 561 string is system-defined. (On Windows, it is, however, always UTF-8.)
 562 If the real user name cannot be determined, the string "Unknown" is
 563 returned.
 564 </p>
 565 <div class="variablelist"><table border="0">
 566 <col align="left" valign="top">
 567 <tbody><tr>
 568 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 569 <td>the user's real name.</td>
 570 </tr></tbody>
 571 </table></div>
 572 </div>
 573 <hr>
 574 <div class="refsect2">
 575 <a name="g-get-user-cache-dir"></a><h3>g_get_user_cache_dir ()</h3>
 576 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_cache_dir                (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 577 <p>
 578 Returns a base directory in which to store non-essential, cached
 579 data specific to particular user.
 580 </p>
 581 <p>
 582 On UNIX platforms this is determined using the mechanisms described in
 583 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 584 XDG Base Directory Specification</a>.
 585 In this case the directory retrieved will be XDG_CACHE_HOME.
 586 </p>
 587 <p>
 588 On Windows is the directory that serves as a common repository for
 589 temporary Internet files. A typical path is
 590 C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
 591 See documentation for CSIDL_INTERNET_CACHE.
 592 </p>
 593 <div class="variablelist"><table border="0">
 594 <col align="left" valign="top">
 595 <tbody><tr>
 596 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 597 <td>a string owned by GLib that must not be modified
 598 or freed.</td>
 599 </tr></tbody>
 600 </table></div>
 601 <p class="since">Since 2.6</p>
 602 </div>
 603 <hr>
 604 <div class="refsect2">
 605 <a name="g-get-user-data-dir"></a><h3>g_get_user_data_dir ()</h3>
 606 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_data_dir                 (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 607 <p>
 608 Returns a base directory in which to access application data such
 609 as icons that is customized for a particular user.
 610 </p>
 611 <p>
 612 On UNIX platforms this is determined using the mechanisms described in
 613 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 614 XDG Base Directory Specification</a>.
 615 In this case the directory retrieved will be XDG_DATA_HOME.
 616 </p>
 617 <p>
 618 On Windows this is the folder to use for local (as opposed to
 619 roaming) application data. See documentation for
 620 CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
 621 what <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-config-dir" title="g_get_user_config_dir ()"><code class="function">g_get_user_config_dir()</code></a> returns.
 622 </p>
 623 <div class="variablelist"><table border="0">
 624 <col align="left" valign="top">
 625 <tbody><tr>
 626 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 627 <td>a string owned by GLib that must not be modified
 628 or freed.</td>
 629 </tr></tbody>
 630 </table></div>
 631 <p class="since">Since 2.6</p>
 632 </div>
 633 <hr>
 634 <div class="refsect2">
 635 <a name="g-get-user-config-dir"></a><h3>g_get_user_config_dir ()</h3>
 636 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_config_dir               (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 637 <p>
 638 Returns a base directory in which to store user-specific application
 639 configuration information such as user preferences and settings.
 640 </p>
 641 <p>
 642 On UNIX platforms this is determined using the mechanisms described in
 643 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 644 XDG Base Directory Specification</a>.
 645 In this case the directory retrieved will be XDG_CONFIG_HOME.
 646 </p>
 647 <p>
 648 On Windows this is the folder to use for local (as opposed to
 649 roaming) application data. See documentation for
 650 CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
 651 what <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-data-dir" title="g_get_user_data_dir ()"><code class="function">g_get_user_data_dir()</code></a> returns.
 652 </p>
 653 <div class="variablelist"><table border="0">
 654 <col align="left" valign="top">
 655 <tbody><tr>
 656 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 657 <td>a string owned by GLib that must not be modified
 658 or freed.</td>
 659 </tr></tbody>
 660 </table></div>
 661 <p class="since">Since 2.6</p>
 662 </div>
 663 <hr>
 664 <div class="refsect2">
 665 <a name="g-get-user-runtime-dir"></a><h3>g_get_user_runtime_dir ()</h3>
 666 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_runtime_dir              (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 667 <p>
 668 Returns a directory that is unique to the current user on the local
 669 system.
 670 </p>
 671 <p>
 672 On UNIX platforms this is determined using the mechanisms described in
 673 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 674 XDG Base Directory Specification</a>.  This is the directory
 675 specified in the <code class="envar">XDG_RUNTIME_DIR</code> environment variable.
 676 In the case that this variable is not set, GLib will issue a warning
 677 message to stderr and return the value of <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-cache-dir" title="g_get_user_cache_dir ()"><code class="function">g_get_user_cache_dir()</code></a>.
 678 </p>
 679 <p>
 680 On Windows this is the folder to use for local (as opposed to
 681 roaming) application data. See documentation for
 682 CSIDL_LOCAL_APPDATA.  Note that on Windows it thus is the same as
 683 what <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-config-dir" title="g_get_user_config_dir ()"><code class="function">g_get_user_config_dir()</code></a> returns.
 684 </p>
 685 <div class="variablelist"><table border="0">
 686 <col align="left" valign="top">
 687 <tbody><tr>
 688 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 689 <td>a string owned by GLib that must not be modified or freed.</td>
 690 </tr></tbody>
 691 </table></div>
 692 <p class="since">Since 2.28</p>
 693 </div>
 694 <hr>
 695 <div class="refsect2">
 696 <a name="GUserDirectory"></a><h3>enum GUserDirectory</h3>
 697 <pre class="programlisting">typedef enum {
 698   G_USER_DIRECTORY_DESKTOP,
 699   G_USER_DIRECTORY_DOCUMENTS,
 700   G_USER_DIRECTORY_DOWNLOAD,
 701   G_USER_DIRECTORY_MUSIC,
 702   G_USER_DIRECTORY_PICTURES,
 703   G_USER_DIRECTORY_PUBLIC_SHARE,
 704   G_USER_DIRECTORY_TEMPLATES,
 705   G_USER_DIRECTORY_VIDEOS,
 706
 707   G_USER_N_DIRECTORIES
 708 } GUserDirectory;
 709 </pre>
 710 <p>
 711 These are logical ids for special directories which are defined
 712 depending on the platform used. You should use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-special-dir" title="g_get_user_special_dir ()"><code class="function">g_get_user_special_dir()</code></a>
 713 to retrieve the full path associated to the logical id.
 714 </p>
 715 <p>
 716 The <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GUserDirectory" title="enum GUserDirectory"><span class="type">GUserDirectory</span></a> enumeration can be extended at later date. Not
 717 every platform has a directory for every logical id in this
 718 enumeration.
 719 </p>
 720 <div class="variablelist"><table border="0">
 721 <col align="left" valign="top">
 722 <tbody>
 723 <tr>
 724 <td><p><a name="G-USER-DIRECTORY-DESKTOP:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_DESKTOP</code></span></p></td>
 725 <td>the user's Desktop directory
 726 </td>
 727 </tr>
 728 <tr>
 729 <td><p><a name="G-USER-DIRECTORY-DOCUMENTS:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_DOCUMENTS</code></span></p></td>
 730 <td>the user's Documents directory
 731 </td>
 732 </tr>
 733 <tr>
 734 <td><p><a name="G-USER-DIRECTORY-DOWNLOAD:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_DOWNLOAD</code></span></p></td>
 735 <td>the user's Downloads directory
 736 </td>
 737 </tr>
 738 <tr>
 739 <td><p><a name="G-USER-DIRECTORY-MUSIC:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_MUSIC</code></span></p></td>
 740 <td>the user's Music directory
 741 </td>
 742 </tr>
 743 <tr>
 744 <td><p><a name="G-USER-DIRECTORY-PICTURES:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_PICTURES</code></span></p></td>
 745 <td>the user's Pictures directory
 746 </td>
 747 </tr>
 748 <tr>
 749 <td><p><a name="G-USER-DIRECTORY-PUBLIC-SHARE:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_PUBLIC_SHARE</code></span></p></td>
 750 <td>the user's shared directory
 751 </td>
 752 </tr>
 753 <tr>
 754 <td><p><a name="G-USER-DIRECTORY-TEMPLATES:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_TEMPLATES</code></span></p></td>
 755 <td>the user's Templates directory
 756 </td>
 757 </tr>
 758 <tr>
 759 <td><p><a name="G-USER-DIRECTORY-VIDEOS:CAPS"></a><span class="term"><code class="literal">G_USER_DIRECTORY_VIDEOS</code></span></p></td>
 760 <td>the user's Movies directory
 761 </td>
 762 </tr>
 763 <tr>
 764 <td><p><a name="G-USER-N-DIRECTORIES:CAPS"></a><span class="term"><code class="literal">G_USER_N_DIRECTORIES</code></span></p></td>
 765 <td>the number of enum values
 766 </td>
 767 </tr>
 768 </tbody>
 769 </table></div>
 770 <p class="since">Since 2.14</p>
 771 </div>
 772 <hr>
 773 <div class="refsect2">
 774 <a name="g-get-user-special-dir"></a><h3>g_get_user_special_dir ()</h3>
 775 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_user_special_dir              (<em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GUserDirectory" title="enum GUserDirectory"><span class="type">GUserDirectory</span></a> directory</code></em>);</pre>
 776 <p>
 777 Returns the full path of a special directory using its logical id.
 778 </p>
 779 <p>
 780 On Unix this is done using the XDG special user directories.
 781 For compatibility with existing practise, <a class="link" href="glib-Miscellaneous-Utility-Functions.html#G-USER-DIRECTORY-DESKTOP:CAPS"><code class="literal">G_USER_DIRECTORY_DESKTOP</code></a>
 782 falls back to <code class="filename">$HOME/Desktop</code> when XDG special
 783 user directories have not been set up.
 784 </p>
 785 <p>
 786 Depending on the platform, the user might be able to change the path
 787 of the special directory without requiring the session to restart; GLib
 788 will not reflect any change once the special directories are loaded.
 789 </p>
 790 <div class="variablelist"><table border="0">
 791 <col align="left" valign="top">
 792 <tbody>
 793 <tr>
 794 <td><p><span class="term"><em class="parameter"><code>directory</code></em> :</span></p></td>
 795 <td>the logical id of special directory</td>
 796 </tr>
 797 <tr>
 798 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 799 <td>the path to the specified special directory, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 800 if the logical id was not found. The returned string is owned by
 801 GLib and should not be modified or freed.</td>
 802 </tr>
 803 </tbody>
 804 </table></div>
 805 <p class="since">Since 2.14</p>
 806 </div>
 807 <hr>
 808 <div class="refsect2">
 809 <a name="g-get-system-data-dirs"></a><h3>g_get_system_data_dirs ()</h3>
 810 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * g_get_system_data_dirs            (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 811 <p>
 812 Returns an ordered list of base directories in which to access
 813 system-wide application data.
 814 </p>
 815 <p>
 816 On UNIX platforms this is determined using the mechanisms described in
 817 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 818 XDG Base Directory Specification</a>
 819 In this case the list of directories retrieved will be XDG_DATA_DIRS.
 820 </p>
 821 <p>
 822 On Windows the first elements in the list are the Application Data
 823 and Documents folders for All Users. (These can be determined only
 824 on Windows 2000 or later and are not present in the list on other
 825 Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
 826 CSIDL_COMMON_DOCUMENTS.
 827 </p>
 828 <p>
 829 Then follows the "share" subfolder in the installation folder for
 830 the package containing the DLL that calls this function, if it can
 831 be determined.
 832 </p>
 833 <p>
 834 Finally the list contains the "share" subfolder in the installation
 835 folder for GLib, and in the installation folder for the package the
 836 application's .exe file belongs to.
 837 </p>
 838 <p>
 839 The installation folders above are determined by looking up the
 840 folder where the module (DLL or EXE) in question is located. If the
 841 folder's name is "bin", its parent is used, otherwise the folder
 842 itself.
 843 </p>
 844 <p>
 845 Note that on Windows the returned list can vary depending on where
 846 this function is called.
 847 </p>
 848 <div class="variablelist"><table border="0">
 849 <col align="left" valign="top">
 850 <tbody><tr>
 851 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 852 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings owned by GLib that must
 853 not be modified or freed. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 854 </td>
 855 </tr></tbody>
 856 </table></div>
 857 <p class="since">Since 2.6</p>
 858 </div>
 859 <hr>
 860 <div class="refsect2">
 861 <a name="g-get-system-config-dirs"></a><h3>g_get_system_config_dirs ()</h3>
 862 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * g_get_system_config_dirs          (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 863 <p>
 864 Returns an ordered list of base directories in which to access
 865 system-wide configuration information.
 866 </p>
 867 <p>
 868 On UNIX platforms this is determined using the mechanisms described in
 869 the <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">
 870 XDG Base Directory Specification</a>.
 871 In this case the list of directories retrieved will be XDG_CONFIG_DIRS.
 872 </p>
 873 <p>
 874 On Windows is the directory that contains application data for all users.
 875 A typical path is C:\Documents and Settings\All Users\Application Data.
 876 This folder is used for application data that is not user specific.
 877 For example, an application can store a spell-check dictionary, a database
 878 of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
 879 This information will not roam and is available to anyone using the computer.
 880 </p>
 881 <div class="variablelist"><table border="0">
 882 <col align="left" valign="top">
 883 <tbody><tr>
 884 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 885 <td>a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings owned by GLib that must
 886 not be modified or freed. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
 887 </td>
 888 </tr></tbody>
 889 </table></div>
 890 <p class="since">Since 2.6</p>
 891 </div>
 892 <hr>
 893 <div class="refsect2">
 894 <a name="g-reload-user-special-dirs-cache"></a><h3>g_reload_user_special_dirs_cache ()</h3>
 895 <pre class="programlisting"><span class="returnvalue">void</span>                g_reload_user_special_dirs_cache    (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 896 <p>
 897 Resets the cache used for <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-special-dir" title="g_get_user_special_dir ()"><code class="function">g_get_user_special_dir()</code></a>, so
 898 that the latest on-disk version is used. Call this only
 899 if you just changed the data on disk yourself.
 900 </p>
 901 <p>
 902 Due to threadsafety issues this may cause leaking of strings
 903 that were previously returned from <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-special-dir" title="g_get_user_special_dir ()"><code class="function">g_get_user_special_dir()</code></a>
 904 that can't be freed. We ensure to only leak the data for
 905 the directories that actually changed value though.
 906 </p>
 907 <p class="since">Since 2.22</p>
 908 </div>
 909 <hr>
 910 <div class="refsect2">
 911 <a name="g-get-host-name"></a><h3>g_get_host_name ()</h3>
 912 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_host_name                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 913 <p>
 914 Return a name for the machine.
 915 </p>
 916 <p>
 917 The returned name is not necessarily a fully-qualified domain name,
 918 or even present in DNS or some other name service at all. It need
 919 not even be unique on your local network or site, but usually it
 920 is. Callers should not rely on the return value having any specific
 921 properties like uniqueness for security purposes. Even if the name
 922 of the machine is changed while an application is running, the
 923 return value from this function does not change. The returned
 924 string is owned by GLib and should not be modified or freed. If no
 925 name can be determined, a default fixed string "localhost" is
 926 returned.
 927 </p>
 928 <div class="variablelist"><table border="0">
 929 <col align="left" valign="top">
 930 <tbody><tr>
 931 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 932 <td>the host name of the machine.</td>
 933 </tr></tbody>
 934 </table></div>
 935 <p class="since">Since 2.8</p>
 936 </div>
 937 <hr>
 938 <div class="refsect2">
 939 <a name="g-get-home-dir"></a><h3>g_get_home_dir ()</h3>
 940 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_home_dir                      (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 941 <p>
 942 Gets the current user's home directory as defined in the
 943 password database.
 944 </p>
 945 <p>
 946 Note that in contrast to traditional UNIX tools, this function
 947 prefers <code class="filename">passwd</code> entries over the <code class="envar">HOME</code>
 948 environment variable.
 949 </p>
 950 <p>
 951 One of the reasons for this decision is that applications in many
 952 cases need special handling to deal with the case where
 953 <code class="envar">HOME</code> is
 954 </p>
 955 <table border="0" summary="Simple list" class="simplelist">
 956 <tr><td>Not owned by the user</td></tr>
 957 <tr><td>Not writeable</td></tr>
 958 <tr><td>Not even readable</td></tr>
 959 </table>
 960 <p>
 961 Since applications are in general <span class="emphasis"><em>not</em></span> written
 962 to deal with these situations it was considered better to make
 963 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-home-dir" title="g_get_home_dir ()"><code class="function">g_get_home_dir()</code></a> not pay attention to <code class="envar">HOME</code> and to
 964 return the real home directory for the user. If applications
 965 want to pay attention to <code class="envar">HOME</code>, they can do:
 966 </p>
 967 <div class="informalexample">
 968   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 969     <tbody>
 970       <tr>
 971         <td class="listing_lines" align="right"><pre>1
 972 2
 973 3</pre></td>
 974         <td class="listing_code"><pre class="programlisting"><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">homedir </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Miscellaneous-Utility-Functions.html#g-getenv">g_getenv</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"HOME"</span><span class="symbol">);</span>
 975 <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">homedir</span><span class="symbol">)</span>
 976 <span class="normal">    homedir </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Miscellaneous-Utility-Functions.html#g-get-home-dir">g_get_home_dir</a></span><span class="normal"> </span><span class="symbol">();</span></pre></td>
 977       </tr>
 978     </tbody>
 979   </table>
 980 </div>
 981
 982 <p>
 983 </p>
 984 <div class="variablelist"><table border="0">
 985 <col align="left" valign="top">
 986 <tbody><tr>
 987 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 988 <td>the current user's home directory</td>
 989 </tr></tbody>
 990 </table></div>
 991 </div>
 992 <hr>
 993 <div class="refsect2">
 994 <a name="g-get-tmp-dir"></a><h3>g_get_tmp_dir ()</h3>
 995 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_get_tmp_dir                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 996 <p>
 997 Gets the directory to use for temporary files. This is found from
 998 inspecting the environment variables <code class="envar">TMPDIR</code>,
 999 <code class="envar">TMP</code>, and <code class="envar">TEMP</code> in that order. If none
1000 of those are defined "/tmp" is returned on UNIX and "C:\" on Windows.
1001 The encoding of the returned string is system-defined. On Windows,
1002 it is always UTF-8. The return value is never <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> or the empty string.
1003 </p>
1004 <div class="variablelist"><table border="0">
1005 <col align="left" valign="top">
1006 <tbody><tr>
1007 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1008 <td>the directory to use for temporary files.</td>
1009 </tr></tbody>
1010 </table></div>
1011 </div>
1012 <hr>
1013 <div class="refsect2">
1014 <a name="g-get-current-dir"></a><h3>g_get_current_dir ()</h3>
1015 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_get_current_dir                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1016 <p>
1017 Gets the current directory.
1018 </p>
1019 <p>
1020 The returned string should be freed when no longer needed.
1021 The encoding of the returned string is system defined.
1022 On Windows, it is always UTF-8.
1023 </p>
1024 <div class="variablelist"><table border="0">
1025 <col align="left" valign="top">
1026 <tbody><tr>
1027 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1028 <td>the current directory</td>
1029 </tr></tbody>
1030 </table></div>
1031 </div>
1032 <hr>
1033 <div class="refsect2">
1034 <a name="g-basename"></a><h3>g_basename ()</h3>
1035 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_basename                          (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);</pre>
1036 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1037 <h3 class="title">Warning</h3>
1038 <p><code class="literal">g_basename</code> has been deprecated since version 2.2 and should not be used in newly-written code. Use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-basename" title="g_path_get_basename ()"><code class="function">g_path_get_basename()</code></a> instead, but notice
1039     that <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-basename" title="g_path_get_basename ()"><code class="function">g_path_get_basename()</code></a> allocates new memory for the
1040     returned string, unlike this function which returns a pointer
1041     into the argument.</p>
1042 </div>
1043 <p>
1044 Gets the name of the file without any leading directory
1045 components. It returns a pointer into the given file name
1046 string.
1047 </p>
1048 <div class="variablelist"><table border="0">
1049 <col align="left" valign="top">
1050 <tbody>
1051 <tr>
1052 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1053 <td>the name of the file</td>
1054 </tr>
1055 <tr>
1056 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1057 <td>the name of the file without any leading
1058 directory components</td>
1059 </tr>
1060 </tbody>
1061 </table></div>
1062 </div>
1063 <hr>
1064 <div class="refsect2">
1065 <a name="g-dirname"></a><h3>g_dirname</h3>
1066 <pre class="programlisting">#define             g_dirname</pre>
1067 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1068 <h3 class="title">Warning</h3>
1069 <p><code class="literal">g_dirname</code> is deprecated and should not be used in newly-written code. use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname" title="g_path_get_dirname ()"><code class="function">g_path_get_dirname()</code></a> instead</p>
1070 </div>
1071 <p>
1072 Gets the directory components of a file name.
1073 </p>
1074 <p>
1075 If the file name has no directory components "." is returned.
1076 The returned string should be freed when no longer needed.
1077 </p>
1078 <div class="variablelist"><table border="0">
1079 <col align="left" valign="top">
1080 <tbody>
1081 <tr>
1082 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1083 <td>the name of the file</td>
1084 </tr>
1085 <tr>
1086 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1087 <td>the directory components of the file</td>
1088 </tr>
1089 </tbody>
1090 </table></div>
1091 </div>
1092 <hr>
1093 <div class="refsect2">
1094 <a name="g-path-is-absolute"></a><h3>g_path_is_absolute ()</h3>
1095 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_path_is_absolute                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);</pre>
1096 <p>
1097 Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the given <em class="parameter"><code>file_name</code></em> is an absolute file name.
1098 Note that this is a somewhat vague concept on Windows.
1099 </p>
1100 <p>
1101 On POSIX systems, an absolute file name is well-defined. It always
1102 starts from the single root directory. For example "/usr/local".
1103 </p>
1104 <p>
1105 On Windows, the concepts of current drive and drive-specific
1106 current directory introduce vagueness. This function interprets as
1107 an absolute file name one that either begins with a directory
1108 separator such as "\Users\tml" or begins with the root on a drive,
1109 for example "C:\Windows". The first case also includes UNC paths
1110 such as "\\myserver\docs\foo". In all cases, either slashes or
1111 backslashes are accepted.
1112 </p>
1113 <p>
1114 Note that a file name relative to the current drive root does not
1115 truly specify a file uniquely over time and across processes, as
1116 the current drive is a per-process value and can be changed.
1117 </p>
1118 <p>
1119 File names relative the current directory on some specific drive,
1120 such as "D:foo/bar", are not interpreted as absolute by this
1121 function, but they obviously are not relative to the normal current
1122 directory as returned by <code class="function">getcwd()</code> or <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-current-dir" title="g_get_current_dir ()"><code class="function">g_get_current_dir()</code></a>
1123 either. Such paths should be avoided, or need to be handled using
1124 Windows-specific code.
1125 </p>
1126 <div class="variablelist"><table border="0">
1127 <col align="left" valign="top">
1128 <tbody>
1129 <tr>
1130 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1131 <td>a file name</td>
1132 </tr>
1133 <tr>
1134 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1135 <td>
1136 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>file_name</code></em> is absolute</td>
1137 </tr>
1138 </tbody>
1139 </table></div>
1140 </div>
1141 <hr>
1142 <div class="refsect2">
1143 <a name="g-path-skip-root"></a><h3>g_path_skip_root ()</h3>
1144 <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *       g_path_skip_root                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);</pre>
1145 <p>
1146 Returns a pointer into <em class="parameter"><code>file_name</code></em> after the root component,
1147 i.e. after the "/" in UNIX or "C:\" under Windows. If <em class="parameter"><code>file_name</code></em>
1148 is not an absolute path it returns <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
1149 </p>
1150 <div class="variablelist"><table border="0">
1151 <col align="left" valign="top">
1152 <tbody>
1153 <tr>
1154 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1155 <td>a file name</td>
1156 </tr>
1157 <tr>
1158 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1159 <td>a pointer into <em class="parameter"><code>file_name</code></em> after the root component</td>
1160 </tr>
1161 </tbody>
1162 </table></div>
1163 </div>
1164 <hr>
1165 <div class="refsect2">
1166 <a name="g-path-get-basename"></a><h3>g_path_get_basename ()</h3>
1167 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_path_get_basename                 (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);</pre>
1168 <p>
1169 Gets the last component of the filename.
1170 </p>
1171 <p>
1172 If <em class="parameter"><code>file_name</code></em> ends with a directory separator it gets the component
1173 before the last slash. If <em class="parameter"><code>file_name</code></em> consists only of directory
1174 separators (and on Windows, possibly a drive letter), a single
1175 separator is returned. If <em class="parameter"><code>file_name</code></em> is empty, it gets ".".
1176 </p>
1177 <div class="variablelist"><table border="0">
1178 <col align="left" valign="top">
1179 <tbody>
1180 <tr>
1181 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1182 <td>the name of the file</td>
1183 </tr>
1184 <tr>
1185 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1186 <td>a newly allocated string containing the last
1187 component of the filename</td>
1188 </tr>
1189 </tbody>
1190 </table></div>
1191 </div>
1192 <hr>
1193 <div class="refsect2">
1194 <a name="g-path-get-dirname"></a><h3>g_path_get_dirname ()</h3>
1195 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_path_get_dirname                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>);</pre>
1196 <p>
1197 Gets the directory components of a file name.
1198 </p>
1199 <p>
1200 If the file name has no directory components "." is returned.
1201 The returned string should be freed when no longer needed.
1202 </p>
1203 <div class="variablelist"><table border="0">
1204 <col align="left" valign="top">
1205 <tbody>
1206 <tr>
1207 <td><p><span class="term"><em class="parameter"><code>file_name</code></em> :</span></p></td>
1208 <td>the name of the file</td>
1209 </tr>
1210 <tr>
1211 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1212 <td>the directory components of the file</td>
1213 </tr>
1214 </tbody>
1215 </table></div>
1216 </div>
1217 <hr>
1218 <div class="refsect2">
1219 <a name="g-build-filename"></a><h3>g_build_filename ()</h3>
1220 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_build_filename                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *first_element</code></em>,
1221                                                          <em class="parameter"><code>...</code></em>);</pre>
1222 <p>
1223 Creates a filename from a series of elements using the correct
1224 separator for filenames.
1225 </p>
1226 <p>
1227 On Unix, this function behaves identically to <code class="literal">g_build_path
1228 (G_DIR_SEPARATOR_S, first_element, ....)</code>.
1229 </p>
1230 <p>
1231 On Windows, it takes into account that either the backslash
1232 (<code class="literal">\</code> or slash (<code class="literal">/</code>) can be used
1233 as separator in filenames, but otherwise behaves as on Unix. When
1234 file pathname separators need to be inserted, the one that last
1235 previously occurred in the parameters (reading from left to right)
1236 is used.
1237 </p>
1238 <p>
1239 No attempt is made to force the resulting filename to be an absolute
1240 path. If the first element is a relative path, the result will
1241 be a relative path.
1242 </p>
1243 <div class="variablelist"><table border="0">
1244 <col align="left" valign="top">
1245 <tbody>
1246 <tr>
1247 <td><p><span class="term"><em class="parameter"><code>first_element</code></em> :</span></p></td>
1248 <td>the first element in the path</td>
1249 </tr>
1250 <tr>
1251 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
1252 <td>remaining elements in path, terminated by <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1253 </td>
1254 </tr>
1255 <tr>
1256 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1257 <td>a newly-allocated string that must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
1258 </tr>
1259 </tbody>
1260 </table></div>
1261 </div>
1262 <hr>
1263 <div class="refsect2">
1264 <a name="g-build-filenamev"></a><h3>g_build_filenamev ()</h3>
1265 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_build_filenamev                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **args</code></em>);</pre>
1266 <p>
1267 Behaves exactly like <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-filename" title="g_build_filename ()"><code class="function">g_build_filename()</code></a>, but takes the path elements
1268 as a string array, instead of varargs. This function is mainly
1269 meant for language bindings.
1270 </p>
1271 <div class="variablelist"><table border="0">
1272 <col align="left" valign="top">
1273 <tbody>
1274 <tr>
1275 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
1276 <td>
1277 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings containing the path elements. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span>
1278 </td>
1279 </tr>
1280 <tr>
1281 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1282 <td>a newly-allocated string that must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
1283 </tr>
1284 </tbody>
1285 </table></div>
1286 <p class="since">Since 2.8</p>
1287 </div>
1288 <hr>
1289 <div class="refsect2">
1290 <a name="g-build-path"></a><h3>g_build_path ()</h3>
1291 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_build_path                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
1292                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *first_element</code></em>,
1293                                                          <em class="parameter"><code>...</code></em>);</pre>
1294 <p>
1295 Creates a path from a series of elements using <em class="parameter"><code>separator</code></em> as the
1296 separator between elements. At the boundary between two elements,
1297 any trailing occurrences of separator in the first element, or
1298 leading occurrences of separator in the second element are removed
1299 and exactly one copy of the separator is inserted.
1300 </p>
1301 <p>
1302 Empty elements are ignored.
1303 </p>
1304 <p>
1305 The number of leading copies of the separator on the result is
1306 the same as the number of leading copies of the separator on
1307 the first non-empty element.
1308 </p>
1309 <p>
1310 The number of trailing copies of the separator on the result is
1311 the same as the number of trailing copies of the separator on
1312 the last non-empty element. (Determination of the number of
1313 trailing copies is done without stripping leading copies, so
1314 if the separator is <code class="literal">ABA</code>, <code class="literal">ABABA</code>
1315 has 1 trailing copy.)
1316 </p>
1317 <p>
1318 However, if there is only a single non-empty element, and there
1319 are no characters in that element not part of the leading or
1320 trailing separators, then the result is exactly the original value
1321 of that element.
1322 </p>
1323 <p>
1324 Other than for determination of the number of leading and trailing
1325 copies of the separator, elements consisting only of copies
1326 of the separator are ignored.
1327 </p>
1328 <div class="variablelist"><table border="0">
1329 <col align="left" valign="top">
1330 <tbody>
1331 <tr>
1332 <td><p><span class="term"><em class="parameter"><code>separator</code></em> :</span></p></td>
1333 <td>a string used to separator the elements of the path.</td>
1334 </tr>
1335 <tr>
1336 <td><p><span class="term"><em class="parameter"><code>first_element</code></em> :</span></p></td>
1337 <td>the first element in the path</td>
1338 </tr>
1339 <tr>
1340 <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
1341 <td>remaining elements in path, terminated by <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1342 </td>
1343 </tr>
1344 <tr>
1345 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1346 <td>a newly-allocated string that must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
1347 </tr>
1348 </tbody>
1349 </table></div>
1350 </div>
1351 <hr>
1352 <div class="refsect2">
1353 <a name="g-build-pathv"></a><h3>g_build_pathv ()</h3>
1354 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_build_pathv                       (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *separator</code></em>,
1355                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **args</code></em>);</pre>
1356 <p>
1357 Behaves exactly like <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-path" title="g_build_path ()"><code class="function">g_build_path()</code></a>, but takes the path elements
1358 as a string array, instead of varargs. This function is mainly
1359 meant for language bindings.
1360 </p>
1361 <div class="variablelist"><table border="0">
1362 <col align="left" valign="top">
1363 <tbody>
1364 <tr>
1365 <td><p><span class="term"><em class="parameter"><code>separator</code></em> :</span></p></td>
1366 <td>a string used to separator the elements of the path.</td>
1367 </tr>
1368 <tr>
1369 <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
1370 <td>
1371 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated array of strings containing the path elements. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1]</span>
1372 </td>
1373 </tr>
1374 <tr>
1375 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1376 <td>a newly-allocated string that must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
1377 </tr>
1378 </tbody>
1379 </table></div>
1380 <p class="since">Since 2.8</p>
1381 </div>
1382 <hr>
1383 <div class="refsect2">
1384 <a name="g-format-size"></a><h3>g_format_size ()</h3>
1385 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_format_size                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> size</code></em>);</pre>
1386 <p>
1387 Formats a size (for example the size of a file) into a human readable
1388 string.  Sizes are rounded to the nearest size prefix (kB, MB, GB)
1389 and are displayed rounded to the nearest tenth. E.g. the file size
1390 3292528 bytes will be converted into the string "3.2 MB".
1391 </p>
1392 <p>
1393 The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
1394 </p>
1395 <p>
1396 This string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> when not needed any longer.
1397 </p>
1398 <p>
1399 See <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size-full" title="g_format_size_full ()"><code class="function">g_format_size_full()</code></a> for more options about how the size might be
1400 formatted.
1401 </p>
1402 <div class="variablelist"><table border="0">
1403 <col align="left" valign="top">
1404 <tbody>
1405 <tr>
1406 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
1407 <td>a size in bytes</td>
1408 </tr>
1409 <tr>
1410 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1411 <td>a newly-allocated formatted string containing a human readable
1412 file size</td>
1413 </tr>
1414 </tbody>
1415 </table></div>
1416 <p class="since">Since 2.30</p>
1417 </div>
1418 <hr>
1419 <div class="refsect2">
1420 <a name="GFormatSizeFlags"></a><h3>enum GFormatSizeFlags</h3>
1421 <pre class="programlisting">typedef enum {
1422   G_FORMAT_SIZE_DEFAULT     = 0,
1423   G_FORMAT_SIZE_LONG_FORMAT = 1 &lt;&lt; 0,
1424   G_FORMAT_SIZE_IEC_UNITS   = 1 &lt;&lt; 1
1425 } GFormatSizeFlags;
1426 </pre>
1427 <p>
1428 Flags to modify the format of the string returned by <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size-full" title="g_format_size_full ()"><code class="function">g_format_size_full()</code></a>.
1429 </p>
1430 <div class="variablelist"><table border="0">
1431 <col align="left" valign="top">
1432 <tbody>
1433 <tr>
1434 <td><p><a name="G-FORMAT-SIZE-DEFAULT:CAPS"></a><span class="term"><code class="literal">G_FORMAT_SIZE_DEFAULT</code></span></p></td>
1435 <td>behave the same as <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size" title="g_format_size ()"><code class="function">g_format_size()</code></a>
1436 </td>
1437 </tr>
1438 <tr>
1439 <td><p><a name="G-FORMAT-SIZE-LONG-FORMAT:CAPS"></a><span class="term"><code class="literal">G_FORMAT_SIZE_LONG_FORMAT</code></span></p></td>
1440 <td>include the exact number of bytes as part
1441     of the returned string.  For example, "45.6 kB (45,612 bytes)".
1442 </td>
1443 </tr>
1444 <tr>
1445 <td><p><a name="G-FORMAT-SIZE-IEC-UNITS:CAPS"></a><span class="term"><code class="literal">G_FORMAT_SIZE_IEC_UNITS</code></span></p></td>
1446 <td>use IEC (base 1024) units with "KiB"-style
1447     suffixes. IEC units should only be used for reporting things with
1448     a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
1449     Network and storage sizes should be reported in the normal SI units.
1450 </td>
1451 </tr>
1452 </tbody>
1453 </table></div>
1454 </div>
1455 <hr>
1456 <div class="refsect2">
1457 <a name="g-format-size-full"></a><h3>g_format_size_full ()</h3>
1458 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_format_size_full                  (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> size</code></em>,
1459                                                          <em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a> flags</code></em>);</pre>
1460 <p>
1461 Formats a size.
1462 </p>
1463 <p>
1464 This function is similar to <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size" title="g_format_size ()"><code class="function">g_format_size()</code></a> but allows for flags
1465 that modify the output. See <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a>.
1466 </p>
1467 <div class="variablelist"><table border="0">
1468 <col align="left" valign="top">
1469 <tbody>
1470 <tr>
1471 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
1472 <td>a size in bytes</td>
1473 </tr>
1474 <tr>
1475 <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td>
1476 <td>
1477 <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a> to modify the output</td>
1478 </tr>
1479 <tr>
1480 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1481 <td>a newly-allocated formatted string containing a human
1482 readable file size</td>
1483 </tr>
1484 </tbody>
1485 </table></div>
1486 <p class="since">Since 2.30</p>
1487 </div>
1488 <hr>
1489 <div class="refsect2">
1490 <a name="g-format-size-for-display"></a><h3>g_format_size_for_display ()</h3>
1491 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_format_size_for_display           (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#goffset" title="goffset"><span class="type">goffset</span></a> size</code></em>);</pre>
1492 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1493 <h3 class="title">Warning</h3>
1494 <p><code class="literal">g_format_size_for_display</code> has been deprecated since version 2.30 and should not be used in newly-written code. This function is broken due to its use of SI
1495     suffixes to denote IEC units. Use <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size" title="g_format_size ()"><code class="function">g_format_size()</code></a> instead.</p>
1496 </div>
1497 <p>
1498 Formats a size (for example the size of a file) into a human
1499 readable string. Sizes are rounded to the nearest size prefix
1500 (KB, MB, GB) and are displayed rounded to the nearest tenth.
1501 E.g. the file size 3292528 bytes will be converted into the
1502 string "3.1 MB".
1503 </p>
1504 <p>
1505 The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
1506 </p>
1507 <p>
1508 This string should be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a> when not needed any longer.
1509 </p>
1510 <div class="variablelist"><table border="0">
1511 <col align="left" valign="top">
1512 <tbody>
1513 <tr>
1514 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
1515 <td>a size in bytes</td>
1516 </tr>
1517 <tr>
1518 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1519 <td>a newly-allocated formatted string containing a human
1520 readable file size</td>
1521 </tr>
1522 </tbody>
1523 </table></div>
1524 <p class="since">Since 2.16</p>
1525 </div>
1526 <hr>
1527 <div class="refsect2">
1528 <a name="g-find-program-in-path"></a><h3>g_find_program_in_path ()</h3>
1529 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_find_program_in_path              (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *program</code></em>);</pre>
1530 <p>
1531 Locates the first executable named <em class="parameter"><code>program</code></em> in the user's path, in the
1532 same way that <code class="function">execvp()</code> would locate it. Returns an allocated string
1533 with the absolute path name, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if the program is not found in
1534 the path. If <em class="parameter"><code>program</code></em> is already an absolute path, returns a copy of
1535 <em class="parameter"><code>program</code></em> if <em class="parameter"><code>program</code></em> exists and is executable, and <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> otherwise.
1536
1537 On Windows, if <em class="parameter"><code>program</code></em> does not have a file type suffix, tries
1538 with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
1539 the <code class="envar">PATHEXT</code> environment variable.
1540 </p>
1541 <p>
1542 On Windows, it looks for the file in the same way as <code class="function">CreateProcess()</code>
1543 would. This means first in the directory where the executing
1544 program was loaded from, then in the current directory, then in the
1545 Windows 32-bit system directory, then in the Windows directory, and
1546 finally in the directories in the <code class="envar">PATH</code> environment
1547 variable. If the program is found, the return value contains the
1548 full name including the type suffix.
1549 </p>
1550 <div class="variablelist"><table border="0">
1551 <col align="left" valign="top">
1552 <tbody>
1553 <tr>
1554 <td><p><span class="term"><em class="parameter"><code>program</code></em> :</span></p></td>
1555 <td>a program name in the GLib file name encoding</td>
1556 </tr>
1557 <tr>
1558 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1559 <td>absolute path, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
1560 </td>
1561 </tr>
1562 </tbody>
1563 </table></div>
1564 </div>
1565 <hr>
1566 <div class="refsect2">
1567 <a name="g-bit-nth-lsf"></a><h3>g_bit_nth_lsf ()</h3>
1568 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_bit_nth_lsf                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> mask</code></em>,
1569                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> nth_bit</code></em>);</pre>
1570 <p>
1571 Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
1572 from (but not including) <em class="parameter"><code>nth_bit</code></em> upwards. Bits are numbered
1573 from 0 (least significant) to sizeof(<a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a>) * 8 - 1 (31 or 63,
1574 usually). To start searching from the 0th bit, set <em class="parameter"><code>nth_bit</code></em> to -1.
1575 </p>
1576 <div class="variablelist"><table border="0">
1577 <col align="left" valign="top">
1578 <tbody>
1579 <tr>
1580 <td><p><span class="term"><em class="parameter"><code>mask</code></em> :</span></p></td>
1581 <td>a <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> containing flags</td>
1582 </tr>
1583 <tr>
1584 <td><p><span class="term"><em class="parameter"><code>nth_bit</code></em> :</span></p></td>
1585 <td>the index of the bit to start the search from</td>
1586 </tr>
1587 <tr>
1588 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1589 <td>the index of the first bit set which is higher than <em class="parameter"><code>nth_bit</code></em>
1590 </td>
1591 </tr>
1592 </tbody>
1593 </table></div>
1594 </div>
1595 <hr>
1596 <div class="refsect2">
1597 <a name="g-bit-nth-msf"></a><h3>g_bit_nth_msf ()</h3>
1598 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_bit_nth_msf                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> mask</code></em>,
1599                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> nth_bit</code></em>);</pre>
1600 <p>
1601 Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
1602 from (but not including) <em class="parameter"><code>nth_bit</code></em> downwards. Bits are numbered
1603 from 0 (least significant) to sizeof(<a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a>) * 8 - 1 (31 or 63,
1604 usually). To start searching from the last bit, set <em class="parameter"><code>nth_bit</code></em> to
1605 -1 or GLIB_SIZEOF_LONG * 8.
1606 </p>
1607 <div class="variablelist"><table border="0">
1608 <col align="left" valign="top">
1609 <tbody>
1610 <tr>
1611 <td><p><span class="term"><em class="parameter"><code>mask</code></em> :</span></p></td>
1612 <td>a <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> containing flags</td>
1613 </tr>
1614 <tr>
1615 <td><p><span class="term"><em class="parameter"><code>nth_bit</code></em> :</span></p></td>
1616 <td>the index of the bit to start the search from</td>
1617 </tr>
1618 <tr>
1619 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1620 <td>the index of the first bit set which is lower than <em class="parameter"><code>nth_bit</code></em>
1621 </td>
1622 </tr>
1623 </tbody>
1624 </table></div>
1625 </div>
1626 <hr>
1627 <div class="refsect2">
1628 <a name="g-bit-storage"></a><h3>g_bit_storage ()</h3>
1629 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_bit_storage                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> number</code></em>);</pre>
1630 <p>
1631 Gets the number of bits used to hold <em class="parameter"><code>number</code></em>,
1632 e.g. if <em class="parameter"><code>number</code></em> is 4, 3 bits are needed.
1633 </p>
1634 <div class="variablelist"><table border="0">
1635 <col align="left" valign="top">
1636 <tbody>
1637 <tr>
1638 <td><p><span class="term"><em class="parameter"><code>number</code></em> :</span></p></td>
1639 <td>a <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a>
1640 </td>
1641 </tr>
1642 <tr>
1643 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1644 <td>the number of bits used to hold <em class="parameter"><code>number</code></em>
1645 </td>
1646 </tr>
1647 </tbody>
1648 </table></div>
1649 </div>
1650 <hr>
1651 <div class="refsect2">
1652 <a name="g-spaced-primes-closest"></a><h3>g_spaced_primes_closest ()</h3>
1653 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_spaced_primes_closest             (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> num</code></em>);</pre>
1654 <p>
1655 Gets the smallest prime number from a built-in array of primes which
1656 is larger than <em class="parameter"><code>num</code></em>. This is used within GLib to calculate the optimum
1657 size of a <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a>.
1658 </p>
1659 <p>
1660 The built-in array of primes ranges from 11 to 13845163 such that
1661 each prime is approximately 1.5-2 times the previous prime.
1662 </p>
1663 <div class="variablelist"><table border="0">
1664 <col align="left" valign="top">
1665 <tbody>
1666 <tr>
1667 <td><p><span class="term"><em class="parameter"><code>num</code></em> :</span></p></td>
1668 <td>a <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a>
1669 </td>
1670 </tr>
1671 <tr>
1672 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1673 <td>the smallest prime number from a built-in array of primes
1674 which is larger than <em class="parameter"><code>num</code></em>
1675 </td>
1676 </tr>
1677 </tbody>
1678 </table></div>
1679 </div>
1680 <hr>
1681 <div class="refsect2">
1682 <a name="g-atexit"></a><h3>g_atexit ()</h3>
1683 <pre class="programlisting"><span class="returnvalue">void</span>                g_atexit                            (<em class="parameter"><code><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GVoidFunc" title="GVoidFunc ()"><span class="type">GVoidFunc</span></a> func</code></em>);</pre>
1684 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1685 <h3 class="title">Warning</h3>
1686 <p><code class="literal">g_atexit</code> has been deprecated since version 2.32 and should not be used in newly-written code. It is best to avoid <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a>.</p>
1687 </div>
1688 <p>
1689 Specifies a function to be called at normal program termination.
1690 </p>
1691 <p>
1692 Since GLib 2.8.2, on Windows <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a> actually is a preprocessor
1693 macro that maps to a call to the <code class="function">atexit()</code> function in the C
1694 library. This means that in case the code that calls <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a>,
1695 i.e. <code class="function">atexit()</code>, is in a DLL, the function will be called when the
1696 DLL is detached from the program. This typically makes more sense
1697 than that the function is called when the GLib DLL is detached,
1698 which happened earlier when <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a> was a function in the GLib
1699 DLL.
1700 </p>
1701 <p>
1702 The behaviour of <code class="function">atexit()</code> in the context of dynamically loaded
1703 modules is not formally specified and varies wildly.
1704 </p>
1705 <p>
1706 On POSIX systems, calling <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a> (or <code class="function">atexit()</code>) in a dynamically
1707 loaded module which is unloaded before the program terminates might
1708 well cause a crash at program exit.
1709 </p>
1710 <p>
1711 Some POSIX systems implement <code class="function">atexit()</code> like Windows, and have each
1712 dynamically loaded module maintain an own atexit chain that is
1713 called when the module is unloaded.
1714 </p>
1715 <p>
1716 On other POSIX systems, before a dynamically loaded module is
1717 unloaded, the registered atexit functions (if any) residing in that
1718 module are called, regardless where the code that registered them
1719 resided. This is presumably the most robust approach.
1720 </p>
1721 <p>
1722 As can be seen from the above, for portability it's best to avoid
1723 calling <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a> (or <code class="function">atexit()</code>) except in the main executable of a
1724 program.
1725 </p>
1726 <div class="variablelist"><table border="0">
1727 <col align="left" valign="top">
1728 <tbody><tr>
1729 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
1730 <td>the function to call on normal program termination. <span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span>
1731 </td>
1732 </tr></tbody>
1733 </table></div>
1734 </div>
1735 <hr>
1736 <div class="refsect2">
1737 <a name="g-parse-debug-string"></a><h3>g_parse_debug_string ()</h3>
1738 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_parse_debug_string                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *string</code></em>,
1739                                                          <em class="parameter"><code>const <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey"><span class="type">GDebugKey</span></a> *keys</code></em>,
1740                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> nkeys</code></em>);</pre>
1741 <p>
1742 Parses a string containing debugging options
1743 into a <a class="link" href="glib-Basic-Types.html#guint" title="guint"><code class="literal">guint</code></a> containing bit flags. This is used
1744 within GDK and GTK+ to parse the debug options passed on the
1745 command line or through environment variables.
1746 </p>
1747 <p>
1748 If <em class="parameter"><code>string</code></em> is equal to <code class="code">"all"</code>, all flags are set. Any flags
1749 specified along with <code class="code">"all"</code> in <em class="parameter"><code>string</code></em> are inverted; thus,
1750 <code class="code">"all,foo,bar"</code> or <code class="code">"foo,bar,all"</code> sets all flags
1751 except those corresponding to <code class="code">"foo"</code> and <code class="code">"bar"</code>.
1752 </p>
1753 <p>
1754 If <em class="parameter"><code>string</code></em> is equal to <code class="code">"help"</code>, all the available keys in <em class="parameter"><code>keys</code></em>
1755 are printed out to standard error.
1756 </p>
1757 <div class="variablelist"><table border="0">
1758 <col align="left" valign="top">
1759 <tbody>
1760 <tr>
1761 <td><p><span class="term"><em class="parameter"><code>string</code></em> :</span></p></td>
1762 <td>a list of debug options separated by colons, spaces, or
1763 commas, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
1764 </td>
1765 </tr>
1766 <tr>
1767 <td><p><span class="term"><em class="parameter"><code>keys</code></em> :</span></p></td>
1768 <td>pointer to an array of <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey"><span class="type">GDebugKey</span></a> which associate
1769 strings with bit flags. <span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=nkeys]</span>
1770 </td>
1771 </tr>
1772 <tr>
1773 <td><p><span class="term"><em class="parameter"><code>nkeys</code></em> :</span></p></td>
1774 <td>the number of <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey"><span class="type">GDebugKey</span></a>s in the array.</td>
1775 </tr>
1776 <tr>
1777 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1778 <td>the combined set of bit flags.</td>
1779 </tr>
1780 </tbody>
1781 </table></div>
1782 </div>
1783 <hr>
1784 <div class="refsect2">
1785 <a name="GDebugKey"></a><h3>struct GDebugKey</h3>
1786 <pre class="programlisting">struct GDebugKey {
1787   const gchar *key;
1788   guint        value;
1789 };
1790 </pre>
1791 <p>
1792 Associates a string with a bit flag.
1793 Used in <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-parse-debug-string" title="g_parse_debug_string ()"><code class="function">g_parse_debug_string()</code></a>.
1794 </p>
1795 <div class="variablelist"><table border="0">
1796 <col align="left" valign="top">
1797 <tbody>
1798 <tr>
1799 <td><p><span class="term">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *<em class="structfield"><code><a name="GDebugKey.key"></a>key</code></em>;</span></p></td>
1800 <td>the string</td>
1801 </tr>
1802 <tr>
1803 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> <em class="structfield"><code><a name="GDebugKey.value"></a>value</code></em>;</span></p></td>
1804 <td>the flag</td>
1805 </tr>
1806 </tbody>
1807 </table></div>
1808 </div>
1809 <hr>
1810 <div class="refsect2">
1811 <a name="GVoidFunc"></a><h3>GVoidFunc ()</h3>
1812 <pre class="programlisting"><span class="returnvalue">void</span>                (*GVoidFunc)                        (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1813 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
1814 <h3 class="title">Warning</h3>
1815 <p><code class="literal">GVoidFunc</code> is deprecated and should not be used in newly-written code.</p>
1816 </div>
1817 <p>
1818 Declares a type of function which takes no arguments
1819 and has no return value. It is used to specify the type
1820 function passed to <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a>.
1821 </p>
1822 </div>
1823 <hr>
1824 <div class="refsect2">
1825 <a name="GFreeFunc"></a><h3>GFreeFunc ()</h3>
1826 <pre class="programlisting"><span class="returnvalue">void</span>                (*GFreeFunc)                        (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
1827 <p>
1828 Declares a type of function which takes an arbitrary
1829 data pointer argument and has no return value. It is
1830 not currently used in GLib or GTK+.
1831 </p>
1832 <div class="variablelist"><table border="0">
1833 <col align="left" valign="top">
1834 <tbody><tr>
1835 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
1836 <td>a data pointer</td>
1837 </tr></tbody>
1838 </table></div>
1839 </div>
1840 <hr>
1841 <div class="refsect2">
1842 <a name="g-qsort-with-data"></a><h3>g_qsort_with_data ()</h3>
1843 <pre class="programlisting"><span class="returnvalue">void</span>                g_qsort_with_data                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> pbase</code></em>,
1844                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> total_elems</code></em>,
1845                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> size</code></em>,
1846                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> compare_func</code></em>,
1847                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
1848 <p>
1849 This is just like the standard C <code class="function">qsort()</code> function, but
1850 the comparison routine accepts a user data argument.
1851 </p>
1852 <div class="variablelist"><table border="0">
1853 <col align="left" valign="top">
1854 <tbody>
1855 <tr>
1856 <td><p><span class="term"><em class="parameter"><code>pbase</code></em> :</span></p></td>
1857 <td>start of array to sort</td>
1858 </tr>
1859 <tr>
1860 <td><p><span class="term"><em class="parameter"><code>total_elems</code></em> :</span></p></td>
1861 <td>elements in the array</td>
1862 </tr>
1863 <tr>
1864 <td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
1865 <td>size of each element</td>
1866 </tr>
1867 <tr>
1868 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
1869 <td>function to compare elements</td>
1870 </tr>
1871 <tr>
1872 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
1873 <td>data to pass to <em class="parameter"><code>compare_func</code></em>
1874 </td>
1875 </tr>
1876 </tbody>
1877 </table></div>
1878 </div>
1879 <hr>
1880 <div class="refsect2">
1881 <a name="g-nullify-pointer"></a><h3>g_nullify_pointer ()</h3>
1882 <pre class="programlisting"><span class="returnvalue">void</span>                g_nullify_pointer                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> *nullify_location</code></em>);</pre>
1883 <p>
1884 Set the pointer at the specified location to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
1885 </p>
1886 <div class="variablelist"><table border="0">
1887 <col align="left" valign="top">
1888 <tbody><tr>
1889 <td><p><span class="term"><em class="parameter"><code>nullify_location</code></em> :</span></p></td>
1890 <td>the memory address of the pointer.</td>
1891 </tr></tbody>
1892 </table></div>
1893 </div>
1894 </div>
1895 </div>
1896 <div class="footer">
1897 <hr>
1898           Generated by GTK-Doc V1.18</div>
1899 </body>
1900 </html>