docs/reference/glib/tmpl/warnings.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Message Output and Debugging Functions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 functions to output messages and help debug applications
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions provide support for outputting messages.
  10 </para>
  11 <para>
  12 The <function>g_return</function> family of macros (g_return_if_fail(),
  13 g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
  14 should only be used for programming errors, a typical use case is
  15 checking for invalid parameters at the beginning of a public function.
  16 They should not be used if you just mean "if (error) return", they
  17 should only be used if you mean "if (bug in program) return".
  18 The program behavior is generally considered undefined after one of these
  19 checks fails. They are not intended for normal control flow, only to
  20 give a perhaps-helpful warning before giving up.
  21 </para>
  22
  23 <!-- ##### SECTION See_Also ##### -->
  24 <para>
  25
  26 </para>
  27
  28 <!-- ##### SECTION Stability_Level ##### -->
  29
  30
  31 <!-- ##### FUNCTION g_print ##### -->
  32 <para>
  33 Outputs a formatted message via the print handler.
  34 The default print handler simply outputs the message to stdout.
  35 </para>
  36 <para>
  37 g_print() should not be used from within libraries for debugging messages,
  38 since it may be redirected by applications to special purpose message
  39 windows or even files.
  40 Instead, libraries should use g_log(), or the convenience functions
  41 g_message(), g_warning() and g_error().
  42 </para>
  43
  44 @format: the message format. See the printf() documentation.
  45 @Varargs: the parameters to insert into the format string.
  46
  47
  48 <!-- ##### FUNCTION g_set_print_handler ##### -->
  49 <para>
  50 Sets the print handler.
  51 Any messages passed to g_print() will be output via the new handler.
  52 The default handler simply outputs the message to stdout.
  53 By providing your own handler you can redirect the output, to a GTK+
  54 widget or a log file for example.
  55 </para>
  56
  57 @func: the new print handler.
  58 @Returns: the old print handler.
  59
  60
  61 <!-- ##### USER_FUNCTION GPrintFunc ##### -->
  62 <para>
  63 Specifies the type of the print handler functions.
  64 These are called with the complete formatted string to output.
  65 </para>
  66
  67 @string: the message to be output.
  68
  69
  70 <!-- ##### FUNCTION g_printerr ##### -->
  71 <para>
  72 Outputs a formatted message via the error message handler.
  73 The default handler simply outputs the message to stderr.
  74 </para>
  75 <para>
  76 g_printerr() should not be used from within libraries. Instead g_log() should
  77 be used, or the convenience functions g_message(), g_warning() and g_error().
  78 </para>
  79
  80 @format: the message format. See the printf() documentation.
  81 @Varargs: the parameters to insert into the format string.
  82
  83
  84 <!-- ##### FUNCTION g_set_printerr_handler ##### -->
  85 <para>
  86 Sets the handler for printing error messages.
  87 Any messages passed to g_printerr() will be output via the new handler.
  88 The default handler simply outputs the message to stderr.
  89 By providing your own handler you can redirect the output, to a GTK+
  90 widget or a log file for example.
  91 </para>
  92
  93 @func: the new error message handler.
  94 @Returns: the old error message handler.
  95
  96
  97 <!-- ##### MACRO g_return_if_fail ##### -->
  98 <para>
  99 Returns from the current function if the expression is not true.
 100 If the expression evaluates to %FALSE, a critical message is logged and
 101 the function returns. This can only be used in functions which do not return
 102 a value.
 103 </para>
 104
 105 @expr: the expression to check.
 106
 107
 108 <!-- ##### MACRO g_return_val_if_fail ##### -->
 109 <para>
 110 Returns from the current function, returning the value @val, if the expression
 111 is not true.
 112 If the expression evaluates to %FALSE, a critical message is logged and
 113 @val is returned.
 114 </para>
 115
 116 @expr: the expression to check.
 117 @val: the value to return from the current function if the expression is not
 118 true.
 119
 120
 121 <!-- ##### MACRO g_return_if_reached ##### -->
 122 <para>
 123 Logs a critical message and returns from the current function.
 124 This can only be used in functions which do not return a value.
 125 </para>
 126
 127
 128
 129 <!-- ##### MACRO g_return_val_if_reached ##### -->
 130 <para>
 131 Logs a critical message and returns @val.
 132 </para>
 133
 134 @val: the value to return from the current function.
 135
 136
 137 <!-- ##### MACRO g_warn_if_fail ##### -->
 138 <para>
 139
 140 </para>
 141
 142 @expr:
 143
 144
 145 <!-- ##### MACRO g_warn_if_reached ##### -->
 146 <para>
 147
 148 </para>
 149
 150
 151
 152 <!-- ##### FUNCTION g_warn_message ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @domain:
 158 @file:
 159 @line:
 160 @func:
 161 @warnexpr:
 162
 163
 164 <!-- ##### FUNCTION g_on_error_query ##### -->
 165 <para>
 166 Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
 167 This function is intended to be used for debugging use only. The following
 168 example shows how it can be used together with the g_log() functions.
 169 </para>
 170 <informalexample><programlisting>
 171 &num;include &lt;glib.h&gt;
 172
 173 static void
 174 log_handler (const gchar   *log_domain,
 175              GLogLevelFlags log_level,
 176              const gchar   *message,
 177              gpointer       user_data)
 178 {
 179   g_log_default_handler (log_domain, log_level, message, user_data);
 180
 181   g_on_error_query (MY_PROGRAM_NAME);
 182 }
 183
 184 int main (int argc, char *argv[])
 185 {
 186   g_log_set_handler (MY_LOG_DOMAIN,
 187                      G_LOG_LEVEL_WARNING |
 188                      G_LOG_LEVEL_ERROR |
 189                      G_LOG_LEVEL_CRITICAL,
 190                      log_handler,
 191                      NULL);
 192
 193  /* ... */
 194 </programlisting></informalexample>
 195 <para>
 196 If [E]xit is selected, the application terminates with a call to
 197 <function>_exit(0)</function>.
 198 </para>
 199 <para>
 200 If [H]alt is selected, the application enters an infinite loop.
 201 The infinite loop can only be stopped by killing the application,
 202 or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
 203 </para>
 204 <para>
 205 If [S]tack trace is selected, g_on_error_stack_trace() is called. This
 206 invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
 207 The prompt is then shown again.
 208 </para>
 209 <para>
 210 If [P]roceed is selected, the function returns.
 211 </para>
 212 <para>
 213 This function may cause different actions on non-UNIX platforms.
 214 </para>
 215
 216 @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
 217 If @prg_name is %NULL, g_get_prgname() is called to get the program name
 218 (which will work correctly if gdk_init() or gtk_init() has been called).
 219
 220
 221 <!-- ##### FUNCTION g_on_error_stack_trace ##### -->
 222 <para>
 223 Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
 224 Called by g_on_error_query() when the [S]tack trace option is selected.
 225 </para>
 226 <para>
 227 This function may cause different actions on non-UNIX platforms.
 228 </para>
 229
 230 @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
 231 If @prg_name is %NULL, g_get_prgname() is called to get the program name
 232 (which will work correctly if gdk_init() or gtk_init() has been called).
 233
 234
 235 <!-- ##### MACRO G_BREAKPOINT ##### -->
 236 <para>
 237 Inserts a breakpoint instruction into the code.  On x86 and alpha systems
 238 this is implemented as a soft interrupt and on other architectures it raises
 239 a %SIGTRAP signal.
 240 </para>
 241
 242
 243