mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-28 01:56:52 +02:00
8d25dee6d5
2004-11-28 Tor Lillqvist <tml@iki.fi> * glib/tmpl/misc_utils.sgml: Document encoding of g_get_user_name(), g_get_real_name(), g_get_tmp_dir() and g_get_current_dir().
396 lines
8.5 KiB
Plaintext
396 lines
8.5 KiB
Plaintext
<!-- ##### 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. 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:
|
|
|
|
|