/src/wrappers/glib/library/core/glib_warnings_and_assertions.e

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