+<?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>,
</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>
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 should only be used in debugging scenarios, because it
- significantly degrades GSlice performance. Extra per slice memory
- is requied to do the necessary bookeeping, and multi-thread scalability
- is given up to perform global slice validation.
- This option is mostly useful in scenarios where program crashes are encountered
- while GSlice is in use, but crashes cannot be reproduced with G_SLICE=always-malloc.
- A potential cause for such a situation that will be caught by G_SLICE=debug-blocks
- is e.g.:
+ 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) */
</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>
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>
<refsect2>
</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>