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>

<!-- ##### 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 NOT 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.


<!-- ##### FUNCTION g_set_prgname ##### -->
<para>
Sets the name of the program. This name should NOT 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.
</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. 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_home_dir ##### -->
<para>
Gets the current user's home directory.
</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.
</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.
</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: