docs/reference/glib/tmpl/messages.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Message Logging
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 versatile support for logging messages with different levels of importance
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions provide support for logging error messages or messages
  10 used for debugging.
  11 </para>
  12
  13 <para>
  14 There are several built-in levels of messages, defined in #GLogLevelFlags.
  15 These can be extended with user-defined levels.
  16 </para>
  17
  18 <!-- ##### SECTION See_Also ##### -->
  19 <para>
  20
  21 </para>
  22
  23 <!-- ##### SECTION Stability_Level ##### -->
  24
  25
  26 <!-- ##### MACRO G_LOG_DOMAIN ##### -->
  27 <para>
  28 Defines the log domain.
  29 For applications, this is typically left as the default %NULL (or "") domain.
  30 Libraries should define this so that any messages which they log can
  31 be differentiated from messages from other libraries and application code.
  32 But be careful not to define it in any public header files.
  33 </para>
  34 <para>
  35 For example, GTK+ uses this in its Makefile.am:
  36 </para>
  37 <informalexample><programlisting>
  38 INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
  39 </programlisting></informalexample>
  40
  41
  42
  43 <!-- ##### MACRO G_LOG_FATAL_MASK ##### -->
  44 <para>
  45 GLib log levels that are considered fatal by default.
  46 </para>
  47
  48
  49
  50 <!-- ##### MACRO G_LOG_LEVEL_USER_SHIFT ##### -->
  51 <para>
  52 Log level shift offset for user defined log levels (0-7 are used by GLib).
  53 </para>
  54
  55
  56
  57 <!-- ##### USER_FUNCTION GLogFunc ##### -->
  58 <para>
  59 Specifies the prototype of log handler functions.
  60 </para>
  61
  62 @log_domain: the log domain of the message.
  63 @log_level: the log level of the message (including the fatal and recursion
  64 flags).
  65 @message: the message to process.
  66 @user_data: user data, set in g_log_set_handler().
  67
  68
  69 <!-- ##### ENUM GLogLevelFlags ##### -->
  70 <para>
  71 Flags specifying the level of log messages. It is possible to change
  72 how GLib treats messages of the various levels using g_log_set_handler()
  73 and g_log_set_fatal_mask().
  74 </para>
  75
  76 @G_LOG_FLAG_RECURSION: internal flag
  77 @G_LOG_FLAG_FATAL: internal flag
  78 @G_LOG_LEVEL_ERROR: log level for errors, see g_error().
  79   This level is also used for messages produced by g_assert().
  80 @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical().
  81   This level is also used for messages produced by g_return_if_fail() and
  82   g_return_val_if_fail().
  83 @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning()
  84 @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message()
  85 @G_LOG_LEVEL_INFO: log level for informational messages
  86 @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
  87 @G_LOG_LEVEL_MASK: a mask including all log levels.
  88
  89 <!-- ##### FUNCTION g_log ##### -->
  90 <para>
  91 Logs an error or debugging message.
  92 If the log level has been set as fatal, the abort()
  93 function is called to terminate the program.
  94 </para>
  95
  96 @log_domain: the log domain, usually #G_LOG_DOMAIN.
  97 @log_level: the log level, either from #GLogLevelFlags or a user-defined level.
  98 @format: the message format. See the printf()
  99 documentation.
 100 @Varargs: the parameters to insert into the format string.
 101
 102
 103 <!-- ##### FUNCTION g_logv ##### -->
 104 <para>
 105 Logs an error or debugging message.
 106 If the log level has been set as fatal, the abort()
 107 function is called to terminate the program.
 108 </para>
 109
 110 @log_domain: the log domain.
 111 @log_level: the log level.
 112 @format: the message format. See the printf()
 113 documentation.
 114 @args: the parameters to insert into the format string.
 115
 116
 117 <!-- ##### MACRO g_message ##### -->
 118 <para>
 119 A convenience function/macro to log a normal message.
 120 </para>
 121
 122 @...: format string, followed by parameters to insert into the format string (as with printf())
 123
 124
 125 <!-- ##### MACRO g_warning ##### -->
 126 <para>
 127 A convenience function/macro to log a warning message.
 128 </para>
 129
 130 <para>
 131 You can make warnings fatal at runtime by setting the %G_DEBUG environment
 132 variable (see <ulink url="glib-running.html">Running GLib Applications</ulink>).
 133 </para>
 134
 135 @...: format string, followed by parameters to insert into the format string (as with printf())
 136
 137
 138 <!-- ##### MACRO g_critical ##### -->
 139 <para>
 140 Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). It's more or less
 141 application-defined what constitutes a critical vs. a regular
 142 warning. You could call g_log_set_always_fatal() to make critical
 143 warnings exit the program, then use g_critical() for fatal errors, for
 144 example.
 145 </para>
 146
 147 <para>
 148 You can also make critical warnings fatal at runtime by setting
 149 the %G_DEBUG environment variable (see
 150 <ulink url="glib-running.html">Running GLib Applications</ulink>).
 151 </para>
 152
 153 @...: format string, followed by parameters to insert into the format string (as with printf())
 154
 155
 156 <!-- ##### MACRO g_error ##### -->
 157 <para>
 158 A convenience function/macro to log an error message.
 159 Error messages are always fatal, resulting in a call to
 160 abort() to terminate the application.
 161 This function will result in a core dump; don't use it for errors you
 162 expect. Using this function indicates a bug in your program, i.e. an
 163 assertion failure.
 164 </para>
 165
 166 @...: format string, followed by parameters to insert into the format string (as with printf())
 167
 168
 169 <!-- ##### MACRO g_debug ##### -->
 170 <para>
 171 A convenience function/macro to log a debug message.
 172 </para>
 173
 174 @...: format string, followed by parameters to insert into the format string (as with printf())
 175 @Since: 2.6
 176
 177
 178 <!-- ##### FUNCTION g_log_set_handler ##### -->
 179 <para>
 180 Sets the log handler for a domain and a set of log levels.
 181 To handle fatal and recursive messages the @log_levels parameter
 182 must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
 183 bit flags.
 184 </para>
 185 <para>
 186 Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
 187 you want to set a handler for this log level you must combine it with
 188 #G_LOG_FLAG_FATAL.
 189 </para>
 190
 191 <example>
 192 <title>Adding a log handler for all warning messages in the default
 193 (application) domain</title>
 194 <programlisting>
 195   g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
 196                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 197 </programlisting>
 198 </example>
 199
 200 <example>
 201 <title>Adding a log handler for all critical messages from GTK+</title>
 202 <programlisting>
 203   g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
 204                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 205 </programlisting>
 206 </example>
 207
 208 <example>
 209 <title>Adding a log handler for <emphasis>all</emphasis> messages from
 210 GLib</title>
 211 <programlisting>
 212   g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
 213                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 214 </programlisting>
 215 </example>
 216
 217 @log_domain: the log domain, or %NULL for the default "" application domain.
 218 @log_levels: the log levels to apply the log handler for. To handle fatal
 219 and recursive messages as well, combine the log levels with the
 220 #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags.
 221 @log_func: the log handler function.
 222 @user_data: data passed to the log handler.
 223 @Returns: the id of the new handler.
 224
 225
 226 <!-- ##### FUNCTION g_log_remove_handler ##### -->
 227 <para>
 228 Removes the log handler.
 229 </para>
 230
 231 @log_domain: the log domain.
 232 @handler_id: the id of the handler, which was returned in g_log_set_handler().
 233
 234
 235 <!-- ##### FUNCTION g_log_set_always_fatal ##### -->
 236 <para>
 237 Sets the message levels which are always fatal, in any log domain.
 238 When a message with any of these levels is logged the program terminates.
 239 You can only set the levels defined by GLib to be fatal.
 240 %G_LOG_LEVEL_ERROR is always fatal.
 241 </para>
 242
 243 <para>
 244 You can also make some message levels
 245 fatal at runtime by setting the %G_DEBUG environment variable (see
 246 <ulink url="glib-running.html">Running GLib Applications</ulink>).
 247 </para>
 248
 249 @fatal_mask: the mask containing bits set for each level of error which is
 250 to be fatal.
 251 @Returns: the old fatal mask.
 252
 253
 254 <!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
 255 <para>
 256 Sets the log levels which are fatal in the given domain.
 257 %G_LOG_LEVEL_ERROR is always fatal.
 258 </para>
 259
 260 @log_domain: the log domain.
 261 @fatal_mask: the new fatal mask.
 262 @Returns: the old fatal mask for the log domain.
 263
 264
 265 <!-- ##### FUNCTION g_log_default_handler ##### -->
 266 <para>
 267 The default log handler set up by GLib; g_log_set_default_handler()
 268 allows to install an alternate default log handler.
 269 This is used if no log handler has been set for the particular log domain
 270 and log level combination. It outputs the message to stderr or stdout
 271 and if the log level is fatal it calls abort().
 272 </para>
 273 <para>
 274 stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
 275 %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for the rest.
 276 </para>
 277
 278 @log_domain: the log domain of the message.
 279 @log_level: the level of the message.
 280 @message: the message.
 281 @unused_data: data passed from g_log() which is unused.
 282
 283
 284 <!-- ##### FUNCTION g_log_set_default_handler ##### -->
 285 <para>
 286 Installs a default log handler which is used if no
 287 log handler has been set for the particular log domain
 288 and log level combination. By default, GLib uses
 289 g_log_default_handler() as default log handler.
 290 </para>
 291
 292 @log_func: the log handler function.
 293 @user_data: data passed to the log handler.
 294 @Returns: the previous default log handler
 295 @Since: 2.6
 296
 297