subversion/include/svn_error.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  * @endcopyright
  17  *
  18  * @file svn_error.h
  19  * @brief Common exception handling for Subversion.
  20  */
  21
  22
  23 \f
  24
  25 #ifndef SVN_ERROR_H
  26 #define SVN_ERROR_H
  27
  28 #include <apr.h>
  29 #include <apr_errno.h>     /* APR's error system */
  30 #include <apr_pools.h>
  31
  32 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  33 #define APR_WANT_STDIO
  34 #endif
  35 #include <apr_want.h>
  36
  37 #include "svn_types.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif /* __cplusplus */
  42
  43 /** the best kind of (@c svn_error_t *) ! */
  44 #define SVN_NO_ERROR   0
  45
  46 /* The actual error codes are kept in a separate file; see comments
  47    there for the reasons why. */
  48 #include "svn_error_codes.h"
  49
  50 /** Set the error location for debug mode. */
  51 void svn_error__locate(const char *file, long line);
  52
  53
  54 /** Put an English description of @a statcode into @a buf and return @a buf,
  55  * NULL-terminated. @a statcode is either an svn error or apr error.
  56  */
  57 char *svn_strerror(apr_status_t statcode, char *buf, apr_size_t bufsize);
  58
  59
  60 /** If @a err has a custom error message, return that, otherwise
  61  * store the generic error string associated with @a err->apr_err into
  62  * @a buf (terminating with NULL) and return @a buf.
  63  *
  64  * @since New in 1.4.
  65  *
  66  * @note @a buf and @a bufsize are provided in the interface so that
  67  * this function is thread-safe and yet does no allocation.
  68  */
  69 const char *svn_err_best_message(svn_error_t *err,
  70                                  char *buf, apr_size_t bufsize);
  71
  72
  73 \f
  74 /** SVN error creation and destruction.
  75  *
  76  * @defgroup svn_error_error_creation_destroy Error creation and destruction
  77  * @{
  78  */
  79
  80 /** Create a nested exception structure.
  81  *
  82  * Input:  an APR or SVN custom error code,
  83  *         a "child" error to wrap,
  84  *         a specific message
  85  *
  86  * Returns:  a new error structure (containing the old one).
  87  *
  88  * @note Errors are always allocated in a subpool of the global pool,
  89  *        since an error's lifetime is generally not related to the
  90  *        lifetime of any convenient pool.  Errors must be freed
  91  *        with svn_error_clear().  The specific message should be @c NULL
  92  *        if there is nothing to add to the general message associated
  93  *        with the error code.
  94  *
  95  *        If creating the "bottommost" error in a chain, pass @c NULL for
  96  *        the child argument.
  97  */
  98 svn_error_t *svn_error_create(apr_status_t apr_err,
  99                               svn_error_t *child,
 100                               const char *message);
 101
 102 /** Wrapper macro to collect file and line information */
 103 #define svn_error_create \
 104   (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
 105
 106 /** Create an error structure with the given @a apr_err and @a child,
 107  * with a printf-style error message produced by passing @a fmt, using
 108  * apr_psprintf().
 109  */
 110 svn_error_t *svn_error_createf(apr_status_t apr_err,
 111                                svn_error_t *child,
 112                                const char *fmt,
 113                                ...)
 114   __attribute__ ((format(printf, 3, 4)));
 115
 116 /** Wrapper macro to collect file and line information */
 117 #define svn_error_createf \
 118   (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
 119
 120 /** Wrap a @a status from an APR function.  If @a fmt is NULL, this is
 121  * equivalent to svn_error_create(status,NULL,NULL).  Otherwise,
 122  * the error message is constructed by formatting @a fmt and the
 123  * following arguments according to apr_psprintf(), and then
 124  * appending ": " and the error message corresponding to @a status.
 125  * (If UTF-8 translation of the APR error message fails, the ": " and
 126  * APR error are not appended to the error message.)
 127  */
 128 svn_error_t *svn_error_wrap_apr(apr_status_t status, const char *fmt, ...)
 129        __attribute__((format(printf, 2, 3)));
 130
 131 /** Wrapper macro to collect file and line information */
 132 #define svn_error_wrap_apr \
 133   (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
 134
 135 /** A quick n' easy way to create a wrapped exception with your own
 136  * message, before throwing it up the stack.  (It uses all of the
 137  * @a child's fields.)
 138  */
 139 svn_error_t *svn_error_quick_wrap(svn_error_t *child, const char *new_msg);
 140
 141 /** Wrapper macro to collect file and line information */
 142 #define svn_error_quick_wrap \
 143   (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
 144
 145 /** Add @a new_err to the end of @a chain's chain of errors.  The @a new_err
 146  * chain will be copied into @a chain's pool and destroyed, so @a new_err
 147  * itself becomes invalid after this function.
 148  */
 149 void svn_error_compose(svn_error_t *chain, svn_error_t *new_err);
 150
 151 /** Return the root cause of @a err by finding the last error in its
 152  * chain (e.g. it or its children).  @a err may be @c SVN_NO_ERROR, in
 153  * which case @c SVN_NO_ERROR is returned.
 154  *
 155  * @since New in 1.5.
 156  */
 157 svn_error_t *svn_error_root_cause(svn_error_t *err);
 158
 159 /** Create a new error that is a deep copy of @a err and return it.
 160  *
 161  * @since New in 1.2.
 162  */
 163 svn_error_t *svn_error_dup(svn_error_t *err);
 164
 165 /** Free the memory used by @a error, as well as all ancestors and
 166  * descendants of @a error.
 167  *
 168  * Unlike other Subversion objects, errors are managed explicitly; you
 169  * MUST clear an error if you are ignoring it, or you are leaking memory.
 170  * For convenience, @a error may be @c NULL, in which case this function does
 171  * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
 172  * ignore errors.
 173  */
 174 void svn_error_clear(svn_error_t *error);
 175
 176
 177 /**
 178  * Very basic default error handler: print out error stack @a error to the
 179  * stdio stream @a stream, with each error prefixed by @a prefix, and quit
 180  * iff the @a fatal flag is set.  Allocations are performed in the @a error's
 181  * pool.
 182  *
 183  * If you're not sure what prefix to pass, just pass "svn: ".  That's
 184  * what code that used to call svn_handle_error() and now calls
 185  * svn_handle_error2() does.
 186  *
 187  * @since New in 1.2.
 188  */
 189 void svn_handle_error2(svn_error_t *error,
 190                        FILE *stream,
 191                        svn_boolean_t fatal,
 192                        const char *prefix);
 193
 194 /** Like svn_handle_error2() but with @c prefix set to "svn: "
 195  *
 196  * @deprecated Provided for backward compatibility with the 1.1 API.
 197  */
 198 void svn_handle_error(svn_error_t *error,
 199                       FILE *stream,
 200                       svn_boolean_t fatal);
 201
 202 /**
 203  * Very basic default warning handler: print out the error @a error to the
 204  * stdio stream @a stream, prefixed by @a prefix.  Allocations are
 205  * performed in the error's pool.
 206  *
 207  * @since New in 1.2.
 208  */
 209 void svn_handle_warning2(FILE *stream, svn_error_t *error, const char *prefix);
 210
 211 /** Like svn_handle_warning2() but with @c prefix set to "svn: "
 212  */
 213 void svn_handle_warning(FILE *stream, svn_error_t *error);
 214
 215
 216 /** A statement macro for checking error values.
 217  *
 218  * Evaluate @a expr.  If it yields an error, return that error from the
 219  * current function.  Otherwise, continue.
 220  *
 221  * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
 222  * but it makes this macro syntactically equivalent to the expression
 223  * statement it resembles.  Without it, statements like
 224  *
 225  * @code
 226  *   if (a)
 227  *     SVN_ERR (some operation);
 228  *   else
 229  *     foo;
 230  * @endcode
 231  *
 232  * would not mean what they appear to.
 233  */
 234 #define SVN_ERR(expr)                           \
 235   do {                                          \
 236     svn_error_t *svn_err__temp = (expr);        \
 237     if (svn_err__temp)                          \
 238       return svn_err__temp;                     \
 239   } while (0)
 240
 241
 242 /** A statement macro, very similar to @c SVN_ERR.
 243  *
 244  * This macro will wrap the error with the specified text before
 245  * returning the error.
 246  */
 247 #define SVN_ERR_W(expr, wrap_msg)                           \
 248   do {                                                      \
 249     svn_error_t *svn_err__temp = (expr);                    \
 250     if (svn_err__temp)                                      \
 251       return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
 252   } while (0)
 253
 254
 255 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
 256  *
 257  * Evaluate @a expr. If it yields an error, handle that error and
 258  * return @c EXIT_FAILURE.
 259  */
 260 #define SVN_INT_ERR(expr)                                        \
 261   do {                                                           \
 262     svn_error_t *svn_err__temp = (expr);                         \
 263     if (svn_err__temp) {                                         \
 264       svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: ");  \
 265       svn_error_clear(svn_err__temp);                            \
 266       return EXIT_FAILURE; }                                     \
 267   } while (0)
 268
 269 /** @} */
 270
 271 /**
 272  * Return TRUE if @a err is an error specifically related to locking a
 273  * path in the repository, FALSE otherwise.
 274  *
 275  * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
 276  * that can be thrown when attempting to lock an item.
 277  *
 278  * @since New in 1.2.
 279  */
 280 #define SVN_ERR_IS_LOCK_ERROR(err)                          \
 281   (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED ||        \
 282    err->apr_err == SVN_ERR_FS_OUT_OF_DATE)                  \
 283
 284 /**
 285  * Return TRUE if @a err is an error specifically related to unlocking
 286  * a path in the repository, FALSE otherwise.
 287  *
 288  * @since New in 1.2.
 289  */
 290 #define SVN_ERR_IS_UNLOCK_ERROR(err)                        \
 291   (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED ||            \
 292    err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN ||             \
 293    err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH ||        \
 294    err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK ||               \
 295    err->apr_err == SVN_ERR_RA_NOT_LOCKED ||                 \
 296    err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
 297
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif /* __cplusplus */
 302
 303 #endif /* SVN_ERROR_H */