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.
  72 </para>
  73
  74 @G_LOG_FLAG_RECURSION:
  75 @G_LOG_FLAG_FATAL:
  76 @G_LOG_LEVEL_ERROR:
  77 @G_LOG_LEVEL_CRITICAL:
  78 @G_LOG_LEVEL_WARNING:
  79 @G_LOG_LEVEL_MESSAGE:
  80 @G_LOG_LEVEL_INFO:
  81 @G_LOG_LEVEL_DEBUG:
  82 @G_LOG_LEVEL_MASK:
  83
  84 <!-- ##### FUNCTION g_log ##### -->
  85 <para>
  86 Logs an error or debugging message.
  87 If the log level has been set as fatal, the abort()
  88 function is called to terminate the program.
  89 </para>
  90
  91 @log_domain: the log domain, usually #G_LOG_DOMAIN.
  92 @log_level: the log level, either from #GLogLevelFlags or a user-defined level.
  93 @format: the message format. See the printf()
  94 documentation.
  95 @Varargs: the parameters to insert into the format string.
  96
  97
  98 <!-- ##### FUNCTION g_logv ##### -->
  99 <para>
 100 Logs an error or debugging message.
 101 If the log level has been set as fatal, the abort()
 102 function is called to terminate the program.
 103 </para>
 104
 105 @log_domain: the log domain.
 106 @log_level: the log level.
 107 @format: the message format. See the printf()
 108 documentation.
 109 @args: the parameters to insert into the format string.
 110
 111
 112 <!-- ##### MACRO g_message ##### -->
 113 <para>
 114 A convenience function/macro to log a normal message.
 115 </para>
 116
 117 @...: format string, followed by parameters to insert into the format string (as with printf())
 118
 119 @...:
 120
 121 @...:
 122
 123 @...:
 124
 125 @...:
 126
 127
 128 <!-- ##### MACRO g_warning ##### -->
 129 <para>
 130 A convenience function/macro to log a warning message.
 131 </para>
 132
 133 @...: format string, followed by parameters to insert into the format string (as with printf())
 134
 135 @...:
 136
 137 @...:
 138
 139 @...:
 140
 141 @...:
 142
 143
 144 <!-- ##### MACRO g_critical ##### -->
 145 <para>
 146 Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). It's more or less
 147 application-defined what constitutes a critical vs. a regular
 148 warning. You could call g_log_set_always_fatal() to make critical
 149 warnings exit the program, then use g_critical() for fatal errors, for
 150 example.
 151 </para>
 152
 153 @...: format string, followed by parameters to insert into the format string (as with printf())
 154
 155 @...:
 156
 157 @...:
 158
 159 @...:
 160
 161 @...:
 162
 163
 164 <!-- ##### MACRO g_error ##### -->
 165 <para>
 166 A convenience function/macro to log an error message.
 167 Error messages are always fatal, resulting in a call to
 168 abort() to terminate the application.
 169 This function will result in a core dump; don't use it for errors you
 170 expect. Using this function indicates a bug in your program, i.e. an
 171 assertion failure.
 172 </para>
 173
 174 @...: format string, followed by parameters to insert into the format string (as with printf())
 175
 176 @...:
 177
 178 @...:
 179
 180 @...:
 181
 182 @...:
 183
 184
 185 <!-- ##### MACRO g_debug ##### -->
 186 <para>
 187 A convenience function/macro to log a debug message.
 188 </para>
 189
 190 @...: format string, followed by parameters to insert into the format string (as with printf())
 191
 192 @...:
 193
 194 @...:
 195
 196 @...:
 197
 198 @...:
 199 @Since: 2.6
 200
 201
 202 <!-- ##### FUNCTION g_log_set_handler ##### -->
 203 <para>
 204 Sets the log handler for a domain and a set of log levels.
 205 To handle fatal and recursive messages the @log_levels parameter
 206 must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
 207 bit flags.
 208 </para>
 209 <para>
 210 Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
 211 you want to set a handler for this log level you must combine it with
 212 #G_LOG_FLAG_FATAL.
 213 </para>
 214
 215 <example>
 216 <title>Adding a log handler for all warning messages in the default
 217 (application) domain</title>
 218 <programlisting>
 219   g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
 220                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 221 </programlisting>
 222 </example>
 223
 224 <example>
 225 <title>Adding a log handler for all critical messages from GTK+</title>
 226 <programlisting>
 227   g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
 228                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 229 </programlisting>
 230 </example>
 231
 232 <example>
 233 <title>Adding a log handler for <emphasis>all</emphasis> messages from
 234 GLib</title>
 235 <programlisting>
 236   g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
 237                      | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
 238 </programlisting>
 239 </example>
 240
 241 @log_domain: the log domain, or %NULL for the default "" application domain.
 242 @log_levels: the log levels to apply the log handler for. To handle fatal
 243 and recursive messages as well, combine the log levels with the
 244 #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags.
 245 @log_func: the log handler function.
 246 @user_data: data passed to the log handler.
 247 @Returns: the id of the new handler.
 248
 249
 250 <!-- ##### FUNCTION g_log_remove_handler ##### -->
 251 <para>
 252 Removes the log handler.
 253 </para>
 254
 255 @log_domain: the log domain.
 256 @handler_id: the id of the handler, which was returned in g_log_set_handler().
 257
 258
 259 <!-- ##### FUNCTION g_log_set_always_fatal ##### -->
 260 <para>
 261 Sets the message levels which are always fatal, in any log domain.
 262 When a message with any of these levels is logged the program terminates.
 263 You can only set the levels defined by GLib to be fatal.
 264 %G_LOG_LEVEL_ERROR is always fatal.
 265 </para>
 266
 267 @fatal_mask: the mask containing bits set for each level of error which is
 268 to be fatal.
 269 @Returns: the old fatal mask.
 270
 271
 272 <!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
 273 <para>
 274 Sets the log levels which are fatal in the given domain.
 275 %G_LOG_LEVEL_ERROR is always fatal.
 276 </para>
 277
 278 @log_domain: the log domain.
 279 @fatal_mask: the new fatal mask.
 280 @Returns: the old fatal mask for the log domain.
 281
 282
 283 <!-- ##### FUNCTION g_log_default_handler ##### -->
 284 <para>
 285 The default log handler set up by GLib; g_log_set_default_handler()
 286 allows to install an alternate default log handler.
 287 This is used if no log handler has been set for the particular log domain
 288 and log level combination. It outputs the message to stderr or stdout
 289 and if the log level is fatal it calls abort().
 290 </para>
 291 <para>
 292 stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
 293 %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for the rest.
 294 </para>
 295
 296 @log_domain: the log domain of the message.
 297 @log_level: the level of the message.
 298 @message: the message.
 299 @unused_data: data passed from g_log() which is unused.
 300
 301
 302 <!-- ##### FUNCTION g_log_set_default_handler ##### -->
 303 <para>
 304 Installs a default log handler which is used is used if no
 305 log handler has been set for the particular log domain
 306 and log level combination. By default, GLib uses
 307 g_log_default_handler() as default log handler.
 308 </para>
 309
 310 @log_func: the log handler function.
 311 @user_data: data passed to the log handler.
 312 @Returns: the previous default log handler
 313 @Since: 2.6
 314
 315