/src/wrappers/glib/library/utilities/glib_miscellaneous_utility_functions.e
Specman e | 789 lines | 2 code | 272 blank | 515 comment | 0 complexity | 350ba1e5a2548d736116366d3921692c MD5 | raw file
1deferred class GLIB_MISCELLANEOUS_UTILITY_FUNCTIONS 2-- Miscellaneous Utility Functions 3 4-- Miscellaneous Utility Functions -- a selection of portable utility functions. 5 6-- Synopsis 7 8 9-- #include <glib.h> 10 11 12-- const gchar* g_get_application_name (void); 13-- void g_set_application_name (const gchar *application_name); 14-- gchar* g_get_prgname (void); 15-- void g_set_prgname (const gchar *prgname); 16-- const gchar* g_getenv (const gchar *variable); 17-- gboolean g_setenv (const gchar *variable, 18-- const gchar *value, 19-- gboolean overwrite); 20-- void g_unsetenv (const gchar *variable); 21-- gchar** g_listenv (void); 22-- const gchar* g_get_user_name (void); 23-- const gchar* g_get_real_name (void); 24-- const gchar* g_get_user_cache_dir (void); 25-- const gchar* g_get_user_data_dir (void); 26-- const gchar* g_get_user_config_dir (void); 27-- const gchar* const * g_get_system_data_dirs (void); 28-- const gchar* const * g_get_system_config_dirs 29-- (void); 30 31-- const gchar* g_get_host_name (void); 32-- const gchar* g_get_home_dir (void); 33-- const gchar* g_get_tmp_dir (void); 34-- gchar* g_get_current_dir (void); 35-- const gchar* g_basename (const gchar *file_name); 36-- #define g_dirname 37-- gboolean g_path_is_absolute (const gchar *file_name); 38-- const gchar* g_path_skip_root (const gchar *file_name); 39-- gchar* g_path_get_basename (const gchar *file_name); 40-- gchar* g_path_get_dirname (const gchar *file_name); 41-- gchar* g_build_filename (const gchar *first_element, 42-- ...); 43-- gchar* g_build_filenamev (gchar **args); 44-- gchar* g_build_path (const gchar *separator, 45-- const gchar *first_element, 46-- ...); 47-- gchar* g_build_pathv (const gchar *separator, 48-- gchar **args); 49 50-- gchar* g_find_program_in_path (const gchar *program); 51 52-- gint g_bit_nth_lsf (gulong mask, 53-- gint nth_bit); 54-- gint g_bit_nth_msf (gulong mask, 55-- gint nth_bit); 56-- guint g_bit_storage (gulong number); 57 58-- guint g_spaced_primes_closest (guint num); 59 60-- void g_atexit (GVoidFunc func); 61 62-- guint g_parse_debug_string (const gchar *string, 63-- const GDebugKey *keys, 64-- guint nkeys); 65-- GDebugKey; 66 67-- void (*GVoidFunc) (void); 68-- void (*GFreeFunc) (gpointer data); 69 70-- void g_qsort_with_data (gconstpointer pbase, 71-- gint total_elems, 72-- gsize size, 73-- GCompareDataFunc compare_func, 74-- gpointer user_data); 75 76-- void g_nullify_pointer (gpointer *nullify_location); 77 78 79-- Description 80 81-- These are portable utility functions. 82 83-- Details 84 85-- g_get_application_name () 86 87-- const gchar* g_get_application_name (void); 88 89-- Gets a human-readable name for the application, as set by 90-- g_set_application_name(). This name should be localized if possible, and is 91-- intended for display to the user. Contrast with g_get_prgname(), which gets a 92-- non-localized name. If g_set_application_name() has not been called, returns the 93-- result of g_get_prgname() (which may be NULL if g_set_prgname() has also not been 94-- called). 95 96-- Returns : human-readable application name. may return NULL 97 98-- Since 2.2 99 100-- --------------------------------------------------------------------------------- 101 102-- g_set_application_name () 103 104-- void g_set_application_name (const gchar *application_name); 105 106-- Sets a human-readable name for the application. This name should be localized if 107-- possible, and is intended for display to the user. Contrast with g_set_prgname(), 108-- which sets a non-localized name. g_set_prgname() will be called automatically by 109-- gtk_init(), but g_set_application_name() will not. 110 111-- Note that for thread safety reasons, this function can only be called once. 112 113-- The application name will be used in contexts such as error messages, or when 114-- displaying an application's name in the task list. 115 116-- application_name : localized name of the application 117 118-- --------------------------------------------------------------------------------- 119 120-- g_get_prgname () 121 122-- gchar* g_get_prgname (void); 123 124-- Gets the name of the program. This name should not be localized, contrast with 125-- g_get_application_name(). (If you are using GDK or GTK+ the program name is set 126-- in gdk_init(), which is called by gtk_init(). The program name is found by taking 127-- the last component of argv[0].) 128 129-- Returns : the name of the program. The returned string belongs to GLib and must 130-- not be modified or freed. 131 132-- --------------------------------------------------------------------------------- 133 134-- g_set_prgname () 135 136-- void g_set_prgname (const gchar *prgname); 137 138-- Sets the name of the program. This name should not be localized, contrast with 139-- g_set_application_name(). Note that for thread-safety reasons this function can 140-- only be called once. 141 142-- prgname : the name of the program. 143 144-- --------------------------------------------------------------------------------- 145 146-- g_getenv () 147 148-- const gchar* g_getenv (const gchar *variable); 149 150-- Returns the value of an environment variable. The name and value are in the GLib 151-- file name encoding. On UNIX, this means the actual bytes which might or might not 152-- be in some consistent character set and encoding. On Windows, it is in UTF-8. On 153-- Windows, in case the environment variable's value contains references to other 154-- environment variables, they are expanded. 155 156-- variable : the environment variable to get, in the GLib file name encoding. 157-- Returns : the value of the environment variable, or NULL if the environment 158-- variable is not found. The returned string may be overwritten by the 159-- next call to g_getenv(), g_setenv() or g_unsetenv(). 160 161-- --------------------------------------------------------------------------------- 162 163-- g_setenv () 164 165-- gboolean g_setenv (const gchar *variable, 166-- const gchar *value, 167-- gboolean overwrite); 168 169-- Sets an environment variable. Both the variable's name and value should be in the 170-- GLib file name encoding. On UNIX, this means that they can be any sequence of 171-- bytes. On Windows, they should be in UTF-8. 172 173-- Note that on some systems, when variables are overwritten, the memory used for 174-- the previous variables and its value isn't reclaimed. 175 176-- variable : the environment variable to set, must not contain '='. 177-- value : the value for to set the variable to. 178-- overwrite : whether to change the variable if it already exists. 179-- Returns : FALSE if the environment variable couldn't be set. 180 181-- Since 2.4 182 183-- --------------------------------------------------------------------------------- 184 185-- g_unsetenv () 186 187-- void g_unsetenv (const gchar *variable); 188 189-- Removes an environment variable from the environment. 190 191-- Note that on some systems, when variables are overwritten, the memory used for 192-- the previous variables and its value isn't reclaimed. Furthermore, this function 193-- can't be guaranteed to operate in a threadsafe way. 194 195-- variable : the environment variable to remove, must not contain '='. 196 197-- Since 2.4 198 199-- --------------------------------------------------------------------------------- 200 201-- g_listenv () 202 203-- gchar** g_listenv (void); 204 205-- Gets the names of all variables set in the environment. 206 207-- Returns : a NULL-terminated list of strings which must be freed with 208-- g_strfreev(). Programs that want to be portable to Windows should 209-- typically use this function and g_getenv() instead of using the environ 210-- array from the C library directly. On Windows, the strings in the 211-- environ array are in system codepage encoding, while in most of the 212-- typical use cases for environment variables in GLib-using programs you 213-- want the UTF-8 encoding that this function and g_getenv() provide. 214 215-- Since 2.8 216 217-- --------------------------------------------------------------------------------- 218 219-- g_get_user_name () 220 221-- const gchar* g_get_user_name (void); 222 223-- Gets the user name of the current user. The encoding of the returned string is 224-- system-defined. On UNIX, it might be the preferred file name encoding, or 225-- something else, and there is no guarantee that it is even consistent on a 226-- machine. On Windows, it is always UTF-8. 227 228-- Returns : the user name of the current user. 229 230-- --------------------------------------------------------------------------------- 231 232-- g_get_real_name () 233 234-- const gchar* g_get_real_name (void); 235 236-- Gets the real name of the user. This usually comes from the user's entry in the 237-- passwd file. The encoding of the returned string is system-defined. (On Windows, 238-- it is, however, always UTF-8.) If the real user name cannot be determined, the 239-- string "Unknown" is returned. 240 241-- Returns : the user's real name. 242 243-- --------------------------------------------------------------------------------- 244 245-- g_get_user_cache_dir () 246 247-- const gchar* g_get_user_cache_dir (void); 248 249-- Returns a base directory in which to store non-essential, cached data specific to 250-- particular user. 251 252-- On UNIX platforms this is determined using the mechanisms described in the XDG 253-- Base Directory Specification 254 255-- Returns : a string owned by GLib that must not be modified or freed. 256 257-- Since 2.6 258 259-- --------------------------------------------------------------------------------- 260 261-- g_get_user_data_dir () 262 263-- const gchar* g_get_user_data_dir (void); 264 265-- Returns a base directory in which to access application data such as icons that 266-- is customized for a particular user. 267 268-- On UNIX platforms this is determined using the mechanisms described in the XDG 269-- Base Directory Specification 270 271-- Returns : a string owned by GLib that must not be modified or freed. 272 273-- Since 2.6 274 275-- --------------------------------------------------------------------------------- 276 277-- g_get_user_config_dir () 278 279-- const gchar* g_get_user_config_dir (void); 280 281-- Returns a base directory in which to store user-specific application 282-- configuration information such as user preferences and settings. 283 284-- On UNIX platforms this is determined using the mechanisms described in the XDG 285-- Base Directory Specification 286 287-- Returns : a string owned by GLib that must not be modified or freed. 288 289-- Since 2.6 290 291-- --------------------------------------------------------------------------------- 292 293-- g_get_system_data_dirs () 294 295-- const gchar* const * g_get_system_data_dirs (void); 296 297-- Returns an ordered list of base directories in which to access system-wide 298-- application data. 299 300-- On UNIX platforms this is determined using the mechanisms described in the XDG 301-- Base Directory Specification 302 303-- On Windows the first elements in the list are the Application Data and Documents 304-- folders for All Users. (These can be determined only on Windows 2000 or later and 305-- are not present in the list on other Windows versions.) See documentation for 306-- CSIDL_COMMON_APPDATA and CSIDL_COMMON_DOCUMENTS. 307 308-- Then follows the "share" subfolder in the installation folder for the package 309-- containing the DLL that calls this function, if it can be determined. 310 311-- Finally the list contains the "share" subfolder in the installation folder for 312-- GLib, and in the installation folder for the package the application's .exe file 313-- belongs to. 314 315-- The installation folders above are determined by looking up the folder where the 316-- module (DLL or EXE) in question is located. If the folder's name is "bin", its 317-- parent is used, otherwise the folder itself. 318 319-- Note that on Windows the returned list can vary depending on where this function 320-- is called. 321 322-- Returns : a NULL-terminated array of strings owned by GLib that must not be 323-- modified or freed. 324 325-- Since 2.6 326 327-- --------------------------------------------------------------------------------- 328 329-- g_get_system_config_dirs () 330 331-- const gchar* const * g_get_system_config_dirs 332-- (void); 333 334-- Returns an ordered list of base directories in which to access system-wide 335-- configuration information. 336 337-- On UNIX platforms this is determined using the mechanisms described in the XDG 338-- Base Directory Specification 339 340-- Returns : a NULL-terminated array of strings owned by GLib that must not be 341-- modified or freed. 342 343-- Since 2.6 344 345-- --------------------------------------------------------------------------------- 346 347-- g_get_host_name () 348 349-- const gchar* g_get_host_name (void); 350 351-- Return a name for the machine. 352 353-- The returned name is not necessarily a fully-qualified domain name, or even 354-- present in DNS or some other name service at all. It need not even be unique on 355-- your local network or site, but usually it is. Callers should not rely on the 356-- return value having any specific properties like uniqueness for security 357-- purposes. Even if the name of the machine is changed while an application is 358-- running, the return value from this function does not change. The returned string 359-- is owned by GLib and should not be modified or freed. If no name can be 360-- determined, a default fixed string "localhost" is returned. 361 362-- Returns : the host name of the machine. 363 364-- Since 2.8 365 366-- --------------------------------------------------------------------------------- 367 368-- g_get_home_dir () 369 370-- const gchar* g_get_home_dir (void); 371 372-- Gets the current user's home directory. 373 374-- Note that in contrast to traditional UNIX tools, this function prefers passwd 375-- entries over the HOME environment variable. 376 377-- Returns : the current user's home directory. 378 379-- --------------------------------------------------------------------------------- 380 381-- g_get_tmp_dir () 382 383-- const gchar* g_get_tmp_dir (void); 384 385-- Gets the directory to use for temporary files. This is found from inspecting the 386-- environment variables TMPDIR, TMP, and TEMP in that order. If none of those are 387-- defined "/tmp" is returned on UNIX and "C:\" on Windows. The encoding of the 388-- returned string is system-defined. On Windows, it is always UTF-8. The return 389-- value is never NULL. 390 391-- Returns : the directory to use for temporary files. 392 393-- --------------------------------------------------------------------------------- 394 395-- g_get_current_dir () 396 397-- gchar* g_get_current_dir (void); 398 399-- Gets the current directory. The returned string should be freed when no longer 400-- needed. The encoding of the returned string is system defined. On Windows, it is 401-- always UTF-8. 402 403-- Returns : the current directory. 404 405-- --------------------------------------------------------------------------------- 406 407-- g_basename () 408 409-- const gchar* g_basename (const gchar *file_name); 410 411-- Warning 412 413-- g_basename has been deprecated since version 2.2 and should not be used in 414-- newly-written code. Use g_path_get_basename() instead, but notice that 415-- g_path_get_basename() allocates new memory for the returned string, unlike this 416-- function which returns a pointer into the argument. 417 418-- Gets the name of the file without any leading directory components. It returns a 419-- pointer into the given file name string. 420 421-- file_name : the name of the file. 422-- Returns : the name of the file without any leading directory components. 423 424-- --------------------------------------------------------------------------------- 425 426-- g_dirname 427 428-- #define g_dirname 429 430-- Warning 431 432-- g_dirname is deprecated and should not be used in newly-written code. 433 434-- This function is deprecated and will be removed in the next major release of 435-- GLib. Use g_path_get_dirname() instead. 436 437-- Gets the directory components of a file name. If the file name has no directory 438-- components "." is returned. The returned string should be freed when no longer 439-- needed. 440 441-- Returns : the directory components of the file. 442 443-- --------------------------------------------------------------------------------- 444 445-- g_path_is_absolute () 446 447-- gboolean g_path_is_absolute (const gchar *file_name); 448 449-- Returns TRUE if the given file_name is an absolute file name, i.e. it contains a 450-- full path from the root directory such as "/usr/local" on UNIX or "C:\windows" on 451-- Windows systems. 452 453-- file_name : a file name. 454-- Returns : TRUE if file_name is an absolute path. 455 456-- --------------------------------------------------------------------------------- 457 458-- g_path_skip_root () 459 460-- const gchar* g_path_skip_root (const gchar *file_name); 461 462-- Returns a pointer into file_name after the root component, i.e. after the "/" in 463-- UNIX or "C:\" under Windows. If file_name is not an absolute path it returns 464-- NULL. 465 466-- file_name : a file name. 467-- Returns : a pointer into file_name after the root component. 468 469-- --------------------------------------------------------------------------------- 470 471-- g_path_get_basename () 472 473-- gchar* g_path_get_basename (const gchar *file_name); 474 475-- Gets the last component of the filename. If file_name ends with a directory 476-- separator it gets the component before the last slash. If file_name consists only 477-- of directory separators (and on Windows, possibly a drive letter), a single 478-- separator is returned. If file_name is empty, it gets ".". 479 480-- file_name : the name of the file. 481-- Returns : a newly allocated string containing the last component of the 482-- filename. 483 484-- --------------------------------------------------------------------------------- 485 486-- g_path_get_dirname () 487 488-- gchar* g_path_get_dirname (const gchar *file_name); 489 490-- Gets the directory components of a file name. If the file name has no directory 491-- components "." is returned. The returned string should be freed when no longer 492-- needed. 493 494-- file_name : the name of the file. 495-- Returns : the directory components of the file. 496 497-- --------------------------------------------------------------------------------- 498 499-- g_build_filename () 500 501-- gchar* g_build_filename (const gchar *first_element, 502-- ...); 503 504-- Creates a filename from a series of elements using the correct separator for 505-- filenames. 506 507-- On Unix, this function behaves identically to g_build_path (G_DIR_SEPARATOR_S, 508-- first_element, ....). 509 510-- On Windows, it takes into account that either the backslash (\ or slash (/) can 511-- be used as separator in filenames, but otherwise behaves as on Unix. When file 512-- pathname separators need to be inserted, the one that last previously occurred in 513-- the parameters (reading from left to right) is used. 514 515-- No attempt is made to force the resulting filename to be an absolute path. If the 516-- first element is a relative path, the result will be a relative path. 517 518-- first_element : the first element in the path 519-- ... : remaining elements in path, terminated by NULL 520-- Returns : a newly-allocated string that must be freed with g_free(). 521 522-- --------------------------------------------------------------------------------- 523 524-- g_build_filenamev () 525 526-- gchar* g_build_filenamev (gchar **args); 527 528-- Behaves exactly like g_build_filename(), but takes the path elements as a string 529-- array, instead of varargs. This function is mainly meant for language bindings. 530 531-- args : NULL-terminated array of strings containing the path elements. 532-- Returns : a newly-allocated string that must be freed with g_free(). 533 534-- Since 2.8 535 536-- --------------------------------------------------------------------------------- 537 538-- g_build_path () 539 540-- gchar* g_build_path (const gchar *separator, 541-- const gchar *first_element, 542-- ...); 543 544-- Creates a path from a series of elements using separator as the separator between 545-- elements. At the boundary between two elements, any trailing occurrences of 546-- separator in the first element, or leading occurrences of separator in the second 547-- element are removed and exactly one copy of the separator is inserted. 548 549-- Empty elements are ignored. 550 551-- The number of leading copies of the separator on the result is the same as the 552-- number of leading copies of the separator on the first non-empty element. 553 554-- The number of trailing copies of the separator on the result is the same as the 555-- number of trailing copies of the separator on the last non-empty element. 556-- (Determination of the number of trailing copies is done without stripping leading 557-- copies, so if the separator is ABA, ABABA has 1 trailing copy.) 558 559-- However, if there is only a single non-empty element, and there are no characters 560-- in that element not part of the leading or trailing separators, then the result 561-- is exactly the original value of that element. 562 563-- Other than for determination of the number of leading and trailing copies of the 564-- separator, elements consisting only of copies of the separator are ignored. 565 566-- separator : a string used to separator the elements of the path. 567-- first_element : the first element in the path 568-- ... : remaining elements in path, terminated by NULL 569-- Returns : a newly-allocated string that must be freed with g_free(). 570 571-- --------------------------------------------------------------------------------- 572 573-- g_build_pathv () 574 575-- gchar* g_build_pathv (const gchar *separator, 576-- gchar **args); 577 578-- Behaves exactly like g_build_path(), but takes the path elements as a string 579-- array, instead of varargs. This function is mainly meant for language bindings. 580 581-- separator : a string used to separator the elements of the path. 582-- args : NULL-terminated array of strings containing the path elements. 583-- Returns : a newly-allocated string that must be freed with g_free(). 584 585-- Since 2.8 586 587-- --------------------------------------------------------------------------------- 588 589-- g_find_program_in_path () 590 591-- gchar* g_find_program_in_path (const gchar *program); 592 593-- Locates the first executable named program in the user's path, in the same way 594-- that execvp() would locate it. Returns an allocated string with the absolute path 595-- name, or NULL if the program is not found in the path. If program is already an 596-- absolute path, returns a copy of program if program exists and is executable, and 597-- NULL otherwise. On Windows, if program does not have a file type suffix, tries 598-- with the suffixes .exe, .cmd, .bat and .com, and the suffixes in the PATHEXT 599-- environment variable. 600 601-- On Windows, it looks for the file in the same way as CreateProcess() would. This 602-- means first in the directory where the executing program was loaded from, then in 603-- the current directory, then in the Windows 32-bit system directory, then in the 604-- Windows directory, and finally in the directories in the PATH environment 605-- variable. If the program is found, the return value contains the full name 606-- including the type suffix. 607 608-- program : a program name in the GLib file name encoding 609-- Returns : absolute path, or NULL 610 611-- --------------------------------------------------------------------------------- 612 613-- g_bit_nth_lsf () 614 615-- gint g_bit_nth_lsf (gulong mask, 616-- gint nth_bit); 617 618-- Find the position of the first bit set in mask, searching from (but not 619-- including) nth_bit upwards. Bits are numbered from 0 (least significant) to 620-- sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, 621-- set nth_bit to -1. 622 623-- mask : a gulong containing flags. 624-- nth_bit : the index of the bit to start the search from. 625-- Returns : the index of the first bit set which is higher than nth_bit. 626 627-- --------------------------------------------------------------------------------- 628 629-- g_bit_nth_msf () 630 631-- gint g_bit_nth_msf (gulong mask, 632-- gint nth_bit); 633 634-- Find the position of the first bit set in mask, searching from (but not 635-- including) nth_bit downwards. Bits are numbered from 0 (least significant) to 636-- sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the last bit, 637-- set nth_bit to -1 or GLIB_SIZEOF_LONG * 8. 638 639-- mask : a gulong containing flags. 640-- nth_bit : the index of the bit to start the search from. 641-- Returns : the index of the first bit set which is lower than nth_bit. 642 643-- --------------------------------------------------------------------------------- 644 645-- g_bit_storage () 646 647-- guint g_bit_storage (gulong number); 648 649-- Gets the number of bits used to hold number, e.g. if number is 4, 3 bits are 650-- needed. 651 652-- number : a guint. 653-- Returns : the number of bits used to hold number. 654 655-- --------------------------------------------------------------------------------- 656 657-- g_spaced_primes_closest () 658 659-- guint g_spaced_primes_closest (guint num); 660 661-- Gets the smallest prime number from a built-in array of primes which is larger 662-- than num. This is used within GLib to calculate the optimum size of a GHashTable. 663 664-- The built-in array of primes ranges from 11 to 13845163 such that each prime is 665-- approximately 1.5-2 times the previous prime. 666 667-- num : a guint. 668-- Returns : the smallest prime number from a built-in array of primes which is 669-- larger than num. 670 671-- --------------------------------------------------------------------------------- 672 673-- g_atexit () 674 675-- void g_atexit (GVoidFunc func); 676 677-- Specifies a function to be called at normal program termination. 678 679-- Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor macro that 680-- maps to a call to the atexit() function in the C library. This means that in case 681-- the code that calls g_atexit(), i.e. atexit(), is in a DLL, the function will be 682-- called when the DLL is detached from the program. This typically makes more sense 683-- than that the function is called when the GLib DLL is detached, which happened 684-- earlier when g_atexit() was a function in the GLib DLL. 685 686-- The behaviour of atexit() in the context of dynamically loaded modules is not 687-- formally specified and varies wildly. 688 689-- On POSIX systems, calling g_atexit() (or atexit()) in a dynamically loaded module 690-- which is unloaded before the program terminates might well cause a crash at 691-- program exit. 692 693-- Some POSIX systems implement atexit() like Windows, and have each dynamically 694-- loaded module maintain an own atexit chain that is called when the module is 695-- unloaded. 696 697-- On other POSIX systems, before a dynamically loaded module is unloaded, the 698-- registered atexit functions (if any) residing in that module are called, 699-- regardless where the code that registered them resided. This is presumably the 700-- most robust approach. 701 702-- As can be seen from the above, for portability it's best to avoid calling 703-- g_atexit() (or atexit()) except in the main executable of a program. 704 705-- func : the function to call on normal program termination. 706 707-- --------------------------------------------------------------------------------- 708 709-- g_parse_debug_string () 710 711-- guint g_parse_debug_string (const gchar *string, 712-- const GDebugKey *keys, 713-- guint nkeys); 714 715-- Parses a string containing debugging options into a guint containing bit flags. 716-- This is used within GDK and GTK+ to parse the debug options passed on the command 717-- line or through environment variables. 718 719-- string : a list of debug options separated by colons, spaces, or commas; or the 720-- string "all" to set all flags. 721-- keys : pointer to an array of GDebugKey which associate strings with bit 722-- flags. 723-- nkeys : the number of GDebugKeys in the array. 724-- Returns : the combined set of bit flags. 725 726-- --------------------------------------------------------------------------------- 727 728-- GDebugKey 729 730-- typedef struct { 731-- gchar *key; 732-- guint value; 733-- } GDebugKey; 734 735-- Associates a string with a bit flag. Used in g_parse_debug_string(). 736 737-- gchar *key; the string 738-- guint value; the flag 739 740-- --------------------------------------------------------------------------------- 741 742-- GVoidFunc () 743 744-- void (*GVoidFunc) (void); 745 746-- Declares a type of function which takes no arguments and has no return value. It 747-- is used to specify the type function passed to g_atexit(). 748 749-- --------------------------------------------------------------------------------- 750 751-- GFreeFunc () 752 753-- void (*GFreeFunc) (gpointer data); 754 755-- Declares a type of function which takes an arbitrary data pointer argument and 756-- has no return value. It is not currently used in GLib or GTK+. 757 758-- data : a data pointer. 759 760-- --------------------------------------------------------------------------------- 761 762-- g_qsort_with_data () 763 764-- void g_qsort_with_data (gconstpointer pbase, 765-- gint total_elems, 766-- gsize size, 767-- GCompareDataFunc compare_func, 768-- gpointer user_data); 769 770-- This is just like the standard C qsort() function, but the comparison routine 771-- accepts a user data argument. 772 773-- pbase : start of array to sort 774-- total_elems : elements in the array 775-- size : size of each element 776-- compare_func : function to compare elements 777-- user_data : data to pass to compare_func 778 779-- --------------------------------------------------------------------------------- 780 781-- g_nullify_pointer () 782 783-- void g_nullify_pointer (gpointer *nullify_location); 784 785-- Set the pointer at the specified location to NULL. 786 787-- nullify_location : the memory address of the pointer. 788 789end -- class GLIB_MISCELLANEOUS_UTILITY_FUNCTIONS