mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-12-08 09:34:50 +01:00
Matthias Clasen
committed by
Philip Withnall
Philip Withnall
parent
7c5fc4eb26
commit
758c5de24e
@@ -28,7 +28,6 @@
|
|||||||
<xi:include href="cross.xml" />
|
<xi:include href="cross.xml" />
|
||||||
<xi:include href="programming.xml" />
|
<xi:include href="programming.xml" />
|
||||||
<xi:include href="xml/compiling.xml" />
|
<xi:include href="xml/compiling.xml" />
|
||||||
<xi:include href="running.xml" />
|
|
||||||
<xi:include href="changes.xml" />
|
<xi:include href="changes.xml" />
|
||||||
<xi:include href="resources.xml" />
|
<xi:include href="resources.xml" />
|
||||||
|
|
||||||
|
|||||||
@@ -40,6 +40,8 @@ show_class_hierarchy = true
|
|||||||
urlmap_file = "urlmap.js"
|
urlmap_file = "urlmap.js"
|
||||||
# The same order will be used when generating the index
|
# The same order will be used when generating the index
|
||||||
content_files = [
|
content_files = [
|
||||||
|
"running.md",
|
||||||
|
|
||||||
"character-set.md",
|
"character-set.md",
|
||||||
"i18n.md",
|
"i18n.md",
|
||||||
|
|
||||||
|
|||||||
@@ -72,7 +72,6 @@ if get_option('gtk_doc')
|
|||||||
],
|
],
|
||||||
content_files : [
|
content_files : [
|
||||||
'cross.xml',
|
'cross.xml',
|
||||||
'running.xml',
|
|
||||||
'building.xml',
|
'building.xml',
|
||||||
'changes.xml',
|
'changes.xml',
|
||||||
'compiling.xml',
|
'compiling.xml',
|
||||||
@@ -159,6 +158,7 @@ expand_content_files = [
|
|||||||
'main-loop.md',
|
'main-loop.md',
|
||||||
'memory-slices.md',
|
'memory-slices.md',
|
||||||
'reference-counting.md',
|
'reference-counting.md',
|
||||||
|
'running.md',
|
||||||
'testing.md',
|
'testing.md',
|
||||||
'threads.md',
|
'threads.md',
|
||||||
]
|
]
|
||||||
|
|||||||
189
docs/reference/glib/running.md
Normal file
189
docs/reference/glib/running.md
Normal file
@@ -0,0 +1,189 @@
|
|||||||
|
Title: Running GLib Applications
|
||||||
|
|
||||||
|
# Running GLib Applications
|
||||||
|
|
||||||
|
## Environment variables
|
||||||
|
|
||||||
|
The runtime behaviour of GLib applications can be influenced by a number of
|
||||||
|
environment variables.
|
||||||
|
|
||||||
|
Standard variables
|
||||||
|
: GLib reads standard environment variables like `LANG`, `PATH`, `HOME`,
|
||||||
|
`TMPDIR`, `TZ` and `LOGNAME`.
|
||||||
|
|
||||||
|
XDG directories
|
||||||
|
: GLib consults the environment variables `XDG_DATA_HOME`,
|
||||||
|
`XDG_DATA_DIRS`, `XDG_CONFIG_HOME`, `XDG_CONFIG_DIRS`, `XDG_CACHE_HOME` and
|
||||||
|
`XDG_RUNTIME_DIR` for the various XDG directories. For more information, see
|
||||||
|
the [XDG basedir specification](https://specifications.freedesktop.org/basedir-spec/latest/).
|
||||||
|
|
||||||
|
`G_FILENAME_ENCODING`
|
||||||
|
: 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.
|
||||||
|
|
||||||
|
`G_BROKEN_FILENAMES`
|
||||||
|
: 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`.
|
||||||
|
|
||||||
|
`G_MESSAGES_PREFIXED`
|
||||||
|
: 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
|
||||||
|
`G_LOG_LEVEL_MESSAGE` and `G_LOG_LEVEL_INFO`. The possible values are error,
|
||||||
|
warning, critical, message, info and debug. You can also use the special
|
||||||
|
values all and help. This environment variable only affects the default log
|
||||||
|
handler, `g_log_default_handler()`.
|
||||||
|
|
||||||
|
`G_MESSAGES_DEBUG`
|
||||||
|
: 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 all. This environment variable only affects
|
||||||
|
the default log handler, `g_log_default_handler()`.
|
||||||
|
|
||||||
|
`G_DEBUG`
|
||||||
|
: This environment variable can be set to a list of debug options, which cause
|
||||||
|
GLib to print out different types of debugging information.
|
||||||
|
|
||||||
|
- `fatal-warnings`: Causes GLib to abort the program at the first call to
|
||||||
|
`g_warning()` or `g_critical()`. Use of this flag is not recommended
|
||||||
|
except when debugging.
|
||||||
|
- `fatal-criticals`: Causes GLib to abort the program at the first call
|
||||||
|
to `g_critical()`. This flag can be useful during debugging and
|
||||||
|
testing.
|
||||||
|
- `gc-friendly`: 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.
|
||||||
|
- `resident-modules`: 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.
|
||||||
|
- `bind-now-modules`: All modules loaded by GModule will bind their
|
||||||
|
symbols at load time, even when the code uses `G_MODULE_BIND_LAZY`.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
`G_SLICE`
|
||||||
|
: This environment variable allowed reconfiguration of the GSlice memory
|
||||||
|
allocator. Since GLib 2.76, GSlice uses the system `malloc()` implementation
|
||||||
|
internally, so this variable is ignored.
|
||||||
|
|
||||||
|
`G_RANDOM_VERSION`
|
||||||
|
: 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 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.
|
||||||
|
|
||||||
|
`LIBCHARSET_ALIAS_DIR`
|
||||||
|
: Allows to specify a nonstandard location for the `charset.aliases` file
|
||||||
|
that is used by the character set conversion routines. The default
|
||||||
|
location is the `libdir` specified at compilation time.
|
||||||
|
|
||||||
|
`TZDIR`
|
||||||
|
: Allows to specify a nonstandard location for the timezone data files that
|
||||||
|
are used by the `GDateTime` API. The default location is under
|
||||||
|
`/usr/share/zoneinfo`. For more information, also look at the `tzset` manual
|
||||||
|
page.
|
||||||
|
|
||||||
|
`G_ENABLE_DIAGNOSTIC`
|
||||||
|
: If set to a non-zero value, this environment variable enables diagnostic
|
||||||
|
messages, like deprecation messages for GObject properties and signals.
|
||||||
|
|
||||||
|
`G_DEBUGGER`
|
||||||
|
: When running on Windows, if set to a non-empty string, GLib will try to
|
||||||
|
interpret the contents of this environment variable as a command line to a
|
||||||
|
debugger, and run it if the process crashes. The debugger command line
|
||||||
|
should contain `%p` and `%e` substitution tokens, which GLib will replace
|
||||||
|
with the process ID of the crashing process and a handle to an event that
|
||||||
|
the debugger should signal to let GLib know that the debugger successfully
|
||||||
|
attached to the process. If `%e` is absent, or if the debugger is not able
|
||||||
|
to signal events, GLib will resume execution after 60 seconds. If `%p` is
|
||||||
|
absent, the debugger won't know which process to attach to, and GLib will
|
||||||
|
also resume execution after 60 seconds. Additionally, even if `G_DEBUGGER`
|
||||||
|
is not set, GLib would still try to print basic exception information (code
|
||||||
|
and address) into `stderr`. By default the debugger gets a new console
|
||||||
|
allocated for it. Set the `G_DEBUGGER_OLD_CONSOLE` environment variable to
|
||||||
|
any non-empty string to make the debugger inherit the console of the
|
||||||
|
crashing process. Normally this is only used by the GLib testsuite. The
|
||||||
|
exception handler is written with the aim of making it as simple as
|
||||||
|
possible, to minimize the risk of it invoking buggy functions or running
|
||||||
|
buggy code, which would result in exceptions being raised recursively.
|
||||||
|
Because of that it lacks most of the amenities that one would expect of
|
||||||
|
GLib. Namely, it does not support Unicode, so it is highly advisable to
|
||||||
|
only use ASCII characters in `G_DEBUGGER`. See also `G_VEH_CATCH`.
|
||||||
|
|
||||||
|
`G_VEH_CATCH`
|
||||||
|
: Catching some exceptions can break the program, since Windows will
|
||||||
|
sometimes use exceptions for execution flow control and other purposes
|
||||||
|
other than signalling a crash. The `G_VEH_CATCH` environment variable
|
||||||
|
augments Vectored Exception Handling on Windows (see `G_DEBUGGER`),
|
||||||
|
allowing GLib to catch more exceptions. Set this variable to a
|
||||||
|
comma-separated list of hexadecimal exception codes that should
|
||||||
|
additionally be caught. By default GLib will only catch Access Violation,
|
||||||
|
Stack Overflow and Illegal Instruction exceptions.
|
||||||
|
|
||||||
|
## Locale
|
||||||
|
|
||||||
|
A number of interfaces in GLib depend on the current locale in which an
|
||||||
|
application is running. Therefore, most GLib-using applications should call
|
||||||
|
`setlocale (LC_ALL, "")` to set up the current locale.
|
||||||
|
|
||||||
|
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.)
|
||||||
|
|
||||||
|
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 `strftime()`.
|
||||||
|
|
||||||
|
## Debugging with GDB
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
To use this you need a version of GDB that supports Python scripting;
|
||||||
|
anything from 7.0 should be fine. 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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
`gforeach i in some_list_variable: print *(GtkWidget *)l`
|
||||||
|
|
||||||
|
Which would print the contents of each widget in a list of widgets.
|
||||||
|
|
||||||
|
## SystemTap
|
||||||
|
|
||||||
|
SystemTap is a dynamic whole-system analysis toolkit. GLib ships with a file
|
||||||
|
`libglib-2.0.so.*.stp` which defines a set of probe points, which you can hook
|
||||||
|
into with custom SystemTap scripts. See the files `libglib-2.0.so.*.stp`,
|
||||||
|
`libgobject-2.0.so.*.stp` and `libgio-2.0.so.*.stp` which are in your shared
|
||||||
|
SystemTap scripts directory.
|
||||||
|
|
||||||
|
## Memory statistics
|
||||||
|
|
||||||
|
`g_mem_profile()` will output a summary `g_malloc()` memory usage, if memory
|
||||||
|
profiling has been enabled by calling:
|
||||||
|
|
||||||
|
```
|
||||||
|
g_mem_set_vtable (glib_mem_profiler_table);
|
||||||
|
```
|
||||||
|
|
||||||
|
upon startup.
|
||||||
|
|
||||||
|
If GLib has been configured with full debugging support, then
|
||||||
|
`g_slice_debug_tree_statistics()` can be called in a debugger to output details
|
||||||
|
about the memory usage of the slice allocator.
|
||||||
@@ -1,371 +0,0 @@
|
|||||||
<?xml version="1.0"?>
|
|
||||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
||||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
||||||
]>
|
|
||||||
<refentry id="glib-running">
|
|
||||||
<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>
|
|
||||||
The runtime behaviour of GLib applications can be influenced by a
|
|
||||||
number of environment variables.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title>Standard variables</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
GLib reads standard environment variables like <envar>LANG</envar>,
|
|
||||||
<envar>PATH</envar>, <envar>HOME</envar>, <envar>TMPDIR</envar>,
|
|
||||||
<envar>TZ</envar> and <envar>LOGNAME</envar>.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara>
|
|
||||||
<title>XDG directories</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
GLib consults the environment variables <envar>XDG_DATA_HOME</envar>,
|
|
||||||
<envar>XDG_DATA_DIRS</envar>, <envar>XDG_CONFIG_HOME</envar>,
|
|
||||||
<envar>XDG_CONFIG_DIRS</envar>, <envar>XDG_CACHE_HOME</envar> and
|
|
||||||
<envar>XDG_RUNTIME_DIR</envar> for the various XDG directories.
|
|
||||||
For more information, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG basedir spec</ulink>.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<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 id="G_MESSAGES_PREFIXED">
|
|
||||||
<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>.
|
|
||||||
The possible values are
|
|
||||||
<literal>error</literal>,
|
|
||||||
<literal>warning</literal>,
|
|
||||||
<literal>critical</literal>,
|
|
||||||
<literal>message</literal>,
|
|
||||||
<literal>info</literal> and
|
|
||||||
<literal>debug</literal>.
|
|
||||||
You can also use the special values
|
|
||||||
<literal>all</literal> and
|
|
||||||
<literal>help</literal>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This environment variable only affects the default log handler,
|
|
||||||
g_log_default_handler().
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G_MESSAGES_DEBUG">
|
|
||||||
<title><envar>G_MESSAGES_DEBUG</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A space-separated list of log domains for which informational
|
|
||||||
and debug messages should be printed. By default, these
|
|
||||||
messages are not printed.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
You can also use the special value <literal>all</literal>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This environment variable only affects the default log handler,
|
|
||||||
g_log_default_handler().
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G-DEBUG:CAPS">
|
|
||||||
<title><envar>G_DEBUG</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This environment 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 g_warning() or g_critical(). Use of this flag is not
|
|
||||||
recommended except when debugging.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>fatal-criticals</term>
|
|
||||||
<listitem><para>Causes GLib to abort the program at the first call
|
|
||||||
to g_critical(). This flag can be useful during debugging and
|
|
||||||
testing.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>gc-friendly</term>
|
|
||||||
<listitem><para>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.</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.</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.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
The special value <literal>all</literal> can be used to turn on all debug options.
|
|
||||||
The special value <literal>help</literal> can be used to print all available options.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G_SLICE">
|
|
||||||
<title><envar>G_SLICE</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This environment variable allowed reconfiguration of the GSlice
|
|
||||||
memory allocator. Since GLib 2.76, GSlice uses the system
|
|
||||||
<literal>malloc()</literal> implementation internally, so this variable is
|
|
||||||
ignored.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G_RANDOM_VERSION">
|
|
||||||
<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 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.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="LIBCHARSET_ALIAS_DIR">
|
|
||||||
<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>
|
|
||||||
|
|
||||||
<formalpara id="TZDIR">
|
|
||||||
<title><envar>TZDIR</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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 id="G_ENABLE_DIAGNOSTIC">
|
|
||||||
<title><envar>G_ENABLE_DIAGNOSTIC</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If set to a non-zero value, this environment variable enables
|
|
||||||
diagnostic messages, like deprecation messages for GObject properties
|
|
||||||
and signals.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G_DEBUGGER">
|
|
||||||
<title><envar>G_DEBUGGER</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
When running on Windows, if set to a non-empty string, GLib will
|
|
||||||
try to interpret the contents of this environment variable as
|
|
||||||
a command line to a debugger, and run it if the process crashes.
|
|
||||||
The debugger command line should contain <literal>%p</literal> and <literal>%e</literal> substitution
|
|
||||||
tokens, which GLib will replace with the process ID of the crashing
|
|
||||||
process and a handle to an event that the debugger should signal
|
|
||||||
to let GLib know that the debugger successfully attached to the
|
|
||||||
process. If <literal>%e</literal> is absent, or if the debugger is not able to
|
|
||||||
signal events, GLib will resume execution after 60 seconds.
|
|
||||||
If <literal>%p</literal> is absent, the debugger won't know which process to attach to,
|
|
||||||
and GLib will also resume execution after 60 seconds.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Additionally, even if <envar>G_DEBUGGER</envar> is not set, GLib would still
|
|
||||||
try to print basic exception information (code and address) into
|
|
||||||
stderr.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
By default the debugger gets a new console allocated for it.
|
|
||||||
Set the <envar>G_DEBUGGER_OLD_CONSOLE</envar> environment variable to any
|
|
||||||
non-empty string to make the debugger inherit the console of
|
|
||||||
the crashing process. Normally this is only used by the GLib
|
|
||||||
testsuite.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The exception handler is written with the aim of making it as
|
|
||||||
simple as possible, to minimize the risk of it invoking
|
|
||||||
buggy functions or running buggy code, which would result
|
|
||||||
in exceptions being raised recursively. Because of that
|
|
||||||
it lacks most of the amenities that one would expect of GLib.
|
|
||||||
Namely, it does not support Unicode, so it is highly advisable
|
|
||||||
to only use ASCII characters in <envar>G_DEBUGGER</envar>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
See also <link linkend="G_VEH_CATCH"><envar>G_VEH_CATCH</envar></link>.
|
|
||||||
</para>
|
|
||||||
</formalpara>
|
|
||||||
|
|
||||||
<formalpara id="G_VEH_CATCH">
|
|
||||||
<title><envar>G_VEH_CATCH</envar></title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Catching some exceptions can break the program, since Windows
|
|
||||||
will sometimes use exceptions for execution flow control and
|
|
||||||
other purposes other than signalling a crash.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The <envar>G_VEH_CATCH</envar> environment variable augments
|
|
||||||
<ulink url="https://docs.microsoft.com/en-us/windows/desktop/debug/vectored-exception-handling">Vectored Exception Handling</ulink>
|
|
||||||
on Windows (see <link linkend="G_DEBUGGER"><envar>G_DEBUGGER</envar></link>), allowing GLib to catch more
|
|
||||||
exceptions. Set this variable to a comma-separated list of
|
|
||||||
hexadecimal exception codes that should additionally be caught.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
By default GLib will only catch Access Violation, Stack Overflow and
|
|
||||||
Illegal Instruction <ulink url="https://docs.microsoft.com/en-us/windows/desktop/api/winnt/ns-winnt-_exception_record">exceptions</ulink>.
|
|
||||||
</para>
|
|
||||||
</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>
|
|
||||||
|
|
||||||
<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 version of GDB that supports Python scripting; anything
|
|
||||||
from 7.0 should be fine. 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>
|
|
||||||
<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>libglib-2.0.so.*.stp</filename> which defines a
|
|
||||||
set of probe points, which you can hook into with custom SystemTap scripts.
|
|
||||||
See the files <filename>libglib-2.0.so.*.stp</filename>, <filename>libgobject-2.0.so.*.stp</filename>
|
|
||||||
and <filename>libgio-2.0.so.*.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>
|
|
||||||
Reference in New Issue
Block a user