/** * @copyright * ==================================================================== * Copyright (c) 2000-2004 CollabNet. All rights reserved. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms * are also available at http://subversion.tigris.org/license-1.html. * If newer versions of this license are posted there, you may use a * newer version instead, at your option. * * This software consists of voluntary contributions made by many * individuals. For exact contribution history, see the revision * history and logs, available at http://subversion.tigris.org/. * ==================================================================== * @endcopyright * * @file svn_error.h * @brief Common exception handling for Subversion. */ #ifndef SVN_ERROR_H #define SVN_ERROR_H #include #include /* APR's error system */ #include #ifndef DOXYGEN_SHOULD_SKIP_THIS #define APR_WANT_STDIO #endif #include #include "svn_types.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** the best kind of (@c svn_error_t *) ! */ #define SVN_NO_ERROR 0 /* The actual error codes are kept in a separate file; see comments there for the reasons why. */ #include "svn_error_codes.h" /** Set the error location for debug mode. */ void svn_error__locate (const char *file, long line); /** Put an English description of @a statcode into @a buf and return @a buf, * null-terminated, @a statcode is either an svn error or apr error. */ char *svn_strerror (apr_status_t statcode, char *buf, apr_size_t bufsize); /** SVN error creation and destruction. * * @defgroup svn_error_error_creation_destroy error creation and destruction * @{ */ /** Create a nested exception structure. * * Input: an APR or SVN custom error code, * a "child" error to wrap, * a specific message * * Returns: a new error structure (containing the old one). * * Notes: Errors are always allocated in a subpool of the global pool, * since an error's lifetime is generally not related to the * lifetime of any convenient pool. Errors must be freed * with @c svn_error_clear(). The specific message should be NULL * if there is nothing to add to the general message associated * with the error code. * * If creating the "bottommost" error in a chain, pass @c NULL for * the child argument. */ svn_error_t *svn_error_create (apr_status_t apr_err, svn_error_t *child, const char *message); /** Wrapper macro to collect file and line information */ #define svn_error_create \ (svn_error__locate(__FILE__,__LINE__), (svn_error_create)) /** Create an error structure with the given @a apr_err and @a child, * with a printf-style error message produced by passing @a fmt, using * @c apr_psprintf. */ svn_error_t *svn_error_createf (apr_status_t apr_err, svn_error_t *child, const char *fmt, ...) __attribute__ ((format (printf, 3, 4))); /** Wrapper macro to collect file and line information */ #define svn_error_createf \ (svn_error__locate(__FILE__,__LINE__), (svn_error_createf)) /** Wrap a status from an APR function. If @a fmt is NULL, this is * equivalent to @c svn_error_create(status, NULL, NULL). Otherwise, * the error message is constructed by formatting @a fmt and the * following arguments according to @c apr_psprintf, and then * appending ": " and the error message corresponding to @a status. * (If UTF-8 translation of the APR error message fails, the ": " and * APR error are not appended to the error message.) */ svn_error_t *svn_error_wrap_apr (apr_status_t status, const char *fmt, ...); /** Wrapper macro to collect file and line information */ #define svn_error_wrap_apr \ (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) /** A quick n' easy way to create a wrappered exception with your own * message, before throwing it up the stack. (It uses all of the * child's fields.) */ svn_error_t *svn_error_quick_wrap (svn_error_t *child, const char *new_msg); /** Wrapper macro to collect file and line information */ #define svn_error_quick_wrap \ (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err * chain will be copied into @a chain's pool and destroyed, so @a new_err * itself becomes invalid after this function. */ void svn_error_compose (svn_error_t *chain, svn_error_t *new_err); /** Free the memory used by @a error, as well as all ancestors and * descendants of @a error. * * Unlike other Subversion objects, errors are managed explicitly; you * MUST clear an error if you are ignoring it, or you are leaking memory. * For convenience, @a error may be @c NULL, in which case this function does * nothing; thus, @c svn_error_clear(svn_foo(...)) works as an idiom to * ignore errors. */ void svn_error_clear (svn_error_t *error); /** Very basic default error handler: print out error stack, and quit * iff the @a fatal flag is set. */ void svn_handle_error (svn_error_t *error, FILE *stream, svn_boolean_t fatal); /** Basic, default warning handler. * * Just prints @a error to the stdio stream given in @a stream. Allocations * are performed in the error's pool. */ void svn_handle_warning (FILE *stream, svn_error_t *error); /** A statement macro for checking error return values. * * Evaluate @a expr. If it yields an error, return that error from the * current function. Otherwise, continue. * * The do { ... } while (0) wrapper has no semantic effect, * but it makes this macro syntactically equivalent to the expression * statement it resembles. Without it, statements like * * * if (a) * SVN_ERR (some operation); * else * foo; * * * would not mean what they appear to. */ #define SVN_ERR(expr) \ do { \ svn_error_t *svn_err__temp = (expr); \ if (svn_err__temp) \ return svn_err__temp; \ } while (0) /** A statement macro, very similar to @c SVN_ERR. * * This macro will wrap the error with the specified text before * returning the error. */ #define SVN_ERR_W(expr, wrap_msg) \ do { \ svn_error_t *svn_err__temp = (expr); \ if (svn_err__temp) \ return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ } while (0) /** A statement macro, similar to @c SVN_ERR, but returns an integer. * * Evaluate @a expr. If it yields an error, handle that error and * return @c EXIT_FAILURE. */ #define SVN_INT_ERR(expr) \ do { \ svn_error_t *svn_err__temp = (expr); \ if (svn_err__temp) { \ svn_handle_error (svn_err__temp, stderr, FALSE); \ svn_error_clear (svn_err__temp); \ return EXIT_FAILURE; } \ } while (0) /** @} */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* SVN_ERROR_H */