| GLib Reference Manual | |
|---|
| @@ -50,166 +30,187 @@ How to run and debug your GLib application |
-GLib inspects a few of environment variables in addition to standard
-variables like LANG, PATH or HOME.
+
+ The runtime behaviour of GLib applications can be influenced by a + number of environment variables.
-Standard variables.Â
+ GLib reads standard environment variables like LANG,
+ PATH, HOME, TMPDIR,
+ TZ and LOGNAME.
+
XDG directories.Â
+ GLib consults the environment variables XDG_DATA_HOME,
+ XDG_DATA_DIRS, XDG_CONFIG_HOME,
+ XDG_CONFIG_DIRS, XDG_CACHE_HOME and
+ XDG_RUNTIME_DIR for the various XDG directories.
+ For more information, see the XDG basedir spec.
+
G_FILENAME_ENCODING.Â
This environment variable can be set to a comma-separated list of character
- set names. GLib assumes that filenames are encoded in the first character
+ set names. GLib assumes that filenames are encoded in the first character
set from that list rather than in UTF-8. The special token "@locale" can be
used to specify the character set for the current locale.
G_BROKEN_FILENAMES.Â
- If this environment variable is set, GLib assumes that filenames are in
+
G_BROKEN_FILENAMES.Â
+ If this environment variable is set, GLib assumes that filenames are in
the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
- priority over G_BROKEN_FILENAMES.
+ priority over G_BROKEN_FILENAMES.
G_MESSAGES_PREFIXED.Â
- A list of log levels for which messages should be prefixed by the
+
G_MESSAGES_PREFIXED.Â
+ A list of log levels for which messages should be prefixed by the
program name and PID of the application. The default is to prefix
- everything except G_LOG_LEVEL_MESSAGE and G_LOG_LEVEL_INFO.
+ everything except G_LOG_LEVEL_MESSAGE and
+ G_LOG_LEVEL_INFO.
+ The possible values are
+ error,
+ warning,
+ critical,
+ message,
+ info and
+ debug.
+ You can also use the special values
+ all and
+ help.
+
+ This environment variable only affects the default log handler,
+ g_log_default_handler().
+
G_MESSAGES_DEBUG.Â
+ A space-separated list of log domains for which informational
+ and debug messages should be printed. By default, these
+ messages are not printed.
+
+ You can also use the special value all.
+
+ This environment variable only affects the default log handler,
+ g_log_default_handler().
G_DEBUG.Â
- If GLib has been configured with --enable-debug=yes,
- this variable can be set to a list of debug options, which cause GLib
- to print out different types of debugging information.
+
G_DEBUG.Â
+ This environment variable can be set to a list of debug options,
+ which cause GLib to print out different types of debugging information.
fatal_warnings |
+fatal-warnings |
Causes GLib to abort the program at the first call - to g_warning() or - g_critical(). This option is - special in that it doesn't require GLib to be configured with - debugging support. |
+ to g_warning() or g_critical().
fatal_criticals |
+fatal-criticals |
Causes GLib to abort the program at the first call - to g_critical(). This option is - special in that it doesn't require GLib to be configured with - debugging support. |
+ to g_critical().
gc-friendly |
-- Newly allocated memory that isn't directly initialized, as well - as memory being freed will be reset to 0. The point here is to - allow memory checkers and similar programs that use bohem GC alike - algorithms to produce more accurate results. - This option is special in that it doesn't require GLib to be - configured with debugging support. - |
+Newly allocated memory that isn't directly initialized, + as well as memory being freed will be reset to 0. The point here is + to allow memory checkers and similar programs that use Boehm GC alike + algorithms to produce more accurate results. |
resident-modules |
-- All modules loaded by GModule will be made resident. This can be useful - for tracking memory leaks in modules which are later unloaded; but it can - also hide bugs where code is accessed after the module would have normally - been unloaded. - This option is special in that it doesn't require GLib to be - configured with debugging support. - |
+All modules loaded by GModule will be made resident. + This can be useful for tracking memory leaks in modules which are + later unloaded; but it can also hide bugs where code is accessed + after the module would have normally been unloaded. |
bind-now-modules |
-- All modules loaded by GModule will bind their symbols at load time, even - when the code uses %G_MODULE_BIND_LAZY. - This option is special in that it doesn't require GLib to be - configured with debugging support. - |
+All modules loaded by GModule will bind their symbols + at load time, even when the code uses %G_MODULE_BIND_LAZY. |
- The special value all can be used to turn on all debug options. - The special value help can be used to print all available options. +
+ The special value all can be used to turn on all debug options. + The special value help can be used to print all available options.
-G_SLICE.Â
- This environment variable allows reconfiguration of the GSlice
- memory allocator.
-
G_SLICE.Â
+ This environment variable allows reconfiguration of the GSlice
+ memory allocator.
+
always-malloc |
-
- This will cause all slices allocated through g_slice_alloc() and
- released by g_slice_free1() to be actually allocated via direct
- calls to g_malloc() and g_free().
- This is most useful for memory checkers and similar programs that
- use Bohem GC alike algorithms to produce more accurate results.
- It can also be in conjunction with debugging features of the system's
- malloc implementation such as glibc's MALLOC_CHECK_=2 to debug
- erroneous slice allocation code, allthough |
+This will cause all slices allocated through
+ g_slice_alloc() and released by g_slice_free1() to be actually
+ allocated via direct calls to g_malloc() and g_free().
+ This is most useful for memory checkers and similar programs that
+ use Boehm GC alike algorithms to produce more accurate results.
+ It can also be in conjunction with debugging features of the system's
+ malloc() implementation such as glibc's MALLOC_CHECK_=2 to debug
+ erroneous slice allocation code, although
+ |
debug-blocks |
-
- Using this option (present since GLib-2.13) engages extra code
- which performs sanity checks on the released memory slices.
- Invalid slice adresses or slice sizes will be reported and lead to
- a program halt.
- This option is for debugging scenarios.
- In particular, client packages sporting their own test suite should
- always enable this option when running tests.
- Global slice validation is ensured by storing size and address information
- for each allocated chunk, and maintaining a global hash table of that data.
- That way, multi-thread scalability is given up, and memory consumption is
- increased. However, the resulting code usually performs acceptably well,
- possibly better than with comparable memory checking carried out using
- external tools. An example of a memory corruption scenario that cannot be
- reproduced with Using this option (present since GLib 2.13) engages + extra code which performs sanity checks on the released memory + slices. Invalid slice adresses or slice sizes will be reported and + lead to a program halt. This option is for debugging scenarios. + In particular, client packages sporting their own test suite should + always enable this option when running tests. + Global slice validation is ensured by storing size and address + information for each allocated chunk, and maintaining a global + hash table of that data. That way, multi-thread scalability is + given up, and memory consumption is increased. However, the + resulting code usually performs acceptably well, possibly better + than with comparable memory checking carried out using external + tools. +An example of a memory corruption scenario that cannot be
+ reproduced with - void *slist = g_slist_alloc(); /* void* gives up type-safety */ - g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */ -- - + void *slist = g_slist_alloc (); /* void* gives up type-safety */ + g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */ + |
- The special value all can be used to turn on all options. - The special value help can be used to print all available options. -
-+ The special value all can be used to turn on all options. + The special value help can be used to print all available options. +
+G_RANDOM_VERSION.Â
If this environment variable is set to '2.0', the outdated
pseudo-random number seeding and generation algorithms from
- GLib-2.0 are used instead of the new better ones. Use the GLib-2.0
- algorithms only if you have sequences of numbers generated with
- Glib-2.0 that you need to reproduce exactly.
+ GLib 2.0 are used instead of the newer, better ones. You should
+ only set this variable if you have sequences of numbers that were
+ generated with Glib 2.0 that you need to reproduce exactly.
LIBCHARSET_ALIAS_DIR.Â
- Allows to specify a nonstandard location for the
+
LIBCHARSET_ALIAS_DIR.Â
+ Allows to specify a nonstandard location for the
charset.aliases file that is used by the
- character set conversion routines. The default location is the
+ character set conversion routines. The default location is the
libdir specified at compilation time.
TZDIR.Â
+ Allows to specify a nonstandard location for the timezone data files
+ that are used by the #GDateTime API. The default location is under
+ /usr/share/zoneinfo. For more information,
+ also look at the tzset manual page.
+
A number of interfaces in GLib depend on the current locale in which
an application is running. Therefore, most GLib-using applications should
-call setlocale (LC_ALL, "") to set up the current
+call setlocale (LC_ALL, "") to set up the current
locale.
@@ -228,15 +229,15 @@ returned by functions like strftime().
-Some code portions contain trap variables that can be set during debugging
-time if GLib has been configured with --enable-debug=yes.
-Such traps lead to immediate code halts to examine the current program state
+Some code portions contain trap variables that can be set during debugging
+time if GLib has been configured with --enable-debug=yes.
+Such traps lead to immediate code halts to examine the current program state
and backtrace.
@@ -248,11 +249,11 @@ static volatile gulong g_trap_realloc_size; static volatile gulong g_trap_malloc_size;
-If set to a size > 0, g_free(),
-g_realloc() and
-g_malloc() will be intercepted if the size
-matches the size of the corresponding memory block. This will only work with
-g_mem_set_vtable (glib_mem_profiler_table) upon startup
+If set to a size > 0, g_free(),
+g_realloc() and
+g_malloc() will be intercepted if the size
+matches the size of the corresponding memory block. This will only work with
+g_mem_set_vtable (glib_mem_profiler_table) upon startup
though, because memory profiling is required to match on the memory block sizes.
@@ -265,12 +266,12 @@ condition 1 n_bytes == 20
to break only on g_malloc() calls where the size of the allocated memory block -is 20. +is 20.
glib ships with a set of python macros for the gdb debugger. These includes pretty printers for lists, hashtables and gobject types. It also has a backtrace filter @@ -300,16 +301,27 @@ Which would print the contents of each widget in a list of widgets.
+SystemTap is a dynamic whole-system
+analysis toolkit. GLib ships with a file glib.stp which defines a
+set of probe points, which you can hook into with custom SystemTap scripts.
+See the files glib.stp and gobject.stp which
+are in your shared SystemTap scripts directory.
+
g_mem_profile() will output a summary g_malloc() memory usage, if memory
-profiling has been enabled by calling
+profiling has been enabled by calling
g_mem_set_vtable (glib_mem_profiler_table) upon startup.
If GLib has been configured with --enable-debug=yes,
-then g_slice_debug_tree_statistics() can be called in a debugger to
+then g_slice_debug_tree_statistics() can be called in a debugger to
output details about the memory usage of the slice allocator.