docs/reference/glib/tmpl/misc_utils.sgml

<!-- ##### SECTION Title ##### -->
Miscellaneous Utility Functions

<!-- ##### SECTION Short_Description ##### -->
a selection of portable utility functions.

<!-- ##### SECTION Long_Description ##### -->
<para>
These are portable utility functions.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### FUNCTION g_get_application_name ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_set_application_name ##### -->
<para>

</para>

@application_name: 


<!-- ##### FUNCTION g_get_prgname ##### -->
<para>
Gets the name of the program. This name should <emphasis>not</emphasis> be localized,
contrast with g_get_application_name().
(If you are using GDK or GTK+ the program name is set in gdk_init(), which
is called by gtk_init(). The program name is found by taking the last
component of <literal>argv[0]</literal>.)
</para>

@Returns: the name of the program. 
  The returned string belongs to GLib and must not be modified or freed.


<!-- ##### FUNCTION g_set_prgname ##### -->
<para>
Sets the name of the program. This name should <emphasis>not</emphasis> be localized, 
contrast with g_set_application_name(). Note that for thread-safety
reasons this function can only be called once.
</para>

@prgname: the name of the program.


<!-- ##### FUNCTION g_getenv ##### -->
<para>

</para>

@variable: 
@Returns: 


<!-- ##### FUNCTION g_setenv ##### -->
<para>

</para>

@variable: 
@value: 
@overwrite: 
@Returns: 


<!-- ##### FUNCTION g_unsetenv ##### -->
<para>

</para>

@variable: 


<!-- ##### FUNCTION g_get_user_name ##### -->
<para>
Gets the user name of the current user. The encoding of the returned
string is system defined. On Unix, it might be the preferred file name
encoding, or something else, and there is no guarantee that it is even
consistent on a machine. On Windows, it is always UTF-8.
</para>

@Returns: the user name of the current user.


<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
Gets the real name of the user. This usually comes from the user's entry in the
<filename>passwd</filename> file. The encoding of the returned string is system
defined. (On Windows, it is, however, always UTF-8.) If the real user name
cannot be determined, the string "Unknown" is returned.
</para>

@Returns: the user's real name.


<!-- ##### FUNCTION g_get_user_cache_dir ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_get_user_data_dir ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_get_user_config_dir ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_get_system_data_dirs ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_get_system_config_dirs ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION g_get_home_dir ##### -->
<para>
Gets the current user's home directory. 
</para>
<para>
Note that in contrast to traditional Unix tools, this function 
prefers <filename>passwd</filename> entries over the <envar>HOME</envar> 
environment variable.
</para>

@Returns: the current user's home directory.


<!-- ##### FUNCTION g_get_tmp_dir ##### -->
<para>
Gets the directory to use for temporary files.
This is found from inspecting the environment variables <envar>TMPDIR</envar>, 
<envar>TMP</envar>, and <envar>TEMP</envar>
in that order. If none of those are defined "/tmp" is returned on UNIX and 
"C:\" on Windows. The encoding of the returned string is system defined. On 
Windows, it is always UTF-8. The return value is never NULL.
</para>

@Returns: the directory to use for temporary files.


<!-- ##### FUNCTION g_get_current_dir ##### -->
<para>
Gets the current directory.
The returned string should be freed when no longer needed. The encoding of the
returned string is system defined. On Windows, it is always UTF-8.
</para>

@Returns: the current directory.


<!-- ##### FUNCTION g_basename ##### -->


@file_name: 
@Returns: 


<!-- ##### MACRO g_dirname ##### -->
<para>
This function is deprecated and will be removed in the next major
release of GLib. Use g_path_get_dirname() instead.
</para>

<para>
Gets the directory components of a file name.
If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.
</para>

@Returns: the directory components of the file.


<!-- ##### FUNCTION g_path_is_absolute ##### -->
<para>
Returns %TRUE if the given @file_name is an absolute file name,
i.e. it contains a full path from the root directory such as '/usr/local'
on UNIX or 'C:\windows' on Windows systems.
</para>

@file_name: a file name.
@Returns: %TRUE if @file_name is an absolute path.


<!-- ##### FUNCTION g_path_skip_root ##### -->
<para>
Returns a pointer into @file_name after the root component, i.e. after
the '/' in UNIX or 'C:\' under Windows. If @file_name is not an absolute
path it returns %NULL.
</para>

@file_name: a file name.
@Returns: a pointer into @file_name after the root component.


<!-- ##### FUNCTION g_path_get_basename ##### -->
<para>

</para>

@file_name: 
@Returns: 


<!-- ##### FUNCTION g_path_get_dirname ##### -->
<para>
Gets the directory components of a file name.  If the file name has no
directory components "." is returned.  The returned string should be
freed when no longer needed.
</para>

@file_name: the name of the file.
@Returns: the directory components of the file.


<!-- ##### FUNCTION g_build_filename ##### -->
<para>

</para>

@first_element: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_build_path ##### -->
<para>

</para>

@separator: 
@first_element: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_find_program_in_path ##### -->
<para>

</para>

@program: 
@Returns: 


<!-- ##### FUNCTION g_bit_nth_lsf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit upwards. Bits are numbered from 0 (least significant)
to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
0th bit, set @nth_bit to -1.
</para>

@mask: a #gulong containing flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is higher than @nth_bit.


<!-- ##### FUNCTION g_bit_nth_msf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit downwards. Bits are numbered from 0 (least significant)
to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8.
</para>

@mask: a #gulong containing flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is lower than @nth_bit.


<!-- ##### FUNCTION g_bit_storage ##### -->
<para>
Gets the number of bits used to hold @number,
e.g. if @number is 4, 3 bits are needed.
</para>

@number: a guint.
@Returns: the number of bits used to hold @number.


<!-- ##### FUNCTION g_spaced_primes_closest ##### -->
<para>
Gets the smallest prime number from a built-in array of primes which
is larger than @num. This is used within GLib to calculate the optimum
size of a #GHashTable.
</para>
<para>
The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.
</para>

@num: a #guint.
@Returns: the smallest prime number from a built-in array of primes which is
larger than @num.


<!-- ##### FUNCTION g_atexit ##### -->
<para>
Specifies a function to be called at normal program termination.
</para>

@func: the function to call on normal program termination.


<!-- ##### FUNCTION g_parse_debug_string ##### -->
<para>
Parses a string containing debugging options separated by ':' into a guint
containing bit flags.
This is used within GDK and GTK+ to parse the debug options passed on the
command line or through environment variables.
</para>

@string: a list of debug options separated by ':' or "all" to set all flags.
@keys: pointer to an array of #GDebugKey which associate strings with
bit flags.
@nkeys: the number of #GDebugKey in the array.
@Returns: the combined set of bit flags.


<!-- ##### STRUCT GDebugKey ##### -->
<para>
Associates a string with a bit flag.
Used in g_parse_debug_string().
</para>

@key: 
@value: 

<!-- ##### USER_FUNCTION GVoidFunc ##### -->
<para>
Declares a type of function which takes no arguments and has no return value.
It is used to specify the type function passed to g_atexit().
</para>



<!-- ##### USER_FUNCTION GFreeFunc ##### -->
<para>
Declares a type of function which takes an arbitrary data pointer argument
and has no return value. It is not currently used in GLib or GTK+.
</para>

@data: a data pointer.


<!-- ##### FUNCTION g_qsort_with_data ##### -->
<para>

</para>

@pbase: 
@total_elems: 
@size: 
@compare_func: 
@user_data: 


<!-- ##### FUNCTION g_nullify_pointer ##### -->
<para>

</para>

@nullify_location: