messages.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Message-Logging">
<refmeta>
<refentrytitle>Message Logging</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Message Logging</refname><refpurpose>versatile support for logging messages with different levels of importance.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="G-LOG-DOMAIN-CAPS">G_LOG_DOMAIN</link>
#define     <link linkend="G-LOG-FATAL-MASK-CAPS">G_LOG_FATAL_MASK</link>
#define     <link linkend="G-LOG-LEVEL-USER-SHIFT-CAPS">G_LOG_LEVEL_USER_SHIFT</link>
void        (<link linkend="GLogFunc">*GLogFunc</link>)                     (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="gpointer">gpointer</link> user_data);
enum        <link linkend="GLogLevelFlags">GLogLevelFlags</link>;

void        <link linkend="g-log">g_log</link>                           (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
void        <link linkend="g-logv">g_logv</link>                          (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *format,
                                             va_list args);
#define     <link linkend="g-message">g_message</link>                       (...)
#define     <link linkend="g-warning">g_warning</link>                       (...)
#define     <link linkend="g-critical">g_critical</link>                      (...)
#define     <link linkend="g-error">g_error</link>                         (...)

<link linkend="guint">guint</link>       <link linkend="g-log-set-handler">g_log_set_handler</link>               (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_levels,
                                             <link linkend="GLogFunc">GLogFunc</link> log_func,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-log-remove-handler">g_log_remove_handler</link>            (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="guint">guint</link> handler_id);
<link linkend="GLogLevelFlags">GLogLevelFlags</link> <link linkend="g-log-set-always-fatal">g_log_set_always_fatal</link>       (<link linkend="GLogLevelFlags">GLogLevelFlags</link> fatal_mask);
<link linkend="GLogLevelFlags">GLogLevelFlags</link> <link linkend="g-log-set-fatal-mask">g_log_set_fatal_mask</link>         (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> fatal_mask);
void        <link linkend="g-log-default-handler">g_log_default_handler</link>           (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="gpointer">gpointer</link> unused_data);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<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 <link linkend="GLogLevelFlags">GLogLevelFlags</link>.
These can be extended with user-defined levels.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-LOG-DOMAIN-CAPS">G_LOG_DOMAIN</title>
<programlisting>#define G_LOG_DOMAIN    ((gchar*) 0)
</programlisting>
<para>
Defines the log domain.
For applications, this is typically left as the default <literal>NULL</literal> (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></refsect2>
<refsect2>
<title><anchor id="G-LOG-FATAL-MASK-CAPS">G_LOG_FATAL_MASK</title>
<programlisting>#define G_LOG_FATAL_MASK        (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)
</programlisting>
<para>
GLib log levels that are considered fatal by default.
</para></refsect2>
<refsect2>
<title><anchor id="G-LOG-LEVEL-USER-SHIFT-CAPS">G_LOG_LEVEL_USER_SHIFT</title>
<programlisting>#define G_LOG_LEVEL_USER_SHIFT  (8)
</programlisting>
<para>
Log level shift offset for user defined log levels (0-7 are used by GLib).
</para></refsect2>
<refsect2>
<title><anchor id="GLogFunc">GLogFunc ()</title>
<programlisting>void        (*GLogFunc)                     (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Specifies the prototype of log handler functions.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>log_domain</parameter>&nbsp;:</entry>
<entry>the log domain of the message.
</entry></row>
<row><entry align="right"><parameter>log_level</parameter>&nbsp;:</entry>
<entry>the log level of the message (including the fatal and recursion
flags).
</entry></row>
<row><entry align="right"><parameter>message</parameter>&nbsp;:</entry>
<entry>the message to process.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data, set in <link linkend="g-log-set-handler">g_log_set_handler</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GLogLevelFlags">enum GLogLevelFlags</title>
<programlisting>typedef enum
{
  /* log flags */
  G_LOG_FLAG_RECURSION          = 1 &lt;&lt; 0,
  G_LOG_FLAG_FATAL              = 1 &lt;&lt; 1,

  /* GLib log levels */
  G_LOG_LEVEL_ERROR             = 1 &lt;&lt; 2,       /* always fatal */
  G_LOG_LEVEL_CRITICAL          = 1 &lt;&lt; 3,
  G_LOG_LEVEL_WARNING           = 1 &lt;&lt; 4,
  G_LOG_LEVEL_MESSAGE           = 1 &lt;&lt; 5,
  G_LOG_LEVEL_INFO              = 1 &lt;&lt; 6,
  G_LOG_LEVEL_DEBUG             = 1 &lt;&lt; 7,

  G_LOG_LEVEL_MASK              = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
} GLogLevelFlags;
</programlisting>
<para>
Flags specifying the level of log messages.
</para></refsect2>
<refsect2>
<title><anchor id="g-log">g_log ()</title>
<programlisting>void        g_log                           (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function><link linkend="abort">abort</link>()</function>
function is called to terminate the program.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>log_domain</parameter>&nbsp;:</entry>
<entry>the log domain, usually <link linkend="G-LOG-DOMAIN-CAPS">G_LOG_DOMAIN</link>.
</entry></row>
<row><entry align="right"><parameter>log_level</parameter>&nbsp;:</entry>
<entry>the log level, either from <link linkend="GLogLevelFlags">GLogLevelFlags</link> or a user-defined level.
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the message format. See the <function>printf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry>the parameters to insert into the format string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-logv">g_logv ()</title>
<programlisting>void        g_logv                          (const <link linkend="gchar">gchar</link> *log_domain,
                                             <link linkend="GLogLevelFlags">GLogLevelFlags</link> log_level,
                                             const <link linkend="gchar">gchar</link> *format,
                                             va_list args);</programlisting>
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function><link linkend="abort">abort</link>()</function>
function is called to terminate the program.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>log_domain</parameter>&nbsp;:</entry>
<entry>the log domain.
</entry></row>
<row><entry align="right"><parameter>log_level</parameter>&nbsp;:</entry>
<entry>the log level.
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry>the message format. See the <function>printf()</function>
documentation.
</entry></row>
<row><entry align="right"><parameter>args</parameter>&nbsp;:</entry>
<entry>the parameters to insert into the format string.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-message">g_message()</title>
<programlisting>#define     g_message(...)</programlisting>
<para>
A convenience function/macro to log a normal message.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>