Message Logging: GLib Reference Manual

## Message Logging Message Logging — versatile support for logging messages with different levels of importance |

## Functions

void | (*GLogFunc) ()
void | g_log ()
void | g_logv ()
#define | g_message()
#define | g_warning()
#define | g_critical()
#define | g_error()
#define | g_info()
#define | g_debug()
guint | g_log_set_handler ()
guint | g_log_set_handler_full ()
void | g_log_remove_handler ()
GLogLevelFlags | g_log_set_always_fatal ()
GLogLevelFlags | g_log_set_fatal_mask ()
void | g_log_default_handler ()
GLogFunc | g_log_set_default_handler ()

## Types and Values

#define | G_LOG_DOMAIN
#define | G_LOG_FATAL_MASK
#define | G_LOG_LEVEL_USER_SHIFT
enum | GLogLevelFlags

## Includes

    #include <glib.h>

## 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.

## Functions

### GLogFunc ()

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

Specifies the prototype of log handler functions.

The default log handler, `g_log_default_handler()`, automatically appends a new-line character to `message` when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed.

#### Parameters

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()` |

### 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.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

#### Parameters

log_domain | the log domain, usually G_LOG_DOMAIN, or `NULL` for the default. | [nullable]
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.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

#### Parameters

log_domain | the log domain, or `NULL` for the default "" application domain. | [nullable]
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(...)

A convenience function/macro to log a normal message.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

### g_warning()

    #define             g_warning(...)

A convenience function/macro to log a warning message.

This is not intended for end user error reporting. Use of GError is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error.

You can make warnings fatal at runtime by setting the `G_DEBUG` environment variable (see Running GLib Applications).

If `g_log_default_handler()` is used as the log handler function, a newline character will automatically be appended to @..., and need not be entered manually.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

### g_critical()

    #define             g_critical(...)

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.

You can also make critical warnings fatal at runtime by setting the `G_DEBUG` environment variable (see Running GLib Applications).

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

### g_error()

    #define             g_error(...)

A convenience function/macro to log an error message.

This is not intended for end user error reporting. Use of GError is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error.

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.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

### g_info()

    #define             g_info(...)

A convenience function/macro to log an informational message. Seldom used.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

Such messages are suppressed by the `g_log_default_handler()` unless the G_MESSAGES_DEBUG environment variable is set appropriately.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

Since: 2.40

### g_debug()

    #define             g_debug(...)

A convenience function/macro to log a debug message.

If `g_log_default_handler()` is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually.

Such messages are suppressed by the `g_log_default_handler()` unless the G_MESSAGES_DEBUG environment variable is set appropriately.

#### Parameters

... | format string, followed by parameters to insert into the format string (as with `printf()`) |

Since: 2.6

### 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_RECURSION 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.

Here is an example for adding a log handler for all warning messages in the default domain:

    1
    2
    g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                       | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

This example adds a log handler for all critical messages from GTK+:

    1
    2
    g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
                       | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

This example adds a log handler for all messages from GLib:

    1
    2
    g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
                       | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

#### Parameters

log_domain | the log domain, or `NULL` for the default "" application domain. | [allow-none]
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

### g_log_set_handler_full ()

    guint
    g_log_set_handler_full (const gchar *log_domain,
                            GLogLevelFlags log_levels,
                            GLogFunc log_func,
                            gpointer user_data,
                            GDestroyNotify destroy);

Like `g_log_sets_handler()`, but takes a destroy notify for the `user_data` .

[rename-to g_log_set_handler]

#### Parameters

log_domain | the log domain, or `NULL` for the default "" application domain. | [allow-none]
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 |
destroy | destroy notify for `user_data` , or `NULL` |

#### Returns

the id of the new handler

Since: 2.46

### g_log_remove_handler ()

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

Removes the log handler.

#### Parameters

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.

You can also make some message levels fatal at runtime by setting the `G_DEBUG` environment variable (see Running GLib Applications).

#### Parameters

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.

#### Parameters

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 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()`. It automatically prints a new-line character after the message, so one does not need to be manually included in `message` .

The behavior of this log handler can be influenced by a number of environment variables:

- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which messages should be prefixed by the program name and PID of the aplication.

- `G_MESSAGES_DEBUG`: A space-separated list of log domains for which debug and informational messages are printed. By default these messages are not printed.

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.

#### Parameters

log_domain | the log domain of the message, or `NULL` for the default "" application domain. | [nullable]
log_level | the level of the message |
message | the message. | [nullable]
unused_data | data passed from `g_log()` which is unused. | [nullable]

### g_log_set_default_handler ()

    GLogFunc
    g_log_set_default_handler (GLogFunc log_func,
                               gpointer user_data);

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.

#### Parameters

log_func | the log handler function |
user_data | data passed to the log handler |

#### Returns

the previous default log handler

Since: 2.6

## Types and Values

### 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:

    1
    AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"

### 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 levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. Higher bits can be used for user-defined log levels.

### enum GLogLevelFlags

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

#### Members

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 warning 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, see `g_info()` |
G_LOG_LEVEL_DEBUG | log level for debug messages, see `g_debug()` |
G_LOG_LEVEL_MASK | a mask including all log levels |