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

  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_MESSAGE_OUTPUT_AND_DEBUGGING
  8-- Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- Message Output and Debugging Functions
 11
 12-- Message Output and Debugging Functions %G —%@ functions to output messages and help debug applications.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19-- void        g_print                         (const gchar *format,
 20--                                              ...);
 21-- GPrintFunc  g_set_print_handler             (GPrintFunc func);
 22-- void        (*GPrintFunc)                   (const gchar *string);
 23
 24-- void        g_printerr                      (const gchar *format,
 25--                                              ...);
 26-- GPrintFunc  g_set_printerr_handler          (GPrintFunc func);
 27
 28-- #define     g_return_if_fail                (expr)
 29-- #define     g_return_val_if_fail            (expr,val)
 30-- #define     g_return_if_reached             ()
 31-- #define     g_return_val_if_reached         (val)
 32
 33-- #define     g_assert                        (expr)
 34-- #define     g_assert_not_reached            ()
 35
 36-- void        g_on_error_query                (const gchar *prg_name);
 37-- void        g_on_error_stack_trace          (const gchar *prg_name);
 38
 39-- #define     G_BREAKPOINT                    ()
 40
 41
 42-- Description
 43
 44-- These functions provide support for outputting messages.
 45-- Details
 46-- g_print ()
 47
 48-- void        g_print                         (const gchar *format,
 49--                                              ...);
 50
 51-- Outputs a formatted message via the print handler. The default print handler simply outputs the message to stdout.
 52
 53-- 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().
 54-- format : 	the message format. See the printf() documentation.
 55-- ... : 	the parameters to insert into the format string.
 56-- g_set_print_handler ()
 57
 58-- GPrintFunc  g_set_print_handler             (GPrintFunc func);
 59
 60-- 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.
 61-- func : 	the new print handler.
 62-- Returns : 	the old print handler.
 63-- GPrintFunc ()
 64
 65-- void        (*GPrintFunc)                   (const gchar *string);
 66
 67-- Specifies the type of the print handler functions. These are called with the complete formatted string to output.
 68-- string : 	the message to be output.
 69-- g_printerr ()
 70
 71-- void        g_printerr                      (const gchar *format,
 72--                                              ...);
 73
 74-- Outputs a formatted message via the error message handler. The default handler simply outputs the message to stderr.
 75
 76-- 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().
 77-- format : 	the message format. See the printf() documentation.
 78-- ... : 	the parameters to insert into the format string.
 79-- g_set_printerr_handler ()
 80
 81-- GPrintFunc  g_set_printerr_handler          (GPrintFunc func);
 82
 83-- 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.
 84-- func : 	the new error message handler.
 85-- Returns : 	the old error message handler.
 86-- g_return_if_fail()
 87
 88-- #define     g_return_if_fail(expr)
 89
 90-- 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.
 91-- expr : 	the expression to check.
 92-- g_return_val_if_fail()
 93
 94-- #define     g_return_val_if_fail(expr,val)
 95
 96-- 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.
 97-- expr : 	the expression to check.
 98-- val : 	the value to return from the current function if the expression is not true.
 99-- g_return_if_reached()
100
101-- #define     g_return_if_reached()
102
103-- Logs a critical message and returns from the current function. This can only be used in functions which do not return a value.
104-- g_return_val_if_reached()
105
106-- #define     g_return_val_if_reached(val)
107
108-- Logs a critical message and returns val.
109-- val : 	the value to return from the current function.
110-- g_assert()
111
112-- #define     g_assert(expr)
113
114-- 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.
115
116-- The macro can be turned off in final releases of code by defining G_DISABLE_ASSERT when compiling the application.
117-- expr : 	the expression to check.
118-- g_assert_not_reached()
119
120-- #define     g_assert_not_reached()
121
122-- 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.
123
124-- The macro can be turned off in final releases of code by defining G_DISABLE_ASSERT when compiling the application.
125-- g_on_error_query ()
126
127-- void        g_on_error_query                (const gchar *prg_name);
128
129-- Prompts the user with [E]xit, [H]alt, show [S]tack trace or [P]roceed. 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.
130
131-- #include <glib.h>
132
133-- static void 
134-- log_handler (const gchar   *log_domain,
135-- 	     GLogLevelFlags log_level,
136-- 	     const gchar   *message,
137-- 	     gpointer       user_data)
138-- {
139--   g_log_default_handler (log_domain, log_level, message, user_data);
140
141--   g_on_error_query (MY_PROGRAM_NAME);
142-- }
143
144-- int main (int argc, char *argv[])
145-- {
146--   g_log_set_handler (MY_LOG_DOMAIN,
147-- 		     G_LOG_LEVEL_WARNING | 
148--                      G_LOG_LEVEL_ERROR | 
149--                      G_LOG_LEVEL_CRITICAL,
150-- 		     log_handler,
151-- 		     NULL);
152
153--  /* ... */  
154
155-- If [E]xit is selected, the application terminates with a call to _exit(0).
156
157-- 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).
158
159-- If [S]tack trace is selected, g_on_error_stack_trace() is called. This invokes gdb, which attaches to the current process and shows a stack trace. The prompt is then shown again.
160
161-- If [P]roceed is selected, the function returns.
162
163-- This function may cause different actions on non-UNIX platforms.
164-- prg_name : 	the program name, needed by gdb 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).
165-- g_on_error_stack_trace ()
166
167-- void        g_on_error_stack_trace          (const gchar *prg_name);
168
169-- Invokes gdb, 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.
170
171-- This function may cause different actions on non-UNIX platforms.
172-- prg_name : 	the program name, needed by gdb 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).
173-- G_BREAKPOINT()
174
175-- #define     G_BREAKPOINT()
176
177-- Inserts a breakpoint instruction into the code (on x86 machines only).
178end