PageRenderTime 63ms CodeModel.GetById 10ms app.highlight 46ms RepoModel.GetById 2ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/glib_miscellaneous_utility_functions.e

http://github.com/tybor/Liberty
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