Message Output and Debugging Functions

Message Output and Debugging Functions — functions to output messages and help debug applications

Functions

Types and Values

Includes

#include <glib.h>

Description

These functions provide support for outputting messages.

The g_return family of macros (g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) should only be used for programming errors, a typical use case is checking for invalid parameters at the beginning of a public function. They should not be used if you just mean "if (error) return", they should only be used if you mean "if (bug in program) return". The program behavior is generally considered undefined after one of these checks fails. They are not intended for normal control flow, only to give a perhaps-helpful warning before giving up.

Structured logging output is supported using g_log_structured(). This differs from the traditional g_log() API in that log messages are handled as a collection of key–value pairs representing individual pieces of information, rather than as a single string containing all the information in an arbitrary format.

The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() will use the traditional g_log() API unless you define the symbol G_LOG_USE_STRUCTURED before including glib.h. But note that even messages logged through the traditional g_log() API are ultimatively passed to g_log_structured(), so that all log messages end up in same destination. If G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become ineffective for the wrapper macros g_warning() and friends (see Testing for Messages).

The support for structured logging was motivated by the following needs (some of which were supported previously; others weren’t):

  • Support for multiple logging levels.

  • Structured log support with the ability to add MESSAGE_IDs (see g_log_structured()).

  • Moving the responsibility for filtering log messages from the program to the log viewer — instead of libraries and programs installing log handlers (with g_log_set_handler()) which filter messages before output, all log messages are outputted, and the log viewer program (such as journalctl) must filter them. This is based on the idea that bugs are sometimes hard to reproduce, so it is better to log everything possible and then use tools to analyse the logs than it is to not be able to reproduce a bug to get additional log data. Code which uses logging in performance-critical sections should compile out the g_log_structured() calls in release builds, and compile them in in debugging builds.

  • A single writer function which handles all log messages in a process, from all libraries and program code; rather than multiple log handlers with poorly defined interactions between them. This allows a program to easily change its logging policy by changing the writer function, for example to log to an additional location or to change what logging output fallbacks are used. The log writer functions provided by GLib are exposed publicly so they can be used from programs’ log writers. This allows log writer policy and implementation to be kept separate.

  • If a library wants to add standard information to all of its log messages (such as library state) or to redact private data (such as passwords or network credentials), it should use a wrapper function around its g_log_structured() calls or implement that in the single log writer function.

  • If a program wants to pass context data from a g_log_structured() call to its log writer function so that, for example, it can use the correct server connection to submit logs to, that user data can be passed as a zero-length GLogField to g_log_structured_array().

  • Color output needed to be supported on the terminal, to make reading through logs easier.

Using Structured Logging

To use structured logging (rather than the old-style logging), either use the g_log_structured() and g_log_structured_array() functions; or define G_LOG_USE_STRUCTURED before including any GLib header, and use the g_message(), g_debug(), g_error() (etc.) macros.

You do not need to define G_LOG_USE_STRUCTURED to use g_log_structured(), but it is a good idea to avoid confusion.

Log Domains

Log domains may be used to broadly split up the origins of log messages. Typically, there are one or a few log domains per application or library. G_LOG_DOMAIN should be used to define the default log domain for the current compilation unit — it is typically defined at the top of a source file, or in the preprocessor flags for a group of source files.

Log domains must be unique, and it is recommended that they are the application or library name, optionally followed by a hyphen and a sub-domain name. For example, bloatpad or bloatpad-io.

Debug Message Output

The default log functions (g_log_default_handler() for the old-style API and g_log_writer_default() for the structured API) both drop debug and informational messages by default, unless the log domains of those messages are listed in the G_MESSAGES_DEBUG environment variable (or it is set to all).

It is recommended that custom log writer functions re-use the G_MESSAGES_DEBUG environment variable, rather than inventing a custom one, so that developers can re-use the same debugging techniques and tools across projects. Since GLib 2.68, this can be implemented by dropping messages for which g_log_writer_default_would_drop() returns TRUE.

Testing for Messages

With the old g_log() API, g_test_expect_message() and g_test_assert_expected_messages() could be used in simple cases to check whether some code under test had emitted a given log message. These functions have been deprecated with the structured logging API, for several reasons:

  • They relied on an internal queue which was too inflexible for many use cases, where messages might be emitted in several orders, some messages might not be emitted deterministically, or messages might be emitted by unrelated log domains.

  • They do not support structured log fields.

  • Examining the log output of code is a bad approach to testing it, and while it might be necessary for legacy code which uses g_log(), it should be avoided for new code using g_log_structured().

They will continue to work as before if g_log() is in use (and G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the structured logging API.

Examining the log output of code is discouraged: libraries should not emit to stderr during defined behaviour, and hence this should not be tested. If the log emissions of a library during undefined behaviour need to be tested, they should be limited to asserting that the library aborts and prints a suitable error message before aborting. This should be done with g_test_trap_assert_stderr().

If it is really necessary to test the structured log messages emitted by a particular piece of code – and the code cannot be restructured to be more suitable to more conventional unit testing – you should write a custom log writer function (see g_log_set_writer_func()) which appends all log messages to a queue. When you want to check the log messages, examine and clear the queue, ignoring irrelevant log messages (for example, from log domains other than the one under test).

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.

This is not used if structured logging is enabled; see Using Structured Logging.

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, G_BREAKPOINT() is called to terminate the program. See the documentation for G_BREAKPOINT() for details of the debugging options this provides.

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.

If structured logging is enabled this will output via the structured log writer function (see g_log_set_writer_func()).

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, G_BREAKPOINT() is called to terminate the program. See the documentation for G_BREAKPOINT() for details of the debugging options this provides.

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.

If structured logging is enabled this will output via the structured log writer function (see g_log_set_writer_func()).

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.

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

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. The message should typically *not* be translated to the user's language.

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.

Warning messages are intended to be used in the event of unexpected external conditions (system misconfiguration, missing files, other trusted programs violating protocol, invalid contents in trusted files, etc.)

If attempting to deal with programmer errors (for example, incorrect function parameters) then you should use G_LOG_LEVEL_CRITICAL instead.

g_warn_if_reached() and g_warn_if_fail() log at G_LOG_LEVEL_WARNING.

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

1
G_DEBUG=fatal-warnings gdb ./my-program

Any unrelated failures can be skipped over in gdb using the continue command.

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.

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

Parameters

...

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

 

g_warning_once()

#define             g_warning_once(...)

Logs a warning only once.

g_warning_once() calls g_warning() with the passed message the first time the statement is executed; subsequent times it is a no-op.

Note! On platforms where the compiler doesn't support variadic macros, the warning is printed each time instead of only once.

Parameters

...

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

 

Since: 2.64


g_critical()

#define             g_critical(...)

Logs a "critical warning" (G_LOG_LEVEL_CRITICAL).

Critical warnings are intended to be used in the event of an error that originated in the current process (a programmer error). Logging of a critical error is by definition an indication of a bug somewhere in the current program (or its libraries).

g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and g_return_val_if_reached() log at G_LOG_LEVEL_CRITICAL.

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

1
G_DEBUG=fatal-warnings gdb ./my-program

You can also use g_log_set_always_fatal().

Any unrelated failures can be skipped over in gdb using the continue command.

The message should typically *not* be translated to the user's language.

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.

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

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. The message should typically *not* be translated to the user's language.

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

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

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() and g_log_writer_default() unless the G_MESSAGES_DEBUG environment variable is set appropriately.

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

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. The message should typically *not* be translated to the user's language.

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() and g_log_writer_default() unless the G_MESSAGES_DEBUG environment variable is set appropriately.

If structured logging is enabled, this will use g_log_structured(); otherwise it will use g_log(). See Using Structured Logging.

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.

This has no effect if structured logging is enabled; see Using Structured Logging.

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.

[nullable]

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_set_handler(), but takes a destroy notify for the user_data .

This has no effect if structured logging is enabled; see Using Structured Logging.

[rename-to g_log_set_handler]

Parameters

log_domain

the log domain, or NULL for the default "" application domain.

[nullable]

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.

This has no effect if structured logging is enabled; see Using Structured Logging.

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

Libraries should not call this function, as it affects all messages logged by a process, including those from other libraries.

Structured log messages (using g_log_structured() and g_log_structured_array()) are fatal only if the default log writer is used; otherwise it is up to the writer function to determine which log messages are fatal. See Using Structured Logging.

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.

This has no effect on structured log messages (using g_log_structured() or g_log_structured_array()). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using g_log_set_writer_func(). See Using Structured Logging.

This function is mostly intended to be used with G_LOG_LEVEL_CRITICAL. You should typically not set G_LOG_LEVEL_WARNING, G_LOG_LEVEL_MESSAGE, G_LOG_LEVEL_INFO or G_LOG_LEVEL_DEBUG as fatal except inside of test programs.

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 G_BREAKPOINT(). 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 application.

  • 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, unless stderr was requested by g_log_writer_default_set_use_stderr().

This has no effect if structured logging is enabled; see Using Structured Logging.

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.

This has no effect if structured logging is enabled; see Using Structured Logging.

Parameters

log_func

the log handler function

 

user_data

data passed to the log handler

 

Returns

the previous default log handler

Since: 2.6


g_log_get_debug_enabled ()

gboolean
g_log_get_debug_enabled (void);

Return whether debug output from the GLib logging system is enabled.

Note that this should not be used to conditionalise calls to g_debug() or other logging functions; it should only be used from GLogWriterFunc implementations.

Note also that the value of this does not depend on G_MESSAGES_DEBUG; see the docs for g_log_set_debug_enabled().

Returns

TRUE if debug output is enabled, FALSE otherwise

Since: 2.72


g_log_set_debug_enabled ()

void
g_log_set_debug_enabled (gboolean enabled);

Enable or disable debug output from the GLib logging system for all domains. This value interacts disjunctively with G_MESSAGES_DEBUG — if either of them would allow a debug message to be outputted, it will be.

Note that this should not be used from within library code to enable debug output — it is intended for external use.

Parameters

enabled

TRUE to enable debug output, FALSE otherwise

 

Since: 2.72


g_log_structured ()

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

Log a message with structured data.

The message will be passed through to the log writer set by the application using g_log_set_writer_func(). If the message is fatal (i.e. its log level is G_LOG_LEVEL_ERROR), the program will be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. See the documentation for GLogWriterFunc for information on chaining writers.

The structured data is provided as key–value pairs, where keys are UTF-8 strings, and values are arbitrary pointers — typically pointing to UTF-8 strings, but that is not a requirement. To pass binary (non-nul-terminated) structured data, use g_log_structured_array(). The keys for structured data should follow the systemd journal fields specification. It is suggested that custom keys are namespaced according to the code which sets them. For example, custom keys from GLib all have a GLIB_ prefix.

Note that keys that expect UTF-8 strings (specifically "MESSAGE" and "GLIB_DOMAIN") must be passed as NUL-terminated UTF-8 strings until GLib version 2.74.1 because the default log handler did not consider the length of the GLogField. Starting with GLib 2.74.1 this is fixed and non-NUL-terminated UTF-8 strings can be passed with their correct length.

The log_domain will be converted into a GLIB_DOMAIN field. log_level will be converted into a PRIORITY field. The format string will have its placeholders substituted for the provided values and be converted into a MESSAGE field.

Other fields you may commonly want to pass into this function:

Note that CODE_FILE, CODE_LINE and CODE_FUNC are automatically set by the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), g_error(), etc, if the symbols G_LOG_USE_STRUCTURED is defined before including glib.h.

