svn_error.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_error.h
00019  * @brief Common exception handling for Subversion.
00020  */
00021 
00022 
00023 
00024 
00025 #ifndef SVN_ERROR_H
00026 #define SVN_ERROR_H
00027 
00028 #include <apr.h>
00029 #include <apr_errno.h>     /* APR's error system */
00030 #include <apr_pools.h>
00031 
00032 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00033 #define APR_WANT_STDIO
00034 #endif
00035 #include <apr_want.h>
00036 
00037 #include "svn_types.h"
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif /* __cplusplus */
00042 
00043 /** the best kind of (@c svn_error_t *) ! */
00044 #define SVN_NO_ERROR   0
00045 
00046 /* The actual error codes are kept in a separate file; see comments
00047    there for the reasons why. */
00048 #include "svn_error_codes.h"
00049 
00050 /** Set the error location for debug mode. */
00051 void svn_error__locate(const char *file, long line);
00052 
00053 
00054 /** Put an English description of @a statcode into @a buf and return @a buf,
00055  * NULL-terminated. @a statcode is either an svn error or apr error.
00056  */
00057 char *svn_strerror(apr_status_t statcode, char *buf, apr_size_t bufsize);
00058 
00059 
00060 /** If @a err has a custom error message, return that, otherwise
00061  * store the generic error string associated with @a err->apr_err into
00062  * @a buf (terminating with NULL) and return @a buf.
00063  *
00064  * @since New in 1.4.
00065  *
00066  * @note @a buf and @a bufsize are provided in the interface so that
00067  * this function is thread-safe and yet does no allocation.
00068  */
00069 const char *svn_err_best_message(svn_error_t *err,
00070                                  char *buf, apr_size_t bufsize);
00071 
00072 
00073 
00074 /** SVN error creation and destruction.
00075  *
00076  * @defgroup svn_error_error_creation_destroy Error creation and destruction
00077  * @{
00078  */
00079 
00080 /** Create a nested exception structure.
00081  *
00082  * Input:  an APR or SVN custom error code,
00083  *         a "child" error to wrap,
00084  *         a specific message
00085  *
00086  * Returns:  a new error structure (containing the old one).
00087  *
00088  * @note Errors are always allocated in a subpool of the global pool,
00089  *        since an error's lifetime is generally not related to the
00090  *        lifetime of any convenient pool.  Errors must be freed
00091  *        with svn_error_clear().  The specific message should be @c NULL
00092  *        if there is nothing to add to the general message associated
00093  *        with the error code.
00094  *
00095  *        If creating the "bottommost" error in a chain, pass @c NULL for
00096  *        the child argument.
00097  */
00098 svn_error_t *svn_error_create(apr_status_t apr_err,
00099                               svn_error_t *child,
00100                               const char *message);
00101 
00102 /** Wrapper macro to collect file and line information */
00103 #define svn_error_create \
00104   (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
00105 
00106 /** Create an error structure with the given @a apr_err and @a child,
00107  * with a printf-style error message produced by passing @a fmt, using
00108  * apr_psprintf().
00109  */
00110 svn_error_t *svn_error_createf(apr_status_t apr_err,
00111                                svn_error_t *child,
00112                                const char *fmt,
00113                                ...)
00114   __attribute__ ((format(printf, 3, 4)));
00115 
00116 /** Wrapper macro to collect file and line information */
00117 #define svn_error_createf \
00118   (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
00119 
00120 /** Wrap a @a status from an APR function.  If @a fmt is NULL, this is
00121  * equivalent to svn_error_create(status,NULL,NULL).  Otherwise,
00122  * the error message is constructed by formatting @a fmt and the
00123  * following arguments according to apr_psprintf(), and then
00124  * appending ": " and the error message corresponding to @a status.
00125  * (If UTF-8 translation of the APR error message fails, the ": " and
00126  * APR error are not appended to the error message.)
00127  */
00128 svn_error_t *svn_error_wrap_apr(apr_status_t status, const char *fmt, ...)
00129        __attribute__((format(printf, 2, 3)));
00130 
00131 /** Wrapper macro to collect file and line information */
00132 #define svn_error_wrap_apr \
00133   (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
00134 
00135 /** A quick n' easy way to create a wrapped exception with your own
00136  * message, before throwing it up the stack.  (It uses all of the
00137  * @a child's fields.)
00138  */
00139 svn_error_t *svn_error_quick_wrap(svn_error_t *child, const char *new_msg);
00140 
00141 /** Wrapper macro to collect file and line information */
00142 #define svn_error_quick_wrap \
00143   (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
00144 
00145 /** Add @a new_err to the end of @a chain's chain of errors.  The @a new_err
00146  * chain will be copied into @a chain's pool and destroyed, so @a new_err
00147  * itself becomes invalid after this function.
00148  */
00149 void svn_error_compose(svn_error_t *chain, svn_error_t *new_err);
00150 
00151 /** Return the root cause of @a err by finding the last error in its
00152  * chain (e.g. it or its children).  @a err may be @c SVN_NO_ERROR, in
00153  * which case @c SVN_NO_ERROR is returned.
00154  *
00155  * @since New in 1.5.
00156  */
00157 svn_error_t *svn_error_root_cause(svn_error_t *err);
00158 
00159 /** Create a new error that is a deep copy of @a err and return it.
00160  *
00161  * @since New in 1.2.
00162  */
00163 svn_error_t *svn_error_dup(svn_error_t *err);
00164 
00165 /** Free the memory used by @a error, as well as all ancestors and
00166  * descendants of @a error.
00167  *
00168  * Unlike other Subversion objects, errors are managed explicitly; you
00169  * MUST clear an error if you are ignoring it, or you are leaking memory.
00170  * For convenience, @a error may be @c NULL, in which case this function does
00171  * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
00172  * ignore errors.
00173  */
00174 void svn_error_clear(svn_error_t *error);
00175 
00176 
00177 /**
00178  * Very basic default error handler: print out error stack @a error to the
00179  * stdio stream @a stream, with each error prefixed by @a prefix, and quit
00180  * iff the @a fatal flag is set.  Allocations are performed in the @a error's
00181  * pool.
00182  *
00183  * If you're not sure what prefix to pass, just pass "svn: ".  That's
00184  * what code that used to call svn_handle_error() and now calls
00185  * svn_handle_error2() does.
00186  *
00187  * @since New in 1.2.
00188  */
00189 void svn_handle_error2(svn_error_t *error,
00190                        FILE *stream,
00191                        svn_boolean_t fatal,
00192                        const char *prefix);
00193 
00194 /** Like svn_handle_error2() but with @c prefix set to "svn: "
00195  *
00196  * @deprecated Provided for backward compatibility with the 1.1 API.
00197  */
00198 void svn_handle_error(svn_error_t *error,
00199                       FILE *stream,
00200                       svn_boolean_t fatal);
00201 
00202 /**
00203  * Very basic default warning handler: print out the error @a error to the
00204  * stdio stream @a stream, prefixed by @a prefix.  Allocations are
00205  * performed in the error's pool.
00206  *
00207  * @since New in 1.2.
00208  */
00209 void svn_handle_warning2(FILE *stream, svn_error_t *error, const char *prefix);
00210 
00211 /** Like svn_handle_warning2() but with @c prefix set to "svn: "
00212  */
00213 void svn_handle_warning(FILE *stream, svn_error_t *error);
00214 
00215 
00216 /** A statement macro for checking error values.
00217  *
00218  * Evaluate @a expr.  If it yields an error, return that error from the
00219  * current function.  Otherwise, continue.
00220  *
00221  * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
00222  * but it makes this macro syntactically equivalent to the expression
00223  * statement it resembles.  Without it, statements like
00224  *
00225  * @code
00226  *   if (a)
00227  *     SVN_ERR (some operation);
00228  *   else
00229  *     foo;
00230  * @endcode
00231  *
00232  * would not mean what they appear to.
00233  */
00234 #define SVN_ERR(expr)                           \
00235   do {                                          \
00236     svn_error_t *svn_err__temp = (expr);        \
00237     if (svn_err__temp)                          \
00238       return svn_err__temp;                     \
00239   } while (0)
00240 
00241 
00242 /** A statement macro, very similar to @c SVN_ERR.
00243  *
00244  * This macro will wrap the error with the specified text before
00245  * returning the error.
00246  */
00247 #define SVN_ERR_W(expr, wrap_msg)                           \
00248   do {                                                      \
00249     svn_error_t *svn_err__temp = (expr);                    \
00250     if (svn_err__temp)                                      \
00251       return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
00252   } while (0)
00253 
00254 
00255 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
00256  *
00257  * Evaluate @a expr. If it yields an error, handle that error and
00258  * return @c EXIT_FAILURE.
00259  */
00260 #define SVN_INT_ERR(expr)                                        \
00261   do {                                                           \
00262     svn_error_t *svn_err__temp = (expr);                         \
00263     if (svn_err__temp) {                                         \
00264       svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: ");  \
00265       svn_error_clear(svn_err__temp);                            \
00266       return EXIT_FAILURE; }                                     \
00267   } while (0)
00268 
00269 /** @} */
00270 
00271 /**
00272  * Return TRUE if @a err is an error specifically related to locking a
00273  * path in the repository, FALSE otherwise.
00274  *
00275  * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
00276  * that can be thrown when attempting to lock an item.
00277  *
00278  * @since New in 1.2.
00279  */
00280 #define SVN_ERR_IS_LOCK_ERROR(err)                          \
00281   (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED ||        \
00282    err->apr_err == SVN_ERR_FS_OUT_OF_DATE)                  \
00283 
00284 /**
00285  * Return TRUE if @a err is an error specifically related to unlocking
00286  * a path in the repository, FALSE otherwise.
00287  *
00288  * @since New in 1.2.
00289  */
00290 #define SVN_ERR_IS_UNLOCK_ERROR(err)                        \
00291   (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED ||            \
00292    err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN ||             \
00293    err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH ||        \
00294    err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK ||               \
00295    err->apr_err == SVN_ERR_RA_NOT_LOCKED ||                 \
00296    err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
00297 
00298 
00299 #ifdef __cplusplus
00300 }
00301 #endif /* __cplusplus */
00302 
00303 #endif /* SVN_ERROR_H */

Generated on Sun Mar 1 17:18:33 2009 for Subversion by  doxygen 1.4.7