Fix doc typos
[platform/upstream/glib.git] / docs / reference / glib / running.sgml
index d05cabe..41215dd 100644 (file)
@@ -1,3 +1,7 @@
+<?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>
@@ -54,7 +58,7 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
   </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>,
@@ -91,14 +95,40 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
                </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>
@@ -109,14 +139,43 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
                  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>
 
@@ -143,16 +202,44 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
   </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>
 
@@ -160,6 +247,9 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
 <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 
@@ -180,8 +270,80 @@ matches the size of the corresponding memory block. This will only work with
 <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>