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  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_error.h
24  * @brief Common exception handling for Subversion.
25  */
26 
27 #ifndef SVN_ERROR_H
28 #define SVN_ERROR_H
29 
30 #include <apr.h> /* for apr_size_t */
31 #include <apr_errno.h> /* APR's error system */
32 #include <apr_pools.h> /* for apr_pool_t */
33 
34 #ifndef DOXYGEN_SHOULD_SKIP_THIS
35 #define APR_WANT_STDIO
36 #endif
37 #include <apr_want.h> /* for FILE* */
38 
39 #include "svn_types.h"
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif /* __cplusplus */
44 
45 
46 /* For the Subversion developers, this #define turns on extended "stack
47  traces" of any errors that get thrown. See the SVN_ERR() macro. */
48 #ifdef SVN_DEBUG
49 #define SVN_ERR__TRACING
50 #endif
51 
52 
53 /** the best kind of (@c svn_error_t *) ! */
54 #define SVN_NO_ERROR 0
55 
56 /* The actual error codes are kept in a separate file; see comments
57  there for the reasons why. */
58 #include "svn_error_codes.h"
59 
60 /** Put an English description of @a statcode into @a buf and return @a buf,
61  * NULL-terminated. @a statcode is either an svn error or apr error.
62  */
63 char *
64 svn_strerror(apr_status_t statcode,
65  char *buf,
66  apr_size_t bufsize);
67 
68 
69 /** If @a err has a custom error message, return that, otherwise
70  * store the generic error string associated with @a err->apr_err into
71  * @a buf (terminating with NULL) and return @a buf.
72  *
73  * @since New in 1.4.
74  *
75  * @note @a buf and @a bufsize are provided in the interface so that
76  * this function is thread-safe and yet does no allocation.
77  */
78 const char *svn_err_best_message(svn_error_t *err,
79  char *buf,
80  apr_size_t bufsize);
81 
82 
83 
84 /** SVN error creation and destruction.
85  *
86  * @defgroup svn_error_error_creation_destroy Error creation and destruction
87  * @{
88  */
89 
90 /** Create a nested exception structure.
91  *
92  * Input: an APR or SVN custom error code,
93  * a "child" error to wrap,
94  * a specific message
95  *
96  * Returns: a new error structure (containing the old one).
97  *
98  * @note Errors are always allocated in a subpool of the global pool,
99  * since an error's lifetime is generally not related to the
100  * lifetime of any convenient pool. Errors must be freed
101  * with svn_error_clear(). The specific message should be @c NULL
102  * if there is nothing to add to the general message associated
103  * with the error code.
104  *
105  * If creating the "bottommost" error in a chain, pass @c NULL for
106  * the child argument.
107  */
108 svn_error_t *
109 svn_error_create(apr_status_t apr_err,
110  svn_error_t *child,
111  const char *message);
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 /** Wrap a @a status from an APR function. If @a fmt is NULL, this is
125  * equivalent to svn_error_create(status,NULL,NULL). Otherwise,
126  * the error message is constructed by formatting @a fmt and the
127  * following arguments according to apr_psprintf(), and then
128  * appending ": " and the error message corresponding to @a status.
129  * (If UTF-8 translation of the APR error message fails, the ": " and
130  * APR error are not appended to the error message.)
131  */
132 svn_error_t *
133 svn_error_wrap_apr(apr_status_t status,
134  const char *fmt,
135  ...)
136  __attribute__((format(printf, 2, 3)));
137 
138 /** A quick n' easy way to create a wrapped exception with your own
139  * message, before throwing it up the stack. (It uses all of the
140  * @a child's fields.)
141  */
142 svn_error_t *
144  const char *new_msg);
145 
146 /** Compose two errors, returning the composition as a brand new error
147  * and consuming the original errors. Either or both of @a err1 and
148  * @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR,
149  * @a err2 will follow @a err1 in the chain of the returned error.
150  *
151  * Either @a err1 or @a err2 can be functions that return svn_error_t*
152  * but if both are functions they can be evaluated in either order as
153  * per the C language rules.
154  *
155  * @since New in 1.6.
156  */
157 svn_error_t *
159  svn_error_t *err2);
160 
161 /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err
162  * chain will be copied into @a chain's pool and destroyed, so @a new_err
163  * itself becomes invalid after this function.
164  *
165  * Either @a chain or @a new_err can be functions that return svn_error_t*
166  * but if both are functions they can be evaluated in either order as
167  * per the C language rules.
168  */
169 void
171  svn_error_t *new_err);
172 
173 /** Return the root cause of @a err by finding the last error in its
174  * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in
175  * which case @c SVN_NO_ERROR is returned.
176  *
177  * @since New in 1.5.
178  */
179 svn_error_t *
181 
182 /** Return the first error in @a err's chain that has an error code @a
183  * apr_err or #SVN_NO_ERROR if there is no error with that code. The
184  * returned error should @em not be cleared as it shares memory with @a err.
185  *
186  * If @a err is #SVN_NO_ERROR, return #SVN_NO_ERROR.
187  *
188  * @since New in 1.7.
189  */
190 svn_error_t *
191 svn_error_find_cause(svn_error_t *err, apr_status_t apr_err);
192 
193 /** Create a new error that is a deep copy of @a err and return it.
194  *
195  * @since New in 1.2.
196  */
197 svn_error_t *
199 
200 /** Free the memory used by @a error, as well as all ancestors and
201  * descendants of @a error.
202  *
203  * Unlike other Subversion objects, errors are managed explicitly; you
204  * MUST clear an error if you are ignoring it, or you are leaking memory.
205  * For convenience, @a error may be @c NULL, in which case this function does
206  * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
207  * ignore errors.
208  */
209 void
211 
212 
213 #if defined(SVN_DEBUG)
214 /** Set the error location for debug mode. */
215 void
216 svn_error__locate(const char *file,
217  long line);
218 
219 /* Wrapper macros to collect file and line information */
220 #define svn_error_create \
221  (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
222 #define svn_error_createf \
223  (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
224 #define svn_error_wrap_apr \
225  (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
226 #define svn_error_quick_wrap \
227  (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
228 #endif
229 
230 
231 /**
232  * Very basic default error handler: print out error stack @a error to the
233  * stdio stream @a stream, with each error prefixed by @a prefix; quit and
234  * clear @a error iff the @a fatal flag is set. Allocations are performed
235  * in the @a error's pool.
236  *
237  * If you're not sure what prefix to pass, just pass "svn: ". That's
238  * what code that used to call svn_handle_error() and now calls
239  * svn_handle_error2() does.
240  *
241  * @since New in 1.2.
242  */
243 void
245  FILE *stream,
246  svn_boolean_t fatal,
247  const char *prefix);
248 
249 /** Like svn_handle_error2() but with @c prefix set to "svn: "
250  *
251  * @deprecated Provided for backward compatibility with the 1.1 API.
252  */
254 void
256  FILE *stream,
257  svn_boolean_t fatal);
258 
259 /**
260  * Very basic default warning handler: print out the error @a error to the
261  * stdio stream @a stream, prefixed by @a prefix. Allocations are
262  * performed in the error's pool.
263  *
264  * @a error may not be @c NULL.
265  *
266  * @since New in 1.2.
267  */
268 void
269 svn_handle_warning2(FILE *stream,
270  svn_error_t *error,
271  const char *prefix);
272 
273 /** Like svn_handle_warning2() but with @c prefix set to "svn: "
274  *
275  * @deprecated Provided for backward compatibility with the 1.1 API.
276  */
278 void
279 svn_handle_warning(FILE *stream,
280  svn_error_t *error);
281 
282 
283 /** A statement macro for checking error values.
284  *
285  * Evaluate @a expr. If it yields an error, return that error from the
286  * current function. Otherwise, continue.
287  *
288  * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
289  * but it makes this macro syntactically equivalent to the expression
290  * statement it resembles. Without it, statements like
291  *
292  * @code
293  * if (a)
294  * SVN_ERR(some operation);
295  * else
296  * foo;
297  * @endcode
298  *
299  * would not mean what they appear to.
300  */
301 #define SVN_ERR(expr) \
302  do { \
303  svn_error_t *svn_err__temp = (expr); \
304  if (svn_err__temp) \
305  return svn_error_trace(svn_err__temp); \
306  } while (0)
307 
308 /**
309  * A macro for wrapping an error in a source-location trace message.
310  *
311  * This macro can be used when directly returning an already created
312  * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure
313  * that the call stack is recorded correctly.
314  *
315  * @since New in 1.7.
316  */
317 #ifdef SVN_ERR__TRACING
318 #define SVN_ERR__TRACED "traced call"
319 
320 #define svn_error_trace(expr) svn_error_quick_wrap((expr), SVN_ERR__TRACED)
321 #else
322 #define svn_error_trace(expr) (expr)
323 #endif
324 
325 /**
326  * Returns an error chain that is based on @a err's error chain but
327  * does not include any error tracing placeholders. @a err is not
328  * modified, except for any allocations using its pool.
329  *
330  * The returned error chain is allocated from @a err's pool and shares
331  * its message and source filename character arrays. The returned
332  * error chain should *not* be cleared because it is not a fully
333  * fledged error chain, only clearing @a err should be done to clear
334  * the returned error chain. If @a err is cleared, then the returned
335  * error chain is unusable.
336  *
337  * @a err can be #SVN_NO_ERROR. If @a err is not #SVN_NO_ERROR, then
338  * the last link in the error chain must be a non-tracing error, i.e,
339  * a real error.
340  *
341  * @since New in 1.7.
342  */
344 
345 
346 /** A statement macro, very similar to @c SVN_ERR.
347  *
348  * This macro will wrap the error with the specified text before
349  * returning the error.
350  */
351 #define SVN_ERR_W(expr, wrap_msg) \
352  do { \
353  svn_error_t *svn_err__temp = (expr); \
354  if (svn_err__temp) \
355  return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
356  } while (0)
357 
358 
359 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
360  *
361  * Evaluate @a expr. If it yields an error, handle that error and
362  * return @c EXIT_FAILURE.
363  */
364 #define SVN_INT_ERR(expr) \
365  do { \
366  svn_error_t *svn_err__temp = (expr); \
367  if (svn_err__temp) { \
368  svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \
369  svn_error_clear(svn_err__temp); \
370  return EXIT_FAILURE; } \
371  } while (0)
372 
373 /** @} */
374 
375 
376 /** Error groups
377  *
378  * @defgroup svn_error_error_groups Error groups
379  * @{
380  */
381 
382 /**
383  * Return TRUE if @a err is an error specifically related to locking a
384  * path in the repository, FALSE otherwise.
385  *
386  * SVN_ERR_FS_OUT_OF_DATE and SVN_ERR_FS_NOT_FOUND are in here because it's a
387  * non-fatal error that can be thrown when attempting to lock an item.
388  *
389  * @since New in 1.2.
390  */
391 #define SVN_ERR_IS_LOCK_ERROR(err) \
392  (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \
393  err->apr_err == SVN_ERR_FS_NOT_FOUND || \
394  err->apr_err == SVN_ERR_FS_OUT_OF_DATE || \
395  err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN)
396 
397 /**
398  * Return TRUE if @a err is an error specifically related to unlocking
399  * a path in the repository, FALSE otherwise.
400  *
401  * @since New in 1.2.
402  */
403 #define SVN_ERR_IS_UNLOCK_ERROR(err) \
404  (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \
405  err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \
406  err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \
407  err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \
408  err->apr_err == SVN_ERR_RA_NOT_LOCKED || \
409  err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
410 
411 /** Evaluates to @c TRUE iff @a apr_err (of type #apr_status_t) is in the given
412  * @a category, which should be one of the @c SVN_ERR_*_CATEGORY_START
413  * constants.
414  *
415  * @since New in 1.7.
416  */
417 #define SVN_ERROR_IN_CATEGORY(apr_err, category) \
418  ((category) == ((apr_err) / SVN_ERR_CATEGORY_SIZE) * SVN_ERR_CATEGORY_SIZE)
419 
420 
421 /** @} */
422 
423 
424 /** Internal malfunctions and assertions
425  *
426  * @defgroup svn_error_malfunction_assertion Malfunctions and assertions
427  * @{
428  */
429 
430 /** Report that an internal malfunction has occurred, and possibly terminate
431  * the program.
432  *
433  * Act as determined by the current "malfunction handler" which may have
434  * been specified by a call to svn_error_set_malfunction_handler() or else
435  * is the default handler as specified in that function's documentation. If
436  * the malfunction handler returns, then cause the function using this macro
437  * to return the error object that it generated.
438  *
439  * @note The intended use of this macro is where execution reaches a point
440  * that cannot possibly be reached unless there is a bug in the program.
441  *
442  * @since New in 1.6.
443  */
444 #define SVN_ERR_MALFUNCTION() \
445  do { \
446  return svn_error_trace(svn_error__malfunction( \
447  TRUE, __FILE__, __LINE__, NULL)); \
448  } while (0)
449 
450 /** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning
451  * an error to the calling function.
452  *
453  * If possible you should use SVN_ERR_MALFUNCTION() instead.
454  *
455  * @since New in 1.6.
456  */
457 #define SVN_ERR_MALFUNCTION_NO_RETURN() \
458  do { \
459  svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \
460  abort(); \
461  } while (1)
462 
463 /** Check that a condition is true: if not, report an error and possibly
464  * terminate the program.
465  *
466  * If the Boolean expression @a expr is true, do nothing. Otherwise,
467  * act as determined by the current "malfunction handler" which may have
468  * been specified by a call to svn_error_set_malfunction_handler() or else
469  * is the default handler as specified in that function's documentation. If
470  * the malfunction handler returns, then cause the function using this macro
471  * to return the error object that it generated.
472  *
473  * @note The intended use of this macro is to check a condition that cannot
474  * possibly be false unless there is a bug in the program.
475  *
476  * @note The condition to be checked should not be computationally expensive
477  * if it is reached often, as, unlike traditional "assert" statements, the
478  * evaluation of this expression is not compiled out in release-mode builds.
479  *
480  * @since New in 1.6.
481  */
482 #define SVN_ERR_ASSERT(expr) \
483  do { \
484  if (!(expr)) \
485  SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \
486  } while (0)
487 
488 /** Similar to SVN_ERR_ASSERT(), but without the option of returning
489  * an error to the calling function.
490  *
491  * If possible you should use SVN_ERR_ASSERT() instead.
492  *
493  * @since New in 1.6.
494  */
495 #define SVN_ERR_ASSERT_NO_RETURN(expr) \
496  do { \
497  if (!(expr)) { \
498  svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \
499  abort(); \
500  } \
501  } while (0)
502 
503 /** Report a "Not implemented" malfunction. Internal use only. */
504 #define SVN__NOT_IMPLEMENTED() \
505  return svn_error__malfunction(TRUE, __FILE__, __LINE__, "Not implemented.")
506 
507 /** A helper function for the macros that report malfunctions. Handle a
508  * malfunction by calling the current "malfunction handler" which may have
509  * been specified by a call to svn_error_set_malfunction_handler() or else
510  * is the default handler as specified in that function's documentation.
511  *
512  * Pass all of the parameters to the handler. The error occurred in the
513  * source file @a file at line @a line, and was an assertion failure of the
514  * expression @a expr, or, if @a expr is null, an unconditional error.
515  *
516  * If @a can_return is true, the handler can return an error object
517  * that is returned by the caller. If @a can_return is false the
518  * method should never return. (The caller will call abort())
519  *
520  * @since New in 1.6.
521  */
522 svn_error_t *
524  const char *file,
525  int line,
526  const char *expr);
527 
528 /** A type of function that handles an assertion failure or other internal
529  * malfunction detected within the Subversion libraries.
530  *
531  * The error occurred in the source file @a file at line @a line, and was an
532  * assertion failure of the expression @a expr, or, if @a expr is null, an
533  * unconditional error.
534  *
535  * If @a can_return is false a function of this type must never return.
536  *
537  * If @a can_return is true a function of this type must do one of:
538  * - Return an error object describing the error, using an error code in
539  * the category SVN_ERR_MALFUNC_CATEGORY_START.
540  * - Never return.
541  *
542  * The function may alter its behaviour according to compile-time
543  * and run-time and even interactive conditions.
544  *
545  * @see SVN_ERROR_IN_CATEGORY()
546  *
547  * @since New in 1.6.
548  */
549 typedef svn_error_t *(*svn_error_malfunction_handler_t)
550  (svn_boolean_t can_return, const char *file, int line, const char *expr);
551 
552 /** Cause subsequent malfunctions to be handled by @a func.
553  * Return the handler that was previously in effect.
554  *
555  * @a func may not be null.
556  *
557  * @note The default handler is svn_error_abort_on_malfunction().
558  *
559  * @note This function must be called in a single-threaded context.
560  *
561  * @since New in 1.6.
562  */
565 
566 /** Handle a malfunction by returning an error object that describes it.
567  *
568  * When @a can_return is false, abort()
569  *
570  * This function implements @c svn_error_malfunction_handler_t.
571  *
572  * @since New in 1.6.
573  */
574 svn_error_t *
576  const char *file,
577  int line,
578  const char *expr);
579 
580 /** Handle a malfunction by printing a message to stderr and aborting.
581  *
582  * This function implements @c svn_error_malfunction_handler_t.
583  *
584  * @since New in 1.6.
585  */
586 svn_error_t *
588  const char *file,
589  int line,
590  const char *expr);
591 
592 /** @} */
593 
594 
595 #ifdef __cplusplus
596 }
597 #endif /* __cplusplus */
598 
599 #endif /* SVN_ERROR_H */