For example:

1
2
3
4
5
g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
                  "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
                  "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
                  "MESSAGE", "This is a debug message about pointer %p and integer %u.",
                  some_pointer, some_integer);

Note that each MESSAGE_ID must be uniquely and randomly generated. If adding a MESSAGE_ID, consider shipping a message catalog with your software.

To pass a user data pointer to the log writer function which is specific to this logging call, you must use g_log_structured_array() and pass the pointer as a field with GLogField.length set to zero, otherwise it will be interpreted as a string.

For example:

1
2
3
4
5
6
7
const GLogField fields[] = {
  { "MESSAGE", "This is a debug message.", -1 },
  { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
  { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
  { "MY_APPLICATION_STATE", state_object, 0 },
};
g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));

Note also that, even if no other structured fields are specified, there must always be a MESSAGE key before the format string. The MESSAGE-format pair has to be the last of the key-value pairs, and MESSAGE is the only field for which printf()-style formatting is supported.

The default writer function for stdout and stderr will automatically append a new-line character after the message, so you should not add one manually to the format string.

Parameters

log_domain

log domain, usually G_LOG_DOMAIN

 

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

...

key-value pairs of structured data to add to the log entry, followed by the key "MESSAGE", followed by a printf()-style message format, followed by parameters to insert in the format string

 

