Subversion
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
subversion
include
svn_error.h
Go to the documentation of this file.
1
/**
2
* @copyright
3
* ====================================================================
4
* Copyright (c) 2000-2004, 2008 CollabNet. All rights reserved.
5
*
6
* This software is licensed as described in the file COPYING, which
7
* you should have received as part of this distribution. The terms
8
* are also available at http://subversion.tigris.org/license-1.html.
9
* If newer versions of this license are posted there, you may use a
10
* newer version instead, at your option.
11
*
12
* This software consists of voluntary contributions made by many
13
* individuals. For exact contribution history, see the revision
14
* history and logs, available at http://subversion.tigris.org/.
15
* ====================================================================
16
* @endcopyright
17
*
18
* @file svn_error.h
19
* @brief Common exception handling for Subversion.
20
*/
21
22
23
24
25
#ifndef SVN_ERROR_H
26
#define SVN_ERROR_H
27
28
#include <apr.h>
/* for apr_size_t */
29
#include <apr_errno.h>
/* APR's error system */
30
#include <apr_pools.h>
/* for apr_pool_t */
31
32
#ifndef DOXYGEN_SHOULD_SKIP_THIS
33
#define APR_WANT_STDIO
34
#endif
35
#include <apr_want.h>
/* for FILE* */
36
37
#include "
svn_types.h
"
38
39
#ifdef __cplusplus
40
extern
"C"
{
41
#endif
/* __cplusplus */
42
43
/** the best kind of (@c svn_error_t *) ! */
44
#define SVN_NO_ERROR 0
45
46
/* The actual error codes are kept in a separate file; see comments
47
there for the reasons why. */
48
#include "
svn_error_codes.h
"
49
50
/** Set the error location for debug mode. */
51
void
52
svn_error__locate
(
const
char
*file,
53
long
line);
54
55
56
/** Put an English description of @a statcode into @a buf and return @a buf,
57
* NULL-terminated. @a statcode is either an svn error or apr error.
58
*/
59
char
*
60
svn_strerror
(apr_status_t statcode,
61
char
*buf,
62
apr_size_t bufsize);
63
64
65
/** If @a err has a custom error message, return that, otherwise
66
* store the generic error string associated with @a err->apr_err into
67
* @a buf (terminating with NULL) and return @a buf.
68
*
69
* @since New in 1.4.
70
*
71
* @note @a buf and @a bufsize are provided in the interface so that
72
* this function is thread-safe and yet does no allocation.
73
*/
74
const
char
*
svn_err_best_message
(
svn_error_t
*err,
75
char
*buf,
76
apr_size_t bufsize);
77
78
79
80
/** SVN error creation and destruction.
81
*
82
* @defgroup svn_error_error_creation_destroy Error creation and destruction
83
* @{
84
*/
85
86
/** Create a nested exception structure.
87
*
88
* Input: an APR or SVN custom error code,
89
* a "child" error to wrap,
90
* a specific message
91
*
92
* Returns: a new error structure (containing the old one).
93
*
94
* @note Errors are always allocated in a subpool of the global pool,
95
* since an error's lifetime is generally not related to the
96
* lifetime of any convenient pool. Errors must be freed
97
* with svn_error_clear(). The specific message should be @c NULL
98
* if there is nothing to add to the general message associated
99
* with the error code.
100
*
101
* If creating the "bottommost" error in a chain, pass @c NULL for
102
* the child argument.
103
*/
104
svn_error_t
*
105
svn_error_create
(apr_status_t apr_err,
106
svn_error_t
*child,
107
const
char
*message);
108
109
/** Wrapper macro to collect file and line information */
110
#define svn_error_create \
111
(svn_error__locate(__FILE__,__LINE__), (svn_error_create))
112
113
/** Create an error structure with the given @a apr_err and @a child,
114
* with a printf-style error message produced by passing @a fmt, using
115
* apr_psprintf().
116
*/
117
svn_error_t
*
118
svn_error_createf
(apr_status_t apr_err,
119
svn_error_t
*child,
120
const
char
*fmt,
121
...)
122
__attribute__ ((format(printf, 3, 4)));
123
124
/** Wrapper macro to collect file and line information */
125
#define svn_error_createf \
126
(svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
127
128
/** Wrap a @a status from an APR function. If @a fmt is NULL, this is
129
* equivalent to svn_error_create(status,NULL,NULL). Otherwise,
130
* the error message is constructed by formatting @a fmt and the
131
* following arguments according to apr_psprintf(), and then
132
* appending ": " and the error message corresponding to @a status.
133
* (If UTF-8 translation of the APR error message fails, the ": " and
134
* APR error are not appended to the error message.)
135
*/
136
svn_error_t
*
137
svn_error_wrap_apr
(apr_status_t status,
138
const
char
*fmt,
139
...)
140
__attribute__((format(printf, 2, 3)));
141
142
/** Wrapper macro to collect file and line information */
143
#define svn_error_wrap_apr \
144
(svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
145
146
/** A quick n' easy way to create a wrapped exception with your own
147
* message, before throwing it up the stack. (It uses all of the
148
* @a child's fields.)
149
*/
150
svn_error_t
*
151
svn_error_quick_wrap
(
svn_error_t
*child,
152
const
char
*new_msg);
153
154
/** Wrapper macro to collect file and line information */
155
#define svn_error_quick_wrap \
156
(svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
157
158
/** Compose two errors, returning the composition as a brand new error
159
* and consuming the original errors. Either or both of @a err1 and
160
* @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR,
161
* @a err2 will follow @a err1 in the chain of the returned error.
162
*
163
* @since New in 1.6.
164
*/
165
svn_error_t
*
166
svn_error_compose_create
(
svn_error_t
*err1,
167
svn_error_t
*err2);
168
169
/** Add @a new_err to the end of @a chain's chain of errors. The @a new_err
170
* chain will be copied into @a chain's pool and destroyed, so @a new_err
171
* itself becomes invalid after this function.
172
*/
173
void
174
svn_error_compose
(
svn_error_t
*chain,
175
svn_error_t
*new_err);
176
177
/** Return the root cause of @a err by finding the last error in its
178
* chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in
179
* which case @c SVN_NO_ERROR is returned.
180
*
181
* @since New in 1.5.
182
*/
183
svn_error_t
*
184
svn_error_root_cause
(
svn_error_t
*err);
185
186
/** Create a new error that is a deep copy of @a err and return it.
187
*
188
* @since New in 1.2.
189
*/
190
svn_error_t
*
191
svn_error_dup
(
svn_error_t
*err);
192
193
/** Free the memory used by @a error, as well as all ancestors and
194
* descendants of @a error.
195
*
196
* Unlike other Subversion objects, errors are managed explicitly; you
197
* MUST clear an error if you are ignoring it, or you are leaking memory.
198
* For convenience, @a error may be @c NULL, in which case this function does
199
* nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
200
* ignore errors.
201
*/
202
void
203
svn_error_clear
(
svn_error_t
*error);
204
205
206
/**
207
* Very basic default error handler: print out error stack @a error to the
208
* stdio stream @a stream, with each error prefixed by @a prefix; quit and
209
* clear @a error iff the @a fatal flag is set. Allocations are performed
210
* in the @a error's pool.
211
*
212
* If you're not sure what prefix to pass, just pass "svn: ". That's
213
* what code that used to call svn_handle_error() and now calls
214
* svn_handle_error2() does.
215
*
216
* @since New in 1.2.
217
*/
218
void
219
svn_handle_error2
(
svn_error_t
*error,
220
FILE *stream,
221
svn_boolean_t
fatal,
222
const
char
*prefix);
223
224
/** Like svn_handle_error2() but with @c prefix set to "svn: "
225
*
226
* @deprecated Provided for backward compatibility with the 1.1 API.
227
*/
228
SVN_DEPRECATED
229
void
230
svn_handle_error
(
svn_error_t
*error,
231
FILE *stream,
232
svn_boolean_t
fatal);
233
234
/**
235
* Very basic default warning handler: print out the error @a error to the
236
* stdio stream @a stream, prefixed by @a prefix. Allocations are
237
* performed in the error's pool.
238
*
239
* @since New in 1.2.
240
*/
241
void
242
svn_handle_warning2
(FILE *stream,
243
svn_error_t
*error,
244
const
char
*prefix);
245
246
/** Like svn_handle_warning2() but with @c prefix set to "svn: "
247
*
248
* @deprecated Provided for backward compatibility with the 1.1 API.
249
*/
250
SVN_DEPRECATED
251
void
252
svn_handle_warning
(FILE *stream,
253
svn_error_t
*error);
254
255
256
/** A statement macro for checking error values.
257
*
258
* Evaluate @a expr. If it yields an error, return that error from the
259
* current function. Otherwise, continue.
260
*
261
* The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
262
* but it makes this macro syntactically equivalent to the expression
263
* statement it resembles. Without it, statements like
264
*
265
* @code
266
* if (a)
267
* SVN_ERR (some operation);
268
* else
269
* foo;
270
* @endcode
271
*
272
* would not mean what they appear to.
273
*/
274
#define SVN_ERR(expr) \
275
do { \
276
svn_error_t *svn_err__temp = (expr); \
277
if (svn_err__temp) \
278
return svn_err__temp; \
279
} while (0)
280
281
282
/** A statement macro, very similar to @c SVN_ERR.
283
*
284
* This macro will wrap the error with the specified text before
285
* returning the error.
286
*/
287
#define SVN_ERR_W(expr, wrap_msg) \
288
do { \
289
svn_error_t *svn_err__temp = (expr); \
290
if (svn_err__temp) \
291
return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
292
} while (0)
293
294
295
/** A statement macro, similar to @c SVN_ERR, but returns an integer.
296
*
297
* Evaluate @a expr. If it yields an error, handle that error and
298
* return @c EXIT_FAILURE.
299
*/
300
#define SVN_INT_ERR(expr) \
301
do { \
302
svn_error_t *svn_err__temp = (expr); \
303
if (svn_err__temp) { \
304
svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \
305
svn_error_clear(svn_err__temp); \
306
return EXIT_FAILURE; } \
307
} while (0)
308
309
/** @} */
310
311
/**
312
* Return TRUE if @a err is an error specifically related to locking a
313
* path in the repository, FALSE otherwise.
314
*
315
* SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
316
* that can be thrown when attempting to lock an item.
317
*
318
* @since New in 1.2.
319
*/
320
#define SVN_ERR_IS_LOCK_ERROR(err) \
321
(err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \
322
err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \
323
324
/**
325
* Return TRUE if @a err is an error specifically related to unlocking
326
* a path in the repository, FALSE otherwise.
327
*
328
* @since New in 1.2.
329
*/
330
#define SVN_ERR_IS_UNLOCK_ERROR(err) \
331
(err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \
332
err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \
333
err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \
334
err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \
335
err->apr_err == SVN_ERR_RA_NOT_LOCKED || \
336
err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
337
338
/** Report that an internal malfunction has occurred, and possibly terminate
339
* the program.
340
*
341
* Act as determined by the current "malfunction handler" which may have
342
* been specified by a call to svn_error_set_malfunction_handler() or else
343
* is the default handler as specified in that function's documentation. If
344
* the malfunction handler returns, then cause the function using this macro
345
* to return the error object that it generated.
346
*
347
* @note The intended use of this macro is where execution reaches a point
348
* that cannot possibly be reached unless there is a bug in the program.
349
*
350
* @since New in 1.6.
351
*/
352
#define SVN_ERR_MALFUNCTION() \
353
do { \
354
return svn_error__malfunction(TRUE, __FILE__, __LINE__, NULL); \
355
} while (0)
356
357
/** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning
358
* an error to the calling function.
359
*
360
* If possible you should use SVN_ERR_MALFUNCTION() instead.
361
*
362
* @since New in 1.6.
363
*/
364
#define SVN_ERR_MALFUNCTION_NO_RETURN() \
365
do { \
366
svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \
367
abort(); \
368
} while (1)
369
370
/** Check that a condition is true: if not, report an error and possibly
371
* terminate the program.
372
*
373
* If the Boolean expression @a expr is true, do nothing. Otherwise,
374
* act as determined by the current "malfunction handler" which may have
375
* been specified by a call to svn_error_set_malfunction_handler() or else
376
* is the default handler as specified in that function's documentation. If
377
* the malfunction handler returns, then cause the function using this macro
378
* to return the error object that it generated.
379
*
380
* @note The intended use of this macro is to check a condition that cannot
381
* possibly be false unless there is a bug in the program.
382
*
383
* @note The condition to be checked should not be computationally expensive
384
* if it is reached often, as, unlike traditional "assert" statements, the
385
* evaluation of this expression is not compiled out in release-mode builds.
386
*
387
* @since New in 1.6.
388
*/
389
#define SVN_ERR_ASSERT(expr) \
390
do { \
391
if (!(expr)) \
392
SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \
393
} while (0)
394
395
/** Similar to SVN_ERR_ASSERT(), but without the option of returning
396
* an error to the calling function.
397
*
398
* If possible you should use SVN_ERR_ASSERT() instead.
399
*
400
* @since New in 1.6.
401
*/
402
#define SVN_ERR_ASSERT_NO_RETURN(expr) \
403
do { \
404
if (!(expr)) { \
405
svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \
406
abort(); \
407
} \
408
} while (0)
409
410
411
/** A helper function for the macros that report malfunctions. Handle a
412
* malfunction by calling the current "malfunction handler" which may have
413
* been specified by a call to svn_error_set_malfunction_handler() or else
414
* is the default handler as specified in that function's documentation.
415
*
416
* Pass all of the parameters to the handler. The error occurred in the
417
* source file @a file at line @a line, and was an assertion failure of the
418
* expression @a expr, or, if @a expr is null, an unconditional error.
419
*
420
* If @a can_return is true, the handler can return an error object
421
* that is returned by the caller. If @a can_return is false the
422
* method should never return. (The caller will call abort())
423
*
424
* @since New in 1.6.
425
*/
426
svn_error_t
*
427
svn_error__malfunction
(
svn_boolean_t
can_return,
428
const
char
*file,
429
int
line,
430
const
char
*expr);
431
432
/** A type of function that handles an assertion failure or other internal
433
* malfunction detected within the Subversion libraries.
434
*
435
* The error occurred in the source file @a file at line @a line, and was an
436
* assertion failure of the expression @a expr, or, if @a expr is null, an
437
* unconditional error.
438
*
439
* If @a can_return is false a function of this type must never return.
440
*
441
* If @a can_return is true a function of this type must do one of:
442
* - Return an error object describing the error, using an error code in
443
* the category SVN_ERR_MALFUNC_CATEGORY_START.
444
* - Never return.
445
*
446
* The function may alter its behaviour according to compile-time
447
* and run-time and even interactive conditions.
448
*
449
* @since New in 1.6.
450
*/
451
typedef
svn_error_t
*(*svn_error_malfunction_handler_t)
452
(
svn_boolean_t
can_return,
const
char
*file,
int
line,
const
char
*expr);
453
454
/** Cause subsequent malfunctions to be handled by @a func.
455
* Return the handler that was previously in effect.
456
*
457
* @a func may not be null.
458
*
459
* @note The default handler is svn_error_abort_on_malfunction().
460
*
461
* @note This function must be called in a single-threaded context.
462
*
463
* @since New in 1.6.
464
*/
465
svn_error_malfunction_handler_t
466
svn_error_set_malfunction_handler
(
svn_error_malfunction_handler_t
func);
467
468
/** Handle a malfunction by returning an error object that describes it.
469
*
470
* When @a can_return is false, abort()
471
*
472
* This function implements @c svn_error_malfunction_handler_t.
473
*
474
* @since New in 1.6.
475
*/
476
svn_error_t
*
477
svn_error_raise_on_malfunction
(
svn_boolean_t
can_return,
478
const
char
*file,
479
int
line,
480
const
char
*expr);
481
482
/** Handle a malfunction by printing a message to stderr and aborting.
483
*
484
* This function implements @c svn_error_malfunction_handler_t.
485
*
486
* @since New in 1.6.
487
*/
488
svn_error_t
*
489
svn_error_abort_on_malfunction
(
svn_boolean_t
can_return,
490
const
char
*file,
491
int
line,
492
const
char
*expr);
493
494
495
#ifdef __cplusplus
496
}
497
#endif
/* __cplusplus */
498
499
#endif
/* SVN_ERROR_H */
Generated on Mon Aug 10 2015 05:02:26 for Subversion by
1.8.1.2