nput: an APR or SVN custom error code, * a "child" error to wrap, * a specific message * * Returns: a new error structure (containing the old one). * * @note 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 svn_error_clear(). The specific message should be @c 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); /** 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 * 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))); /** Wrap a @a status from an APR function. If @a fmt is NULL, this is * equivalent to svn_error_create(status,NULL,NULL). Otherwise, * the error message is constructed by formatting @a fmt and the * following arguments according to 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, ...) __attribute__((format(printf, 2, 3))); /** If @a child is SVN_NO_ERROR, return SVN_NO_ERROR. * Else, prepend a new error to the error chain of @a child. The new error * uses @a new_msg as error message but all other error attributes (such * as the error code) are copied from @a child. */ svn_error_t * svn_error_quick_wrap(svn_error_t *child, const char *new_msg); /** Like svn_error_quick_wrap(), but with format string support. * * @since New in 1.9. */ svn_error_t * svn_error_quick_wrapf(svn_error_t *child, const char *fmt, ...) __attribute__((format(printf, 2, 3))); /** Compose two errors, returning the composition as a brand new error * and consuming the original errors. Either or both of @a err1 and * @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR, * @a err2 will follow @a err1 in the chain of the returned error. * * Either @a err1 or @a err2 can be functions that return svn_error_t* * but if both are functions they can be evaluated in either order as * per the C language rules. * * @since New in 1.6. */ svn_error_t * svn_error_compose_create(svn_error_t *err1, svn_error_t *err2); /** 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. * * Either @a chain or @a new_err can be functions that return svn_error_t* * but if both are functions they can be evaluated in either order as * per the C language rules. */ void svn_error_compose(svn_error_t *chain, svn_error_t *new_err); /** Return the root cause of @a err by finding the last error in its * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in * which case @c SVN_NO_ERROR is returned. The returned error should * @em not be cleared as it shares memory with @a err. * * @since New in 1.5. */ svn_error_t * svn_error_root_cause(svn_error_t *err); /** Return the first error in @a err's chain that has an error code @a * apr_err or #SVN_NO_ERROR if there is no error with that code. The * returned error should @em not be cleared as it shares memory with @a err. * * If @a err is #SVN_NO_ERROR, return #SVN_NO_ERROR. * * @since New in 1.7. */ svn_error_t * svn_error_find_cause(svn_error_t *err, apr_status_t apr_err); /** Create a new error that is a deep copy of @a err and return it. * * @since New in 1.2. */ svn_error_t * svn_error_dup(const svn_error_t *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, svn_error_clear(svn_foo(...)) works as an idiom to * ignore errors. */ void svn_error_clear(svn_error_t *error); #if defined(SVN_ERR__TRACING) /** Set the error location for debug mode. */ void svn_error__locate(const char *file, long line); /* Wrapper macros to collect file and line information */ #define svn_error_create \ (svn_error__locate(__FILE__,__LINE__), (svn_error_create)) #define svn_error_createf \ (svn_error__locate(__FILE__,__LINE__), (svn_error_createf)) #define svn_error_wrap_apr \ (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) #define svn_error_quick_wrap \ (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) #define svn_error_quick_wrapf \ (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrapf)) #endif /** * Very basic default error handler: print out error stack @a error to the * stdio stream @a stream, with each error prefixed by @a prefix; quit and * clear @a error iff the @a fatal flag is set. Allocations are performed * in the @a error's pool. * * If you're not sure what prefix to pass, just pass "svn: ". That's * what code that used to call svn_handle_error() and now calls * svn_handle_error2() does. * * Note that this should only be used from commandline specific code, or * code that knows that @a stream is really where the application wants * to receive its errors on. * * @since New in 1.2. */ void svn_handle_error2(svn_error_t *error, FILE *stream, svn_boolean_t fatal, const char *prefix); /** Like svn_handle_error2() but with @c prefix set to "svn: " * * @deprecated Provided for backward compatibility with the 1.1 API. */ SVN_DEPRECATED void svn_handle_error(svn_error_t *error, FILE *stream, svn_boolean_t fatal); /** * Very basic default warning handler: print out the error @a error to the * stdio stream @a stream, prefixed by @a prefix. Allocations are * performed in the error's pool. * * @a error may not be @c NULL. * * @note This does not clear @a error. * * @since New in 1.2. */ void svn_handle_warning2(FILE *stream, const svn_error_t *error, const char *prefix); /** Like svn_handle_warning2() but with @c prefix set to "svn: " * * @deprecated Provided for backward compatibility with the 1.1 API. */ SVN_DEPRECATED void svn_handle_warning(FILE *stream, svn_error_t *error); /** A statement macro for checking error 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 * * @code * if (a) * SVN_ERR(some operation); * else * foo; * @endcode * * 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_error_trace(svn_err__temp); \ } while (0) /** * A macro for wrapping an error in a source-location trace message. * * This macro can be used when directly returning an already created * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure * that the call stack is recorded correctly. * * @since New in 1.7. */ #ifdef SVN_ERR__TRACING svn_error_t * svn_error__trace(const char *file, long line, svn_error_t *err); #define svn_error_trace(expr) svn_error__trace(__FILE__, __LINE__, (expr)) #else #define svn_error_trace(expr) (expr) #endif /** * Returns an error chain that is based on @a err's error chain but * does not include any error tracing placeholders. @a err is not * modified, except for any allocations using its pool. * * The returned error chain is allocated from @a err's pool and shares * its message and source filename character arrays. The returned * error chain should *not* be cleared because it is not a fully * fledged error chain, only clearing @a err should be done to clear * the returned error chain. If @a err is cleared, then the returned * error chain is unusable. * * @a err can be #SVN_NO_ERROR. If @a err is not #SVN_NO_ERROR, then * the last link in the error chain must be a non-tracing error, i.e, * a real error. * * @since New in 1.7. */ svn_error_t *svn_error_purge_tracing(svn_error_t *err); /** 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 intended for the main() function of the 'svn' program. * * Evaluate @a expr. If it yields an error, display the error on stdout * and return @c EXIT_FAILURE. * * @note Not for use in the library, as it prints to stderr. This macro * no longer suits the needs of the 'svn' program, and is not generally * suitable for third-party use as it assumes the program name is 'svn'. * * @deprecated Provided for backward compatibility with the 1.8 API. Consider * using svn_handle_error2() or svn_cmdline_handle_exit_error() instead. */ #define SVN_INT_ERR(expr) \ do { \ svn_error_t *svn_err__temp = (expr); \ if (svn_err__temp) { \ svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \ svn_error_clear(svn_err__temp); \ return EXIT_FAILURE; } \ } while (0) /** @} */