1 | /* GLIB - Library of useful routines for C programming |
2 | * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Lesser General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2.1 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Lesser General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General Public |
15 | * License along with this library; if not, see <http://www.gnu.org/licenses/>. |
16 | */ |
17 | |
18 | /* |
19 | * Modified by the GLib Team and others 1997-2000. See the AUTHORS |
20 | * file for a list of people on the GLib Team. See the ChangeLog |
21 | * files for a list of changes. These files are distributed with |
22 | * GLib at ftp://ftp.gtk.org/pub/gtk/. |
23 | */ |
24 | |
25 | #ifndef __G_MESSAGES_H__ |
26 | #define __G_MESSAGES_H__ |
27 | |
28 | #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) |
29 | #error "Only <glib.h> can be included directly." |
30 | #endif |
31 | |
32 | #include <stdarg.h> |
33 | #include <glib/gatomic.h> |
34 | #include <glib/gtypes.h> |
35 | #include <glib/gmacros.h> |
36 | #include <glib/gvariant.h> |
37 | |
38 | G_BEGIN_DECLS |
39 | |
40 | /* calculate a string size, guaranteed to fit format + args. |
41 | */ |
42 | GLIB_AVAILABLE_IN_ALL |
43 | gsize g_printf_string_upper_bound (const gchar* format, |
44 | va_list args) G_GNUC_PRINTF(1, 0); |
45 | |
46 | /* Log level shift offset for user defined |
47 | * log levels (0-7 are used by GLib). |
48 | */ |
49 | #define G_LOG_LEVEL_USER_SHIFT (8) |
50 | |
51 | /* Glib log levels and flags. |
52 | */ |
53 | typedef enum |
54 | { |
55 | /* log flags */ |
56 | G_LOG_FLAG_RECURSION = 1 << 0, |
57 | G_LOG_FLAG_FATAL = 1 << 1, |
58 | |
59 | /* GLib log levels */ |
60 | G_LOG_LEVEL_ERROR = 1 << 2, /* always fatal */ |
61 | G_LOG_LEVEL_CRITICAL = 1 << 3, |
62 | G_LOG_LEVEL_WARNING = 1 << 4, |
63 | G_LOG_LEVEL_MESSAGE = 1 << 5, |
64 | G_LOG_LEVEL_INFO = 1 << 6, |
65 | G_LOG_LEVEL_DEBUG = 1 << 7, |
66 | |
67 | G_LOG_LEVEL_MASK = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL) |
68 | } GLogLevelFlags; |
69 | |
70 | /* GLib log levels that are considered fatal by default */ |
71 | #define G_LOG_FATAL_MASK (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR) |
72 | |
73 | typedef void (*GLogFunc) (const gchar *log_domain, |
74 | GLogLevelFlags log_level, |
75 | const gchar *message, |
76 | gpointer user_data); |
77 | |
78 | /* Logging mechanism |
79 | */ |
80 | GLIB_AVAILABLE_IN_ALL |
81 | guint g_log_set_handler (const gchar *log_domain, |
82 | GLogLevelFlags log_levels, |
83 | GLogFunc log_func, |
84 | gpointer user_data); |
85 | GLIB_AVAILABLE_IN_2_46 |
86 | guint g_log_set_handler_full (const gchar *log_domain, |
87 | GLogLevelFlags log_levels, |
88 | GLogFunc log_func, |
89 | gpointer user_data, |
90 | GDestroyNotify destroy); |
91 | GLIB_AVAILABLE_IN_ALL |
92 | void g_log_remove_handler (const gchar *log_domain, |
93 | guint handler_id); |
94 | GLIB_AVAILABLE_IN_ALL |
95 | void g_log_default_handler (const gchar *log_domain, |
96 | GLogLevelFlags log_level, |
97 | const gchar *message, |
98 | gpointer unused_data); |
99 | GLIB_AVAILABLE_IN_ALL |
100 | GLogFunc g_log_set_default_handler (GLogFunc log_func, |
101 | gpointer user_data); |
102 | GLIB_AVAILABLE_IN_ALL |
103 | void g_log (const gchar *log_domain, |
104 | GLogLevelFlags log_level, |
105 | const gchar *format, |
106 | ...) G_GNUC_PRINTF (3, 4); |
107 | GLIB_AVAILABLE_IN_ALL |
108 | void g_logv (const gchar *log_domain, |
109 | GLogLevelFlags log_level, |
110 | const gchar *format, |
111 | va_list args) G_GNUC_PRINTF(3, 0); |
112 | GLIB_AVAILABLE_IN_ALL |
113 | GLogLevelFlags g_log_set_fatal_mask (const gchar *log_domain, |
114 | GLogLevelFlags fatal_mask); |
115 | GLIB_AVAILABLE_IN_ALL |
116 | GLogLevelFlags g_log_set_always_fatal (GLogLevelFlags fatal_mask); |
117 | |
118 | /* Structured logging mechanism. */ |
119 | |
120 | /** |
121 | * GLogWriterOutput: |
122 | * @G_LOG_WRITER_HANDLED: Log writer has handled the log entry. |
123 | * @G_LOG_WRITER_UNHANDLED: Log writer could not handle the log entry. |
124 | * |
125 | * Return values from #GLogWriterFuncs to indicate whether the given log entry |
126 | * was successfully handled by the writer, or whether there was an error in |
127 | * handling it (and hence a fallback writer should be used). |
128 | * |
129 | * If a #GLogWriterFunc ignores a log entry, it should return |
130 | * %G_LOG_WRITER_HANDLED. |
131 | * |
132 | * Since: 2.50 |
133 | */ |
134 | typedef enum |
135 | { |
136 | G_LOG_WRITER_HANDLED = 1, |
137 | G_LOG_WRITER_UNHANDLED = 0, |
138 | } GLogWriterOutput; |
139 | |
140 | /** |
141 | * GLogField: |
142 | * @key: field name (UTF-8 string) |
143 | * @value: field value (arbitrary bytes) |
144 | * @length: length of @value, in bytes, or -1 if it is nul-terminated |
145 | * |
146 | * Structure representing a single field in a structured log entry. See |
147 | * g_log_structured() for details. |
148 | * |
149 | * Log fields may contain arbitrary values, including binary with embedded nul |
150 | * bytes. If the field contains a string, the string must be UTF-8 encoded and |
151 | * have a trailing nul byte. Otherwise, @length must be set to a non-negative |
152 | * value. |
153 | * |
154 | * Since: 2.50 |
155 | */ |
156 | typedef struct _GLogField GLogField; |
157 | struct _GLogField |
158 | { |
159 | const gchar *key; |
160 | gconstpointer value; |
161 | gssize length; |
162 | }; |
163 | |
164 | /** |
165 | * GLogWriterFunc: |
166 | * @log_level: log level of the message |
167 | * @fields: (array length=n_fields): fields forming the message |
168 | * @n_fields: number of @fields |
169 | * @user_data: user data passed to g_log_set_writer_func() |
170 | * |
171 | * Writer function for log entries. A log entry is a collection of one or more |
172 | * #GLogFields, using the standard [field names from journal |
173 | * specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html). |
174 | * See g_log_structured() for more information. |
175 | * |
176 | * Writer functions must ignore fields which they do not recognise, unless they |
177 | * can write arbitrary binary output, as field values may be arbitrary binary. |
178 | * |
179 | * @log_level is guaranteed to be included in @fields as the `PRIORITY` field, |
180 | * but is provided separately for convenience of deciding whether or where to |
181 | * output the log entry. |
182 | * |
183 | * Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log |
184 | * message successfully or if they deliberately ignored it. If there was an |
185 | * error handling the message (for example, if the writer function is meant to |
186 | * send messages to a remote logging server and there is a network error), it |
187 | * should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be |
188 | * chained and fall back to simpler handlers in case of failure. |
189 | * |
190 | * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully; |
191 | * %G_LOG_WRITER_UNHANDLED otherwise |
192 | * Since: 2.50 |
193 | */ |
194 | typedef GLogWriterOutput (*GLogWriterFunc) (GLogLevelFlags log_level, |
195 | const GLogField *fields, |
196 | gsize n_fields, |
197 | gpointer user_data); |
198 | |
199 | GLIB_AVAILABLE_IN_2_50 |
200 | void g_log_structured (const gchar *log_domain, |
201 | GLogLevelFlags log_level, |
202 | ...); |
203 | GLIB_AVAILABLE_IN_2_50 |
204 | void g_log_structured_array (GLogLevelFlags log_level, |
205 | const GLogField *fields, |
206 | gsize n_fields); |
207 | |
208 | GLIB_AVAILABLE_IN_2_50 |
209 | void g_log_variant (const gchar *log_domain, |
210 | GLogLevelFlags log_level, |
211 | GVariant *fields); |
212 | |
213 | GLIB_AVAILABLE_IN_2_50 |
214 | void g_log_set_writer_func (GLogWriterFunc func, |
215 | gpointer user_data, |
216 | GDestroyNotify user_data_free); |
217 | |
218 | GLIB_AVAILABLE_IN_2_50 |
219 | gboolean g_log_writer_supports_color (gint output_fd); |
220 | GLIB_AVAILABLE_IN_2_50 |
221 | gboolean g_log_writer_is_journald (gint output_fd); |
222 | |
223 | GLIB_AVAILABLE_IN_2_50 |
224 | gchar *g_log_writer_format_fields (GLogLevelFlags log_level, |
225 | const GLogField *fields, |
226 | gsize n_fields, |
227 | gboolean use_color); |
228 | |
229 | GLIB_AVAILABLE_IN_2_50 |
230 | GLogWriterOutput g_log_writer_journald (GLogLevelFlags log_level, |
231 | const GLogField *fields, |
232 | gsize n_fields, |
233 | gpointer user_data); |
234 | GLIB_AVAILABLE_IN_2_50 |
235 | GLogWriterOutput g_log_writer_standard_streams (GLogLevelFlags log_level, |
236 | const GLogField *fields, |
237 | gsize n_fields, |
238 | gpointer user_data); |
239 | GLIB_AVAILABLE_IN_2_50 |
240 | GLogWriterOutput g_log_writer_default (GLogLevelFlags log_level, |
241 | const GLogField *fields, |
242 | gsize n_fields, |
243 | gpointer user_data); |
244 | |
245 | GLIB_AVAILABLE_IN_2_68 |
246 | void g_log_writer_default_set_use_stderr (gboolean use_stderr); |
247 | GLIB_AVAILABLE_IN_2_68 |
248 | gboolean g_log_writer_default_would_drop (GLogLevelFlags log_level, |
249 | const char *log_domain); |
250 | |
251 | /** |
252 | * G_DEBUG_HERE: |
253 | * |
254 | * A convenience form of g_log_structured(), recommended to be added to |
255 | * functions when debugging. It prints the current monotonic time and the code |
256 | * location using %G_STRLOC. |
257 | * |
258 | * Since: 2.50 |
259 | */ |
260 | #define G_DEBUG_HERE() \ |
261 | g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
262 | "CODE_FILE", __FILE__, \ |
263 | "CODE_LINE", G_STRINGIFY (__LINE__), \ |
264 | "CODE_FUNC", G_STRFUNC, \ |
265 | "MESSAGE", "%" G_GINT64_FORMAT ": %s", \ |
266 | g_get_monotonic_time (), G_STRLOC) |
267 | |
268 | /* internal */ |
269 | void _g_log_fallback_handler (const gchar *log_domain, |
270 | GLogLevelFlags log_level, |
271 | const gchar *message, |
272 | gpointer unused_data); |
273 | |
274 | /* Internal functions, used to implement the following macros */ |
275 | GLIB_AVAILABLE_IN_ALL |
276 | void g_return_if_fail_warning (const char *log_domain, |
277 | const char *pretty_function, |
278 | const char *expression) G_ANALYZER_NORETURN; |
279 | GLIB_AVAILABLE_IN_ALL |
280 | void g_warn_message (const char *domain, |
281 | const char *file, |
282 | int line, |
283 | const char *func, |
284 | const char *warnexpr) G_ANALYZER_NORETURN; |
285 | GLIB_DEPRECATED |
286 | G_NORETURN |
287 | void g_assert_warning (const char *log_domain, |
288 | const char *file, |
289 | const int line, |
290 | const char *pretty_function, |
291 | const char *expression); |
292 | |
293 | GLIB_AVAILABLE_IN_2_56 |
294 | void g_log_structured_standard (const gchar *log_domain, |
295 | GLogLevelFlags log_level, |
296 | const gchar *file, |
297 | const gchar *line, |
298 | const gchar *func, |
299 | const gchar *message_format, |
300 | ...) G_GNUC_PRINTF (6, 7); |
301 | |
302 | #ifndef G_LOG_DOMAIN |
303 | #define G_LOG_DOMAIN ((gchar*) 0) |
304 | #endif /* G_LOG_DOMAIN */ |
305 | |
306 | #if defined(G_HAVE_ISO_VARARGS) && !G_ANALYZER_ANALYZING |
307 | #if defined(G_LOG_USE_STRUCTURED) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_56 |
308 | #define g_error(...) G_STMT_START { \ |
309 | g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, \ |
310 | __FILE__, G_STRINGIFY (__LINE__), \ |
311 | G_STRFUNC, __VA_ARGS__); \ |
312 | for (;;) ; \ |
313 | } G_STMT_END |
314 | #define g_message(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, \ |
315 | __FILE__, G_STRINGIFY (__LINE__), \ |
316 | G_STRFUNC, __VA_ARGS__) |
317 | #define g_critical(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \ |
318 | __FILE__, G_STRINGIFY (__LINE__), \ |
319 | G_STRFUNC, __VA_ARGS__) |
320 | #define g_warning(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, \ |
321 | __FILE__, G_STRINGIFY (__LINE__), \ |
322 | G_STRFUNC, __VA_ARGS__) |
323 | #define g_info(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, \ |
324 | __FILE__, G_STRINGIFY (__LINE__), \ |
325 | G_STRFUNC, __VA_ARGS__) |
326 | #define g_debug(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
327 | __FILE__, G_STRINGIFY (__LINE__), \ |
328 | G_STRFUNC, __VA_ARGS__) |
329 | #else |
330 | /* for(;;) ; so that GCC knows that control doesn't go past g_error(). |
331 | * Put space before ending semicolon to avoid C++ build warnings. |
332 | */ |
333 | #define g_error(...) G_STMT_START { \ |
334 | g_log (G_LOG_DOMAIN, \ |
335 | G_LOG_LEVEL_ERROR, \ |
336 | __VA_ARGS__); \ |
337 | for (;;) ; \ |
338 | } G_STMT_END |
339 | #define g_message(...) g_log (G_LOG_DOMAIN, \ |
340 | G_LOG_LEVEL_MESSAGE, \ |
341 | __VA_ARGS__) |
342 | #define g_critical(...) g_log (G_LOG_DOMAIN, \ |
343 | G_LOG_LEVEL_CRITICAL, \ |
344 | __VA_ARGS__) |
345 | #define g_warning(...) g_log (G_LOG_DOMAIN, \ |
346 | G_LOG_LEVEL_WARNING, \ |
347 | __VA_ARGS__) |
348 | #define g_info(...) g_log (G_LOG_DOMAIN, \ |
349 | G_LOG_LEVEL_INFO, \ |
350 | __VA_ARGS__) |
351 | #define g_debug(...) g_log (G_LOG_DOMAIN, \ |
352 | G_LOG_LEVEL_DEBUG, \ |
353 | __VA_ARGS__) |
354 | #endif |
355 | #elif defined(G_HAVE_GNUC_VARARGS) && !G_ANALYZER_ANALYZING |
356 | #if defined(G_LOG_USE_STRUCTURED) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_56 |
357 | #define g_error(format...) G_STMT_START { \ |
358 | g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, \ |
359 | __FILE__, G_STRINGIFY (__LINE__), \ |
360 | G_STRFUNC, format); \ |
361 | for (;;) ; \ |
362 | } G_STMT_END |
363 | #define g_message(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, \ |
364 | __FILE__, G_STRINGIFY (__LINE__), \ |
365 | G_STRFUNC, format) |
366 | #define g_critical(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \ |
367 | __FILE__, G_STRINGIFY (__LINE__), \ |
368 | G_STRFUNC, format) |
369 | #define g_warning(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, \ |
370 | __FILE__, G_STRINGIFY (__LINE__), \ |
371 | G_STRFUNC, format) |
372 | #define g_info(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, \ |
373 | __FILE__, G_STRINGIFY (__LINE__), \ |
374 | G_STRFUNC, format) |
375 | #define g_debug(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ |
376 | __FILE__, G_STRINGIFY (__LINE__), \ |
377 | G_STRFUNC, format) |
378 | #else |
379 | #define g_error(format...) G_STMT_START { \ |
380 | g_log (G_LOG_DOMAIN, \ |
381 | G_LOG_LEVEL_ERROR, \ |
382 | format); \ |
383 | for (;;) ; \ |
384 | } G_STMT_END |
385 | |
386 | #define g_message(format...) g_log (G_LOG_DOMAIN, \ |
387 | G_LOG_LEVEL_MESSAGE, \ |
388 | format) |
389 | #define g_critical(format...) g_log (G_LOG_DOMAIN, \ |
390 | G_LOG_LEVEL_CRITICAL, \ |
391 | format) |
392 | #define g_warning(format...) g_log (G_LOG_DOMAIN, \ |
393 | G_LOG_LEVEL_WARNING, \ |
394 | format) |
395 | #define g_info(format...) g_log (G_LOG_DOMAIN, \ |
396 | G_LOG_LEVEL_INFO, \ |
397 | format) |
398 | #define g_debug(format...) g_log (G_LOG_DOMAIN, \ |
399 | G_LOG_LEVEL_DEBUG, \ |
400 | format) |
401 | #endif |
402 | #else /* no varargs macros */ |
403 | static G_NORETURN void g_error (const gchar *format, ...) G_ANALYZER_NORETURN; |
404 | static void g_critical (const gchar *format, ...) G_ANALYZER_NORETURN; |
405 | |
406 | static inline void |
407 | g_error (const gchar *format, |
408 | ...) |
409 | { |
410 | va_list args; |
411 | va_start (args, format); |
412 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, format, args); |
413 | va_end (args); |
414 | |
415 | for(;;) ; |
416 | } |
417 | static inline void |
418 | g_message (const gchar *format, |
419 | ...) |
420 | { |
421 | va_list args; |
422 | va_start (args, format); |
423 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, format, args); |
424 | va_end (args); |
425 | } |
426 | static inline void |
427 | g_critical (const gchar *format, |
428 | ...) |
429 | { |
430 | va_list args; |
431 | va_start (args, format); |
432 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, format, args); |
433 | va_end (args); |
434 | } |
435 | static inline void |
436 | g_warning (const gchar *format, |
437 | ...) |
438 | { |
439 | va_list args; |
440 | va_start (args, format); |
441 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, format, args); |
442 | va_end (args); |
443 | } |
444 | static inline void |
445 | g_info (const gchar *format, |
446 | ...) |
447 | { |
448 | va_list args; |
449 | va_start (args, format); |
450 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, format, args); |
451 | va_end (args); |
452 | } |
453 | static inline void |
454 | g_debug (const gchar *format, |
455 | ...) |
456 | { |
457 | va_list args; |
458 | va_start (args, format); |
459 | g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, format, args); |
460 | va_end (args); |
461 | } |
462 | #endif /* !__GNUC__ */ |
463 | |
464 | /** |
465 | * g_warning_once: |
466 | * @...: format string, followed by parameters to insert |
467 | * into the format string (as with printf()) |
468 | * |
469 | * Logs a warning only once. |
470 | * |
471 | * g_warning_once() calls g_warning() with the passed message the first time |
472 | * the statement is executed; subsequent times it is a no-op. |
473 | * |
474 | * Note! On platforms where the compiler doesn't support variadic macros, the |
475 | * warning is printed each time instead of only once. |
476 | * |
477 | * Since: 2.64 |
478 | */ |
479 | #if defined(G_HAVE_ISO_VARARGS) && !G_ANALYZER_ANALYZING |
480 | #define g_warning_once(...) \ |
481 | G_STMT_START { \ |
482 | static int G_PASTE (_GWarningOnceBoolean, __LINE__) = 0; /* (atomic) */ \ |
483 | if (g_atomic_int_compare_and_exchange (&G_PASTE (_GWarningOnceBoolean, __LINE__), \ |
484 | 0, 1)) \ |
485 | g_warning (__VA_ARGS__); \ |
486 | } G_STMT_END \ |
487 | GLIB_AVAILABLE_MACRO_IN_2_64 |
488 | #elif defined(G_HAVE_GNUC_VARARGS) && !G_ANALYZER_ANALYZING |
489 | #define g_warning_once(format...) \ |
490 | G_STMT_START { \ |
491 | static int G_PASTE (_GWarningOnceBoolean, __LINE__) = 0; /* (atomic) */ \ |
492 | if (g_atomic_int_compare_and_exchange (&G_PASTE (_GWarningOnceBoolean, __LINE__), \ |
493 | 0, 1)) \ |
494 | g_warning (format); \ |
495 | } G_STMT_END \ |
496 | GLIB_AVAILABLE_MACRO_IN_2_64 |
497 | #else |
498 | #define g_warning_once g_warning |
499 | #endif |
500 | |
501 | /** |
502 | * GPrintFunc: |
503 | * @string: the message to output |
504 | * |
505 | * Specifies the type of the print handler functions. |
506 | * These are called with the complete formatted string to output. |
507 | */ |
508 | typedef void (*GPrintFunc) (const gchar *string); |
509 | GLIB_AVAILABLE_IN_ALL |
510 | void g_print (const gchar *format, |
511 | ...) G_GNUC_PRINTF (1, 2); |
512 | GLIB_AVAILABLE_IN_ALL |
513 | GPrintFunc g_set_print_handler (GPrintFunc func); |
514 | GLIB_AVAILABLE_IN_ALL |
515 | void g_printerr (const gchar *format, |
516 | ...) G_GNUC_PRINTF (1, 2); |
517 | GLIB_AVAILABLE_IN_ALL |
518 | GPrintFunc g_set_printerr_handler (GPrintFunc func); |
519 | |
520 | /** |
521 | * g_warn_if_reached: |
522 | * |
523 | * Logs a warning. |
524 | * |
525 | * Since: 2.16 |
526 | */ |
527 | #define g_warn_if_reached() \ |
528 | do { \ |
529 | g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); \ |
530 | } while (0) |
531 | |
532 | /** |
533 | * g_warn_if_fail: |
534 | * @expr: the expression to check |
535 | * |
536 | * Logs a warning if the expression is not true. |
537 | * |
538 | * Since: 2.16 |
539 | */ |
540 | #define g_warn_if_fail(expr) \ |
541 | do { \ |
542 | if G_LIKELY (expr) ; \ |
543 | else g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); \ |
544 | } while (0) |
545 | |
546 | #ifdef G_DISABLE_CHECKS |
547 | |
548 | /** |
549 | * g_return_if_fail: |
550 | * @expr: the expression to check |
551 | * |
552 | * Verifies that the expression @expr, usually representing a precondition, |
553 | * evaluates to %TRUE. If the function returns a value, use |
554 | * g_return_val_if_fail() instead. |
555 | * |
556 | * If @expr evaluates to %FALSE, the current function should be considered to |
557 | * have undefined behaviour (a programmer error). The only correct solution |
558 | * to such an error is to change the module that is calling the current |
559 | * function, so that it avoids this incorrect call. |
560 | * |
561 | * To make this undefined behaviour visible, if @expr evaluates to %FALSE, |
562 | * the result is usually that a critical message is logged and the current |
563 | * function returns. |
564 | * |
565 | * If `G_DISABLE_CHECKS` is defined then the check is not performed. You |
566 | * should therefore not depend on any side effects of @expr. |
567 | * |
568 | * To debug failure of a g_return_if_fail() check, run the code under a debugger |
569 | * with `G_DEBUG=fatal-criticals` or `G_DEBUG=fatal-warnings` defined in the |
570 | * environment (see [Running GLib Applications](glib-running.html)): |
571 | * |
572 | * |[ |
573 | * G_DEBUG=fatal-warnings gdb ./my-program |
574 | * ]| |
575 | * |
576 | * Any unrelated failures can be skipped over in |
577 | * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. |
578 | */ |
579 | #define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END |
580 | |
581 | /** |
582 | * g_return_val_if_fail: |
583 | * @expr: the expression to check |
584 | * @val: the value to return from the current function |
585 | * if the expression is not true |
586 | * |
587 | * Verifies that the expression @expr, usually representing a precondition, |
588 | * evaluates to %TRUE. If the function does not return a value, use |
589 | * g_return_if_fail() instead. |
590 | * |
591 | * If @expr evaluates to %FALSE, the current function should be considered to |
592 | * have undefined behaviour (a programmer error). The only correct solution |
593 | * to such an error is to change the module that is calling the current |
594 | * function, so that it avoids this incorrect call. |
595 | * |
596 | * To make this undefined behaviour visible, if @expr evaluates to %FALSE, |
597 | * the result is usually that a critical message is logged and @val is |
598 | * returned from the current function. |
599 | * |
600 | * If `G_DISABLE_CHECKS` is defined then the check is not performed. You |
601 | * should therefore not depend on any side effects of @expr. |
602 | * |
603 | * See g_return_if_fail() for guidance on how to debug failure of this check. |
604 | */ |
605 | #define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END |
606 | |
607 | /** |
608 | * g_return_if_reached: |
609 | * |
610 | * Logs a critical message and returns from the current function. |
611 | * This can only be used in functions which do not return a value. |
612 | * |
613 | * See g_return_if_fail() for guidance on how to debug failure of this check. |
614 | */ |
615 | #define g_return_if_reached() G_STMT_START{ return; }G_STMT_END |
616 | |
617 | /** |
618 | * g_return_val_if_reached: |
619 | * @val: the value to return from the current function |
620 | * |
621 | * Logs a critical message and returns @val. |
622 | * |
623 | * See g_return_if_fail() for guidance on how to debug failure of this check. |
624 | */ |
625 | #define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END |
626 | |
627 | #else /* !G_DISABLE_CHECKS */ |
628 | |
629 | #define g_return_if_fail(expr) \ |
630 | G_STMT_START { \ |
631 | if (G_LIKELY (expr)) \ |
632 | { } \ |
633 | else \ |
634 | { \ |
635 | g_return_if_fail_warning (G_LOG_DOMAIN, \ |
636 | G_STRFUNC, \ |
637 | #expr); \ |
638 | return; \ |
639 | } \ |
640 | } G_STMT_END |
641 | |
642 | #define g_return_val_if_fail(expr, val) \ |
643 | G_STMT_START { \ |
644 | if (G_LIKELY (expr)) \ |
645 | { } \ |
646 | else \ |
647 | { \ |
648 | g_return_if_fail_warning (G_LOG_DOMAIN, \ |
649 | G_STRFUNC, \ |
650 | #expr); \ |
651 | return (val); \ |
652 | } \ |
653 | } G_STMT_END |
654 | |
655 | #define g_return_if_reached() \ |
656 | G_STMT_START { \ |
657 | g_log (G_LOG_DOMAIN, \ |
658 | G_LOG_LEVEL_CRITICAL, \ |
659 | "file %s: line %d (%s): should not be reached", \ |
660 | __FILE__, \ |
661 | __LINE__, \ |
662 | G_STRFUNC); \ |
663 | return; \ |
664 | } G_STMT_END |
665 | |
666 | #define g_return_val_if_reached(val) \ |
667 | G_STMT_START { \ |
668 | g_log (G_LOG_DOMAIN, \ |
669 | G_LOG_LEVEL_CRITICAL, \ |
670 | "file %s: line %d (%s): should not be reached", \ |
671 | __FILE__, \ |
672 | __LINE__, \ |
673 | G_STRFUNC); \ |
674 | return (val); \ |
675 | } G_STMT_END |
676 | |
677 | #endif /* !G_DISABLE_CHECKS */ |
678 | |
679 | G_END_DECLS |
680 | |
681 | #endif /* __G_MESSAGES_H__ */ |
682 | |