<!-- ##### 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_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: