docs/reference/glib/tmpl/warnings.sgml

<!-- ##### SECTION Title ##### -->
Message Output and Debugging Functions

<!-- ##### SECTION Short_Description ##### -->
functions to output messages and help debug applications.

<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for outputting messages.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### FUNCTION g_print ##### -->
<para>
Outputs a formatted message via the print handler.
The default print handler simply outputs the message to stdout.
</para>
<para>
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().
</para>

@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.


<!-- ##### FUNCTION g_set_print_handler ##### -->
<para>
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.
</para>

@func: the new print handler.
@Returns: the old print handler.


<!-- ##### USER_FUNCTION GPrintFunc ##### -->
<para>
Specifies the type of the print handler functions.
These are called with the complete formatted string to output.
</para>

@string: the message to be output.


<!-- ##### FUNCTION g_printerr ##### -->
<para>
Outputs a formatted message via the error message handler.
The default handler simply outputs the message to stderr.
</para>
<para>
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().
</para>

@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.


<!-- ##### FUNCTION g_set_printerr_handler ##### -->
<para>
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.
</para>

@func: the new error message handler.
@Returns: the old error message handler.


<!-- ##### MACRO g_return_if_fail ##### -->
<para>
Returns from the current function if the expression is not true.
If the expression evaluates to %FALSE, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</para>

@expr: the expression to check.


<!-- ##### MACRO g_return_val_if_fail ##### -->
<para>
Returns from the current function, returning the value @val, if the expression
is not true.
If the expression evaluates to %FALSE, a critical message is logged and
@val is returned.
</para>

@expr: the expression to check.
@val: the value to return from the current function if the expression is not
true.


<!-- ##### MACRO g_return_if_reached ##### -->
<para>
Logs a critical message and returns from the current function. 
This can only be used in functions which do not return a value.
</para>



<!-- ##### MACRO g_return_val_if_reached ##### -->
<para>
Logs a critical message and returns @val. 
</para>

@val: the value to return from the current function.


<!-- ##### MACRO g_assert ##### -->
<para>
Debugging macro to terminate the application if the assertion fails.
If the assertion fails (i.e. the expression is not true), an error message
is logged and the application is terminated.
</para>
<para>
The macro can be turned off in final releases of code by defining
#G_DISABLE_ASSERT when compiling the application.
</para>

@expr: the expression to check.


<!-- ##### MACRO g_assert_not_reached ##### -->
<para>
Debugging macro to terminate the application if it is ever reached.
If it is reached, an error message is logged and the application is terminated.
</para>
<para>
The macro can be turned off in final releases of code by defining
#G_DISABLE_ASSERT when compiling the application.
</para>



<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
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.
</para>
<informalexample><programlisting>
&num;include &lt;glib.h&gt;

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

 /* ... */  
</programlisting></informalexample>
<para>
If [E]xit is selected, the application terminates with a call to
<function>_exit(0)</function>.
</para>
<para>
If [H]alt is selected, the application enters an infinite loop.
The infinite loop can only be stopped by killing the application,
or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
</para>
<para>
If [S]tack trace is selected, g_on_error_stack_trace() is called. This
invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</para>
<para>
If [P]roceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-UNIX platforms.
</para>

@prg_name: the program name, needed by <command>gdb</command> 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).


<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
Invokes <command>gdb</command>, 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.
</para>
<para>
This function may cause different actions on non-UNIX platforms.
</para>

@prg_name: the program name, needed by <command>gdb</command> 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).


<!-- ##### MACRO G_BREAKPOINT ##### -->
<para>
Inserts a breakpoint instruction into the code (on x86 machines only).
</para>