Since: 2.50


g_log_variant ()

void
g_log_variant (const gchar *log_domain,
               GLogLevelFlags log_level,
               GVariant *fields);

Log a message with structured data, accepting the data within a GVariant. This version is especially useful for use in other languages, via introspection.

The only mandatory item in the fields dictionary is the "MESSAGE" which must contain the text shown to the user.

The values in the fields dictionary are likely to be of type String (G_VARIANT_TYPE_STRING). Array of bytes (G_VARIANT_TYPE_BYTESTRING) is also supported. In this case the message is handled as binary and will be forwarded to the log writer as such. The size of the array should not be higher than G_MAXSSIZE. Otherwise it will be truncated to this size. For other types g_variant_print() will be used to convert the value into a string.

For more details on its usage and about the parameters, see g_log_structured().

Parameters

log_domain

log domain, usually G_LOG_DOMAIN.

[nullable]

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

a dictionary (GVariant of the type G_VARIANT_TYPE_VARDICT) containing the key-value pairs of message data.

 

Since: 2.50


g_log_structured_array ()

void
g_log_structured_array (GLogLevelFlags log_level,
                        const GLogField *fields,
                        gsize n_fields);

Log a message with structured data. The message will be passed through to the log writer set by the application using g_log_set_writer_func(). If the message is fatal (i.e. its log level is G_LOG_LEVEL_ERROR), the program will be aborted at the end of this function.

See g_log_structured() for more documentation.

This assumes that log_level is already present in fields (typically as the PRIORITY field).

Parameters

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

key–value pairs of structured data to add to the log message.

[array length=n_fields]

n_fields

number of elements in the fields array

 

Since: 2.50


G_DEBUG_HERE

#define             G_DEBUG_HERE()

A convenience form of g_log_structured(), recommended to be added to functions when debugging. It prints the current monotonic time and the code location using G_STRLOC.

Since: 2.50


GLogWriterFunc ()

GLogWriterOutput
(*GLogWriterFunc) (GLogLevelFlags log_level,
                   const GLogField *fields,
                   gsize n_fields,
                   gpointer user_data);

Writer function for log entries. A log entry is a collection of one or more GLogFields, using the standard field names from journal specification. See g_log_structured() for more information.

Writer functions must ignore fields which they do not recognise, unless they can write arbitrary binary output, as field values may be arbitrary binary.

log_level is guaranteed to be included in fields as the PRIORITY field, but is provided separately for convenience of deciding whether or where to output the log entry.

Writer functions should return G_LOG_WRITER_HANDLED if they handled the log message successfully or if they deliberately ignored it. If there was an error handling the message (for example, if the writer function is meant to send messages to a remote logging server and there is a network error), it should return G_LOG_WRITER_UNHANDLED. This allows writer functions to be chained and fall back to simpler handlers in case of failure.

Parameters

log_level

log level of the message

 

fields

fields forming the message.

[array length=n_fields]

n_fields

number of fields

 

user_data

user data passed to g_log_set_writer_func()

 

Returns

G_LOG_WRITER_HANDLED if the log entry was handled successfully; G_LOG_WRITER_UNHANDLED otherwise

Since: 2.50


g_log_set_writer_func ()

void
g_log_set_writer_func (GLogWriterFunc func,
                       gpointer user_data,
                       GDestroyNotify user_data_free);

Set a writer function which will be called to format and write out each log message. Each program should set a writer function, or the default writer (g_log_writer_default()) will be used.

Libraries **must not** call this function — only programs are allowed to install a writer function, as there must be a single, central point where log messages are formatted and outputted.

There can only be one writer function. It is an error to set more than one.

Parameters

func

log writer function, which must not be NULL

 

user_data

user data to pass to func .

[closure func]

user_data_free

function to free user_data once it’s finished with, if non-NULL.

[destroy func]

Since: 2.50


g_log_writer_supports_color ()

gboolean
g_log_writer_supports_color (gint output_fd);

