| <!-- ##### 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 ##### --> |
| |
| |
| <!-- ##### 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. |
| </para> |
| |
| @G_LOG_FLAG_RECURSION: |
| @G_LOG_FLAG_FATAL: |
| @G_LOG_LEVEL_ERROR: |
| @G_LOG_LEVEL_CRITICAL: |
| @G_LOG_LEVEL_WARNING: |
| @G_LOG_LEVEL_MESSAGE: |
| @G_LOG_LEVEL_INFO: |
| @G_LOG_LEVEL_DEBUG: |
| @G_LOG_LEVEL_MASK: |
| |
| <!-- ##### 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> |
| |
| @...: 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> |
| |
| @...: 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> |
| |
| @...: the parameters to insert into the format string. |
| @...: |
| @...: |
| @...: |
| |
| @...: |
| |
| @...: |
| |
| @...: |
| |
| @...: |
| |
| @...: |
| |
| |
| <!-- ##### 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> |
| |
| @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 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 |
| |
| |