gmessages.h 25 KB

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