GLib Reference Manual
<<< Previous PageHomeUpNext Page >>>

Message Logging

Name

Message Logging -- versatile support for logging messages with different levels of importance.

Synopsis


#include <glib.h>


#define     G_LOG_DOMAIN
extern      const gchar		*g_log_domain_glib;
extern      const char      *g_log_domain_gmodule;
#define     G_LOG_FATAL_MASK
#define     G_LOG_LEVEL_USER_SHIFT
void        (*GLogFunc)                     (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer user_data);
enum        GLogLevelFlags;

void        g_log                           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             ...);
void        g_logv                          (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             va_list args);
#define     g_message                       (format, args...)
#define     g_warning                       (format, args...)
#define     g_error                         (format, args...)

guint       g_log_set_handler               (const gchar *log_domain,
                                             GLogLevelFlags log_levels,
                                             GLogFunc log_func,
                                             gpointer user_data);
void        g_log_remove_handler            (const gchar *log_domain,
                                             guint handler_id);
GLogLevelFlags g_log_set_always_fatal       (GLogLevelFlags fatal_mask);
GLogLevelFlags g_log_set_fatal_mask         (const gchar *log_domain,
                                             GLogLevelFlags fatal_mask);
void        g_log_default_handler           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer unused_data);

GErrorFunc  g_set_error_handler             (GErrorFunc func);
void        (*GErrorFunc)                   (const gchar *str);
GWarningFunc g_set_warning_handler          (GWarningFunc func);
void        (*GWarningFunc)                 (const gchar *str);
GPrintFunc  g_set_message_handler           (GPrintFunc func);

Description

These functions provide support for logging error messages or messages used for debugging.

There are several built-in levels of messages, defined in GLogLevelFlags. These can be extended with user-defined levels.

Details

G_LOG_DOMAIN

#define	G_LOG_DOMAIN	((gchar*) 0)

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.

For example, GTK uses this in its Makefile.am: 

INCLUDES = \
	-DG_LOG_DOMAIN=\"Gtk\"

g_log_domain_glib

extern	        const gchar		*g_log_domain_glib;

g_log_domain_gmodule

extern const char      *g_log_domain_gmodule;

G_LOG_FATAL_MASK

#define	G_LOG_FATAL_MASK	(G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)

GLib log levels that are considered fatal by default.

G_LOG_LEVEL_USER_SHIFT

#define	G_LOG_LEVEL_USER_SHIFT	(8)

Log level shift offset for user defined log levels (0-7 are used by GLib).

GLogFunc ()

void        (*GLogFunc)                     (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer user_data);

Specifies the prototype of log handler functions.

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

typedef enum
{
  /* log flags */
  G_LOG_FLAG_RECURSION		= 1 << 0,
  G_LOG_FLAG_FATAL		= 1 << 1,
  
  /* GLib log levels */
  G_LOG_LEVEL_ERROR		= 1 << 2,	/* always fatal */
  G_LOG_LEVEL_CRITICAL		= 1 << 3,
  G_LOG_LEVEL_WARNING		= 1 << 4,
  G_LOG_LEVEL_MESSAGE		= 1 << 5,
  G_LOG_LEVEL_INFO		= 1 << 6,
  G_LOG_LEVEL_DEBUG		= 1 << 7,
  
  G_LOG_LEVEL_MASK		= ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
} GLogLevelFlags;

Flags specifying the level of log messages.

g_log ()

void        g_log                           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             ...);

Logs an error or debugging message. If the log level has been set as fatal, the abort() function is called to terminate the program.

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.
... :the parameters to insert into the format string.

g_logv ()

void        g_logv                          (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *format,
                                             va_list args);

Logs an error or debugging message. If the log level has been set as fatal, the abort() function is called to terminate the program.

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.

g_message()

#define     g_message(format, args...)

A convenience function/macro to log a normal message.

format :the message format. See the printf() documentation.
args... :the parameters to insert into the format string.

g_warning()

#define     g_warning(format, args...)

A convenience function/macro to log a warning message.

format :the message format. See the printf() documentation.
args... :the parameters to insert into the format string.

g_error()

#define     g_error(format, args...)

A convenience function/macro to log an error message. Error messages are always fatal, resulting in a call to abort() to terminate the application.

format :the message format. See the printf() documentation.
args... :the parameters to insert into the format string.

g_log_set_handler ()

guint       g_log_set_handler               (const gchar *log_domain,
                                             GLogLevelFlags log_levels,
                                             GLogFunc log_func,
                                             gpointer user_data);

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_RECURSIVE bit flags.

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.

Example 1. Adding a log handler for all warning messages

  g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                     | G_LOG_FLAG_RECURSIVE, my_log_handler, NULL);

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_RECURSIVE bit flags.
log_func :the log handler function.
user_data :data passed to the log handler.
Returns :the id of the new handler.

g_log_remove_handler ()

void        g_log_remove_handler            (const gchar *log_domain,
                                             guint handler_id);

Removes the log handler.

log_domain :the log domain.
handler_id :the id of the handler, which was returned in g_log_set_handler().

g_log_set_always_fatal ()

GLogLevelFlags g_log_set_always_fatal       (GLogLevelFlags fatal_mask);

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.

fatal_mask :the mask containing bits set for each level of error which is to be fatal.
Returns :the old fatal mask.

g_log_set_fatal_mask ()

GLogLevelFlags g_log_set_fatal_mask         (const gchar *log_domain,
                                             GLogLevelFlags fatal_mask);

Sets the log levels which are fatal in the given domain. G_LOG_LEVEL_ERROR is always fatal.

log_domain :the log domain.
fatal_mask :the new fatal mask.
Returns :the old fatal mask for the log domain.

g_log_default_handler ()

void        g_log_default_handler           (const gchar *log_domain,
                                             GLogLevelFlags log_level,
                                             const gchar *message,
                                             gpointer unused_data);

The 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().

stderr is used for levels G_LOG_LEVEL_ERROR, G_LOG_LEVEL_CRITICAL, and G_LOG_LEVEL_WARNING. stdout is used for the rest. (On the Windows platform, stdout is always used.)

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.

g_set_error_handler ()

GErrorFunc  g_set_error_handler             (GErrorFunc func);

Sets the function to be called to handle error messages. This function is deprecated in favour of the new logging facilities.

func :the function to be called to handle error messages.
Returns :the old error handler.

GErrorFunc ()

void        (*GErrorFunc)                   (const gchar *str);

Specifies the type of function passed to g_set_error_handler().

str :the error message.

g_set_warning_handler ()

GWarningFunc g_set_warning_handler          (GWarningFunc func);

Sets the function to be called to handle warning messages. This function is deprecated in favour of the new logging facilities.

func :the function to be called to handle warning messages.
Returns :the old warning handler.

GWarningFunc ()

void        (*GWarningFunc)                 (const gchar *str);

Specifies the type of function passed to g_set_warning_handler().

str :the warning message.

g_set_message_handler ()

GPrintFunc  g_set_message_handler           (GPrintFunc func);

Sets the function to be called to handle messages. This function is deprecated in favour of the new logging facilities.

func :the function to be called to handle normal messages.
Returns :the old message handler.



<<< Previous PageHomeUpNext Page >>>
Message Output and Debugging FunctionsGLib Utilities