Top | ![]() |
![]() |
![]() |
![]() |
Message Output and Debugging FunctionsMessage Output and Debugging Functions — functions to output messages and help debug applications |
void | g_print () |
GPrintFunc | g_set_print_handler () |
void | (*GPrintFunc) () |
void | g_printerr () |
GPrintFunc | g_set_printerr_handler () |
#define | g_return_if_fail() |
#define | g_return_val_if_fail() |
#define | g_return_if_reached |
#define | g_return_val_if_reached() |
#define | g_warn_if_fail() |
#define | g_warn_if_reached |
void | g_on_error_query () |
void | g_on_error_stack_trace () |
#define | G_BREAKPOINT |
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_ID
s (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.
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()
.
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.
void
(*GPrintFunc) (const gchar *string
);
Specifies the type of the print handler functions. These are called with the complete formatted string to output.
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()
.
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.
#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
.
#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
.
#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.
#define g_return_val_if_reached(val)
Logs a critical message and returns val
.
#define g_warn_if_fail(expr)
Logs a warning if the expression is not true.
Since: 2.16
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.
prg_name |
the program name, needed by gdb for the "[S]tack trace"
option. If |
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.