Back to home page

EIC code displayed by LXR
 
 

    

File indexing completed on 2025-12-21 09:54:06 

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019 
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026 
0027 #ifndef __G_MESSAGES_H__
0028 #define __G_MESSAGES_H__
0029 
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033 
0034 #include <stdarg.h>
0035 #include <glib/gatomic.h>
0036 #include <glib/gtypes.h>
0037 #include <glib/gmacros.h>
0038 #include <glib/gvariant.h>
0039 
0040 G_BEGIN_DECLS
0041 
0042 /* calculate a string size, guaranteed to fit format + args.
0043  */
0044 GLIB_AVAILABLE_IN_ALL
0045 gsize   g_printf_string_upper_bound (const gchar* format,
0046                      va_list      args) G_GNUC_PRINTF(1, 0);
0047 
0048 /* Log level shift offset for user defined
0049  * log levels (0-7 are used by GLib).
0050  */
0051 #define G_LOG_LEVEL_USER_SHIFT  (8)
0052 
0053 /* Glib log levels and flags.
0054  */
0055 typedef enum
0056 {
0057   /* log flags */
0058   G_LOG_FLAG_RECURSION          = 1 << 0,
0059   G_LOG_FLAG_FATAL              = 1 << 1,
0060 
0061   /* GLib log levels */
0062   G_LOG_LEVEL_ERROR             = 1 << 2,       /* always fatal */
0063   G_LOG_LEVEL_CRITICAL          = 1 << 3,
0064   G_LOG_LEVEL_WARNING           = 1 << 4,
0065   G_LOG_LEVEL_MESSAGE           = 1 << 5,
0066   G_LOG_LEVEL_INFO              = 1 << 6,
0067   G_LOG_LEVEL_DEBUG             = 1 << 7,
0068 
0069   G_LOG_LEVEL_MASK              = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
0070 } GLogLevelFlags;
0071 
0072 /* GLib log levels that are considered fatal by default */
0073 #define G_LOG_FATAL_MASK        (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)
0074 
0075 typedef void            (*GLogFunc)             (const gchar   *log_domain,
0076                                                  GLogLevelFlags log_level,
0077                                                  const gchar   *message,
0078                                                  gpointer       user_data);
0079 
0080 /* Logging mechanism
0081  */
0082 GLIB_AVAILABLE_IN_ALL
0083 guint           g_log_set_handler       (const gchar    *log_domain,
0084                                          GLogLevelFlags  log_levels,
0085                                          GLogFunc        log_func,
0086                                          gpointer        user_data);
0087 GLIB_AVAILABLE_IN_2_46
0088 guint           g_log_set_handler_full  (const gchar    *log_domain,
0089                                          GLogLevelFlags  log_levels,
0090                                          GLogFunc        log_func,
0091                                          gpointer        user_data,
0092                                          GDestroyNotify  destroy);
0093 GLIB_AVAILABLE_IN_ALL
0094 void            g_log_remove_handler    (const gchar    *log_domain,
0095                                          guint           handler_id);
0096 GLIB_AVAILABLE_IN_ALL
0097 void            g_log_default_handler   (const gchar    *log_domain,
0098                                          GLogLevelFlags  log_level,
0099                                          const gchar    *message,
0100                                          gpointer        unused_data);
0101 GLIB_AVAILABLE_IN_ALL
0102 GLogFunc        g_log_set_default_handler (GLogFunc      log_func,
0103                        gpointer      user_data);
0104 GLIB_AVAILABLE_IN_ALL
0105 void            g_log                   (const gchar    *log_domain,
0106                                          GLogLevelFlags  log_level,
0107                                          const gchar    *format,
0108                                          ...) G_GNUC_PRINTF (3, 4);
0109 GLIB_AVAILABLE_IN_ALL
0110 void            g_logv                  (const gchar    *log_domain,
0111                                          GLogLevelFlags  log_level,
0112                                          const gchar    *format,
0113                                          va_list         args) G_GNUC_PRINTF(3, 0);
0114 GLIB_AVAILABLE_IN_ALL
0115 GLogLevelFlags  g_log_set_fatal_mask    (const gchar    *log_domain,
0116                                          GLogLevelFlags  fatal_mask);
0117 GLIB_AVAILABLE_IN_ALL
0118 GLogLevelFlags  g_log_set_always_fatal  (GLogLevelFlags  fatal_mask);
0119 
0120 /* Structured logging mechanism. */
0121 
0122 /**
0123  * GLogWriterOutput:
0124  * @G_LOG_WRITER_HANDLED: Log writer has handled the log entry.
0125  * @G_LOG_WRITER_UNHANDLED: Log writer could not handle the log entry.
0126  *
0127  * Return values from #GLogWriterFuncs to indicate whether the given log entry
0128  * was successfully handled by the writer, or whether there was an error in
0129  * handling it (and hence a fallback writer should be used).
0130  *
0131  * If a #GLogWriterFunc ignores a log entry, it should return
0132  * %G_LOG_WRITER_HANDLED.
0133  *
0134  * Since: 2.50
0135  */
0136 typedef enum
0137 {
0138   G_LOG_WRITER_HANDLED = 1,
0139   G_LOG_WRITER_UNHANDLED = 0,
0140 } GLogWriterOutput;
0141 
0142 /**
0143  * GLogField:
0144  * @key: field name (UTF-8 string)
0145  * @value: field value (arbitrary bytes)
0146  * @length: length of @value, in bytes, or -1 if it is nul-terminated
0147  *
0148  * Structure representing a single field in a structured log entry. See
0149  * g_log_structured() for details.
0150  *
0151  * Log fields may contain arbitrary values, including binary with embedded nul
0152  * bytes. If the field contains a string, the string must be UTF-8 encoded and
0153  * have a trailing nul byte. Otherwise, @length must be set to a non-negative
0154  * value.
0155  *
0156  * Since: 2.50
0157  */
0158 typedef struct _GLogField GLogField;
0159 struct _GLogField
0160 {
0161   const gchar *key;
0162   gconstpointer value;
0163   gssize length;
0164 };
0165 
0166 /**
0167  * GLogWriterFunc:
0168  * @log_level: log level of the message
0169  * @fields: (array length=n_fields): fields forming the message
0170  * @n_fields: number of @fields
0171  * @user_data: user data passed to g_log_set_writer_func()
0172  *
0173  * Writer function for log entries. A log entry is a collection of one or more
0174  * #GLogFields, using the standard [field names from journal
0175  * specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html).
0176  * See g_log_structured() for more information.
0177  *
0178  * Writer functions must ignore fields which they do not recognise, unless they
0179  * can write arbitrary binary output, as field values may be arbitrary binary.
0180  *
0181  * @log_level is guaranteed to be included in @fields as the `PRIORITY` field,
0182  * but is provided separately for convenience of deciding whether or where to
0183  * output the log entry.
0184  *
0185  * Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log
0186  * message successfully or if they deliberately ignored it. If there was an
0187  * error handling the message (for example, if the writer function is meant to
0188  * send messages to a remote logging server and there is a network error), it
0189  * should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be
0190  * chained and fall back to simpler handlers in case of failure.
0191  *
0192  * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
0193  *   %G_LOG_WRITER_UNHANDLED otherwise
0194  *
0195  * Since: 2.50
0196  */
0197 typedef GLogWriterOutput (*GLogWriterFunc)     (GLogLevelFlags   log_level,
0198                                                 const GLogField *fields,
0199                                                 gsize            n_fields,
0200                                                 gpointer         user_data);
0201 
0202 GLIB_AVAILABLE_IN_2_50
0203 void             g_log_structured              (const gchar     *log_domain,
0204                                                 GLogLevelFlags   log_level,
0205                                                 ...);
0206 GLIB_AVAILABLE_IN_2_50
0207 void             g_log_structured_array        (GLogLevelFlags   log_level,
0208                                                 const GLogField *fields,
0209                                                 gsize            n_fields);
0210 
0211 GLIB_AVAILABLE_IN_2_50
0212 void             g_log_variant                 (const gchar     *log_domain,
0213                                                 GLogLevelFlags   log_level,
0214                                                 GVariant        *fields);
0215 
0216 GLIB_AVAILABLE_IN_2_50
0217 void             g_log_set_writer_func         (GLogWriterFunc   func,
0218                                                 gpointer         user_data,
0219                                                 GDestroyNotify   user_data_free);
0220 
0221 GLIB_AVAILABLE_IN_2_50
0222 gboolean         g_log_writer_supports_color   (gint             output_fd);
0223 GLIB_AVAILABLE_IN_2_50
0224 gboolean         g_log_writer_is_journald      (gint             output_fd);
0225 
0226 GLIB_AVAILABLE_IN_2_50
0227 gchar           *g_log_writer_format_fields    (GLogLevelFlags   log_level,
0228                                                 const GLogField *fields,
0229                                                 gsize            n_fields,
0230                                                 gboolean         use_color);
0231 
0232 GLIB_AVAILABLE_IN_2_80
0233 GLogWriterOutput g_log_writer_syslog           (GLogLevelFlags   log_level,
0234                                                 const GLogField *fields,
0235                                                 gsize            n_fields,
0236                                                 gpointer         user_data);
0237 GLIB_AVAILABLE_IN_2_50
0238 GLogWriterOutput g_log_writer_journald         (GLogLevelFlags   log_level,
0239                                                 const GLogField *fields,
0240                                                 gsize            n_fields,
0241                                                 gpointer         user_data);
0242 GLIB_AVAILABLE_IN_2_50
0243 GLogWriterOutput g_log_writer_standard_streams (GLogLevelFlags   log_level,
0244                                                 const GLogField *fields,
0245                                                 gsize            n_fields,
0246                                                 gpointer         user_data);
0247 GLIB_AVAILABLE_IN_2_50
0248 GLogWriterOutput g_log_writer_default          (GLogLevelFlags   log_level,
0249                                                 const GLogField *fields,
0250                                                 gsize            n_fields,
0251                                                 gpointer         user_data);
0252 
0253 GLIB_AVAILABLE_IN_2_68
0254 void            g_log_writer_default_set_use_stderr (gboolean use_stderr);
0255 GLIB_AVAILABLE_IN_2_68
0256 gboolean        g_log_writer_default_would_drop (GLogLevelFlags  log_level,
0257                                                  const char     *log_domain);
0258 GLIB_AVAILABLE_IN_2_80
0259 void            g_log_writer_default_set_debug_domains (const gchar * const *domains);
0260 
0261 
0262 /* G_MESSAGES_DEBUG enablement */
0263 GLIB_AVAILABLE_IN_2_72
0264 gboolean         g_log_get_debug_enabled       (void);
0265 GLIB_AVAILABLE_IN_2_72
0266 void             g_log_set_debug_enabled       (gboolean         enabled);
0267 
0268 /**
0269  * G_DEBUG_HERE:
0270  *
0271  * A convenience form of g_log_structured(), recommended to be added to
0272  * functions when debugging. It prints the current monotonic time and the code
0273  * location using %G_STRLOC.
0274  *
0275  * Since: 2.50
0276  */
0277 #define G_DEBUG_HERE()                                          \
0278   g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,            \
0279                     "CODE_FILE", __FILE__,                      \
0280                     "CODE_LINE", G_STRINGIFY (__LINE__),        \
0281                     "CODE_FUNC", G_STRFUNC,                      \
0282                     "MESSAGE", "%" G_GINT64_FORMAT ": %s",      \
0283                     g_get_monotonic_time (), G_STRLOC)
0284 
0285 /* internal */
0286 void    _g_log_fallback_handler (const gchar   *log_domain,
0287                          GLogLevelFlags log_level,
0288                          const gchar   *message,
0289                          gpointer       unused_data);
0290 
0291 /* Internal functions, used to implement the following macros */
0292 GLIB_AVAILABLE_IN_ALL
0293 void g_return_if_fail_warning (const char *log_domain,
0294                    const char *pretty_function,
0295                    const char *expression) G_ANALYZER_NORETURN;
0296 GLIB_AVAILABLE_IN_ALL
0297 void g_warn_message           (const char     *domain,
0298                                const char     *file,
0299                                int             line,
0300                                const char     *func,
0301                                const char     *warnexpr) G_ANALYZER_NORETURN;
0302 G_NORETURN
0303 GLIB_DEPRECATED
0304 void g_assert_warning         (const char *log_domain,
0305                    const char *file,
0306                    const int   line,
0307                        const char *pretty_function,
0308                        const char *expression);
0309 
0310 GLIB_AVAILABLE_IN_2_56
0311 void g_log_structured_standard (const gchar    *log_domain,
0312                                 GLogLevelFlags  log_level,
0313                                 const gchar    *file,
0314                                 const gchar    *line,
0315                                 const gchar    *func,
0316                                 const gchar    *message_format,
0317                                 ...) G_GNUC_PRINTF (6, 7);
0318 
0319 #ifndef G_LOG_DOMAIN
0320 #define G_LOG_DOMAIN    ((gchar*) 0)
0321 #endif  /* G_LOG_DOMAIN */
0322 
0323 #if defined(G_HAVE_ISO_VARARGS) && !G_ANALYZER_ANALYZING
0324 #if defined(G_LOG_USE_STRUCTURED) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_56
0325 #define g_error(...)  G_STMT_START {                                            \
0326                         g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, \
0327                                                    __FILE__, G_STRINGIFY (__LINE__), \
0328                                                    G_STRFUNC, __VA_ARGS__); \
0329                         for (;;) ;                                              \
0330                       } G_STMT_END
0331 #define g_message(...)  g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, \
0332                                                    __FILE__, G_STRINGIFY (__LINE__), \
0333                                                    G_STRFUNC, __VA_ARGS__)
0334 #define g_critical(...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \
0335                                                    __FILE__, G_STRINGIFY (__LINE__), \
0336                                                    G_STRFUNC, __VA_ARGS__)
0337 #define g_warning(...)  g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, \
0338                                                    __FILE__, G_STRINGIFY (__LINE__), \
0339                                                    G_STRFUNC, __VA_ARGS__)
0340 #define g_info(...)     g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, \
0341                                                    __FILE__, G_STRINGIFY (__LINE__), \
0342                                                    G_STRFUNC, __VA_ARGS__)
0343 #define g_debug(...)    g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
0344                                                    __FILE__, G_STRINGIFY (__LINE__), \
0345                                                    G_STRFUNC, __VA_ARGS__)
0346 #else
0347 /* for(;;) ; so that GCC knows that control doesn't go past g_error().
0348  * Put space before ending semicolon to avoid C++ build warnings.
0349  */
0350 #define g_error(...)  G_STMT_START {                 \
0351                         g_log (G_LOG_DOMAIN,         \
0352                                G_LOG_LEVEL_ERROR,    \
0353                                __VA_ARGS__);         \
0354                         for (;;) ;                   \
0355                       } G_STMT_END
0356 #define g_message(...)  g_log (G_LOG_DOMAIN,         \
0357                                G_LOG_LEVEL_MESSAGE,  \
0358                                __VA_ARGS__)
0359 #define g_critical(...) g_log (G_LOG_DOMAIN,         \
0360                                G_LOG_LEVEL_CRITICAL, \
0361                                __VA_ARGS__)
0362 #define g_warning(...)  g_log (G_LOG_DOMAIN,         \
0363                                G_LOG_LEVEL_WARNING,  \
0364                                __VA_ARGS__)
0365 #define g_info(...)     g_log (G_LOG_DOMAIN,         \
0366                                G_LOG_LEVEL_INFO,     \
0367                                __VA_ARGS__)
0368 #define g_debug(...)    g_log (G_LOG_DOMAIN,         \
0369                                G_LOG_LEVEL_DEBUG,    \
0370                                __VA_ARGS__)
0371 #endif
0372 #elif defined(G_HAVE_GNUC_VARARGS)  && !G_ANALYZER_ANALYZING
0373 #if defined(G_LOG_USE_STRUCTURED) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_56
0374 #define g_error(format...)   G_STMT_START {                                          \
0375                                g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, \
0376                                                           __FILE__, G_STRINGIFY (__LINE__), \
0377                                                           G_STRFUNC, format); \
0378                                for (;;) ;                                            \
0379                              } G_STMT_END
0380 #define g_message(format...)  g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, \
0381                                                          __FILE__, G_STRINGIFY (__LINE__), \
0382                                                          G_STRFUNC, format)
0383 #define g_critical(format...) g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \
0384                                                          __FILE__, G_STRINGIFY (__LINE__), \
0385                                                          G_STRFUNC, format)
0386 #define g_warning(format...)  g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, \
0387                                                          __FILE__, G_STRINGIFY (__LINE__), \
0388                                                          G_STRFUNC, format)
0389 #define g_info(format...)     g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, \
0390                                                          __FILE__, G_STRINGIFY (__LINE__), \
0391                                                          G_STRFUNC, format)
0392 #define g_debug(format...)    g_log_structured_standard (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
0393                                                          __FILE__, G_STRINGIFY (__LINE__), \
0394                                                          G_STRFUNC, format)
0395 #else
0396 #define g_error(format...)    G_STMT_START {                 \
0397                                 g_log (G_LOG_DOMAIN,         \
0398                                        G_LOG_LEVEL_ERROR,    \
0399                                        format);              \
0400                                 for (;;) ;                   \
0401                               } G_STMT_END
0402 
0403 #define g_message(format...)    g_log (G_LOG_DOMAIN,         \
0404                                        G_LOG_LEVEL_MESSAGE,  \
0405                                        format)
0406 #define g_critical(format...)   g_log (G_LOG_DOMAIN,         \
0407                                        G_LOG_LEVEL_CRITICAL, \
0408                                        format)
0409 #define g_warning(format...)    g_log (G_LOG_DOMAIN,         \
0410                                        G_LOG_LEVEL_WARNING,  \
0411                                        format)
0412 #define g_info(format...)       g_log (G_LOG_DOMAIN,         \
0413                                        G_LOG_LEVEL_INFO,     \
0414                                        format)
0415 #define g_debug(format...)      g_log (G_LOG_DOMAIN,         \
0416                                        G_LOG_LEVEL_DEBUG,    \
0417                                        format)
0418 #endif
0419 #else   /* no varargs macros */
0420 G_NORETURN static void g_error (const gchar *format, ...) G_ANALYZER_NORETURN;
0421 static void g_critical (const gchar *format, ...) G_ANALYZER_NORETURN;
0422 
0423 static inline void
0424 g_error (const gchar *format,
0425          ...)
0426 {
0427   va_list args;
0428   va_start (args, format);
0429   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, format, args);
0430   va_end (args);
0431 
0432   for(;;) ;
0433 }
0434 static inline void
0435 g_message (const gchar *format,
0436            ...)
0437 {
0438   va_list args;
0439   va_start (args, format);
0440   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, format, args);
0441   va_end (args);
0442 }
0443 static inline void
0444 g_critical (const gchar *format,
0445             ...)
0446 {
0447   va_list args;
0448   va_start (args, format);
0449   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, format, args);
0450   va_end (args);
0451 }
0452 static inline void
0453 g_warning (const gchar *format,
0454            ...)
0455 {
0456   va_list args;
0457   va_start (args, format);
0458   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, format, args);
0459   va_end (args);
0460 }
0461 static inline void
0462 g_info (const gchar *format,
0463         ...)
0464 {
0465   va_list args;
0466   va_start (args, format);
0467   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, format, args);
0468   va_end (args);
0469 }
0470 static inline void
0471 g_debug (const gchar *format,
0472          ...)
0473 {
0474   va_list args;
0475   va_start (args, format);
0476   g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, format, args);
0477   va_end (args);
0478 }
0479 #endif  /* !__GNUC__ */
0480 
0481 /**
0482  * g_warning_once:
0483  * @...: format string, followed by parameters to insert
0484  *     into the format string (as with printf())
0485  *
0486  * Logs a warning only once.
0487  *
0488  * g_warning_once() calls g_warning() with the passed message the first time
0489  * the statement is executed; subsequent times it is a no-op.
0490  *
0491  * Note! On platforms where the compiler doesn't support variadic macros, the
0492  * warning is printed each time instead of only once.
0493  *
0494  * Since: 2.64
0495  */
0496 #if defined(G_HAVE_ISO_VARARGS) && !G_ANALYZER_ANALYZING
0497 #define g_warning_once(...) \
0498   G_STMT_START { \
0499     static int G_PASTE (_GWarningOnceBoolean, __LINE__) = 0;  /* (atomic) */ \
0500     if (g_atomic_int_compare_and_exchange (&G_PASTE (_GWarningOnceBoolean, __LINE__), \
0501                                            0, 1)) \
0502       g_warning (__VA_ARGS__); \
0503   } G_STMT_END \
0504   GLIB_AVAILABLE_MACRO_IN_2_64
0505 #elif defined(G_HAVE_GNUC_VARARGS)  && !G_ANALYZER_ANALYZING
0506 #define g_warning_once(format...) \
0507   G_STMT_START { \
0508     static int G_PASTE (_GWarningOnceBoolean, __LINE__) = 0;  /* (atomic) */ \
0509     if (g_atomic_int_compare_and_exchange (&G_PASTE (_GWarningOnceBoolean, __LINE__), \
0510                                            0, 1)) \
0511       g_warning (format); \
0512   } G_STMT_END \
0513   GLIB_AVAILABLE_MACRO_IN_2_64
0514 #else
0515 #define g_warning_once g_warning
0516 #endif
0517 
0518 /**
0519  * GPrintFunc:
0520  * @string: the message to output
0521  *
0522  * Specifies the type of the print handler functions.
0523  * These are called with the complete formatted string to output.
0524  */
0525 typedef void    (*GPrintFunc)           (const gchar    *string);
0526 GLIB_AVAILABLE_IN_ALL
0527 void            g_print                 (const gchar    *format,
0528                                          ...) G_GNUC_PRINTF (1, 2);
0529 GLIB_AVAILABLE_IN_ALL
0530 GPrintFunc      g_set_print_handler     (GPrintFunc      func);
0531 GLIB_AVAILABLE_IN_ALL
0532 void            g_printerr              (const gchar    *format,
0533                                          ...) G_GNUC_PRINTF (1, 2);
0534 GLIB_AVAILABLE_IN_ALL
0535 GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
0536 
0537 /**
0538  * g_warn_if_reached:
0539  *
0540  * Logs a warning.
0541  *
0542  * Since: 2.16
0543  */
0544 #define g_warn_if_reached() \
0545   do { \
0546     g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); \
0547   } while (0)
0548 
0549 /**
0550  * g_warn_if_fail:
0551  * @expr: the expression to check
0552  *
0553  * Logs a warning if the expression is not true.
0554  *
0555  * Unlike g_return_if_fail(), the expression is always evaluated, even if
0556  * checks and assertions are disabled.
0557  *
0558  * Since: 2.16
0559  */
0560 #define g_warn_if_fail(expr) \
0561   do { \
0562     if G_LIKELY (expr) ; \
0563     else g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); \
0564   } while (0)
0565 
0566 #ifdef G_DISABLE_CHECKS
0567 
0568 /**
0569  * g_return_if_fail:
0570  * @expr: the expression to check
0571  *
0572  * Verifies that the expression @expr, usually representing a precondition,
0573  * evaluates to %TRUE. If the function returns a value, use
0574  * g_return_val_if_fail() instead.
0575  *
0576  * If @expr evaluates to %FALSE, the current function should be considered to
0577  * have undefined behaviour (a programmer error). The only correct solution
0578  * to such an error is to change the module that is calling the current
0579  * function, so that it avoids this incorrect call.
0580  *
0581  * To make this undefined behaviour visible, if @expr evaluates to %FALSE,
0582  * the result is usually that a critical message is logged and the current
0583  * function returns.
0584  *
0585  * If `G_DISABLE_CHECKS` is defined then the check is not performed.  You
0586  * should therefore not depend on any side effects of @expr.
0587  *
0588  * To debug failure of a g_return_if_fail() check, run the code under a debugger
0589  * with `G_DEBUG=fatal-criticals` or `G_DEBUG=fatal-warnings` defined in the
0590  * environment (see [Running GLib Applications](glib-running.html)):
0591  *
0592  * |[
0593  *   G_DEBUG=fatal-warnings gdb ./my-program
0594  * ]|
0595  *
0596  * Any unrelated failures can be skipped over in
0597  * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
0598  */
0599 #define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END
0600 
0601 /**
0602  * g_return_val_if_fail:
0603  * @expr: the expression to check
0604  * @val: the value to return from the current function
0605  *       if the expression is not true
0606  *
0607  * Verifies that the expression @expr, usually representing a precondition,
0608  * evaluates to %TRUE. If the function does not return a value, use
0609  * g_return_if_fail() instead.
0610  *
0611  * If @expr evaluates to %FALSE, the current function should be considered to
0612  * have undefined behaviour (a programmer error). The only correct solution
0613  * to such an error is to change the module that is calling the current
0614  * function, so that it avoids this incorrect call.
0615  *
0616  * To make this undefined behaviour visible, if @expr evaluates to %FALSE,
0617  * the result is usually that a critical message is logged and @val is
0618  * returned from the current function.
0619  *
0620  * If `G_DISABLE_CHECKS` is defined then the check is not performed.  You
0621  * should therefore not depend on any side effects of @expr.
0622  *
0623  * See g_return_if_fail() for guidance on how to debug failure of this check.
0624  */
0625 #define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END
0626 
0627 /**
0628  * g_return_if_reached:
0629  *
0630  * Logs a critical message and returns from the current function.
0631  * This can only be used in functions which do not return a value.
0632  *
0633  * See g_return_if_fail() for guidance on how to debug failure of this check.
0634  */
0635 #define g_return_if_reached() G_STMT_START{ return; }G_STMT_END
0636 
0637 /**
0638  * g_return_val_if_reached:
0639  * @val: the value to return from the current function
0640  *
0641  * Logs a critical message and returns @val.
0642  *
0643  * See g_return_if_fail() for guidance on how to debug failure of this check.
0644  */
0645 #define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END
0646 
0647 #else /* !G_DISABLE_CHECKS */
0648 
0649 #define g_return_if_fail(expr) \
0650   G_STMT_START { \
0651     if (G_LIKELY (expr)) \
0652       { } \
0653     else \
0654       { \
0655         g_return_if_fail_warning (G_LOG_DOMAIN, \
0656                                   G_STRFUNC, \
0657                                   #expr); \
0658         return; \
0659       } \
0660   } G_STMT_END
0661 
0662 #define g_return_val_if_fail(expr, val) \
0663   G_STMT_START { \
0664     if (G_LIKELY (expr)) \
0665       { } \
0666     else \
0667       { \
0668         g_return_if_fail_warning (G_LOG_DOMAIN, \
0669                                   G_STRFUNC, \
0670                                   #expr); \
0671         return (val); \
0672       } \
0673   } G_STMT_END
0674 
0675 #define g_return_if_reached() \
0676   G_STMT_START { \
0677     g_log (G_LOG_DOMAIN, \
0678            G_LOG_LEVEL_CRITICAL, \
0679            "file %s: line %d (%s): should not be reached", \
0680            __FILE__, \
0681            __LINE__, \
0682            G_STRFUNC); \
0683     return; \
0684   } G_STMT_END
0685 
0686 #define g_return_val_if_reached(val) \
0687   G_STMT_START { \
0688     g_log (G_LOG_DOMAIN, \
0689            G_LOG_LEVEL_CRITICAL, \
0690            "file %s: line %d (%s): should not be reached", \
0691            __FILE__, \
0692            __LINE__, \
0693            G_STRFUNC); \
0694     return (val); \
0695   } G_STMT_END
0696 
0697 #endif /* !G_DISABLE_CHECKS */
0698 
0699 G_END_DECLS
0700 
0701 #endif /* __G_MESSAGES_H__ */
[ Source navigation ] [ Diff markup ] [ Identifier search ] [ general search ]

This page was automatically generated by the 2.3.7 LXR engine.

The LXR team
Valid CSS 2.1! Valid HTML 4.01!