This repository has been archived by the owner on Nov 17, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
messages.sgml
275 lines (203 loc) · 7.29 KB
/
messages.sgml
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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
<!-- ##### SECTION Title ##### -->
Message Logging
<!-- ##### SECTION Short_Description ##### -->
versatile support for logging messages with different levels of importance.
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide support for logging error messages or messages
used for debugging.
</para>
<para>
There are several built-in levels of messages, defined in #GLogLevelFlags.
These can be extended with user-defined levels.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO G_LOG_DOMAIN ##### -->
<para>
Defines the log domain.
For applications, this is typically left as the default NULL (or "") domain.
Libraries should define this so that any messages which they log can
be differentiated from messages from other libraries and application code.
But be careful not to define it in any public header files.
</para>
<para>
For example, GTK uses this in its Makefile.am:
<informalexample><programlisting>
INCLUDES = \
-DG_LOG_DOMAIN=\"Gtk\"
</programlisting></informalexample>
</para>
<!-- ##### VARIABLE g_log_domain_glib ##### -->
<para>
</para>
<!-- ##### VARIABLE g_log_domain_gmodule ##### -->
<para>
</para>
<!-- ##### MACRO G_LOG_FATAL_MASK ##### -->
<para>
GLib log levels that are considered fatal by default.
</para>
<!-- ##### MACRO G_LOG_LEVEL_USER_SHIFT ##### -->
<para>
Log level shift offset for user defined log levels (0-7 are used by GLib).
</para>
<!-- ##### USER_FUNCTION GLogFunc ##### -->
<para>
Specifies the prototype of log handler functions.
</para>
@log_domain: the log domain of the message.
@log_level: the log level of the message (including the fatal and recursion
flags).
@message: the message to process.
@user_data: user data, set in g_log_set_handler().
<!-- ##### ENUM GLogLevelFlags ##### -->
<para>
Flags specifying the level of log messages.
</para>
@G_LOG_FLAG_RECURSION:
@G_LOG_FLAG_FATAL:
@G_LOG_LEVEL_ERROR:
@G_LOG_LEVEL_CRITICAL:
@G_LOG_LEVEL_WARNING:
@G_LOG_LEVEL_MESSAGE:
@G_LOG_LEVEL_INFO:
@G_LOG_LEVEL_DEBUG:
@G_LOG_LEVEL_MASK:
<!-- ##### FUNCTION g_log ##### -->
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function>abort()</function>
function is called to terminate the program.
</para>
@log_domain: the log domain, usually #G_LOG_DOMAIN.
@log_level: the log level, either from #GLogLevelFlags or a user-defined level.
@format: the message format. See the <function>printf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_logv ##### -->
<para>
Logs an error or debugging message.
If the log level has been set as fatal, the <function>abort()</function>
function is called to terminate the program.
</para>
@log_domain: the log domain.
@log_level: the log level.
@format: the message format. See the <function>printf()</function>
documentation.
@args: the parameters to insert into the format string.
<!-- ##### MACRO g_message ##### -->
<para>
A convenience function/macro to log a normal message.
</para>
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_warning ##### -->
<para>
A convenience function/macro to log a warning message.
</para>
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_error ##### -->
<para>
A convenience function/macro to log an error message.
Error messages are always fatal, resulting in a call to
<function>abort()</function> to terminate the application.
</para>
@format: the message format. See the <function>printf()</function>
documentation.
@args...: the parameters to insert into the format string.
<!-- ##### FUNCTION g_log_set_handler ##### -->
<para>
Sets the log handler for a domain and a set of log levels.
Note that to handle fatal and recursive messages the @log_levels parameter
must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
<example>
<title>Adding a log handler for all warning messages</title>
<programlisting>
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
| G_LOG_FLAG_RECURSIVE, my_log_handler, NULL);
</programlisting>
</example>
</para>
@log_domain: the log domain, or NULL for the default "" application domain.
@log_levels: the log levels to apply the log handler for. To handle fatal
and recursive messages as well, comine the log levels with the G_LOG_FLAG_FATAL
and G_LOG_FLAG_RECURSIVE bit flags.
@log_func: the log handler function.
@user_data: data passed to the log handler.
@Returns: the id of the new handler.
<!-- ##### FUNCTION g_log_remove_handler ##### -->
<para>
Removes the log handler.
</para>
@log_domain: the log domain.
@handler_id: the id of the handler, which was returned in g_log_set_handler().
<!-- ##### FUNCTION g_log_set_always_fatal ##### -->
<para>
Sets the message levels which are always fatal, in any log domain.
When a message with any of these levels is logged the program terminates.
You can only set the levels defined by GLib to be fatal.
%G_LOG_LEVEL_ERROR is always fatal.
</para>
@fatal_mask: the mask containing bits set for each level of error which is
to be fatal.
@Returns: the old fatal mask.
<!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
<para>
Sets the log levels which are fatal in the given domain.
%G_LOG_LEVEL_ERROR is always fatal.
</para>
@log_domain: the log domain.
@fatal_mask: the new fatal mask.
@Returns: the old fatal mask for the log domain.
<!-- ##### FUNCTION g_log_default_handler ##### -->
<para>
The default log handler.
This is used if no log handler has been set for the particular log domain
and log level combination. It outputs the message to stderr or stdout
and if the log level is fatal it calls <function>abort()</function>.
</para>
<para>
stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and
%G_LOG_LEVEL_WARNING. stdout is used for the rest.
(On the Windows platform, stdout is always used.)
</para>
@log_domain: the log domain of the message.
@log_level: the level of the message.
@message: the message.
@unused_data: data passed from g_log which is unused.
<!-- ##### FUNCTION g_set_error_handler ##### -->
<para>
Sets the function to be called to handle error messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func: the function to be called to handle error messages.
@Returns: the old error handler.
<!-- ##### USER_FUNCTION GErrorFunc ##### -->
<para>
Specifies the type of function passed to g_set_error_handler().
</para>
@str: the error message.
<!-- ##### FUNCTION g_set_warning_handler ##### -->
<para>
Sets the function to be called to handle warning messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func: the function to be called to handle warning messages.
@Returns: the old warning handler.
<!-- ##### USER_FUNCTION GWarningFunc ##### -->
<para>
Specifies the type of function passed to g_set_warning_handler().
</para>
@str: the warning message.
<!-- ##### FUNCTION g_set_message_handler ##### -->
<para>
Sets the function to be called to handle messages.
This function is deprecated in favour of the new logging facilities.
</para>
@func: the function to be called to handle normal messages.
@Returns: the old message handler.