1 /* gerror.h - Error reporting system
2 *
3 * Copyright 2000 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20
21 #ifndef __G_ERROR_H__
22 #define __G_ERROR_H__
23
24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25 #error "Only <glib.h> can be included directly."
26 #endif
27
28 #include <stdarg.h>
29
30 #include <glib/gquark.h>
31
32 G_BEGIN_DECLS
33
34 /**
35 * GError:
36 * @domain: error domain, e.g. %G_FILE_ERROR
37 * @code: error code, e.g. %G_FILE_ERROR_NOENT
38 * @message: human-readable informative error message
39 *
40 * The `GError` structure contains information about
41 * an error that has occurred.
42 */
43 typedef struct _GError GError;
44
45 struct _GError
46 {
47 GQuark domain;
48 gint code;
49 gchar *message;
50 };
51
52 /**
53 * G_DEFINE_EXTENDED_ERROR:
54 * @ErrorType: name to return a #GQuark for
55 * @error_type: prefix for the function name
56 *
57 * A convenience macro which defines two functions. First, returning
58 * the #GQuark for the extended error type @ErrorType; it is called
59 * `error_type_quark()`. Second, returning the private data from a
60 * passed #GError; it is called `error_type_get_private()`.
61 *
62 * For this macro to work, a type named `ErrorTypePrivate` should be
63 * defined, `error_type_private_init()`, `error_type_private_copy()`
64 * and `error_type_private_clear()` functions need to be either
65 * declared or defined. The functions should be similar to
66 * #GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc,
67 * respectively, but they should receive the private data type instead
68 * of #GError.
69 *
70 * See [Extended #GError Domains][gerror-extended-domains] for an example.
71 *
72 * Since: 2.68
73 */
74 #define G_DEFINE_EXTENDED_ERROR(ErrorType, error_type) \
75 static inline ErrorType ## Private * \
76 error_type ## _get_private (const GError *error) \
77 { \
78 /* Copied from gtype.c (STRUCT_ALIGNMENT and ALIGN_STRUCT macros). */ \
79 const gsize sa = 2 * sizeof (gsize); \
80 const gsize as = (sizeof (ErrorType ## Private) + (sa - 1)) & -sa; \
81 g_return_val_if_fail (error != NULL, NULL); \
82 g_return_val_if_fail (error->domain == error_type ## _quark (), NULL); \
83 return (ErrorType ## Private *) (((guint8 *)error) - as); \
84 } \
85 \
86 static void \
87 g_error_with_ ## error_type ## _private_init (GError *error) \
88 { \
89 ErrorType ## Private *priv = error_type ## _get_private (error); \
90 error_type ## _private_init (priv); \
91 } \
92 \
93 static void \
94 g_error_with_ ## error_type ## _private_copy (const GError *src_error, \
95 GError *dest_error) \
96 { \
97 const ErrorType ## Private *src_priv = error_type ## _get_private (src_error); \
98 ErrorType ## Private *dest_priv = error_type ## _get_private (dest_error); \
99 error_type ## _private_copy (src_priv, dest_priv); \
100 } \
101 \
102 static void \
103 g_error_with_ ## error_type ## _private_clear (GError *error) \
104 { \
105 ErrorType ## Private *priv = error_type ## _get_private (error); \
106 error_type ## _private_clear (priv); \
107 } \
108 \
109 GQuark \
110 error_type ## _quark (void) \
111 { \
112 static GQuark q; \
113 static gsize initialized = 0; \
114 \
115 if (g_once_init_enter (&initialized)) \
116 { \
117 q = g_error_domain_register_static (#ErrorType, \
118 sizeof (ErrorType ## Private), \
119 g_error_with_ ## error_type ## _private_init, \
120 g_error_with_ ## error_type ## _private_copy, \
121 g_error_with_ ## error_type ## _private_clear); \
122 g_once_init_leave (&initialized, 1); \
123 } \
124 \
125 return q; \
126 }
127
128 /**
129 * GErrorInitFunc:
130 * @error: extended error
131 *
132 * Specifies the type of function which is called just after an
133 * extended error instance is created and its fields filled. It should
134 * only initialize the fields in the private data, which can be
135 * received with the generated `*_get_private()` function.
136 *
137 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
138 * already takes care of getting the private data from @error.
139 *
140 * Since: 2.68
141 */
142 typedef void (*GErrorInitFunc) (GError *error);
143
144 /**
145 * GErrorCopyFunc:
146 * @src_error: source extended error
147 * @dest_error: destination extended error
148 *
149 * Specifies the type of function which is called when an extended
150 * error instance is copied. It is passed the pointer to the
151 * destination error and source error, and should copy only the fields
152 * of the private data from @src_error to @dest_error.
153 *
154 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
155 * already takes care of getting the private data from @src_error and
156 * @dest_error.
157 *
158 * Since: 2.68
159 */
160 typedef void (*GErrorCopyFunc) (const GError *src_error, GError *dest_error);
161
162 /**
163 * GErrorClearFunc:
164 * @error: extended error to clear
165 *
166 * Specifies the type of function which is called when an extended
167 * error instance is freed. It is passed the error pointer about to be
168 * freed, and should free the error's private data fields.
169 *
170 * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
171 * already takes care of getting the private data from @error.
172 *
173 * Since: 2.68
174 */
175 typedef void (*GErrorClearFunc) (GError *error);
176
177 GLIB_AVAILABLE_IN_2_68
178 GQuark g_error_domain_register_static (const char *error_type_name,
179 gsize error_type_private_size,
180 GErrorInitFunc error_type_init,
181 GErrorCopyFunc error_type_copy,
182 GErrorClearFunc error_type_clear);
183
184 GLIB_AVAILABLE_IN_2_68
185 GQuark g_error_domain_register (const char *error_type_name,
186 gsize error_type_private_size,
187 GErrorInitFunc error_type_init,
188 GErrorCopyFunc error_type_copy,
189 GErrorClearFunc error_type_clear);
190
191 GLIB_AVAILABLE_IN_ALL
192 GError* g_error_new (GQuark domain,
193 gint code,
194 const gchar *format,
195 ...) G_GNUC_PRINTF (3, 4);
196
197 GLIB_AVAILABLE_IN_ALL
198 GError* g_error_new_literal (GQuark domain,
199 gint code,
200 const gchar *message);
201 GLIB_AVAILABLE_IN_ALL
202 GError* g_error_new_valist (GQuark domain,
203 gint code,
204 const gchar *format,
205 va_list args) G_GNUC_PRINTF(3, 0);
206
207 GLIB_AVAILABLE_IN_ALL
208 void g_error_free (GError *error);
209 GLIB_AVAILABLE_IN_ALL
210 GError* g_error_copy (const GError *error);
211
212 GLIB_AVAILABLE_IN_ALL
213 gboolean g_error_matches (const GError *error,
214 GQuark domain,
215 gint code);
216
217 /* if (err) *err = g_error_new(domain, code, format, ...), also has
218 * some sanity checks.
219 */
220 GLIB_AVAILABLE_IN_ALL
221 void g_set_error (GError **err,
222 GQuark domain,
223 gint code,
224 const gchar *format,
225 ...) G_GNUC_PRINTF (4, 5);
226
227 GLIB_AVAILABLE_IN_ALL
228 void g_set_error_literal (GError **err,
229 GQuark domain,
230 gint code,
231 const gchar *message);
232
233 /* if (dest) *dest = src; also has some sanity checks.
234 */
235 GLIB_AVAILABLE_IN_ALL
236 void g_propagate_error (GError **dest,
237 GError *src);
238
239 /* if (err && *err) { g_error_free(*err); *err = NULL; } */
240 GLIB_AVAILABLE_IN_ALL
241 void g_clear_error (GError **err);
242
243 /* if (err) prefix the formatted string to the ->message */
244 GLIB_AVAILABLE_IN_ALL
245 void g_prefix_error (GError **err,
246 const gchar *format,
247 ...) G_GNUC_PRINTF (2, 3);
248
249 /* if (err) prefix the string to the ->message */
250 GLIB_AVAILABLE_IN_2_70
251 void g_prefix_error_literal (GError **err,
252 const gchar *prefix);
253
254 /* g_propagate_error then g_error_prefix on dest */
255 GLIB_AVAILABLE_IN_ALL
256 void g_propagate_prefixed_error (GError **dest,
257 GError *src,
258 const gchar *format,
259 ...) G_GNUC_PRINTF (3, 4);
260
261 G_END_DECLS
262
263 #endif /* __G_ERROR_H__ */