<refentry id="glib-Warnings-and-Assertions">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Warnings-and-Assertions.top_of_page">Message Output and Debugging Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Message Output and Debugging Functions</refname>
<refpurpose>functions to output messages and help debug applications</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Warnings-and-Assertions.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

<link linkend="void">void</link>                <link linkend="g-print">g_print</link>                             (const <link linkend="gchar">gchar</link> *format,
                                                         ...);
<link linkend="GPrintFunc">GPrintFunc</link>          <link linkend="g-set-print-handler">g_set_print_handler</link>                 (<link linkend="GPrintFunc">GPrintFunc</link> func);
<link linkend="void">void</link>                (<link linkend="GPrintFunc">*GPrintFunc</link>)                       (const <link linkend="gchar">gchar</link> *string);

<link linkend="void">void</link>                <link linkend="g-printerr">g_printerr</link>                          (const <link linkend="gchar">gchar</link> *format,
                                                         ...);
<link linkend="GPrintFunc">GPrintFunc</link>          <link linkend="g-set-printerr-handler">g_set_printerr_handler</link>              (<link linkend="GPrintFunc">GPrintFunc</link> func);

#define             <link linkend="g-return-if-fail">g_return_if_fail</link>                    (expr)
#define             <link linkend="g-return-val-if-fail">g_return_val_if_fail</link>                (expr,val)
#define             <link linkend="g-return-if-reached">g_return_if_reached</link>                 ()
#define             <link linkend="g-return-val-if-reached">g_return_val_if_reached</link>             (val)
#define             <link linkend="g-warn-if-fail">g_warn_if_fail</link>                      (expr)
#define             <link linkend="g-warn-if-reached">g_warn_if_reached</link>                   ()

<link linkend="void">void</link>                <link linkend="g-on-error-query">g_on_error_query</link>                    (const <link linkend="gchar">gchar</link> *prg_name);
<link linkend="void">void</link>                <link linkend="g-on-error-stack-trace">g_on_error_stack_trace</link>              (const <link linkend="gchar">gchar</link> *prg_name);

#define             <link linkend="G-BREAKPOINT--CAPS">G_BREAKPOINT</link>                        ()
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Warnings-and-Assertions.description" role="desc">
<title role="desc.title">Description</title>
<para>
These functions provide support for outputting messages.
</para>
<para>
The <function>g_return</function> family of macros (<link linkend="g-return-if-fail"><function>g_return_if_fail()</function></link>,
<link linkend="g-return-val-if-fail"><function>g_return_val_if_fail()</function></link>, <link linkend="g-return-if-reached"><function>g_return_if_reached()</function></link>, <link linkend="g-return-val-if-reached"><function>g_return_val_if_reached()</function></link>)
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.
</para>
</refsect1>

<refsect1 id="glib-Warnings-and-Assertions.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-print" role="function">
<title>g_print ()</title>
<indexterm zone="g-print"><primary sortas="print">g_print</primary></indexterm><programlisting><link linkend="void">void</link>                g_print                             (const <link linkend="gchar">gchar</link> *format,
                                                         ...);</programlisting>
<para>
Outputs a formatted message via the print handler.
The default print handler simply outputs the message to stdout.
</para>
<para>
<link linkend="g-print"><function>g_print()</function></link> 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 <link linkend="g-log"><function>g_log()</function></link>, or the convenience functions
<link linkend="g-message"><function>g_message()</function></link>, <link linkend="g-warning"><function>g_warning()</function></link> and <link linkend="g-error"><function>g_error()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-set-print-handler" role="function">
<title>g_set_print_handler ()</title>
<indexterm zone="g-set-print-handler"><primary sortas="set_print_handler">g_set_print_handler</primary></indexterm><programlisting><link linkend="GPrintFunc">GPrintFunc</link>          g_set_print_handler                 (<link linkend="GPrintFunc">GPrintFunc</link> func);</programlisting>
<para>
Sets the print handler.
Any messages passed to <link linkend="g-print"><function>g_print()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the new print handler.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the old print handler.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPrintFunc" role="function">
<title>GPrintFunc ()</title>
<indexterm zone="GPrintFunc"><primary sortas="PrintFunc">GPrintFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GPrintFunc)                       (const <link linkend="gchar">gchar</link> *string);</programlisting>
<para>
Specifies the type of the print handler functions.
These are called with the complete formatted string to output.
</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&#160;:</term>
<listitem><simpara>the message to be output.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-printerr" role="function">
<title>g_printerr ()</title>
<indexterm zone="g-printerr"><primary sortas="printerr">g_printerr</primary></indexterm><programlisting><link linkend="void">void</link>                g_printerr                          (const <link linkend="gchar">gchar</link> *format,
                                                         ...);</programlisting>
