Message Output and Debugging Functions

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

Functions

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

Functions

g_print ()

void
g_print (const gchar *format,
         ...);

Outputs a formatted message via the print handler. The default print handler simply outputs the message to stdout, without appending a trailing new-line character. Typically, format should end with its own new-line character.

g_print() should not be used from within libraries for debugging messages, since it may be redirected by applications to special purpose message windows or even files. Instead, libraries should use g_log(), or the convenience functions g_message(), g_warning() and g_error().

Parameters

format

the message format. See the printf() documentation

 

...

the parameters to insert into the format string

 

g_set_print_handler ()

GPrintFunc
g_set_print_handler (GPrintFunc func);

Sets the print handler.

Any messages passed to g_print() will be output via the new handler. The default handler simply outputs the message to stdout. By providing your own handler you can redirect the output, to a GTK+ widget or a log file for example.

Parameters

func

the new print handler

 

Returns

the old print handler


GPrintFunc ()

void
(*GPrintFunc) (const gchar *string);

Specifies the type of the print handler functions. These are called with the complete formatted string to output.

Parameters

string

the message to output

 

g_printerr ()

void
g_printerr (const gchar *format,
            ...);

Outputs a formatted message via the error message handler. The default handler simply outputs the message to stderr, without appending a trailing new-line character. Typically, format should end with its own new-line character.

g_printerr() should not be used from within libraries. Instead g_log() should be used, or the convenience functions g_message(), g_warning() and g_error().

Parameters

format

the message format. See the printf() documentation

 

...

the parameters to insert into the format string

 

g_set_printerr_handler ()

GPrintFunc
g_set_printerr_handler (GPrintFunc func);

Sets the handler for printing error messages.

Any messages passed to g_printerr() will be output via the new handler. The default handler simply outputs the message to stderr. By providing your own handler you can redirect the output, to a GTK+ widget or a log file for example.

Parameters

func

the new error message handler

 

Returns

the old error message handler


g_return_if_fail()

#define             g_return_if_fail(expr)

Verifies that the expression expr , usually representing a precondition, evaluates to TRUE. If the function returns a value, use g_return_val_if_fail() instead.

If expr evaluates to FALSE, the current function should be considered to have undefined behaviour (a programmer error). The only correct solution to such an error is to change the module that is calling the current function, so that it avoids this incorrect call.

To make this undefined behaviour visible, if expr evaluates to FALSE, the result is usually that a critical message is logged and the current function returns.

If G_DISABLE_CHECKS is defined then the check is not performed. You should therefore not depend on any side effects of expr .

Parameters

expr

the expression to check

 

g_return_val_if_fail()

#define             g_return_val_if_fail(expr,val)

Verifies that the expression expr , usually representing a precondition, evaluates to TRUE. If the function does not return a value, use g_return_if_fail() instead.

If expr evaluates to FALSE, the current function should be considered to have undefined behaviour (a programmer error). The only correct solution to such an error is to change the module that is calling the current function, so that it avoids this incorrect call.

To make this undefined behaviour visible, if expr evaluates to FALSE, the result is usually that a critical message is logged and val is returned from the current function.

If G_DISABLE_CHECKS is defined then the check is not performed. You should therefore not depend on any side effects of expr .

Parameters

expr

the expression to check

 

val

the value to return from the current function if the expression is not true

 

g_return_if_reached

#define             g_return_if_reached()

Logs a critical message and returns from the current function. This can only be used in functions which do not return a value.


g_return_val_if_reached()

#define             g_return_val_if_reached(val)

Logs a critical message and returns val .

Parameters

val

the value to return from the current function

 

g_warn_if_fail()

#define             g_warn_if_fail(expr)

Logs a warning if the expression is not true.

Parameters

expr

the expression to check

 

Since: 2.16


g_warn_if_reached

#define             g_warn_if_reached()

Logs a warning.

Since: 2.16


g_on_error_query ()

void
g_on_error_query (const gchar *prg_name);

Prompts the user with [E]xit, [H]alt, show [S]tack trace or [P]roceed. This function is intended to be used for debugging use only. The following example shows how it can be used together with the g_log() functions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#include <glib.h>

static void
log_handler (const gchar   *log_domain,
             GLogLevelFlags log_level,
             const gchar   *message,
             gpointer       user_data)
{
  g_log_default_handler (log_domain, log_level, message, user_data);

  g_on_error_query (MY_PROGRAM_NAME);
}

int
main (int argc, char *argv[])
{
  g_log_set_handler (MY_LOG_DOMAIN,
                     G_LOG_LEVEL_WARNING |
                     G_LOG_LEVEL_ERROR |
                     G_LOG_LEVEL_CRITICAL,
                     log_handler,
                     NULL);
  ...

If "[E]xit" is selected, the application terminates with a call to _exit(0).

If "[S]tack" trace is selected, g_on_error_stack_trace() is called. This invokes gdb, which attaches to the current process and shows a stack trace. The prompt is then shown again.

If "[P]roceed" is selected, the function returns.

This function may cause different actions on non-UNIX platforms.

Parameters

prg_name

the program name, needed by gdb for the "[S]tack trace" option. If prg_name is NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called)

 

g_on_error_stack_trace ()

void
g_on_error_stack_trace (const gchar *prg_name);

Invokes gdb, which attaches to the current process and shows a stack trace. Called by g_on_error_query() when the "[S]tack trace" option is selected. You can get the current process's program name with g_get_prgname(), assuming that you have called gtk_init() or gdk_init().

This function may cause different actions on non-UNIX platforms.

Parameters

prg_name

the program name, needed by gdb for the "[S]tack trace" option

 

G_BREAKPOINT

#  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END

Inserts a breakpoint instruction into the code.

On x86 and alpha systems this is implemented as a soft interrupt and on other architectures it raises a SIGTRAP signal.

Types and Values