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
12 * http://www.apache.org/licenses/LICENSE-2.0
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
20 * ====================================================================
24 * @brief Common exception handling for Subversion.
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 */
34 #ifndef DOXYGEN_SHOULD_SKIP_THIS
35 #define APR_WANT_STDIO
37 #include <apr_want.h> /* for FILE* */
39 #include "svn_types.h"
43 #endif /* __cplusplus */
46 /* For the Subversion developers, this #define turns on extended "stack
47 traces" of any errors that get thrown. See the SVN_ERR() macro. */
49 #define SVN_ERR__TRACING
53 /** the best kind of (@c svn_error_t *) ! */
54 #define SVN_NO_ERROR 0
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"
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.
64 svn_strerror(apr_status_t statcode,
70 * Return the symbolic name of an error code. If the error code
71 * is in svn_error_codes.h, return the name of the macro as a string.
72 * If the error number is not recognised, return @c NULL.
74 * An error number may not be recognised because it was defined in a future
75 * version of Subversion (e.g., a 1.9.x server may transmit a defined-in-1.9.0
76 * error number to a 1.8.x client).
78 * An error number may be recognised @em incorrectly if the @c apr_status_t
79 * value originates in another library (such as libserf) which also uses APR.
80 * (This is a theoretical concern only: the @c apr_err member of #svn_error_t
81 * should never contain a "foreign" @c apr_status_t value, and
82 * in any case Subversion and Serf use non-overlapping subsets of the
83 * @c APR_OS_START_USERERR range.)
85 * Support for error codes returned by APR itself (i.e., not in the
86 * @c APR_OS_START_USERERR range, as defined in apr_errno.h) may be implemented
89 * @note In rare cases, a single numeric code has more than one symbolic name.
90 * (For example, #SVN_ERR_WC_NOT_DIRECTORY and #SVN_ERR_WC_NOT_WORKING_COPY).
91 * In those cases, it is not guaranteed which symbolic name is returned.
96 svn_error_symbolic_name(apr_status_t statcode);
99 /** If @a err has a custom error message, return that, otherwise
100 * store the generic error string associated with @a err->apr_err into
101 * @a buf (terminating with NULL) and return @a buf.
105 * @note @a buf and @a bufsize are provided in the interface so that
106 * this function is thread-safe and yet does no allocation.
108 const char *svn_err_best_message(svn_error_t *err,
114 /** SVN error creation and destruction.
116 * @defgroup svn_error_error_creation_destroy Error creation and destruction
120 /** Create a nested exception structure.
122 * Input: an APR or SVN custom error code,
123 * a "child" error to wrap,
126 * Returns: a new error structure (containing the old one).
128 * @note Errors are always allocated in a subpool of the global pool,
129 * since an error's lifetime is generally not related to the
130 * lifetime of any convenient pool. Errors must be freed
131 * with svn_error_clear(). The specific message should be @c NULL
132 * if there is nothing to add to the general message associated
133 * with the error code.
135 * If creating the "bottommost" error in a chain, pass @c NULL for
136 * the child argument.
139 svn_error_create(apr_status_t apr_err,
141 const char *message);
143 /** Create an error structure with the given @a apr_err and @a child,
144 * with a printf-style error message produced by passing @a fmt, using
148 svn_error_createf(apr_status_t apr_err,
152 __attribute__ ((format(printf, 3, 4)));
154 /** Wrap a @a status from an APR function. If @a fmt is NULL, this is
155 * equivalent to svn_error_create(status,NULL,NULL). Otherwise,
156 * the error message is constructed by formatting @a fmt and the
157 * following arguments according to apr_psprintf(), and then
158 * appending ": " and the error message corresponding to @a status.
159 * (If UTF-8 translation of the APR error message fails, the ": " and
160 * APR error are not appended to the error message.)
163 svn_error_wrap_apr(apr_status_t status,
166 __attribute__((format(printf, 2, 3)));
168 /** A quick n' easy way to create a wrapped exception with your own
169 * message, before throwing it up the stack. (It uses all of the
170 * @a child's fields.)
173 svn_error_quick_wrap(svn_error_t *child,
174 const char *new_msg);
176 /** Compose two errors, returning the composition as a brand new error
177 * and consuming the original errors. Either or both of @a err1 and
178 * @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR,
179 * @a err2 will follow @a err1 in the chain of the returned error.
181 * Either @a err1 or @a err2 can be functions that return svn_error_t*
182 * but if both are functions they can be evaluated in either order as
183 * per the C language rules.
188 svn_error_compose_create(svn_error_t *err1,
191 /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err
192 * chain will be copied into @a chain's pool and destroyed, so @a new_err
193 * itself becomes invalid after this function.
195 * Either @a chain or @a new_err can be functions that return svn_error_t*
196 * but if both are functions they can be evaluated in either order as
197 * per the C language rules.
200 svn_error_compose(svn_error_t *chain,
201 svn_error_t *new_err);
203 /** Return the root cause of @a err by finding the last error in its
204 * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in
205 * which case @c SVN_NO_ERROR is returned.
210 svn_error_root_cause(svn_error_t *err);
212 /** Return the first error in @a err's chain that has an error code @a
213 * apr_err or #SVN_NO_ERROR if there is no error with that code. The
214 * returned error should @em not be cleared as it shares memory with @a err.
216 * If @a err is #SVN_NO_ERROR, return #SVN_NO_ERROR.
221 svn_error_find_cause(svn_error_t *err, apr_status_t apr_err);
223 /** Create a new error that is a deep copy of @a err and return it.
228 svn_error_dup(svn_error_t *err);
230 /** Free the memory used by @a error, as well as all ancestors and
231 * descendants of @a error.
233 * Unlike other Subversion objects, errors are managed explicitly; you
234 * MUST clear an error if you are ignoring it, or you are leaking memory.
235 * For convenience, @a error may be @c NULL, in which case this function does
236 * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
240 svn_error_clear(svn_error_t *error);
243 #if defined(SVN_ERR__TRACING)
244 /** Set the error location for debug mode. */
246 svn_error__locate(const char *file,
249 /* Wrapper macros to collect file and line information */
250 #define svn_error_create \
251 (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
252 #define svn_error_createf \
253 (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
254 #define svn_error_wrap_apr \
255 (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
256 #define svn_error_quick_wrap \
257 (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
262 * Very basic default error handler: print out error stack @a error to the
263 * stdio stream @a stream, with each error prefixed by @a prefix; quit and
264 * clear @a error iff the @a fatal flag is set. Allocations are performed
265 * in the @a error's pool.
267 * If you're not sure what prefix to pass, just pass "svn: ". That's
268 * what code that used to call svn_handle_error() and now calls
269 * svn_handle_error2() does.
274 svn_handle_error2(svn_error_t *error,
279 /** Like svn_handle_error2() but with @c prefix set to "svn: "
281 * @deprecated Provided for backward compatibility with the 1.1 API.
285 svn_handle_error(svn_error_t *error,
287 svn_boolean_t fatal);
290 * Very basic default warning handler: print out the error @a error to the
291 * stdio stream @a stream, prefixed by @a prefix. Allocations are
292 * performed in the error's pool.
294 * @a error may not be @c NULL.
299 svn_handle_warning2(FILE *stream,
303 /** Like svn_handle_warning2() but with @c prefix set to "svn: "
305 * @deprecated Provided for backward compatibility with the 1.1 API.
309 svn_handle_warning(FILE *stream,
313 /** A statement macro for checking error values.
315 * Evaluate @a expr. If it yields an error, return that error from the
316 * current function. Otherwise, continue.
318 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
319 * but it makes this macro syntactically equivalent to the expression
320 * statement it resembles. Without it, statements like
324 * SVN_ERR(some operation);
329 * would not mean what they appear to.
331 #define SVN_ERR(expr) \
333 svn_error_t *svn_err__temp = (expr); \
335 return svn_error_trace(svn_err__temp); \
339 * A macro for wrapping an error in a source-location trace message.
341 * This macro can be used when directly returning an already created
342 * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure
343 * that the call stack is recorded correctly.
347 #ifdef SVN_ERR__TRACING
349 svn_error__trace(const char *file, long line, svn_error_t *err);
351 #define svn_error_trace(expr) svn_error__trace(__FILE__, __LINE__, (expr))
353 #define svn_error_trace(expr) (expr)
357 * Returns an error chain that is based on @a err's error chain but
358 * does not include any error tracing placeholders. @a err is not
359 * modified, except for any allocations using its pool.
361 * The returned error chain is allocated from @a err's pool and shares
362 * its message and source filename character arrays. The returned
363 * error chain should *not* be cleared because it is not a fully
364 * fledged error chain, only clearing @a err should be done to clear
365 * the returned error chain. If @a err is cleared, then the returned
366 * error chain is unusable.
368 * @a err can be #SVN_NO_ERROR. If @a err is not #SVN_NO_ERROR, then
369 * the last link in the error chain must be a non-tracing error, i.e,
374 svn_error_t *svn_error_purge_tracing(svn_error_t *err);
377 /** A statement macro, very similar to @c SVN_ERR.
379 * This macro will wrap the error with the specified text before
380 * returning the error.
382 #define SVN_ERR_W(expr, wrap_msg) \
384 svn_error_t *svn_err__temp = (expr); \
386 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
390 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
392 * Evaluate @a expr. If it yields an error, handle that error and
393 * return @c EXIT_FAILURE.
395 #define SVN_INT_ERR(expr) \
397 svn_error_t *svn_err__temp = (expr); \
398 if (svn_err__temp) { \
399 svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \
400 svn_error_clear(svn_err__temp); \
401 return EXIT_FAILURE; } \
409 * @defgroup svn_error_error_groups Error groups
414 * Return TRUE if @a err is an error specifically related to locking a
415 * path in the repository, FALSE otherwise.
417 * SVN_ERR_FS_OUT_OF_DATE and SVN_ERR_FS_NOT_FOUND are in here because it's a
418 * non-fatal error that can be thrown when attempting to lock an item.
422 #define SVN_ERR_IS_LOCK_ERROR(err) \
423 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \
424 err->apr_err == SVN_ERR_FS_NOT_FOUND || \
425 err->apr_err == SVN_ERR_FS_OUT_OF_DATE || \
426 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN)
429 * Return TRUE if @a err is an error specifically related to unlocking
430 * a path in the repository, FALSE otherwise.
434 #define SVN_ERR_IS_UNLOCK_ERROR(err) \
435 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \
436 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \
437 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \
438 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \
439 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \
440 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
442 /** Evaluates to @c TRUE iff @a apr_err (of type apr_status_t) is in the given
443 * @a category, which should be one of the @c SVN_ERR_*_CATEGORY_START
448 #define SVN_ERROR_IN_CATEGORY(apr_err, category) \
449 ((category) == ((apr_err) / SVN_ERR_CATEGORY_SIZE) * SVN_ERR_CATEGORY_SIZE)
455 /** Internal malfunctions and assertions
457 * @defgroup svn_error_malfunction_assertion Malfunctions and assertions
461 /** Report that an internal malfunction has occurred, and possibly terminate
464 * Act as determined by the current "malfunction handler" which may have
465 * been specified by a call to svn_error_set_malfunction_handler() or else
466 * is the default handler as specified in that function's documentation. If
467 * the malfunction handler returns, then cause the function using this macro
468 * to return the error object that it generated.
470 * @note The intended use of this macro is where execution reaches a point
471 * that cannot possibly be reached unless there is a bug in the program.
475 #define SVN_ERR_MALFUNCTION() \
477 return svn_error_trace(svn_error__malfunction( \
478 TRUE, __FILE__, __LINE__, NULL)); \
481 /** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning
482 * an error to the calling function.
484 * If possible you should use SVN_ERR_MALFUNCTION() instead.
488 #define SVN_ERR_MALFUNCTION_NO_RETURN() \
490 svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \
494 /** Like SVN_ERR_ASSERT(), but append ERR to the returned error chain.
496 * If EXPR is false, return a malfunction error whose chain includes ERR.
497 * If EXPR is true, do nothing. (In particular, this does not clear ERR.)
499 * Types: (svn_boolean_t expr, svn_error_t *err)
503 #ifdef __clang_analyzer__
505 /* Just ignore ERR. If the assert triggers, it'll be our least concern. */
506 #define SVN_ERR_ASSERT_E(expr, err) assert((expr))
508 #define SVN_ERR_ASSERT_E(expr, err) \
511 return svn_error_compose_create( \
512 svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr), \
519 /** Check that a condition is true: if not, report an error and possibly
520 * terminate the program.
522 * If the Boolean expression @a expr is true, do nothing. Otherwise,
523 * act as determined by the current "malfunction handler" which may have
524 * been specified by a call to svn_error_set_malfunction_handler() or else
525 * is the default handler as specified in that function's documentation. If
526 * the malfunction handler returns, then cause the function using this macro
527 * to return the error object that it generated.
529 * @note The intended use of this macro is to check a condition that cannot
530 * possibly be false unless there is a bug in the program.
532 * @note The condition to be checked should not be computationally expensive
533 * if it is reached often, as, unlike traditional "assert" statements, the
534 * evaluation of this expression is not compiled out in release-mode builds.
538 * @see SVN_ERR_ASSERT_E()
540 #ifdef __clang_analyzer__
542 #define SVN_ERR_ASSERT(expr) assert((expr))
544 #define SVN_ERR_ASSERT(expr) \
547 SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \
551 /** Similar to SVN_ERR_ASSERT(), but without the option of returning
552 * an error to the calling function.
554 * If possible you should use SVN_ERR_ASSERT() instead.
558 #define SVN_ERR_ASSERT_NO_RETURN(expr) \
561 svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \
566 /** Report a "Not implemented" malfunction. Internal use only. */
567 #define SVN__NOT_IMPLEMENTED() \
568 return svn_error__malfunction(TRUE, __FILE__, __LINE__, "Not implemented.")
570 /** A helper function for the macros that report malfunctions. Handle a
571 * malfunction by calling the current "malfunction handler" which may have
572 * been specified by a call to svn_error_set_malfunction_handler() or else
573 * is the default handler as specified in that function's documentation.
575 * Pass all of the parameters to the handler. The error occurred in the
576 * source file @a file at line @a line, and was an assertion failure of the
577 * expression @a expr, or, if @a expr is null, an unconditional error.
579 * If @a can_return is true, the handler can return an error object
580 * that is returned by the caller. If @a can_return is false the
581 * method should never return. (The caller will call abort())
586 svn_error__malfunction(svn_boolean_t can_return,
591 /** A type of function that handles an assertion failure or other internal
592 * malfunction detected within the Subversion libraries.
594 * The error occurred in the source file @a file at line @a line, and was an
595 * assertion failure of the expression @a expr, or, if @a expr is null, an
596 * unconditional error.
598 * If @a can_return is false a function of this type must never return.
600 * If @a can_return is true a function of this type must do one of:
601 * - Return an error object describing the error, using an error code in
602 * the category SVN_ERR_MALFUNC_CATEGORY_START.
605 * The function may alter its behaviour according to compile-time
606 * and run-time and even interactive conditions.
608 * @see SVN_ERROR_IN_CATEGORY()
612 typedef svn_error_t *(*svn_error_malfunction_handler_t)
613 (svn_boolean_t can_return, const char *file, int line, const char *expr);
615 /** Cause subsequent malfunctions to be handled by @a func.
616 * Return the handler that was previously in effect.
618 * @a func may not be null.
620 * @note The default handler is svn_error_abort_on_malfunction().
622 * @note This function must be called in a single-threaded context.
626 svn_error_malfunction_handler_t
627 svn_error_set_malfunction_handler(svn_error_malfunction_handler_t func);
629 /** Handle a malfunction by returning an error object that describes it.
631 * When @a can_return is false, abort()
633 * This function implements @c svn_error_malfunction_handler_t.
638 svn_error_raise_on_malfunction(svn_boolean_t can_return,
643 /** Handle a malfunction by printing a message to stderr and aborting.
645 * This function implements @c svn_error_malfunction_handler_t.
650 svn_error_abort_on_malfunction(svn_boolean_t can_return,
660 #endif /* __cplusplus */
662 #endif /* SVN_ERROR_H */