| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Running GLib Applications</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="index.html" title="GLib Reference Manual"> |
| <link rel="up" href="glib.html" title="GLib Overview"> |
| <link rel="prev" href="glib-compiling.html" title="Compiling GLib Applications"> |
| <link rel="next" href="glib-changes.html" title="Changes to GLib"> |
| <meta name="generator" content="GTK-Doc V1.14 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> |
| <td><a accesskey="p" href="glib-compiling.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
| <td><a accesskey="u" href="glib.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
| <th width="100%" align="center">GLib Reference Manual</th> |
| <td><a accesskey="n" href="glib-changes.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry" title="Running GLib Applications"> |
| <a name="glib-running"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle">Running GLib Applications</span></h2> |
| <p>Running GLib Applications — |
| How to run and debug your GLib application |
| </p> |
| </td> |
| <td valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1" title="Running and debugging GLib Applications"> |
| <a name="id489959"></a><h2>Running and debugging GLib Applications</h2> |
| <div class="refsect2" title="Environment variables"> |
| <a name="id488386"></a><h3>Environment variables</h3> |
| <p> |
| GLib inspects a few of environment variables in addition to standard |
| variables like <code class="envar">LANG</code>, <code class="envar">PATH</code> or <code class="envar">HOME</code>. |
| </p> |
| <p title="G_FILENAME_ENCODING"><a name="G_FILENAME_ENCODING"></a><b><code class="envar">G_FILENAME_ENCODING</code>. </b> |
| 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 from that list rather than in UTF-8. The special token "@locale" can be |
| used to specify the character set for the current locale. |
| </p> |
| <p title="G_BROKEN_FILENAMES"><a name="G_BROKEN_FILENAMES"></a><b><code class="envar">G_BROKEN_FILENAMES</code>. </b> |
| 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. |
| </p> |
| <p title="G_MESSAGES_PREFIXED"><a name="G_MESSAGES_PREFIXED"></a><b><code class="envar">G_MESSAGES_PREFIXED</code>. </b> |
| 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 <code class="literal">G_LOG_LEVEL_MESSAGE</code> and <code class="literal">G_LOG_LEVEL_INFO</code>. |
| </p> |
| <p title="G_DEBUG"><a name="G_DEBUG"></a><b><code class="envar">G_DEBUG</code>. </b> |
| If GLib has been configured with <code class="option">--enable-debug=yes</code>, |
| this variable can be set to a list of debug options, which cause GLib |
| to print out different types of debugging information. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><span class="term">fatal_warnings</span></p></td> |
| <td><p>Causes GLib to abort the program at the first call |
| to <a class="link" href="glib-Message-Logging.html#g-warning" title="g_warning()">g_warning</a>() or |
| <a class="link" href="glib-Message-Logging.html#g-critical" title="g_critical()">g_critical</a>(). This option is |
| special in that it doesn't require GLib to be configured with |
| debugging support.</p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">fatal_criticals</span></p></td> |
| <td><p>Causes GLib to abort the program at the first call |
| to <a class="link" href="glib-Message-Logging.html#g-critical" title="g_critical()">g_critical</a>(). This option is |
| special in that it doesn't require GLib to be configured with |
| debugging support.</p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">gc-friendly</span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">resident-modules</span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">bind-now-modules</span></p></td> |
| <td><p> |
| 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. |
| </p></td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p title="G_DEBUG"> |
| 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. |
| </p> |
| <p title="G_SLICE"><a name="G_SLICE"></a><b><code class="envar">G_SLICE</code>. </b> |
| This environment variable allows reconfiguration of the GSlice |
| memory allocator. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><span class="term">always-malloc</span></p></td> |
| <td><p> |
| 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 <code class="literal">debug-blocks</code> |
| usually is a better suited debugging tool. |
| </p></td> |
| </tr> |
| <tr> |
| <td><p><span class="term">debug-blocks</span></p></td> |
| <td> |
| <p> |
| 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 |
| <span class="emphasis"><em>always enable this option when running tests</em></span>. |
| 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 <code class="literal">G_SLICE=always-malloc</code>, but will be caught |
| by <code class="literal">G_SLICE=debug-blocks</code> is as follows: |
| </p> |
| <pre class="programlisting"> |
| void *slist = g_slist_alloc(); /* void* gives up type-safety */ |
| g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */ |
| </pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p title="G_SLICE"> |
| The special value all can be used to turn on all options. |
| The special value help can be used to print all available options. |
| </p> |
| <p title="G_RANDOM_VERSION"><a name="G_RANDOM_VERSION"></a><b><code class="envar">G_RANDOM_VERSION</code>. </b> |
| 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. |
| </p> |
| <p title="LIBCHARSET_ALIAS_DIR"><a name="LIBCHARSET_ALIAS_DIR"></a><b><code class="envar">LIBCHARSET_ALIAS_DIR</code>. </b> |
| Allows to specify a nonstandard location for the |
| <code class="filename">charset.aliases</code> file that is used by the |
| character set conversion routines. The default location is the |
| <em class="replaceable"><code>libdir</code></em> specified at compilation time. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2" title="Locale"> |
| <a name="setlocale"></a><h3>Locale</h3> |
| <p> |
| A number of interfaces in GLib depend on the current locale in which |
| an application is running. Therefore, most GLib-using applications should |
| call <code class="function">setlocale (LC_ALL, "")</code> to set up the current |
| locale. |
| </p> |
| <p> |
| 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.) |
| </p> |
| <p> |
| 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 <code class="function">strftime()</code>. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2" title="Traps and traces"> |
| <a name="id489194"></a><h3>Traps and traces</h3> |
| <p> |
| |
| |
| |
| Some code portions contain trap variables that can be set during debugging |
| time if GLib has been configured with <code class="option">--enable-debug=yes</code>. |
| Such traps lead to immediate code halts to examine the current program state |
| and backtrace. |
| </p> |
| <p> |
| Currently, the following trap variables exist: |
| </p> |
| <pre class="programlisting"> |
| static volatile gulong g_trap_free_size; |
| static volatile gulong g_trap_realloc_size; |
| static volatile gulong g_trap_malloc_size; |
| </pre> |
| <p> |
| If set to a size > 0, <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()">g_free</a>(), |
| <a class="link" href="glib-Memory-Allocation.html#g-realloc" title="g_realloc ()">g_realloc</a>() and |
| <a class="link" href="glib-Memory-Allocation.html#g-malloc" title="g_malloc ()">g_malloc</a>() will be intercepted if the size |
| matches the size of the corresponding memory block. This will only work with |
| <code class="literal">g_mem_set_vtable (glib_mem_profiler_table)</code> upon startup |
| though, because memory profiling is required to match on the memory block sizes. |
| </p> |
| <p> |
| Note that many modern debuggers support conditional breakpoints, which achieve |
| pretty much the same. E.g. in gdb, you can do |
| </p> |
| <pre class="programlisting"> |
| break g_malloc |
| condition 1 n_bytes == 20 |
| </pre> |
| <p> |
| to break only on g_malloc() calls where the size of the allocated memory block |
| is 20. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2" title="Gdb debugging macros"> |
| <a name="id458184"></a><h3>Gdb debugging macros</h3> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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 |
| </p> |
| <pre class="programlisting"> |
| gforeach i in some_list_variable: print *(GtkWidget *)l |
| </pre> |
| <p> |
| Which would print the contents of each widget in a list of widgets. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2" title="Memory statistics"> |
| <a name="id458219"></a><h3>Memory statistics</h3> |
| <p> |
| g_mem_profile() will output a summary g_malloc() memory usage, if memory |
| profiling has been enabled by calling |
| <code class="literal">g_mem_set_vtable (glib_mem_profiler_table)</code> upon startup. |
| </p> |
| <p> |
| If GLib has been configured with <code class="option">--enable-debug=yes</code>, |
| then g_slice_debug_tree_statistics() can be called in a debugger to |
| output details about the memory usage of the slice allocator. |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr> |
| Generated by GTK-Doc V1.14</div> |
| </body> |
| </html> |