glib-Warnings-and-Assertions.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Message Output and Debugging Functions</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-core.html" title="GLib Core Application Support"><link rel="previous" href="glib-Error-Reporting.html" title="Error Reporting"><link rel="next" href="glib-Message-Logging.html" title="Message Logging"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="refentry" href="glib-building.html" title="Compiling the GLib package"><link rel="refentry" href="glib-cross-compiling.html" title="Cross-compiling the GLib package"><link rel="refentry" href="glib-compiling.html" title="Compiling GLib Applications"><link rel="refentry" href="glib-running.html" title="Running GLib Applications"><link rel="refentry" href="glib-changes.html" title="Changes to GLib"><link rel="refentry" href="glib-resources.html" title="Mailing lists and bug reports"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="refentry" href="glib-Basic-Types.html" title="Basic Types"><link rel="refentry" href="glib-Limits-of-Basic-Types.html" title="Limits of Basic Types"><link rel="refentry" href="glib-Standard-Macros.html" title="Standard Macros"><link rel="refentry" href="glib-Type-Conversion-Macros.html" title="Type Conversion Macros"><link rel="refentry" href="glib-Byte-Order-Macros.html" title="Byte Order Macros"><link rel="refentry" href="glib-Numerical-Definitions.html" title="Numerical Definitions"><link rel="refentry" href="glib-Miscellaneous-Macros.html" title="Miscellaneous Macros"><link rel="refentry" href="glib-Atomic-Operations.html" title="Atomic Operations"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="refentry" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop"><link rel="refentry" href="glib-Threads.html" title="
Threads"><link rel="refentry" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="refentry" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues"><link rel="refentry" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><link rel="refentry" href="glib-Memory-Allocation.html" title="Memory Allocation"><link rel="refentry" href="glib-IO-Channels.html" title="IO Channels"><link rel="refentry" href="glib-Error-Reporting.html" title="Error Reporting"><link rel="refentry" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><link rel="refentry" href="glib-Message-Logging.html" title="Message Logging"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="refentry" href="glib-String-Utility-Functions.html" title="String Utility Functions"><link rel="refentry" href="glib-Character-Set-Conversion.html" title="Character Set Conversion"><link rel="refentry" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation"><link rel="refentry" href="glib-I18N.html" title="Internationalization"><link rel="refentry" href="glib-Date-and-Time-Functions.html" title="Date and Time Functions"><link rel="refentry" href="glib-Random-Numbers.html" title="Random Numbers"><link rel="refentry" href="glib-Hook-Functions.html" title="Hook Functions"><link rel="refentry" href="glib-Miscellaneous-Utility-Functions.html" title="Miscellaneous Utility Functions"><link rel="refentry" href="glib-Lexical-Scanner.html" title="Lexical Scanner"><link rel="refentry" href="glib-Automatic-String-Completion.html" title="Automatic String Completion"><link rel="refentry" href="glib-Timers.html" title="Timers"><link rel="refentry" href="glib-Spawning-Processes.html" title="Spawning Processes"><link rel="refentry" href="glib-File-Utilities.html" title="File Utilities"><link rel="refentry" href="glib-Shell-related-Utilities.html" title="Shell-related Utilities"><link rel="refentry" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching"><link rel="refentry" href="glib-Simple-XML-Subset-Parser.html" title="Simple XML Subset Parser"><link rel="refentry" href="glib-Windows-Compatability-Functions.html" title="Windows Compatibility Functions"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="refentry" href="glib-Memory-Chunks.html" title="Memory Chunks"><link rel="refentry" href="glib-Doubly-Linked-Lists.html" title="Doubly-Linked Lists"><link rel="refentry" href="glib-Singly-Linked-Lists.html" title="Singly-Linked Lists"><link rel="refentry" href="glib-Double-ended-Queues.html" title="Double-ended Queues"><link rel="refentry" href="glib-Trash-Stacks.html" title="Trash Stacks"><link rel="refentry" href="glib-Hash-Tables.html" title="Hash Tables"><link rel="refentry" href="glib-Strings.html" title="Strings"><link rel="refentry" href="glib-String-Chunks.html" title="String Chunks"><link rel="refentry" href="glib-Arrays.html" title="Arrays"><link rel="refentry" href="glib-Pointer-Arrays.html" title="Pointer Arrays"><link rel="refentry" href="glib-Byte-Arrays.html" title="Byte Arrays"><link rel="refentry" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees"><link rel="refentry" href="glib-N-ary-Trees.html" title="N-ary Trees"><link rel="refentry" href="glib-Quarks.html" title="Quarks"><link rel="refentry" href="glib-Keyed-Data-Lists.html" title="Keyed Data Lists"><link rel="refentry" href="glib-Datasets.html" title="Datasets"><link rel="refentry" href="glib-Relations-and-Tuples.html" title="Relations and Tuples"><link rel="refentry" href="glib-Caches.html" title="Caches"><link rel="refentry" href="glib-Memory-Allocators.html" title="Memory Allocators"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="refentry" href="glib-gettextize.html" title="glib-gettextize"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="glib-Warnings-and-Assertions.html#id3089081" title="Description"><link rel="section" href="glib-Warnings-and-Assertions.html#id3089092" title="Details"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-Error-Reporting.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Message-Logging.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Warnings-and-Assertions"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Message Output and Debugging Functions</span></h2><p>Message Output and Debugging Functions — functions to output messages and help debug applications.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib.h>
void <a href="glib-Warnings-and-Assertions.html#g-print">g_print</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);
<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> <a href="glib-Warnings-and-Assertions.html#g-set-print-handler">g_set_print_handler</a> (<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> func);
void (<a href="glib-Warnings-and-Assertions.html#GPrintFunc">*GPrintFunc</a>) (const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);
void <a href="glib-Warnings-and-Assertions.html#g-printerr">g_printerr</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);
<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> <a href="glib-Warnings-and-Assertions.html#g-set-printerr-handler">g_set_printerr_handler</a> (<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> func);
#define <a href="glib-Warnings-and-Assertions.html#g-return-if-fail">g_return_if_fail</a> (expr)
#define <a href="glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a> (expr,val)
#define <a href="glib-Warnings-and-Assertions.html#g-return-if-reached">g_return_if_reached</a> ()
#define <a href="glib-Warnings-and-Assertions.html#g-return-val-if-reached">g_return_val_if_reached</a> (val)
#define <a href="glib-Warnings-and-Assertions.html#g-assert">g_assert</a> (expr)
#define <a href="glib-Warnings-and-Assertions.html#g-assert-not-reached">g_assert_not_reached</a> ()
void <a href="glib-Warnings-and-Assertions.html#g-on-error-query">g_on_error_query</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *prg_name);
void <a href="glib-Warnings-and-Assertions.html#g-on-error-stack-trace">g_on_error_stack_trace</a> (const <a href="glib-Basic-Types.html#gchar">gchar</a> *prg_name);
#define <a href="glib-Warnings-and-Assertions.html#G-BREAKPOINT-CAPS">G_BREAKPOINT</a> ()
</pre></div><div class="refsect1" lang="en"><a name="id3089081"></a><h2>Description</h2><p>
These functions provide support for outputting messages.
</p></div><div class="refsect1" lang="en"><a name="id3089092"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3089097"></a><h3><a name="g-print"></a>g_print ()</h3><a class="indexterm" name="id3089107"></a><pre class="programlisting">void g_print (const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);</pre><p>
Outputs a formatted message via the print handler.
The default print handler simply outputs the message to stdout.
</p><p>
<a href="glib-Warnings-and-Assertions.html#g-print"><tt class="function">g_print()</tt></a> 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 <a href="glib-Message-Logging.html#g-log"><tt class="function">g_log()</tt></a>, or the convenience functions
<a href="glib-Message-Logging.html#g-message"><tt class="function">g_message()</tt></a>, <a href="glib-Message-Logging.html#g-warning"><tt class="function">g_warning()</tt></a> and <a href="glib-Message-Logging.html#g-error"><tt class="function">g_error()</tt></a>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>format</tt></i> :</span></td><td>the message format. See the <tt class="function"><tt class="function">printf()</tt></tt>
documentation.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>...</tt></i> :</span></td><td>the parameters to insert into the format string.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089248"></a><h3><a name="g-set-print-handler"></a>g_set_print_handler ()</h3><a class="indexterm" name="id3089260"></a><pre class="programlisting"><a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> g_set_print_handler (<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> func);</pre><p>
Sets the print handler.
Any messages passed to <a href="glib-Warnings-and-Assertions.html#g-print"><tt class="function">g_print()</tt></a> 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.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>func</tt></i> :</span></td><td>the new print handler.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the old print handler.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089330"></a><h3><a name="GPrintFunc"></a>GPrintFunc ()</h3><a class="indexterm" name="id3089341"></a><pre class="programlisting">void (*GPrintFunc) (const <a href="glib-Basic-Types.html#gchar">gchar</a> *string);</pre><p>
Specifies the type of the print handler functions.
These are called with the complete formatted string to output.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>string</tt></i> :</span></td><td>the message to be output.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089389"></a><h3><a name="g-printerr"></a>g_printerr ()</h3><a class="indexterm" name="id3089400"></a><pre class="programlisting">void g_printerr (const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);</pre><p>
Outputs a formatted message via the error message handler.
The default handler simply outputs the message to stderr.
</p><p>
<a href="glib-Warnings-and-Assertions.html#g-printerr"><tt class="function">g_printerr()</tt></a> should not be used from within libraries. Instead <a href="glib-Message-Logging.html#g-log"><tt class="function">g_log()</tt></a> should
be used, or the convenience functions <a href="glib-Message-Logging.html#g-message"><tt class="function">g_message()</tt></a>, <a href="glib-Message-Logging.html#g-warning"><tt class="function">g_warning()</tt></a> and <a href="glib-Message-Logging.html#g-error"><tt class="function">g_error()</tt></a>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>format</tt></i> :</span></td><td>the message format. See the <tt class="function"><tt class="function">printf()</tt></tt>
documentation.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>...</tt></i> :</span></td><td>the parameters to insert into the format string.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089533"></a><h3><a name="g-set-printerr-handler"></a>g_set_printerr_handler ()</h3><a class="indexterm" name="id3089545"></a><pre class="programlisting"><a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> g_set_printerr_handler (<a href="glib-Warnings-and-Assertions.html#GPrintFunc">GPrintFunc</a> func);</pre><p>
Sets the handler for printing error messages.
Any messages passed to <a href="glib-Warnings-and-Assertions.html#g-printerr"><tt class="function">g_printerr()</tt></a> 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.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>func</tt></i> :</span></td><td>the new error message handler.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the old error message handler.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089617"></a><h3><a name="g-return-if-fail"></a>g_return_if_fail()</h3><a class="indexterm" name="id3089628"></a><pre class="programlisting">#define g_return_if_fail(expr)</pre><p>
Returns from the current function if the expression is not true.
If the expression evaluates to <tt class="literal">FALSE</tt>, a critical message is logged and
the function returns. This can only be used in functions which do not return
a value.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>expr</tt></i> :</span></td><td>the expression to check.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089671"></a><h3><a name="g-return-val-if-fail"></a>g_return_val_if_fail()</h3><a class="indexterm" name="id3089682"></a><pre class="programlisting">#define g_return_val_if_fail(expr,val)</pre><p>
Returns from the current function, returning the value <i class="parameter"><tt>val</tt></i>, if the expression
is not true.
If the expression evaluates to <tt class="literal">FALSE</tt>, a critical message is logged and
<i class="parameter"><tt>val</tt></i> is returned.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>expr</tt></i> :</span></td><td>the expression to check.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>val</tt></i> :</span></td><td>the value to return from the current function if the expression is not
true.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089750"></a><h3><a name="g-return-if-reached"></a>g_return_if_reached()</h3><a class="indexterm" name="id3089762"></a><pre class="programlisting">#define g_return_if_reached()</pre><p>
Logs a critical message and returns from the current function.
This can only be used in functions which do not return a value.
</p></div><hr><div class="refsect2" lang="en"><a name="id3089779"></a><h3><a name="g-return-val-if-reached"></a>g_return_val_if_reached()</h3><a class="indexterm" name="id3089790"></a><pre class="programlisting">#define g_return_val_if_reached(val)</pre><p>
Logs a critical message and returns <i class="parameter"><tt>val</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>val</tt></i> :</span></td><td>the value to return from the current function.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089830"></a><h3><a name="g-assert"></a>g_assert()</h3><a class="indexterm" name="id3089840"></a><pre class="programlisting">#define g_assert(expr)</pre><p>
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.
</p><p>
The macro can be turned off in final releases of code by defining
<span class="type">G_DISABLE_ASSERT</span> when compiling the application.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>expr</tt></i> :</span></td><td>the expression to check.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3089892"></a><h3><a name="g-assert-not-reached"></a>g_assert_not_reached()</h3><a class="indexterm" name="id3089903"></a><pre class="programlisting">#define g_assert_not_reached()</pre><p>
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.
</p><p>
The macro can be turned off in final releases of code by defining
<span class="type">G_DISABLE_ASSERT</span> when compiling the application.
</p></div><hr><div class="refsect2" lang="en"><a name="id3089936"></a><h3><a name="g-on-error-query"></a>g_on_error_query ()</h3><a class="indexterm" name="id3089946"></a><pre class="programlisting">void g_on_error_query (const <a href="glib-Basic-Types.html#gchar">gchar</a> *prg_name);</pre><p>
Prompts the user with <tt class="computeroutput">[E]xit, [H]alt, show [S]tack trace or [P]roceed</tt>.
This function is intended to be used for debugging use only.
FIXME: How do you set it up?
</p><p>
If [E]xit is selected, the application terminates with a call to
<tt class="function">_exit(0)</tt>.
</p><p>
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 <span class="type">glib_on_error_halt</span> to <tt class="literal">FALSE</tt> (possibly via a debugger).
</p><p>
If [S]tack trace is selected, <a href="glib-Warnings-and-Assertions.html#g-on-error-stack-trace"><tt class="function">g_on_error_stack_trace()</tt></a> is called. This
invokes <span><b class="command">gdb</b></span>, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</p><p>
If [P]roceed is selected, the function returns.
</p><p>
This function may cause different actions on non-UNIX platforms.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>prg_name</tt></i> :</span></td><td>the program name, needed by <span><b class="command">gdb</b></span> for the [S]tack trace option.
If <i class="parameter"><tt>prg_name</tt></i> is <tt class="literal">NULL</tt>, <a href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname"><tt class="function">g_get_prgname()</tt></a> is called to get the program name
(which will work correctly if <a
href="../gdk/gdk-General.html#gdk-init"
><tt class="function">gdk_init()</tt></a> or <a
href="../gtk/gtk-General.html#gtk-init"
><tt class="function">gtk_init()</tt></a> has been called).
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3090119"></a><h3><a name="g-on-error-stack-trace"></a>g_on_error_stack_trace ()</h3><a class="indexterm" name="id3090130"></a><pre class="programlisting">void g_on_error_stack_trace (const <a href="glib-Basic-Types.html#gchar">gchar</a> *prg_name);</pre><p>
Invokes <span><b class="command">gdb</b></span>, which attaches to the current process and shows a stack trace.
Called by <a href="glib-Warnings-and-Assertions.html#g-on-error-query"><tt class="function">g_on_error_query()</tt></a> when the [S]tack trace option is selected.
</p><p>
This function may cause different actions on non-UNIX platforms.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>prg_name</tt></i> :</span></td><td>the program name, needed by <span><b class="command">gdb</b></span> for the [S]tack trace option.
If <i class="parameter"><tt>prg_name</tt></i> is <tt class="literal">NULL</tt>, <a href="glib-Miscellaneous-Utility-Functions.html#g-get-prgname"><tt class="function">g_get_prgname()</tt></a> is called to get the program name
(which will work correctly if <a
href="../gdk/gdk-General.html#gdk-init"
><tt class="function">gdk_init()</tt></a> or <a
href="../gtk/gtk-General.html#gtk-init"
><tt class="function">gtk_init()</tt></a> has been called).
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3090250"></a><h3><a name="G-BREAKPOINT-CAPS"></a>G_BREAKPOINT()</h3><a class="indexterm" name="id3090262"></a><pre class="programlisting">#define G_BREAKPOINT()</pre><p>
Inserts a breakpoint instruction into the code (on x86 machines only).
</p></div></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="glib-Error-Reporting.html"><b><< Error Reporting</b></a></td><td align="right"><a accesskey="n" href="glib-Message-Logging.html"><b>Message Logging >></b></a></td></tr></table></body></html>