+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
<refentry id="glib-running" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Running GLib Applications</refentrytitle>
</para>
</formalpara>
-<formalpara id="G_DEBUG">
+<formalpara id="G-DEBUG:CAPS">
<title><envar>G_DEBUG</envar></title>
<para>
If GLib has been configured with <option>--enable-debug=yes</option>,
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>resident-modules</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>bind-now-modules</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
+ 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.
</para>
</formalpara>
<formalpara id="G_SLICE">
<title><envar>G_SLICE</envar></title>
<para>
- This environment variable allows reconfiguration of the #GSlice
+ This environment variable allows reconfiguration of the GSlice
memory allocator.
<variablelist>
<varlistentry>
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.
+ 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.
+ erroneous slice allocation code, allthough <literal>debug-blocks</literal>
+ usually is a better suited debugging tool.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>debug-blocks</term>
+ <listitem>
+ <para>
+ 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
+ <emphasis>always enable this option when running tests</emphasis>.
+ 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 <literal>G_SLICE=always-malloc</literal>, but will be caught
+ by <literal>G_SLICE=debug-blocks</literal> is as follows:
+ <programlisting>
+ void *slist = g_slist_alloc(); /* void* gives up type-safety */
+ g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */
+ </programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
+ The special value all can be used to turn on all options.
+ The special value help can be used to print all available options.
</para>
</formalpara>
</para>
</formalpara>
-<formalpara id="G_WIN32_PRETEND_WIN9X">
- <title><envar>G_WIN32_PRETEND_WIN9X</envar></title>
+<formalpara id="TZDIR">
+ <title><envar>TZDIR</envar></title>
<para>
- Setting this variable to any value forces g_win32_get_windows_version()
- to return a version code for Windows 9x. This is mainly an internal
- debugging aid for GTK+ and GLib developers, to be able to check the
- code paths for Windows 9x.
+ Allows to specify a nonstandard location for the timezone data files
+ that are used by the #GDateTime API. The default location is under
+ <filename>/usr/share/zoneinfo</filename>. For more information,
+ also look at the <command>tzset</command> manual page.
</para>
-</formalpara>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="setlocale">
+<title>Locale</title>
+
+<para>
+A number of interfaces in GLib depend on the current locale in which
+an application is running. Therefore, most GLib-using applications should
+call <function>setlocale (LC_ALL, "")</function> to set up the current
+locale.
+</para>
+
+<para>
+On Windows, in a C program there are several locale concepts
+that not necessarily are synchronized. On one hand, there is the
+system default ANSI code-page, which determines what encoding is used
+for file names handled by the C library's functions and the Win32
+API. (We are talking about the "narrow" functions here that take
+character pointers, not the "wide" ones.)
+</para>
+
+<para>
+On the other hand, there is the C library's current locale. The
+character set (code-page) used by that is not necessarily the same as
+the system default ANSI code-page. Strings in this character set are
+returned by functions like <function>strftime()</function>.
+</para>
</refsect2>
<title>Traps and traces</title>
<para>
+<indexterm><primary>g_trap_free_size</primary></indexterm>
+<indexterm><primary>g_trap_realloc_size</primary></indexterm>
+<indexterm><primary>g_trap_malloc_size</primary></indexterm>
Some code portions contain trap variables that can be set during debugging
time if GLib has been configured with <option>--enable-debug=yes</option>.
Such traps lead to immediate code halts to examine the current program state
<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup
though, because memory profiling is required to match on the memory block sizes.
</para>
+<para>
+Note that many modern debuggers support conditional breakpoints, which achieve
+pretty much the same. E.g. in gdb, you can do
+<programlisting>
+break g_malloc
+condition 1 n_bytes == 20
+</programlisting>
+to break only on g_malloc() calls where the size of the allocated memory block
+is 20.
+</para>
</refsect2>
-</refsect1>
+<refsect2>
+<title>Gdb debugging macros</title>
+<para>
+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
+that makes backtraces with signal emissions easier to read.
+</para>
+
+<para>
+To use this you need a recent enough gdb that supports python scripting. Gdb 7.0
+should be recent enough, but branches of the "archer" gdb tree as used in Fedora 11
+and Fedora 12 should work too. You then need to install glib in the same prefix as
+gdb so that the python gdb autoloaded files get installed in the right place for
+gdb to pick up.
+</para>
+
+<para>
+General pretty printing should just happen without having to do anything special.
+To get the signal emission filtered backtrace you must use the "new-backtrace" command
+instead of the standard one.
+</para>
+
+<para>
+There is also a new command called gforeach that can be used to apply a command
+on each item in a list. E.g. you can do
+<programlisting>
+gforeach i in some_list_variable: print *(GtkWidget *)l
+</programlisting>
+Which would print the contents of each widget in a list of widgets.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>SystemTap</title>
+
+<para>
+<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> is a dynamic whole-system
+analysis toolkit. GLib ships with a file <filename>glib.stp</filename> which defines a
+set of probe points, which you can hook into with custom SystemTap scripts.
+See the files <filename>glib.stp</filename> and <filename>gobject.stp</filename> which
+are in your shared SystemTap scripts directory.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Memory statistics</title>
+
+<para>
+g_mem_profile() will output a summary g_malloc() memory usage, if memory
+profiling has been enabled by calling
+<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup.
+</para>
+
+<para>
+If GLib has been configured with <option>--enable-debug=yes</option>,
+then g_slice_debug_tree_statistics() can be called in a debugger to
+output details about the memory usage of the slice allocator.
+</para>
+
+</refsect2>
+</refsect1>
</refentry>