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