1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
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]
|
