/src/wrappers/glib/library/core/glib_warnings_and_assertions.e
Specman e | 261 lines | 2 code | 96 blank | 163 comment | 0 complexity | c1368ffd942710e95c5f89d34bf1ac5c MD5 | raw file
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