Message Output and Debugging Functions

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

## Synopsis

    #include <glib.h>

    void                g_print                             (const gchar *format,
                                                             ...);
    GPrintFunc          g_set_print_handler                 (GPrintFunc func);
    void                (*GPrintFunc)                       (const gchar *string);

    void                g_printerr                          (const gchar *format,
                                                             ...);
    GPrintFunc          g_set_printerr_handler              (GPrintFunc func);

    #define             g_return_if_fail                    (expr)
    #define             g_return_val_if_fail                (expr,
                                                             val)
    #define             g_return_if_reached
    #define             g_return_val_if_reached             (val)
    #define             g_warn_if_fail                      (expr)
    #define             g_warn_if_reached

    void                g_on_error_query                    (const gchar *prg_name);
    void                g_on_error_stack_trace              (const gchar *prg_name);

    #define             G_BREAKPOINT

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

## Details

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

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

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

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

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

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

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

`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 evaluates to `TRUE`. If the expression evaluates to `FALSE`, a critical message is logged and the current function returns. This can only be used in functions which do not return a value.

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

`expr` : | the expression to check

### g_return_val_if_fail()

    #define             g_return_val_if_fail(expr,val)

Verifies that the expression evaluates to `TRUE`. If the expression evaluates to `FALSE`, 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`.

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

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

`expr` : | the expression to check

Since 2.16

### g_warn_if_reached

    #define             g_warn_if_reached()

Logs a critical 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.

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

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