mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-10 17:53:07 +02:00
301 lines
8.9 KiB
Plaintext
301 lines
8.9 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Message Logging
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
versatile support for logging messages with different levels of importance
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
These functions provide support for logging error messages or messages
|
|
used for debugging.
|
|
</para>
|
|
|
|
<para>
|
|
There are several built-in levels of messages, defined in #GLogLevelFlags.
|
|
These can be extended with user-defined levels.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### SECTION Image ##### -->
|
|
|
|
|
|
<!-- ##### MACRO G_LOG_DOMAIN ##### -->
|
|
<para>
|
|
Defines the log domain.
|
|
For applications, this is typically left as the default %NULL (or "") domain.
|
|
Libraries should define this so that any messages which they log can
|
|
be differentiated from messages from other libraries and application code.
|
|
But be careful not to define it in any public header files.
|
|
</para>
|
|
<para>
|
|
For example, GTK+ uses this in its Makefile.am:
|
|
</para>
|
|
<informalexample><programlisting>
|
|
INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
|
|
</programlisting></informalexample>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_LOG_FATAL_MASK ##### -->
|
|
<para>
|
|
GLib log levels that are considered fatal by default.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_LOG_LEVEL_USER_SHIFT ##### -->
|
|
<para>
|
|
Log level shift offset for user defined log levels (0-7 are used by GLib).
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GLogFunc ##### -->
|
|
<para>
|
|
Specifies the prototype of log handler functions.
|
|
</para>
|
|
|
|
@log_domain: the log domain of the message.
|
|
@log_level: the log level of the message (including the fatal and recursion
|
|
flags).
|
|
@message: the message to process.
|
|
@user_data: user data, set in g_log_set_handler().
|
|
|
|
|
|
<!-- ##### ENUM GLogLevelFlags ##### -->
|
|
<para>
|
|
Flags specifying the level of log messages. It is possible to change
|
|
how GLib treats messages of the various levels using g_log_set_handler()
|
|
and g_log_set_fatal_mask().
|
|
</para>
|
|
|
|
@G_LOG_FLAG_RECURSION: internal flag
|
|
@G_LOG_FLAG_FATAL: internal flag
|
|
@G_LOG_LEVEL_ERROR: log level for errors, see g_error().
|
|
This level is also used for messages produced by g_assert().
|
|
@G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical().
|
|
This level is also used for messages produced by g_return_if_fail() and
|
|
g_return_val_if_fail().
|
|
@G_LOG_LEVEL_WARNING: log level for warnings, see g_warning()
|
|
@G_LOG_LEVEL_MESSAGE: log level for messages, see g_message()
|
|
@G_LOG_LEVEL_INFO: log level for informational messages
|
|
@G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
|
|
@G_LOG_LEVEL_MASK: a mask including all log levels.
|
|
|
|
<!-- ##### FUNCTION g_log ##### -->
|
|
<para>
|
|
Logs an error or debugging message.
|
|
If the log level has been set as fatal, the abort()
|
|
function is called to terminate the program.
|
|
</para>
|
|
|
|
@log_domain: the log domain, usually #G_LOG_DOMAIN.
|
|
@log_level: the log level, either from #GLogLevelFlags or a user-defined level.
|
|
@format: the message format. See the printf()
|
|
documentation.
|
|
@Varargs: the parameters to insert into the format string.
|
|
|
|
|
|
<!-- ##### FUNCTION g_logv ##### -->
|
|
<para>
|
|
Logs an error or debugging message.
|
|
If the log level has been set as fatal, the abort()
|
|
function is called to terminate the program.
|
|
</para>
|
|
|
|
@log_domain: the log domain.
|
|
@log_level: the log level.
|
|
@format: the message format. See the printf()
|
|
documentation.
|
|
@args: the parameters to insert into the format string.
|
|
|
|
|
|
<!-- ##### MACRO g_message ##### -->
|
|
<para>
|
|
A convenience function/macro to log a normal message.
|
|
</para>
|
|
|
|
@...: format string, followed by parameters to insert into the format string (as with printf())
|
|
|
|
|
|
<!-- ##### MACRO g_warning ##### -->
|
|
<para>
|
|
A convenience function/macro to log a warning message.
|
|
</para>
|
|
|
|
<para>
|
|
You can make warnings fatal at runtime by setting the %G_DEBUG environment
|
|
variable (see <ulink url="glib-running.html">Running GLib Applications</ulink>).
|
|
</para>
|
|
|
|
@...: format string, followed by parameters to insert into the format string (as with printf())
|
|
|
|
|
|
<!-- ##### MACRO g_critical ##### -->
|
|
<para>
|
|
Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). It's more or less
|
|
application-defined what constitutes a critical vs. a regular
|
|
warning. You could call g_log_set_always_fatal() to make critical
|
|
warnings exit the program, then use g_critical() for fatal errors, for
|
|
example.
|
|
</para>
|
|
|
|
<para>
|
|
You can also make critical warnings fatal at runtime by setting
|
|
the %G_DEBUG environment variable (see
|
|
<ulink url="glib-running.html">Running GLib Applications</ulink>).
|
|
</para>
|
|
|
|
@...: format string, followed by parameters to insert into the format string (as with printf())
|
|
|
|
|
|
<!-- ##### MACRO g_error ##### -->
|
|
<para>
|
|
A convenience function/macro to log an error message.
|
|
Error messages are always fatal, resulting in a call to
|
|
abort() to terminate the application.
|
|
This function will result in a core dump; don't use it for errors you
|
|
expect. Using this function indicates a bug in your program, i.e. an
|
|
assertion failure.
|
|
</para>
|
|
|
|
@...: format string, followed by parameters to insert into the format string (as with printf())
|
|
|
|
|
|
<!-- ##### MACRO g_debug ##### -->
|
|
<para>
|
|
A convenience function/macro to log a debug message.
|
|
</para>
|
|
|
|
@...: format string, followed by parameters to insert into the format string (as with printf())
|
|
@Since: 2.6
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_set_handler ##### -->
|
|
<para>
|
|
Sets the log handler for a domain and a set of log levels.
|
|
To handle fatal and recursive messages the @log_levels parameter
|
|
must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
|
|
bit flags.
|
|
</para>
|
|
<para>
|
|
Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
|
|
you want to set a handler for this log level you must combine it with
|
|
#G_LOG_FLAG_FATAL.
|
|
</para>
|
|
|
|
<example>
|
|
<title>Adding a log handler for all warning messages in the default
|
|
(application) domain</title>
|
|
<programlisting>
|
|
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Adding a log handler for all critical messages from GTK+</title>
|
|
<programlisting>
|
|
g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Adding a log handler for <emphasis>all</emphasis> messages from
|
|
GLib</title>
|
|
<programlisting>
|
|
g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
</programlisting>
|
|
</example>
|
|
|
|
@log_domain: the log domain, or %NULL for the default "" application domain.
|
|
@log_levels: the log levels to apply the log handler for. To handle fatal
|
|
and recursive messages as well, combine the log levels with the
|
|
#G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags.
|
|
@log_func: the log handler function.
|
|
@user_data: data passed to the log handler.
|
|
@Returns: the id of the new handler.
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_remove_handler ##### -->
|
|
<para>
|
|
Removes the log handler.
|
|
</para>
|
|
|
|
@log_domain: the log domain.
|
|
@handler_id: the id of the handler, which was returned in g_log_set_handler().
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_set_always_fatal ##### -->
|
|
<para>
|
|
Sets the message levels which are always fatal, in any log domain.
|
|
When a message with any of these levels is logged the program terminates.
|
|
You can only set the levels defined by GLib to be fatal.
|
|
%G_LOG_LEVEL_ERROR is always fatal.
|
|
</para>
|
|
|
|
<para>
|
|
You can also make some message levels
|
|
fatal at runtime by setting the %G_DEBUG environment variable (see
|
|
<ulink url="glib-running.html">Running GLib Applications</ulink>).
|
|
</para>
|
|
|
|
@fatal_mask: the mask containing bits set for each level of error which is
|
|
to be fatal.
|
|
@Returns: the old fatal mask.
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
|
|
<para>
|
|
Sets the log levels which are fatal in the given domain.
|
|
%G_LOG_LEVEL_ERROR is always fatal.
|
|
</para>
|
|
|
|
@log_domain: the log domain.
|
|
@fatal_mask: the new fatal mask.
|
|
@Returns: the old fatal mask for the log domain.
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_default_handler ##### -->
|
|
<para>
|
|
The default log handler set up by GLib; g_log_set_default_handler()
|
|
allows to install an alternate default log handler.
|
|
This is used if no log handler has been set for the particular log domain
|
|
and log level combination. It outputs the message to stderr or stdout
|
|
and if the log level is fatal it calls abort().
|
|
</para>
|
|
<para>
|
|
stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
|
|
%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for the rest.
|
|
</para>
|
|
|
|
@log_domain: the log domain of the message.
|
|
@log_level: the level of the message.
|
|
@message: the message.
|
|
@unused_data: data passed from g_log() which is unused.
|
|
|
|
|
|
<!-- ##### FUNCTION g_log_set_default_handler ##### -->
|
|
<para>
|
|
Installs a default log handler which is used if no
|
|
log handler has been set for the particular log domain
|
|
and log level combination. By default, GLib uses
|
|
g_log_default_handler() as default log handler.
|
|
</para>
|
|
|
|
@log_func: the log handler function.
|
|
@user_data: data passed to the log handler.
|
|
@Returns: the previous default log handler
|
|
@Since: 2.6
|
|
|
|
|