<para>
Outputs a formatted message via the error message handler.
The default handler simply outputs the message to stderr.
</para>
<para>
<link linkend="g-printerr"><function>g_printerr()</function></link> should not be used from within libraries. Instead <link linkend="g-log"><function>g_log()</function></link> should
be used, or the convenience functions <link linkend="g-message"><function>g_message()</function></link>, <link linkend="g-warning"><function>g_warning()</function></link> and <link linkend="g-error"><function>g_error()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-set-printerr-handler" role="function">
<title>g_set_printerr_handler ()</title>
<indexterm zone="g-set-printerr-handler"><primary sortas="set_printerr_handler">g_set_printerr_handler</primary></indexterm><programlisting><link linkend="GPrintFunc">GPrintFunc</link>          g_set_printerr_handler              (<link linkend="GPrintFunc">GPrintFunc</link> func);</programlisting>
<para>
Sets the handler for printing error messages.
Any messages passed to <link linkend="g-printerr"><function>g_printerr()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara>the new error message handler.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the old error message handler.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-return-if-fail" role="macro">
<title>g_return_if_fail()</title>
<indexterm zone="g-return-if-fail"><primary sortas="return_if_fail">g_return_if_fail</primary></indexterm><programlisting>#define             g_return_if_fail(expr)</programlisting>
<para>
Returns from the current function if the expression is not true.
If the expression evaluates to <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</para><variablelist role="params">
<varlistentry><term><parameter>expr</parameter>&#160;:</term>
<listitem><simpara>the expression to check.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-return-val-if-fail" role="macro">
<title>g_return_val_if_fail()</title>
<indexterm zone="g-return-val-if-fail"><primary sortas="return_val_if_fail">g_return_val_if_fail</primary></indexterm><programlisting>#define             g_return_val_if_fail(expr,val)</programlisting>
<para>
Returns from the current function, returning the value <parameter>val</parameter>, if the expression
is not true.
If the expression evaluates to <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, a critical message is logged and
<parameter>val</parameter> is returned.
</para><variablelist role="params">
<varlistentry><term><parameter>expr</parameter>&#160;:</term>
<listitem><simpara>the expression to check.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>the value to return from the current function if the expression is not
true.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-return-if-reached" role="macro">
<title>g_return_if_reached()</title>
<indexterm zone="g-return-if-reached"><primary sortas="return_if_reached">g_return_if_reached</primary></indexterm><programlisting>#define             g_return_if_reached()</programlisting>
<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></refsect2>
<refsect2 id="g-return-val-if-reached" role="macro">
<title>g_return_val_if_reached()</title>
<indexterm zone="g-return-val-if-reached"><primary sortas="return_val_if_reached">g_return_val_if_reached</primary></indexterm><programlisting>#define             g_return_val_if_reached(val)</programlisting>
<para>
Logs a critical message and returns <parameter>val</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>the value to return from the current function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-warn-if-fail" role="macro" condition="since:2.16">
<title>g_warn_if_fail()</title>
<indexterm zone="g-warn-if-fail" role="2.16"><primary sortas="warn_if_fail">g_warn_if_fail</primary></indexterm><programlisting>#define             g_warn_if_fail(expr)</programlisting>
<para>
Logs a warning if the expression is not true.
</para><variablelist role="params">
<varlistentry><term><parameter>expr</parameter>&#160;:</term>
<listitem><simpara>the expression to check
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-warn-if-reached" role="macro" condition="since:2.16">
<title>g_warn_if_reached()</title>
<indexterm zone="g-warn-if-reached" role="2.16"><primary sortas="warn_if_reached">g_warn_if_reached</primary></indexterm><programlisting>#define             g_warn_if_reached()</programlisting>
<para>
Logs a critical warning.
</para><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-on-error-query" role="function">
<title>g_on_error_query ()</title>
<indexterm zone="g-on-error-query"><primary sortas="on_error_query">g_on_error_query</primary></indexterm><programlisting><link linkend="void">void</link>                g_on_error_query                    (const <link linkend="gchar">gchar</link> *prg_name);</programlisting>
<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 <link linkend="g-log"><function>g_log()</function></link> 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 <link linkend="glib-on-error-halt"><type>glib_on_error_halt</type></link> to <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> (possibly via a debugger).
</para>
<para>
If [S]tack trace is selected, <link linkend="g-on-error-stack-trace"><function>g_on_error_stack_trace()</function></link> 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><variablelist role="params">
<varlistentry><term><parameter>prg_name</parameter>&#160;:</term>
<listitem><simpara>the program name, needed by <command>gdb</command> for the [S]tack trace option.
If <parameter>prg_name</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, <link linkend="g-get-prgname"><function>g_get_prgname()</function></link> is called to get the program name
(which will work correctly if <link linkend="gdk-init"><function>gdk_init()</function></link> or <link linkend="gtk-init"><function>gtk_init()</function></link> has been called).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-on-error-stack-trace" role="function">
<title>g_on_error_stack_trace ()</title>
<indexterm zone="g-on-error-stack-trace"><primary sortas="on_error_stack_trace">g_on_error_stack_trace</primary></indexterm><programlisting><link linkend="void">void</link>                g_on_error_stack_trace              (const <link linkend="gchar">gchar</link> *prg_name);</programlisting>
<para>
Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
Called by <link linkend="g-on-error-query"><function>g_on_error_query()</function></link> when the [S]tack trace option is selected.
</para>
<para>
This function may cause different actions on non-UNIX platforms.
</para><variablelist role="params">
<varlistentry><term><parameter>prg_name</parameter>&#160;:</term>
<listitem><simpara>the program name, needed by <command>gdb</command> for the [S]tack trace option.
If <parameter>prg_name</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, <link linkend="g-get-prgname"><function>g_get_prgname()</function></link> is called to get the program name
(which will work correctly if <link linkend="gdk-init"><function>gdk_init()</function></link> or <link linkend="gtk-init"><function>gtk_init()</function></link> has been called).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="G-BREAKPOINT--CAPS" role="macro">
<title>G_BREAKPOINT()</title>
<indexterm zone="G-BREAKPOINT--CAPS"><primary sortas="BREAKPOINT">G_BREAKPOINT</primary></indexterm><programlisting>#define             G_BREAKPOINT()</programlisting>
<para>
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 <link linkend="SIGTRAP--CAPS"><literal>SIGTRAP</literal></link> signal.
</para></refsect2>

</refsect1>




</refentry>
