Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 *
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 *
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
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 *
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 *
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
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
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  */
229 void
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  */
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 *
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  */
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 *
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 *
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 */