mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-28 02:20:04 +01:00
3532e3ca1c
Move it to a separate file. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3037
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
Title: Warnings and Assertions
|
||
SPDX-License-Identifier: LGPL-2.1-or-later
|
||
SPDX-FileCopyrightText: 2018 Endless Mobile, Inc.
|
||
SPDX-FileCopyrightText: 2023 Daniel Carpenter
|
||
|
||
# Warnings and Assertions
|
||
|
||
GLib defines several warning functions and assertions which can be used to
|
||
warn of programmer errors when calling functions, and print error messages
|
||
from command line programs.
|
||
|
||
## Pre-condition Assertions
|
||
|
||
The [func@GLib.return_if_fail], [func@GLib.return_val_if_fail],
|
||
[func@GLib.return_if_reached] and [func@GLib.return_val_if_reached] macros are
|
||
intended as pre-condition assertions, to be used at the top of a public function
|
||
to check that the function’s arguments are acceptable. Any failure of such a
|
||
pre-condition assertion is considered a programming error on the part of the
|
||
caller of the public API, and the program is considered to be in an undefined
|
||
state afterwards. They are similar to the libc [`assert()`](man:assert(3))
|
||
function, but provide more context on failures.
|
||
|
||
For example:
|
||
```c
|
||
gboolean
|
||
g_dtls_connection_shutdown (GDtlsConnection *conn,
|
||
gboolean shutdown_read,
|
||
gboolean shutdown_write,
|
||
GCancellable *cancellable,
|
||
GError **error)
|
||
{
|
||
// local variable declarations
|
||
|
||
g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
|
||
g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
|
||
g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
|
||
|
||
// function body
|
||
|
||
return return_val;
|
||
}
|
||
```
|
||
|
||
[func@GLib.warn_if_fail] and [func@GLib.warn_if_reached] behave similarly, but
|
||
they will not abort the program on failure. The program should be considered to
|
||
be in an undefined state if they fail, however.
|
||
|
||
## Messages
|
||
|
||
[func@GLib.print] and [func@GLib.printerr] are intended to be used for
|
||
output from command line applications, since they output to standard output
|
||
and standard error by default — whereas functions like [func@GLib.message] and
|
||
[func@GLib.log] may be redirected to special purpose message windows, files, or
|
||
the system journal.
|
||
|
||
The default print handlers may be overridden with [func@GLib.set_print_handler]
|
||
and [func@GLib.set_printerr_handler].
|
||
|
||
### Encoding
|
||
|
||
If the console encoding is not UTF-8 (as specified by
|
||
[func@GLib.get_console_charset]) then these functions convert the message first.
|
||
Any Unicode characters not defined by that charset are replaced by `'?'`. On
|
||
Linux, [`setlocale()`](man:setlocale(3)) must be called early in `main()` to
|
||
load the encoding. This behaviour can be changed by providing custom handlers to
|
||
[func@GLib.set_print_handler], [func@GLib.set_printerr_handler] and
|
||
[func@GLib.log_set_handler].
|
||
|
||
## Debugging Utilities
|
||
|
||
* [func@GLib.on_error_query]
|
||
* [func@GLib.on_error_stack_trace]
|
||
* [func@GLib.BREAKPOINT]
|