Check whether the given output_fd file descriptor supports ANSI color escape sequences. If so, they can safely be used when formatting log messages.

Parameters

output_fd

output file descriptor to check

 

Returns

TRUE if ANSI color escapes are supported, FALSE otherwise

Since: 2.50


g_log_writer_is_journald ()

gboolean
g_log_writer_is_journald (gint output_fd);

Check whether the given output_fd file descriptor is a connection to the systemd journal, or something else (like a log file or stdout or stderr).

Invalid file descriptors are accepted and return FALSE, which allows for the following construct without needing any additional error handling:

1
is_journald = g_log_writer_is_journald (fileno (stderr));

Parameters

output_fd

output file descriptor to check

 

Returns

TRUE if output_fd points to the journal, FALSE otherwise

Since: 2.50


g_log_writer_format_fields ()

gchar *
g_log_writer_format_fields (GLogLevelFlags log_level,
                            const GLogField *fields,
                            gsize n_fields,
                            gboolean use_color);

Format a structured log message as a string suitable for outputting to the terminal (or elsewhere). This will include the values of all fields it knows how to interpret, which includes MESSAGE and GLIB_DOMAIN (see the documentation for g_log_structured()). It does not include values from unknown fields.

The returned string does **not** have a trailing new-line character. It is encoded in the character set of the current locale, which is not necessarily UTF-8.

Parameters

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

key–value pairs of structured data forming the log message.

[array length=n_fields]

n_fields

number of elements in the fields array

 

use_color

TRUE to use ANSI color escape sequences when formatting the message, FALSE to not

 

Returns

string containing the formatted log message, in the character set of the current locale.

[transfer full]

Since: 2.50


g_log_writer_journald ()

GLogWriterOutput
g_log_writer_journald (GLogLevelFlags log_level,
                       const GLogField *fields,
                       gsize n_fields,
                       gpointer user_data);

Format a structured log message and send it to the systemd journal as a set of key–value pairs. All fields are sent to the journal, but if a field has length zero (indicating program-specific data) then only its key will be sent.

This is suitable for use as a GLogWriterFunc.

If GLib has been compiled without systemd support, this function is still defined, but will always return G_LOG_WRITER_UNHANDLED.

Parameters

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

key–value pairs of structured data forming the log message.

[array length=n_fields]

n_fields

number of elements in the fields array

 

user_data

user data passed to g_log_set_writer_func()

 

Returns

G_LOG_WRITER_HANDLED on success, G_LOG_WRITER_UNHANDLED otherwise

Since: 2.50


g_log_writer_standard_streams ()

GLogWriterOutput
g_log_writer_standard_streams (GLogLevelFlags log_level,
                               const GLogField *fields,
                               gsize n_fields,
                               gpointer user_data);

Format a structured log message and print it to either stdout or stderr, depending on its log level. G_LOG_LEVEL_INFO and G_LOG_LEVEL_DEBUG messages are sent to stdout, or to stderr if requested by g_log_writer_default_set_use_stderr(); all other log levels are sent to stderr. Only fields which are understood by this function are included in the formatted string which is printed.

If the output stream supports ANSI color escape sequences, they will be used in the output.

A trailing new-line character is added to the log message when it is printed.

This is suitable for use as a GLogWriterFunc.

Parameters

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

key–value pairs of structured data forming the log message.

[array length=n_fields]

n_fields

number of elements in the fields array

 

user_data

user data passed to g_log_set_writer_func()

 

Returns

G_LOG_WRITER_HANDLED on success, G_LOG_WRITER_UNHANDLED otherwise

Since: 2.50


g_log_writer_default ()

GLogWriterOutput
g_log_writer_default (GLogLevelFlags log_level,
                      const GLogField *fields,
                      gsize n_fields,
                      gpointer user_data);

Format a structured log message and output it to the default log destination for the platform. On Linux, this is typically the systemd journal, falling back to stdout or stderr if running from the terminal or if output is being redirected to a file.

Support for other platform-specific logging mechanisms may be added in future. Distributors of GLib may modify this function to impose their own (documented) platform-specific log writing policies.

This is suitable for use as a GLogWriterFunc, and is the default writer used if no other is set using g_log_set_writer_func().

