<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">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<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.13 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
-<link rel="chapter" href="glib.html" title="GLib Overview">
-<link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
-<link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
-<link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
-<link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
-<link rel="chapter" href="tools.html" title="GLib Tools">
-<link rel="index" href="api-index-full.html" title="Index">
-<link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
-<link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
-<link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
-<link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
-<link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
-<link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
-<link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
-<link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
-<link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
-<link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
-<link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
-<link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
-<link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
</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">
<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">
+<div class="refentry">
<a name="glib-running"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
</td>
<td valign="top" align="right"></td>
</tr></table></div>
-<div class="refsect1" title="Running and debugging GLib Applications">
-<a name="id492288"></a><h2>Running and debugging GLib Applications</h2>
-<div class="refsect2" title="Environment variables">
-<a name="id489536"></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>.
+<div class="refsect1">
+<a name="id478891"></a><h2>Running and debugging GLib Applications</h2>
+<div class="refsect2">
+<a name="id472486"></a><h3>Environment variables</h3>
+<p>
+ The runtime behaviour of GLib applications can be influenced by a
+ number of environment variables.
</p>
-<p title="G_FILENAME_ENCODING"><a name="G_FILENAME_ENCODING"></a><b><code class="envar">G_FILENAME_ENCODING</code>. </b>
+<p><b>Standard variables. </b>
+ GLib reads standard environment variables like <code class="envar">LANG</code>,
+ <code class="envar">PATH</code>, <code class="envar">HOME</code>, <code class="envar">TMPDIR</code>,
+ <code class="envar">TZ</code> and <code class="envar">LOGNAME</code>.
+ </p>
+<p><b>XDG directories. </b>
+ GLib consults the environment variables <code class="envar">XDG_DATA_HOME</code>,
+ <code class="envar">XDG_DATA_DIRS</code>, <code class="envar">XDG_CONFIG_HOME</code>,
+ <code class="envar">XDG_CONFIG_DIRS</code>, <code class="envar">XDG_CACHE_HOME</code> and
+ <code class="envar">XDG_RUNTIME_DIR</code> for the various XDG directories.
+ For more information, see the <a class="ulink" href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html" target="_top">XDG basedir spec</a>.
+ </p>
+<p><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 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
+<p><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.
+ 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
+<p><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>.
+ everything except <code class="literal">G_LOG_LEVEL_MESSAGE</code> and
+ <code class="literal">G_LOG_LEVEL_INFO</code>.
+ The possible values are
+ <code class="literal">error</code>,
+ <code class="literal">warning</code>,
+ <code class="literal">critical</code>,
+ <code class="literal">message</code>,
+ <code class="literal">info</code> and
+ <code class="literal">debug</code>.
+ You can also use the special values
+ <code class="literal">all</code> and
+ <code class="literal">help</code>.
+
+ This environment variable only affects the default log handler,
+ g_log_default_handler().
+ </p>
+<p><a name="G_MESSAGES_DEBUG"></a><b><code class="envar">G_MESSAGES_DEBUG</code>. </b>
+ 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 <code class="literal">all</code>.
+
+ This environment variable only affects the default log handler,
+ g_log_default_handler().
</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><a name="G-DEBUG:CAPS"></a><b><code class="envar">G_DEBUG</code>. </b>
+ This environment 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><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>
+ to g_warning() or g_critical().</p></td>
</tr>
<tr>
-<td><p><span class="term">fatal_criticals</span></p></td>
+<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>
+ to g_critical().</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>
+<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 Boehm GC alike
+ algorithms to produce more accurate results.</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>
+<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.</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>
+<td><p>All modules loaded by GModule will bind their symbols
+ at load time, even when the code uses %G_MODULE_BIND_LAZY.</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>
+ 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>
+<p><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>
+<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 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
+ <code class="literal">debug-blocks</code> is usually 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>
+<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.</p>
+<p>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>
+ void *slist = g_slist_alloc (); /* void* gives up type-safety */
+ g_list_free (slist); /* corruption: sizeof (GSList) != sizeof (GList) */
+ </pre>
</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>
+<p>
+ 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><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.
+ 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.
</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
+<p><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
+ character set conversion routines. The default location is the
<em class="replaceable"><code>libdir</code></em> specified at compilation time.
</p>
+<p><a name="TZDIR"></a><b><code class="envar">TZDIR</code>. </b>
+ Allows to specify a nonstandard location for the timezone data files
+ that are used by the #GDateTime API. The default location is under
+ <code class="filename">/usr/share/zoneinfo</code>. For more information,
+ also look at the <span class="command"><strong>tzset</strong></span> manual page.
+ </p>
</div>
<hr>
-<div class="refsect2" title="Locale">
+<div class="refsect2">
<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
+call <code class="function">setlocale (LC_ALL, "")</code> to set up the current
locale.
</p>
<p>
</p>
</div>
<hr>
-<div class="refsect2" title="Traps and traces">
-<a name="id492704"></a><h3>Traps and traces</h3>
+<div class="refsect2">
+<a name="id449610"></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
+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>
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
+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>
</pre>
<p>
to break only on g_malloc() calls where the size of the allocated memory block
-is 20.
+is 20.
</p>
</div>
<hr>
-<div class="refsect2" title="Gdb debugging macros">
-<a name="id457417"></a><h3>Gdb debugging macros</h3>
+<div class="refsect2">
+<a name="id449694"></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
</p>
</div>
<hr>
-<div class="refsect2" title="Memory statistics">
-<a name="id457452"></a><h3>Memory statistics</h3>
+<div class="refsect2">
+<a name="id449728"></a><h3>SystemTap</h3>
+<p>
+<a class="ulink" href="http://sourceware.org/systemtap/" target="_top">SystemTap</a> is a dynamic whole-system
+analysis toolkit. GLib ships with a file <code class="filename">glib.stp</code> which defines a
+set of probe points, which you can hook into with custom SystemTap scripts.
+See the files <code class="filename">glib.stp</code> and <code class="filename">gobject.stp</code> which
+are in your shared SystemTap scripts directory.
+</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="id449764"></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
+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
+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 class="footer">
<hr>
- Generated by GTK-Doc V1.13</div>
+ Generated by GTK-Doc V1.18</div>
</body>
</html>
\ No newline at end of file
projects / platform / upstream / glib2.0.git / blobdiff