running.sgml   [plain text]

<refentry id="glib-running" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Running GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Running GLib Applications</refname>
<refpurpose>
How to run and debug your GLib application
</refpurpose>
</refnamediv>

<refsect1>
<title>Running and debugging GLib Applications</title>

<refsect2>
<title>Environment variables</title>

<para> 
GLib inspects a few of environment variables in addition to standard
variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. 
</para>

<formalpara id="G_FILENAME_ENCODING">
  <title><envar>G_FILENAME_ENCODING</envar></title>

  <para>
    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.
  </para>
</formalpara>

<formalpara id="G_BROKEN_FILENAMES">
  <title><envar>G_BROKEN_FILENAMES</envar></title>

  <para>
    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. 
  </para>
</formalpara>

<formalpara>
  <title><envar>G_MESSAGES_PREFIXED</envar></title>

  <para>
    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 <literal>G_LOG_LEVEL_MESSAGE</literal> and <literal>G_LOG_LEVEL_INFO</literal>. 
  </para>
</formalpara>

<formalpara>
  <title><envar>G_DEBUG</envar></title>

  <para>
    If GLib has been configured with <option>--enable-debug=yes</option>,
    this variable can be set to a list of debug options, which cause GLib
    to print out different types of debugging information.
    <variablelist>
      <varlistentry>
        <term>fatal_warnings</term>
        <listitem><para>Causes GLib to abort the program at the first call
           to <link linkend="g-warning">g_warning</link>(). This option is 
           special in that it doesn't require GLib to be configured with 
           debugging support.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </para>
</formalpara>

<formalpara>
  <title><envar>G_RANDOM_VERSION</envar></title>

  <para>
    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.  
  </para>
</formalpara> 

<formalpara>
  <title><envar>LIBCHARSET_ALIAS_DIR</envar></title>

  <para>
    Allows to specify a nonstandard location for the 
    <filename>charset.aliases</filename> file that is used by the
    character set conversion routines. The default location is the 
    <replaceable>libdir</replaceable> specified at compilation time.
  </para>
</formalpara> 

</refsect2>

<refsect2>
<title>Traps and traces</title>

<para>
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 
and backtrace.
</para>

<para>
Currently, the following trap variables exist:
<programlisting>
static volatile gulong g_trap_free_size;
static volatile gulong g_trap_realloc_size;
static volatile gulong g_trap_malloc_size;
</programlisting>
If set to a size > 0, <link linkend="g-free">g_free</link>(), 
<link linkend="g-realloc">g_realloc</link>() and 
<link linkend="g-malloc">g_malloc</link>() will be intercepted if the size 
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>
</refsect2>

</refsect1>

</refentry>