As with g_log_default_handler(), this function drops debug and informational messages unless their log domain (or all) is listed in the space-separated G_MESSAGES_DEBUG environment variable.

g_log_writer_default() uses the mask set by g_log_set_always_fatal() to determine which messages are fatal. When using a custom writer func instead it is up to the writer function to determine which log messages are fatal.

Parameters

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

fields

key–value pairs of structured data forming the log message.

[array length=n_fields]

n_fields

number of elements in the fields array

 

user_data

user data passed to g_log_set_writer_func()

 

Returns

G_LOG_WRITER_HANDLED on success, G_LOG_WRITER_UNHANDLED otherwise

Since: 2.50


g_log_writer_default_set_use_stderr ()

void
g_log_writer_default_set_use_stderr (gboolean use_stderr);

Configure whether the built-in log functions (g_log_default_handler() for the old-style API, and both g_log_writer_default() and g_log_writer_standard_streams() for the structured API) will output all log messages to stderr.

By default, log messages of levels G_LOG_LEVEL_INFO and G_LOG_LEVEL_DEBUG are sent to stdout, and other log messages are sent to stderr. This is problematic for applications that intend to reserve stdout for structured output such as JSON or XML.

This function sets global state. It is not thread-aware, and should be called at the very start of a program, before creating any other threads or creating objects that could create worker threads of their own.

Parameters

use_stderr

If TRUE, use stderr for log messages that would normally have appeared on stdout

 

Since: 2.68


g_log_writer_default_would_drop ()

gboolean
g_log_writer_default_would_drop (GLogLevelFlags log_level,
                                 const char *log_domain);

Check whether g_log_writer_default() and g_log_default_handler() would ignore a message with the given domain and level.

As with g_log_default_handler(), this function drops debug and informational messages unless their log domain (or all) is listed in the space-separated G_MESSAGES_DEBUG environment variable.

This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format:

1
2
if (g_log_writer_default_would_drop (log_level, log_domain))
  return G_LOG_WRITER_HANDLED;

or to skip an expensive computation if it is only needed for a debugging message, and G_MESSAGES_DEBUG is not set:

1
2
3
4
5
6
7
if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN))
  {
    gchar *result = expensive_computation (my_object);

    g_debug ("my_object result: %s", result);
    g_free (result);
  }

Parameters

log_domain

log domain.

[nullable]

log_level

log level, either from GLogLevelFlags, or a user-defined level

 

Returns

TRUE if the log message would be dropped by GLib's default log handlers

Since: 2.68

Types and Values

G_LOG_DOMAIN

#define G_LOG_DOMAIN    ((gchar*) 0)

Defines the log domain. See Log Domains.

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.

Log domains must be unique, and it is recommended that they are the application or library name, optionally followed by a hyphen and a sub-domain name. For example, bloatpad or bloatpad-io.

If undefined, it defaults to the default NULL (or "") log domain; this is not advisable, as it cannot be filtered against using the G_MESSAGES_DEBUG environment variable.

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

1
AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"

Applications can choose to leave it as the default NULL (or "") domain. However, defining the domain offers the same advantages as above.


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.

This is not used if structured logging is enabled; see Using Structured Logging.


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

 

struct GLogField

struct GLogField {
  const gchar *key;
  gconstpointer value;
  gssize length;
};

Structure representing a single field in a structured log entry. See g_log_structured() for details.

Log fields may contain arbitrary values, including binary with embedded nul bytes. If the field contains a string, the string must be UTF-8 encoded and have a trailing nul byte. Otherwise, length must be set to a non-negative value.

Members

const gchar *key;

field name (UTF-8 string)

 

gconstpointer value;

field value (arbitrary bytes)

 

gssize length;

length of value , in bytes, or -1 if it is nul-terminated

 

Since: 2.50


enum GLogWriterOutput

Return values from GLogWriterFuncs to indicate whether the given log entry was successfully handled by the writer, or whether there was an error in handling it (and hence a fallback writer should be used).

If a GLogWriterFunc ignores a log entry, it should return G_LOG_WRITER_HANDLED.

Members

G_LOG_WRITER_HANDLED

Log writer has handled the log entry.

 

G_LOG_WRITER_UNHANDLED

Log writer could not handle the log entry.

 

Since: 2.50