| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Miscellaneous Utility Functions: GLib Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GLib Reference Manual"> |
| <link rel="up" href="glib-utilities.html" title="GLib Utilities"> |
| <link rel="prev" href="glib-Hook-Functions.html" title="Hook Functions"> |
| <link rel="next" href="glib-Lexical-Scanner.html" title="Lexical Scanner"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#glib-Miscellaneous-Utility-Functions.description" class="shortcut">Description</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="glib-Hook-Functions.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="glib-Lexical-Scanner.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="glib-Miscellaneous-Utility-Functions"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="glib-Miscellaneous-Utility-Functions.top_of_page"></a>Miscellaneous Utility Functions</span></h2> |
| <p>Miscellaneous Utility Functions — a selection of portable utility functions</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.functions"></a><h2>Functions</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="functions_return"> |
| <col class="functions_name"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-application-name" title="g_get_application_name ()">g_get_application_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-application-name" title="g_set_application_name ()">g_set_application_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname" title="g_get_prgname ()">g_get_prgname</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-set-prgname" title="g_set_prgname ()">g_set_prgname</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> ** |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-environ" title="g_get_environ ()">g_get_environ</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-getenv" title="g_environ_getenv ()">g_environ_getenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> ** |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-setenv" title="g_environ_setenv ()">g_environ_setenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> ** |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-environ-unsetenv" title="g_environ_unsetenv ()">g_environ_unsetenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()">g_getenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-setenv" title="g_setenv ()">g_setenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()">g_unsetenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> ** |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-listenv" title="g_listenv ()">g_listenv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-user-name" title="g_get_user_name ()">g_get_user_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-real-name" title="g_get_real_name ()">g_get_real_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * const * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-host-name" title="g_get_host_name ()">g_get_host_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-home-dir" title="g_get_home_dir ()">g_get_home_dir</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-tmp-dir" title="g_get_tmp_dir ()">g_get_tmp_dir</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-get-current-dir" title="g_get_current_dir ()">g_get_current_dir</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-basename" title="g_basename ()">g_basename</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-is-absolute" title="g_path_is_absolute ()">g_path_is_absolute</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-skip-root" title="g_path_skip_root ()">g_path_skip_root</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-basename" title="g_path_get_basename ()">g_path_get_basename</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname" title="g_path_get_dirname ()">g_path_get_dirname</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-filename" title="g_build_filename ()">g_build_filename</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-filenamev" title="g_build_filenamev ()">g_build_filenamev</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-path" title="g_build_path ()">g_build_path</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-build-pathv" title="g_build_pathv ()">g_build_pathv</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size" title="g_format_size ()">g_format_size</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-format-size-full" title="g_format_size_full ()">g_format_size_full</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <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> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-nth-lsf" title="g_bit_nth_lsf()">g_bit_nth_lsf</a><span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-nth-msf" title="g_bit_nth_msf()">g_bit_nth_msf</a><span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-bit-storage" title="g_bit_storage()">g_bit_storage</a><span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#guint" title="guint ()"><span class="returnvalue">guint</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-spaced-primes-closest" title="g_spaced_primes_closest ()">g_spaced_primes_closest</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()">g_atexit</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#guint" title="guint ()"><span class="returnvalue">guint</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-parse-debug-string" title="g_parse_debug_string ()">g_parse_debug_string</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <span class="c_punctuation">(</span><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GVoidFunc" title="GVoidFunc ()">*GVoidFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <span class="c_punctuation">(</span><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFreeFunc" title="GFreeFunc ()">*GFreeFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-qsort-with-data" title="g_qsort_with_data ()">g_qsort_with_data</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-nullify-pointer" title="g_nullify_pointer ()">g_nullify_pointer</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.other"></a><h2>Types and Values</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="name"> |
| <col class="description"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="datatype_keyword">enum</td> |
| <td class="function_name"><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GUserDirectory" title="enum GUserDirectory">GUserDirectory</a></td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"><a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-dirname" title="g_dirname">g_dirname</a></td> |
| </tr> |
| <tr> |
| <td class="datatype_keyword">enum</td> |
| <td class="function_name"><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags">GFormatSizeFlags</a></td> |
| </tr> |
| <tr> |
| <td class="datatype_keyword">struct</td> |
| <td class="function_name"><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GDebugKey" title="struct GDebugKey">GDebugKey</a></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.includes"></a><h2>Includes</h2> |
| <pre class="synopsis">#include <glib.h> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.description"></a><h2>Description</h2> |
| <p>These are portable utility functions.</p> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.functions_details"></a><h2>Functions</h2> |
| <div class="refsect2"> |
| <a name="g-get-application-name"></a><h3>g_get_application_name ()</h3> |
| <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> |
| <p>Gets a human-readable name for the application, as set by |
| <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 |
| possible, and is intended for display to the user. Contrast with |
| <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 |
| <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 |
| <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 |
| been called).</p> |
| <div class="refsect3"> |
| <a name="g-get-application-name.returns"></a><h4>Returns</h4> |
| <p> human-readable application name. may return <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-2.html#api-index-2.2">2.2</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-set-application-name"></a><h3>g_set_application_name ()</h3> |
| <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> |
| <p>Sets a human-readable name for the application. This name should be |
| localized if possible, and is intended for display to the user. |
| Contrast with <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. |
| <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://developer.gnome.org/gtk3/gtk3-General.html#gtk-init"><code class="function">gtk_init()</code></a>, |
| 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.</p> |
| <p>Note that for thread safety reasons, this function can only |
| be called once.</p> |
| <p>The application name will be used in contexts such as error messages, |
| or when displaying an application's name in the task list.</p> |
| <div class="refsect3"> |
| <a name="g-set-application-name.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>application_name</p></td> |
| <td class="parameter_description"><p>localized name of the application</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-2.html#api-index-2.2">2.2</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-prgname"></a><h3>g_get_prgname ()</h3> |
| <pre class="programlisting">const <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> |
| <p>Gets the name of the program. This name should not be localized, |
| in contrast to <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>.</p> |
| <p>If you are using GDK or GTK+ the program name is set in <a href="http://developer.gnome.org/gdk3/gdk3-General.html#gdk-init"><code class="function">gdk_init()</code></a>, |
| which is called by <a href="http://developer.gnome.org/gtk3/gtk3-General.html#gtk-init"><code class="function">gtk_init()</code></a>. The program name is found by taking |
| the last component of <em class="parameter"><code>argv</code></em> |
| [0].</p> |
| <div class="refsect3"> |
| <a name="g-get-prgname.returns"></a><h4>Returns</h4> |
| <p> the name of the program. The returned string belongs |
| to GLib and must not be modified or freed.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-set-prgname"></a><h3>g_set_prgname ()</h3> |
| <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> |
| <p>Sets the name of the program. This name should not be localized, |
| in contrast to <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>.</p> |
| <p>Note that for thread-safety reasons this function can only be called once.</p> |
| <div class="refsect3"> |
| <a name="g-set-prgname.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>prgname</p></td> |
| <td class="parameter_description"><p>the name of the program.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-environ"></a><h3>g_get_environ ()</h3> |
| <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> |
| <p>Gets the list of environment variables for the current process.</p> |
| <p>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 |
| form 'NAME=VALUE'.</p> |
| <p>This is equivalent to direct access to the 'environ' global variable, |
| except portable.</p> |
| <p>The return value is freshly allocated and it should be freed with |
| <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.</p> |
| <div class="refsect3"> |
| <a name="g-get-environ.returns"></a><h4>Returns</h4> |
| <p> the list of |
| environment variables. </p> |
| <p><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></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-28.html#api-index-2.28">2.28</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-environ-getenv"></a><h3>g_environ_getenv ()</h3> |
| <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>, |
| <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> |
| <p>Returns the value of the environment variable <em class="parameter"><code>variable</code></em> |
| in the |
| provided list <em class="parameter"><code>envp</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-environ-getenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>envp</p></td> |
| <td class="parameter_description"><p> an environment |
| 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>), or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> |
| for an empty environment list. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<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></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to get</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-environ-getenv.returns"></a><h4>Returns</h4> |
| <p> 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 |
| the environment variable is not set in <em class="parameter"><code>envp</code></em> |
| . The returned |
| string is owned by <em class="parameter"><code>envp</code></em> |
| , and will be freed if <em class="parameter"><code>variable</code></em> |
| is |
| set or unset again.</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-32.html#api-index-2.32">2.32</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-environ-setenv"></a><h3>g_environ_setenv ()</h3> |
| <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>, |
| <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>, |
| <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>, |
| <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> |
| <p>Sets the environment variable <em class="parameter"><code>variable</code></em> |
| in the provided list |
| <em class="parameter"><code>envp</code></em> |
| to <em class="parameter"><code>value</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-environ-setenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>envp</p></td> |
| <td class="parameter_description"><p> an |
| environment 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>), or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for an empty |
| environment list. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<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></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to set, must not contain '='</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>value</p></td> |
| <td class="parameter_description"><p>the value for to set the variable to</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>overwrite</p></td> |
| <td class="parameter_description"><p>whether to change the variable if it already exists</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-environ-setenv.returns"></a><h4>Returns</h4> |
| <p> the |
| 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>. </p> |
| <p><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></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-32.html#api-index-2.32">2.32</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-environ-unsetenv"></a><h3>g_environ_unsetenv ()</h3> |
| <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>, |
| <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> |
| <p>Removes the environment variable <em class="parameter"><code>variable</code></em> |
| from the provided |
| environment <em class="parameter"><code>envp</code></em> |
| .</p> |
| <div class="refsect3"> |
| <a name="g-environ-unsetenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>envp</p></td> |
| <td class="parameter_description"><p> an environment |
| 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>), |
| or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for an empty environment list. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<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></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to remove, must not contain '='</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-environ-unsetenv.returns"></a><h4>Returns</h4> |
| <p> the |
| 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>. </p> |
| <p><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></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-32.html#api-index-2.32">2.32</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-getenv"></a><h3>g_getenv ()</h3> |
| <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> |
| <p>Returns the value of an environment variable.</p> |
| <p>On UNIX, the name and value are byte strings which might or might not |
| be in some consistent character set and encoding. On Windows, they are |
| in UTF-8. |
| On Windows, in case the environment variable's value contains |
| references to other environment variables, they are expanded.</p> |
| <div class="refsect3"> |
| <a name="g-getenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to get</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-getenv.returns"></a><h4>Returns</h4> |
| <p> 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 |
| the environment variable is not found. The returned string |
| 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> |
| or <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()"><code class="function">g_unsetenv()</code></a>.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-setenv"></a><h3>g_setenv ()</h3> |
| <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>, |
| <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>, |
| <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> |
| <p>Sets an environment variable. On UNIX, both the variable's name and |
| value can be arbitrary byte strings, except that the variable's name |
| cannot contain '='. On Windows, they should be in UTF-8.</p> |
| <p>Note that on some systems, when variables are overwritten, the memory |
| used for the previous variables and its value isn't reclaimed.</p> |
| <p>You should be mindful of the fact that environment variable handling |
| in UNIX is not thread-safe, and your program may crash if one thread |
| calls <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-setenv" title="g_setenv ()"><code class="function">g_setenv()</code></a> while another thread is calling <code class="function">getenv()</code>. (And note |
| that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) |
| This function is only safe to use at the very start of your program, |
| before creating any other threads (or creating objects that create |
| worker threads of their own).</p> |
| <p>If you need to set up the environment for a child process, you can |
| 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 |
| <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 |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-setenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to set, must not contain '='.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>value</p></td> |
| <td class="parameter_description"><p>the value for to set the variable to.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>overwrite</p></td> |
| <td class="parameter_description"><p>whether to change the variable if it already exists.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-setenv.returns"></a><h4>Returns</h4> |
| <p> <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.</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-4.html#api-index-2.4">2.4</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-unsetenv"></a><h3>g_unsetenv ()</h3> |
| <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> |
| <p>Removes an environment variable from the environment.</p> |
| <p>Note that on some systems, when variables are overwritten, the |
| memory used for the previous variables and its value isn't reclaimed.</p> |
| <p>You should be mindful of the fact that environment variable handling |
| in UNIX is not thread-safe, and your program may crash if one thread |
| calls <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-unsetenv" title="g_unsetenv ()"><code class="function">g_unsetenv()</code></a> while another thread is calling <code class="function">getenv()</code>. (And note |
| that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) This |
| function is only safe to use at the very start of your program, before |
| creating any other threads (or creating objects that create worker |
| threads of their own).</p> |
| <p>If you need to set up the environment for a child process, you can |
| 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 |
| <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 |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-unsetenv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>variable</p></td> |
| <td class="parameter_description"><p>the environment variable to remove, must not contain '='</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-4.html#api-index-2.4">2.4</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-listenv"></a><h3>g_listenv ()</h3> |
| <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> |
| <p>Gets the names of all variables set in the environment.</p> |
| <p>Programs that want to be portable to Windows should typically use |
| 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 |
| from the C library directly. On Windows, the strings in the environ |
| array are in system codepage encoding, while in most of the typical |
| use cases for environment variables in GLib-using programs you want |
| the UTF-8 encoding that this function and <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-getenv" title="g_getenv ()"><code class="function">g_getenv()</code></a> provide.</p> |
| <div class="refsect3"> |
| <a name="g-listenv.returns"></a><h4>Returns</h4> |
| <p> a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated |
| 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>. </p> |
| <p><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></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-name"></a><h3>g_get_user_name ()</h3> |
| <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> |
| <p>Gets the user name of the current user. The encoding of the returned |
| string is system-defined. On UNIX, it might be the preferred file name |
| encoding, or something else, and there is no guarantee that it is even |
| consistent on a machine. On Windows, it is always UTF-8.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-name.returns"></a><h4>Returns</h4> |
| <p> the user name of the current user. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-real-name"></a><h3>g_get_real_name ()</h3> |
| <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> |
| <p>Gets the real name of the user. This usually comes from the user's |
| entry in the <code class="literal">passwd</code> file. The encoding of the returned string is |
| system-defined. (On Windows, it is, however, always UTF-8.) If the |
| real user name cannot be determined, the string "Unknown" is |
| returned.</p> |
| <div class="refsect3"> |
| <a name="g-get-real-name.returns"></a><h4>Returns</h4> |
| <p> the user's real name. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-cache-dir"></a><h3>g_get_user_cache_dir ()</h3> |
| <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> |
| <p>Returns a base directory in which to store non-essential, cached |
| data specific to particular user.</p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a>. |
| In this case the directory retrieved will be XDG_CACHE_HOME.</p> |
| <p>On Windows is the directory that serves as a common repository for |
| temporary Internet files. A typical path is |
| C:\Documents and Settings\username\Local Settings\Temporary Internet Files. |
| See documentation for CSIDL_INTERNET_CACHE.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-cache-dir.returns"></a><h4>Returns</h4> |
| <p> a string owned by GLib that must not be modified |
| or freed. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-6.html#api-index-2.6">2.6</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-data-dir"></a><h3>g_get_user_data_dir ()</h3> |
| <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> |
| <p>Returns a base directory in which to access application data such |
| as icons that is customized for a particular user. </p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a>. |
| In this case the directory retrieved will be <code class="literal">XDG_DATA_HOME</code>.</p> |
| <p>On Windows this is the folder to use for local (as opposed to |
| roaming) application data. See documentation for |
| CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-data-dir.returns"></a><h4>Returns</h4> |
| <p> a string owned by GLib that must not be modified |
| or freed. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-6.html#api-index-2.6">2.6</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-config-dir"></a><h3>g_get_user_config_dir ()</h3> |
| <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> |
| <p>Returns a base directory in which to store user-specific application |
| configuration information such as user preferences and settings. </p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a>. |
| In this case the directory retrieved will be <code class="literal">XDG_CONFIG_HOME</code>.</p> |
| <p>On Windows this is the folder to use for local (as opposed to |
| roaming) application data. See documentation for |
| CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-config-dir.returns"></a><h4>Returns</h4> |
| <p> a string owned by GLib that must not be modified |
| or freed. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-6.html#api-index-2.6">2.6</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-runtime-dir"></a><h3>g_get_user_runtime_dir ()</h3> |
| <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> |
| <p>Returns a directory that is unique to the current user on the local |
| system.</p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a>. |
| This is the directory |
| specified in the <code class="literal">XDG_RUNTIME_DIR</code> environment variable. |
| In the case that this variable is not set, we 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>, after verifying that it exists.</p> |
| <p>On Windows this is the folder to use for local (as opposed to |
| roaming) application data. See documentation for |
| CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-runtime-dir.returns"></a><h4>Returns</h4> |
| <p> a string owned by GLib that must not be |
| modified or freed. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-28.html#api-index-2.28">2.28</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-user-special-dir"></a><h3>g_get_user_special_dir ()</h3> |
| <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> |
| <p>Returns the full path of a special directory using its logical id.</p> |
| <p>On UNIX this is done using the XDG special user directories. |
| 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> |
| falls back to <code class="literal">$HOME/Desktop</code> when XDG special user directories have |
| not been set up. </p> |
| <p>Depending on the platform, the user might be able to change the path |
| of the special directory without requiring the session to restart; GLib |
| will not reflect any change once the special directories are loaded.</p> |
| <div class="refsect3"> |
| <a name="g-get-user-special-dir.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>directory</p></td> |
| <td class="parameter_description"><p>the logical id of special directory</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-get-user-special-dir.returns"></a><h4>Returns</h4> |
| <p> 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> if the logical id was not found. The returned string is owned by |
| GLib and should not be modified or freed. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-14.html#api-index-2.14">2.14</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-system-data-dirs"></a><h3>g_get_system_data_dirs ()</h3> |
| <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> |
| <p>Returns an ordered list of base directories in which to access |
| system-wide application data.</p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a> |
| In this case the list of directories retrieved will be XDG_DATA_DIRS.</p> |
| <p>On Windows the first elements in the list are the Application Data |
| and Documents folders for All Users. (These can be determined only |
| on Windows 2000 or later and are not present in the list on other |
| Windows versions.) See documentation for CSIDL_COMMON_APPDATA and |
| CSIDL_COMMON_DOCUMENTS.</p> |
| <p>Then follows the "share" subfolder in the installation folder for |
| the package containing the DLL that calls this function, if it can |
| be determined.</p> |
| <p>Finally the list contains the "share" subfolder in the installation |
| folder for GLib, and in the installation folder for the package the |
| application's .exe file belongs to.</p> |
| <p>The installation folders above are determined by looking up the |
| folder where the module (DLL or EXE) in question is located. If the |
| folder's name is "bin", its parent is used, otherwise the folder |
| itself.</p> |
| <p>Note that on Windows the returned list can vary depending on where |
| this function is called.</p> |
| <div class="refsect3"> |
| <a name="g-get-system-data-dirs.returns"></a><h4>Returns</h4> |
| <p> 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 not be |
| modified or freed. </p> |
| <p><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> filename][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-6.html#api-index-2.6">2.6</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-system-config-dirs"></a><h3>g_get_system_config_dirs ()</h3> |
| <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> |
| <p>Returns an ordered list of base directories in which to access |
| system-wide configuration information.</p> |
| <p>On UNIX platforms this is determined using the mechanisms described |
| in the |
| <a class="ulink" href="http://www.freedesktop.org/Standards/basedir-spec" target="_top">XDG Base Directory Specification</a>. |
| In this case the list of directories retrieved will be <code class="literal">XDG_CONFIG_DIRS</code>.</p> |
| <p>On Windows is the directory that contains application data for all users. |
| A typical path is C:\Documents and Settings\All Users\Application Data. |
| This folder is used for application data that is not user specific. |
| For example, an application can store a spell-check dictionary, a database |
| of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. |
| This information will not roam and is available to anyone using the computer.</p> |
| <div class="refsect3"> |
| <a name="g-get-system-config-dirs.returns"></a><h4>Returns</h4> |
| <p> 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 not be |
| modified or freed. </p> |
| <p><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> filename][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-6.html#api-index-2.6">2.6</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-reload-user-special-dirs-cache"></a><h3>g_reload_user_special_dirs_cache ()</h3> |
| <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> |
| <p>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 |
| that the latest on-disk version is used. Call this only |
| if you just changed the data on disk yourself.</p> |
| <p>Due to threadsafety issues this may cause leaking of strings |
| 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> |
| that can't be freed. We ensure to only leak the data for |
| the directories that actually changed value though.</p> |
| <p class="since">Since: <a class="link" href="api-index-2-22.html#api-index-2.22">2.22</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-host-name"></a><h3>g_get_host_name ()</h3> |
| <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> |
| <p>Return a name for the machine. </p> |
| <p>The returned name is not necessarily a fully-qualified domain name, |
| or even present in DNS or some other name service at all. It need |
| not even be unique on your local network or site, but usually it |
| is. Callers should not rely on the return value having any specific |
| properties like uniqueness for security purposes. Even if the name |
| of the machine is changed while an application is running, the |
| return value from this function does not change. The returned |
| string is owned by GLib and should not be modified or freed. If no |
| name can be determined, a default fixed string "localhost" is |
| returned.</p> |
| <div class="refsect3"> |
| <a name="g-get-host-name.returns"></a><h4>Returns</h4> |
| <p> the host name of the machine.</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-home-dir"></a><h3>g_get_home_dir ()</h3> |
| <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> |
| <p>Gets the current user's home directory.</p> |
| <p>As with most UNIX tools, this function will return the value of the |
| <code class="literal">HOME</code> environment variable if it is set to an existing absolute path |
| name, falling back to the <code class="literal">passwd</code> file in the case that it is unset.</p> |
| <p>If the path given in <code class="literal">HOME</code> is non-absolute, does not exist, or is |
| not a directory, the result is undefined.</p> |
| <p>Before version 2.36 this function would ignore the <code class="literal">HOME</code> environment |
| variable, taking the value from the <code class="literal">passwd</code> database instead. This was |
| changed to increase the compatibility of GLib with other programs (and |
| the XDG basedir specification) and to increase testability of programs |
| based on GLib (by making it easier to run them from test frameworks).</p> |
| <p>If your program has a strong requirement for either the new or the |
| old behaviour (and if you don't wish to increase your GLib |
| dependency to ensure that the new behaviour is in effect) then you |
| should either directly check the <code class="literal">HOME</code> environment variable yourself |
| or unset it before calling any functions in GLib.</p> |
| <div class="refsect3"> |
| <a name="g-get-home-dir.returns"></a><h4>Returns</h4> |
| <p> the current user's home directory. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-tmp-dir"></a><h3>g_get_tmp_dir ()</h3> |
| <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> |
| <p>Gets the directory to use for temporary files.</p> |
| <p>On UNIX, this is taken from the <code class="literal">TMPDIR</code> environment variable. |
| If the variable is not set, <code class="literal">P_tmpdir</code> is |
| used, as defined by the system C library. Failing that, a |
| hard-coded default of "/tmp" is returned.</p> |
| <p>On Windows, the <code class="literal">TEMP</code> environment variable is used, with the |
| root directory of the Windows installation (eg: "C:\") used |
| as a default.</p> |
| <p>The encoding of the returned string is system-defined. On Windows, |
| 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.</p> |
| <div class="refsect3"> |
| <a name="g-get-tmp-dir.returns"></a><h4>Returns</h4> |
| <p> the directory to use for temporary files. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-get-current-dir"></a><h3>g_get_current_dir ()</h3> |
| <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> |
| <p>Gets the current directory.</p> |
| <p>The returned string should be freed when no longer needed. |
| The encoding of the returned string is system defined. |
| On Windows, it is always UTF-8.</p> |
| <p>Since GLib 2.40, this function will return the value of the "PWD" |
| environment variable if it is set and it happens to be the same as |
| the current directory. This can make a difference in the case that |
| the current directory is the target of a symbolic link.</p> |
| <div class="refsect3"> |
| <a name="g-get-current-dir.returns"></a><h4>Returns</h4> |
| <p> the current directory. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-basename"></a><h3>g_basename ()</h3> |
| <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> |
| <div class="warning"> |
| <p><code class="literal">g_basename</code> has been deprecated since version 2.2 and should not be used in newly-written code.</p> |
| <p>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 |
| 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 |
| returned string, unlike this function which returns a pointer |
| into the argument.</p> |
| </div> |
| <p>Gets the name of the file without any leading directory |
| components. It returns a pointer into the given file name |
| string.</p> |
| <div class="refsect3"> |
| <a name="g-basename.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> the name of the file. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-basename.returns"></a><h4>Returns</h4> |
| <p> the name of the file without any leading |
| directory components. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-path-is-absolute"></a><h3>g_path_is_absolute ()</h3> |
| <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> |
| <p>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. |
| Note that this is a somewhat vague concept on Windows.</p> |
| <p>On POSIX systems, an absolute file name is well-defined. It always |
| starts from the single root directory. For example "/usr/local".</p> |
| <p>On Windows, the concepts of current drive and drive-specific |
| current directory introduce vagueness. This function interprets as |
| an absolute file name one that either begins with a directory |
| separator such as "\Users\tml" or begins with the root on a drive, |
| for example "C:\Windows". The first case also includes UNC paths |
| such as "\myserver\docs\foo". In all cases, either slashes or |
| backslashes are accepted.</p> |
| <p>Note that a file name relative to the current drive root does not |
| truly specify a file uniquely over time and across processes, as |
| the current drive is a per-process value and can be changed.</p> |
| <p>File names relative the current directory on some specific drive, |
| such as "D:foo/bar", are not interpreted as absolute by this |
| function, but they obviously are not relative to the normal current |
| directory as returned by <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> |
| either. Such paths should be avoided, or need to be handled using |
| Windows-specific code.</p> |
| <div class="refsect3"> |
| <a name="g-path-is-absolute.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> a file name. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-path-is-absolute.returns"></a><h4>Returns</h4> |
| <p> <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</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-path-skip-root"></a><h3>g_path_skip_root ()</h3> |
| <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> |
| <p>Returns a pointer into <em class="parameter"><code>file_name</code></em> |
| after the root component, |
| i.e. after the "/" in UNIX or "C:\" under Windows. If <em class="parameter"><code>file_name</code></em> |
| |
| 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>.</p> |
| <div class="refsect3"> |
| <a name="g-path-skip-root.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> a file name. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-path-skip-root.returns"></a><h4>Returns</h4> |
| <p> a pointer into <em class="parameter"><code>file_name</code></em> |
| after the |
| root component. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-path-get-basename"></a><h3>g_path_get_basename ()</h3> |
| <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> |
| <p>Gets the last component of the filename.</p> |
| <p>If <em class="parameter"><code>file_name</code></em> |
| ends with a directory separator it gets the component |
| before the last slash. If <em class="parameter"><code>file_name</code></em> |
| consists only of directory |
| separators (and on Windows, possibly a drive letter), a single |
| separator is returned. If <em class="parameter"><code>file_name</code></em> |
| is empty, it gets ".".</p> |
| <div class="refsect3"> |
| <a name="g-path-get-basename.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> the name of the file. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-path-get-basename.returns"></a><h4>Returns</h4> |
| <p> a newly allocated string containing the last |
| component of the filename. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-path-get-dirname"></a><h3>g_path_get_dirname ()</h3> |
| <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> |
| <p>Gets the directory components of a file name.</p> |
| <p>If the file name has no directory components "." is returned. |
| The returned string should be freed when no longer needed.</p> |
| <div class="refsect3"> |
| <a name="g-path-get-dirname.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> the name of the file. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-path-get-dirname.returns"></a><h4>Returns</h4> |
| <p> the directory components of the file. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-build-filename"></a><h3>g_build_filename ()</h3> |
| <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>, |
| <em class="parameter"><code>...</code></em>);</pre> |
| <p>Creates a filename from a series of elements using the correct |
| separator for filenames.</p> |
| <p>On Unix, this function behaves identically to <code class="literal">g_build_path |
| (G_DIR_SEPARATOR_S, first_element, ....)</code>.</p> |
| <p>On Windows, it takes into account that either the backslash |
| (<code class="literal">\</code> or slash (<code class="literal">/</code>) can be used as separator in filenames, but |
| otherwise behaves as on UNIX. When file pathname separators need |
| to be inserted, the one that last previously occurred in the |
| parameters (reading from left to right) is used.</p> |
| <p>No attempt is made to force the resulting filename to be an absolute |
| path. If the first element is a relative path, the result will |
| be a relative path.</p> |
| <div class="refsect3"> |
| <a name="g-build-filename.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>first_element</p></td> |
| <td class="parameter_description"><p> the first element in the path. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>...</p></td> |
| <td class="parameter_description"><p>remaining elements in path, terminated by <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-build-filename.returns"></a><h4>Returns</h4> |
| <p> 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>. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-build-filenamev"></a><h3>g_build_filenamev ()</h3> |
| <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> |
| <p>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 |
| as a string array, instead of varargs. This function is mainly |
| meant for language bindings.</p> |
| <div class="refsect3"> |
| <a name="g-build-filenamev.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>args</p></td> |
| <td class="parameter_description"><p> <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. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-build-filenamev.returns"></a><h4>Returns</h4> |
| <p> 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>. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-build-path"></a><h3>g_build_path ()</h3> |
| <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>, |
| <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>, |
| <em class="parameter"><code>...</code></em>);</pre> |
| <p>Creates a path from a series of elements using <em class="parameter"><code>separator</code></em> |
| as the |
| separator between elements. At the boundary between two elements, |
| any trailing occurrences of separator in the first element, or |
| leading occurrences of separator in the second element are removed |
| and exactly one copy of the separator is inserted.</p> |
| <p>Empty elements are ignored.</p> |
| <p>The number of leading copies of the separator on the result is |
| the same as the number of leading copies of the separator on |
| the first non-empty element.</p> |
| <p>The number of trailing copies of the separator on the result is |
| the same as the number of trailing copies of the separator on |
| the last non-empty element. (Determination of the number of |
| trailing copies is done without stripping leading copies, so |
| if the separator is <code class="literal">ABA</code>, then <code class="literal">ABABA</code> has 1 trailing copy.)</p> |
| <p>However, if there is only a single non-empty element, and there |
| are no characters in that element not part of the leading or |
| trailing separators, then the result is exactly the original value |
| of that element.</p> |
| <p>Other than for determination of the number of leading and trailing |
| copies of the separator, elements consisting only of copies |
| of the separator are ignored.</p> |
| <div class="refsect3"> |
| <a name="g-build-path.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>separator</p></td> |
| <td class="parameter_description"><p> a string used to separator the elements of the path. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>first_element</p></td> |
| <td class="parameter_description"><p> the first element in the path. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>...</p></td> |
| <td class="parameter_description"><p>remaining elements in path, terminated by <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-build-path.returns"></a><h4>Returns</h4> |
| <p> 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>. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-build-pathv"></a><h3>g_build_pathv ()</h3> |
| <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>, |
| <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> |
| <p>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 |
| as a string array, instead of varargs. This function is mainly |
| meant for language bindings.</p> |
| <div class="refsect3"> |
| <a name="g-build-pathv.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>separator</p></td> |
| <td class="parameter_description"><p>a string used to separator the elements of the path.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>args</p></td> |
| <td class="parameter_description"><p> <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. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> zero-terminated=1][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> filename]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-build-pathv.returns"></a><h4>Returns</h4> |
| <p> 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>. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-format-size"></a><h3>g_format_size ()</h3> |
| <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> |
| <p>Formats a size (for example the size of a file) into a human readable |
| string. Sizes are rounded to the nearest size prefix (kB, MB, GB) |
| and are displayed rounded to the nearest tenth. E.g. the file size |
| 3292528 bytes will be converted into the string "3.2 MB".</p> |
| <p>The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).</p> |
| <p>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.</p> |
| <p>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 |
| formatted.</p> |
| <div class="refsect3"> |
| <a name="g-format-size.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>size</p></td> |
| <td class="parameter_description"><p>a size in bytes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-format-size.returns"></a><h4>Returns</h4> |
| <p> a newly-allocated formatted string containing a human readable |
| file size</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-30.html#api-index-2.30">2.30</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-format-size-full"></a><h3>g_format_size_full ()</h3> |
| <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>, |
| <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> |
| <p>Formats a size.</p> |
| <p>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 |
| that modify the output. See <a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a>.</p> |
| <div class="refsect3"> |
| <a name="g-format-size-full.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>size</p></td> |
| <td class="parameter_description"><p>a size in bytes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>flags</p></td> |
| <td class="parameter_description"><p><a class="link" href="glib-Miscellaneous-Utility-Functions.html#GFormatSizeFlags" title="enum GFormatSizeFlags"><span class="type">GFormatSizeFlags</span></a> to modify the output</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-format-size-full.returns"></a><h4>Returns</h4> |
| <p> a newly-allocated formatted string containing a human |
| readable file size</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-30.html#api-index-2.30">2.30</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-format-size-for-display"></a><h3>g_format_size_for_display ()</h3> |
| <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> |
| <div class="warning"> |
| <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.</p> |
| <p>This function is broken due to its use of SI |
| 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> |
| </div> |
| <p>Formats a size (for example the size of a file) into a human |
| readable string. Sizes are rounded to the nearest size prefix |
| (KB, MB, GB) and are displayed rounded to the nearest tenth. |
| E.g. the file size 3292528 bytes will be converted into the |
| string "3.1 MB".</p> |
| <p>The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).</p> |
| <p>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.</p> |
| <div class="refsect3"> |
| <a name="g-format-size-for-display.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>size</p></td> |
| <td class="parameter_description"><p>a size in bytes</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-format-size-for-display.returns"></a><h4>Returns</h4> |
| <p> a newly-allocated formatted string containing a human |
| readable file size</p> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-16.html#api-index-2.16">2.16</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-find-program-in-path"></a><h3>g_find_program_in_path ()</h3> |
| <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> |
| <p>Locates the first executable named <em class="parameter"><code>program</code></em> |
| in the user's path, in the |
| same way that <code class="function">execvp()</code> would locate it. Returns an allocated string |
| 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 |
| the path. If <em class="parameter"><code>program</code></em> |
| is already an absolute path, returns a copy of |
| <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.</p> |
| <p>On Windows, if <em class="parameter"><code>program</code></em> |
| does not have a file type suffix, tries |
| with the suffixes .exe, .cmd, .bat and .com, and the suffixes in |
| the <code class="literal">PATHEXT</code> environment variable. </p> |
| <p>On Windows, it looks for the file in the same way as <code class="function">CreateProcess()</code> |
| would. This means first in the directory where the executing |
| program was loaded from, then in the current directory, then in the |
| Windows 32-bit system directory, then in the Windows directory, and |
| finally in the directories in the <code class="literal">PATH</code> environment variable. If |
| the program is found, the return value contains the full name |
| including the type suffix.</p> |
| <div class="refsect3"> |
| <a name="g-find-program-in-path.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>program</p></td> |
| <td class="parameter_description"><p> a program name in the GLib file name encoding. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-find-program-in-path.returns"></a><h4>Returns</h4> |
| <p> a newly-allocated string with the absolute path, |
| or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-bit-nth-lsf"></a><h3>g_bit_nth_lsf()</h3> |
| <pre class="programlisting">#define g_bit_nth_lsf(mask, nth_bit)</pre> |
| <p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em> |
| , searching |
| from (but not including) <em class="parameter"><code>nth_bit</code></em> |
| upwards. Bits are numbered |
| 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, |
| usually). To start searching from the 0th bit, set <em class="parameter"><code>nth_bit</code></em> |
| to -1.</p> |
| <div class="refsect3"> |
| <a name="g-bit-nth-lsf.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>mask</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> containing flags</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>nth_bit</p></td> |
| <td class="parameter_description"><p>the index of the bit to start the search from</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-bit-nth-lsf.returns"></a><h4>Returns</h4> |
| <p> the index of the first bit set which is higher than <em class="parameter"><code>nth_bit</code></em> |
| , or -1 |
| if no higher bits are set</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-bit-nth-msf"></a><h3>g_bit_nth_msf()</h3> |
| <pre class="programlisting">#define g_bit_nth_msf(mask, nth_bit)</pre> |
| <p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em> |
| , searching |
| from (but not including) <em class="parameter"><code>nth_bit</code></em> |
| downwards. Bits are numbered |
| 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, |
| usually). To start searching from the last bit, set <em class="parameter"><code>nth_bit</code></em> |
| to |
| -1 or GLIB_SIZEOF_LONG * 8.</p> |
| <div class="refsect3"> |
| <a name="g-bit-nth-msf.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>mask</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Basic-Types.html#gulong" title="gulong"><span class="type">gulong</span></a> containing flags</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>nth_bit</p></td> |
| <td class="parameter_description"><p>the index of the bit to start the search from</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-bit-nth-msf.returns"></a><h4>Returns</h4> |
| <p> the index of the first bit set which is lower than <em class="parameter"><code>nth_bit</code></em> |
| , or -1 |
| if no lower bits are set</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-bit-storage"></a><h3>g_bit_storage()</h3> |
| <pre class="programlisting">#define g_bit_storage(number)</pre> |
| <p>Gets the number of bits used to hold <em class="parameter"><code>number</code></em> |
| , |
| e.g. if <em class="parameter"><code>number</code></em> |
| is 4, 3 bits are needed.</p> |
| <div class="refsect3"> |
| <a name="g-bit-storage.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>number</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Basic-Types.html#guint" title="guint ()"><span class="type">guint</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-bit-storage.returns"></a><h4>Returns</h4> |
| <p> the number of bits used to hold <em class="parameter"><code>number</code></em> |
| </p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-spaced-primes-closest"></a><h3>g_spaced_primes_closest ()</h3> |
| <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> |
| <p>Gets the smallest prime number from a built-in array of primes which |
| is larger than <em class="parameter"><code>num</code></em> |
| . This is used within GLib to calculate the optimum |
| size of a <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a>.</p> |
| <p>The built-in array of primes ranges from 11 to 13845163 such that |
| each prime is approximately 1.5-2 times the previous prime.</p> |
| <div class="refsect3"> |
| <a name="g-spaced-primes-closest.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>num</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Basic-Types.html#guint" title="guint ()"><span class="type">guint</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-spaced-primes-closest.returns"></a><h4>Returns</h4> |
| <p> the smallest prime number from a built-in array of primes |
| which is larger than <em class="parameter"><code>num</code></em> |
| </p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-atexit"></a><h3>g_atexit ()</h3> |
| <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> |
| <div class="warning"> |
| <p><code class="literal">g_atexit</code> has been deprecated since version 2.32 and should not be used in newly-written code.</p> |
| <p>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> |
| </div> |
| <p>Specifies a function to be called at normal program termination.</p> |
| <p>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 |
| macro that maps to a call to the <code class="function">atexit()</code> function in the C |
| 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>, |
| i.e. <code class="function">atexit()</code>, is in a DLL, the function will be called when the |
| DLL is detached from the program. This typically makes more sense |
| than that the function is called when the GLib DLL is detached, |
| which happened earlier when <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 |
| DLL.</p> |
| <p>The behaviour of <code class="function">atexit()</code> in the context of dynamically loaded |
| modules is not formally specified and varies wildly.</p> |
| <p>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 |
| loaded module which is unloaded before the program terminates might |
| well cause a crash at program exit.</p> |
| <p>Some POSIX systems implement <code class="function">atexit()</code> like Windows, and have each |
| dynamically loaded module maintain an own atexit chain that is |
| called when the module is unloaded.</p> |
| <p>On other POSIX systems, before a dynamically loaded module is |
| unloaded, the registered atexit functions (if any) residing in that |
| module are called, regardless where the code that registered them |
| resided. This is presumably the most robust approach.</p> |
| <p>As can be seen from the above, for portability it's best to avoid |
| 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 |
| program.</p> |
| <div class="refsect3"> |
| <a name="g-atexit.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>func</p></td> |
| <td class="parameter_description"><p> the function to call on normal program termination. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-parse-debug-string"></a><h3>g_parse_debug_string ()</h3> |
| <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>, |
| <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>, |
| <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> |
| <p>Parses a string containing debugging options |
| 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 |
| within GDK and GTK+ to parse the debug options passed on the |
| command line or through environment variables.</p> |
| <p>If <em class="parameter"><code>string</code></em> |
| is equal to "all", all flags are set. Any flags |
| specified along with "all" in <em class="parameter"><code>string</code></em> |
| are inverted; thus, |
| "all,foo,bar" or "foo,bar,all" sets all flags except those |
| corresponding to "foo" and "bar".</p> |
| <p>If <em class="parameter"><code>string</code></em> |
| is equal to "help", all the available keys in <em class="parameter"><code>keys</code></em> |
| |
| are printed out to standard error.</p> |
| <div class="refsect3"> |
| <a name="g-parse-debug-string.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>string</p></td> |
| <td class="parameter_description"><p> a list of debug options separated by colons, spaces, or |
| commas, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>keys</p></td> |
| <td class="parameter_description"><p> 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 |
| strings with bit flags. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=nkeys]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>nkeys</p></td> |
| <td class="parameter_description"><p>the number of <a href="glib-Miscellaneous-Utility-Functions.html#GDebugKey"><span class="type">GDebugKeys</span></a> in the array.</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-parse-debug-string.returns"></a><h4>Returns</h4> |
| <p> the combined set of bit flags.</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GVoidFunc"></a><h3>GVoidFunc ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| <span class="c_punctuation">(</span>*GVoidFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <div class="warning"><p><code class="literal">GVoidFunc</code> is deprecated and should not be used in newly-written code.</p></div> |
| <p>Declares a type of function which takes no arguments |
| and has no return value. It is used to specify the type |
| function passed to <a class="link" href="glib-Miscellaneous-Utility-Functions.html#g-atexit" title="g_atexit ()"><code class="function">g_atexit()</code></a>.</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GFreeFunc"></a><h3>GFreeFunc ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| <span class="c_punctuation">(</span>*GFreeFunc<span class="c_punctuation">)</span> (<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> |
| <p>Declares a type of function which takes an arbitrary |
| data pointer argument and has no return value. It is |
| not currently used in GLib or GTK+.</p> |
| <div class="refsect3"> |
| <a name="GFreeFunc.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>data</p></td> |
| <td class="parameter_description"><p>a data pointer</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-qsort-with-data"></a><h3>g_qsort_with_data ()</h3> |
| <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>, |
| <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>, |
| <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> size</code></em>, |
| <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>, |
| <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> |
| <p>This is just like the standard C <code class="function">qsort()</code> function, but |
| the comparison routine accepts a user data argument.</p> |
| <p>This is guaranteed to be a stable sort since version 2.32.</p> |
| <div class="refsect3"> |
| <a name="g-qsort-with-data.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>pbase</p></td> |
| <td class="parameter_description"><p> start of array to sort. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>total_elems</p></td> |
| <td class="parameter_description"><p>elements in the array</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>size</p></td> |
| <td class="parameter_description"><p>size of each element</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>compare_func</p></td> |
| <td class="parameter_description"><p>function to compare elements</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>user_data</p></td> |
| <td class="parameter_description"><p>data to pass to <em class="parameter"><code>compare_func</code></em> |
| </p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-nullify-pointer"></a><h3>g_nullify_pointer ()</h3> |
| <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> |
| <p>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>.</p> |
| <div class="refsect3"> |
| <a name="g-nullify-pointer.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>nullify_location</p></td> |
| <td class="parameter_description"><p> the memory address of the pointer. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Miscellaneous-Utility-Functions.other_details"></a><h2>Types and Values</h2> |
| <div class="refsect2"> |
| <a name="GUserDirectory"></a><h3>enum GUserDirectory</h3> |
| <p>These are logical ids for special directories which are defined |
| 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> |
| to retrieve the full path associated to the logical id.</p> |
| <p>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 |
| every platform has a directory for every logical id in this |
| enumeration.</p> |
| <div class="refsect3"> |
| <a name="GUserDirectory.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="enum_members_name"> |
| <col class="enum_members_description"> |
| <col width="200px" class="enum_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-DESKTOP:CAPS"></a>G_USER_DIRECTORY_DESKTOP</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Desktop directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-DOCUMENTS:CAPS"></a>G_USER_DIRECTORY_DOCUMENTS</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Documents directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-DOWNLOAD:CAPS"></a>G_USER_DIRECTORY_DOWNLOAD</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Downloads directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-MUSIC:CAPS"></a>G_USER_DIRECTORY_MUSIC</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Music directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-PICTURES:CAPS"></a>G_USER_DIRECTORY_PICTURES</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Pictures directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-PUBLIC-SHARE:CAPS"></a>G_USER_DIRECTORY_PUBLIC_SHARE</p></td> |
| <td class="enum_member_description"> |
| <p>the user's shared directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-TEMPLATES:CAPS"></a>G_USER_DIRECTORY_TEMPLATES</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Templates directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-DIRECTORY-VIDEOS:CAPS"></a>G_USER_DIRECTORY_VIDEOS</p></td> |
| <td class="enum_member_description"> |
| <p>the user's Movies directory</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-USER-N-DIRECTORIES:CAPS"></a>G_USER_N_DIRECTORIES</p></td> |
| <td class="enum_member_description"> |
| <p>the number of enum values</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p class="since">Since: <a class="link" href="api-index-2-14.html#api-index-2.14">2.14</a></p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-dirname"></a><h3>g_dirname</h3> |
| <pre class="programlisting">#define g_dirname</pre> |
| <div class="warning"> |
| <p><code class="literal">g_dirname</code> is deprecated and should not be used in newly-written code.</p> |
| <p>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> |
| </div> |
| <p>Gets the directory components of a file name.</p> |
| <p>If the file name has no directory components "." is returned. |
| The returned string should be freed when no longer needed.</p> |
| <div class="refsect3"> |
| <a name="g-dirname.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> the name of the file. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-dirname.returns"></a><h4>Returns</h4> |
| <p> the directory components of the file. </p> |
| <p><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> filename]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GFormatSizeFlags"></a><h3>enum GFormatSizeFlags</h3> |
| <p>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>.</p> |
| <div class="refsect3"> |
| <a name="GFormatSizeFlags.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="enum_members_name"> |
| <col class="enum_members_description"> |
| <col width="200px" class="enum_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-FORMAT-SIZE-DEFAULT:CAPS"></a>G_FORMAT_SIZE_DEFAULT</p></td> |
| <td class="enum_member_description"> |
| <p>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></p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-FORMAT-SIZE-LONG-FORMAT:CAPS"></a>G_FORMAT_SIZE_LONG_FORMAT</p></td> |
| <td class="enum_member_description"> |
| <p>include the exact number of bytes as part |
| of the returned string. For example, "45.6 kB (45,612 bytes)".</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-FORMAT-SIZE-IEC-UNITS:CAPS"></a>G_FORMAT_SIZE_IEC_UNITS</p></td> |
| <td class="enum_member_description"> |
| <p>use IEC (base 1024) units with "KiB"-style |
| suffixes. IEC units should only be used for reporting things with |
| a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. |
| Network and storage sizes should be reported in the normal SI units.</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GDebugKey"></a><h3>struct GDebugKey</h3> |
| <pre class="programlisting">struct GDebugKey { |
| const gchar *key; |
| guint value; |
| }; |
| </pre> |
| <p>Associates a string with a bit flag. |
| 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>.</p> |
| <div class="refsect3"> |
| <a name="GDebugKey.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="struct_members_name"> |
| <col class="struct_members_description"> |
| <col width="200px" class="struct_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="struct_member_name"><p>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>;</p></td> |
| <td class="struct_member_description"><p>the string</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="struct_member_name"><p><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>;</p></td> |
| <td class="struct_member_description"><p>the flag</p></td> |
| <td class="struct_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |