Subversion
svn_error.h
Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004, 2008 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>        /* for apr_size_t */
00029 #include <apr_errno.h>  /* APR's error system */
00030 #include <apr_pools.h>  /* for apr_pool_t */
00031 
00032 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00033 #define APR_WANT_STDIO
00034 #endif
00035 #include <apr_want.h>   /* for FILE* */
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
00052 svn_error__locate(const char *file,
00053                   long line);
00054 
00055 
00056 /** Put an English description of @a statcode into @a buf and return @a buf,
00057  * NULL-terminated. @a statcode is either an svn error or apr error.
00058  */
00059 char *
00060 svn_strerror(apr_status_t statcode,
00061              char *buf,
00062              apr_size_t bufsize);
00063 
00064 
00065 /** If @a err has a custom error message, return that, otherwise
00066  * store the generic error string associated with @a err->apr_err into
00067  * @a buf (terminating with NULL) and return @a buf.
00068  *
00069  * @since New in 1.4.
00070  *
00071  * @note @a buf and @a bufsize are provided in the interface so that
00072  * this function is thread-safe and yet does no allocation.
00073  */
00074 const char *svn_err_best_message(svn_error_t *err,
00075                                  char *buf,
00076                                  apr_size_t bufsize);
00077 
00078 
00079 
00080 /** SVN error creation and destruction.
00081  *
00082  * @defgroup svn_error_error_creation_destroy Error creation and destruction
00083  * @{
00084  */
00085 
00086 /** Create a nested exception structure.
00087  *
00088  * Input:  an APR or SVN custom error code,
00089  *         a "child" error to wrap,
00090  *         a specific message
00091  *
00092  * Returns:  a new error structure (containing the old one).
00093  *
00094  * @note Errors are always allocated in a subpool of the global pool,
00095  *        since an error's lifetime is generally not related to the
00096  *        lifetime of any convenient pool.  Errors must be freed
00097  *        with svn_error_clear().  The specific message should be @c NULL
00098  *        if there is nothing to add to the general message associated
00099  *        with the error code.
00100  *
00101  *        If creating the "bottommost" error in a chain, pass @c NULL for
00102  *        the child argument.
00103  */
00104 svn_error_t *
00105 svn_error_create(apr_status_t apr_err,
00106                  svn_error_t *child,
00107                  const char *message);
00108 
00109 /** Wrapper macro to collect file and line information */
00110 #define svn_error_create \
00111   (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
00112 
00113 /** Create an error structure with the given @a apr_err and @a child,
00114  * with a printf-style error message produced by passing @a fmt, using
00115  * apr_psprintf().
00116  */
00117 svn_error_t *
00118 svn_error_createf(apr_status_t apr_err,
00119                   svn_error_t *child,
00120                   const char *fmt,
00121                   ...)
00122   __attribute__ ((format(printf, 3, 4)));
00123 
00124 /** Wrapper macro to collect file and line information */
00125 #define svn_error_createf \
00126   (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
00127 
00128 /** Wrap a @a status from an APR function.  If @a fmt is NULL, this is
00129  * equivalent to svn_error_create(status,NULL,NULL).  Otherwise,
00130  * the error message is constructed by formatting @a fmt and the
00131  * following arguments according to apr_psprintf(), and then
00132  * appending ": " and the error message corresponding to @a status.
00133  * (If UTF-8 translation of the APR error message fails, the ": " and
00134  * APR error are not appended to the error message.)
00135  */
00136 svn_error_t *
00137 svn_error_wrap_apr(apr_status_t status,
00138                    const char *fmt,
00139                    ...)
00140        __attribute__((format(printf, 2, 3)));
00141 
00142 /** Wrapper macro to collect file and line information */
00143 #define svn_error_wrap_apr \
00144   (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
00145 
00146 /** A quick n' easy way to create a wrapped exception with your own
00147  * message, before throwing it up the stack.  (It uses all of the
00148  * @a child's fields.)
00149  */
00150 svn_error_t *
00151 svn_error_quick_wrap(svn_error_t *child,
00152                      const char *new_msg);
00153 
00154 /** Wrapper macro to collect file and line information */
00155 #define svn_error_quick_wrap \
00156   (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
00157 
00158 /** Compose two errors, returning the composition as a brand new error
00159  * and consuming the original errors.  Either or both of @a err1 and
00160  * @a err2 may be @c SVN_NO_ERROR.  If both are not @c SVN_NO_ERROR,
00161  * @a err2 will follow @a err1 in the chain of the returned error.
00162  *
00163  * @since New in 1.6.
00164  */
00165 svn_error_t *
00166 svn_error_compose_create(svn_error_t *err1,
00167                          svn_error_t *err2);
00168 
00169 /** Add @a new_err to the end of @a chain's chain of errors.  The @a new_err
00170  * chain will be copied into @a chain's pool and destroyed, so @a new_err
00171  * itself becomes invalid after this function.
00172  */
00173 void
00174 svn_error_compose(svn_error_t *chain,
00175                   svn_error_t *new_err);
00176 
00177 /** Return the root cause of @a err by finding the last error in its
00178  * chain (e.g. it or its children).  @a err may be @c SVN_NO_ERROR, in
00179  * which case @c SVN_NO_ERROR is returned.
00180  *
00181  * @since New in 1.5.
00182  */
00183 svn_error_t *
00184 svn_error_root_cause(svn_error_t *err);
00185 
00186 /** Create a new error that is a deep copy of @a err and return it.
00187  *
00188  * @since New in 1.2.
00189  */
00190 svn_error_t *
00191 svn_error_dup(svn_error_t *err);
00192 
00193 /** Free the memory used by @a error, as well as all ancestors and
00194  * descendants of @a error.
00195  *
00196  * Unlike other Subversion objects, errors are managed explicitly; you
00197  * MUST clear an error if you are ignoring it, or you are leaking memory.
00198  * For convenience, @a error may be @c NULL, in which case this function does
00199  * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
00200  * ignore errors.
00201  */
00202 void
00203 svn_error_clear(svn_error_t *error);
00204 
00205 
00206 /**
00207  * Very basic default error handler: print out error stack @a error to the
00208  * stdio stream @a stream, with each error prefixed by @a prefix; quit and
00209  * clear @a error iff the @a fatal flag is set.  Allocations are performed
00210  * in the @a error's pool.
00211  *
00212  * If you're not sure what prefix to pass, just pass "svn: ".  That's
00213  * what code that used to call svn_handle_error() and now calls
00214  * svn_handle_error2() does.
00215  *
00216  * @since New in 1.2.
00217  */
00218 void
00219 svn_handle_error2(svn_error_t *error,
00220                   FILE *stream,
00221                   svn_boolean_t fatal,
00222                   const char *prefix);
00223 
00224 /** Like svn_handle_error2() but with @c prefix set to "svn: "
00225  *
00226  * @deprecated Provided for backward compatibility with the 1.1 API.
00227  */
00228 SVN_DEPRECATED
00229 void
00230 svn_handle_error(svn_error_t *error,
00231                  FILE *stream,
00232                  svn_boolean_t fatal);
00233 
00234 /**
00235  * Very basic default warning handler: print out the error @a error to the
00236  * stdio stream @a stream, prefixed by @a prefix.  Allocations are
00237  * performed in the error's pool.
00238  *
00239  * @since New in 1.2.
00240  */
00241 void
00242 svn_handle_warning2(FILE *stream,
00243                     svn_error_t *error,
00244                     const char *prefix);
00245 
00246 /** Like svn_handle_warning2() but with @c prefix set to "svn: "
00247  *
00248  * @deprecated Provided for backward compatibility with the 1.1 API.
00249  */
00250 SVN_DEPRECATED
00251 void
00252 svn_handle_warning(FILE *stream,
00253                    svn_error_t *error);
00254 
00255 
00256 /** A statement macro for checking error values.
00257  *
00258  * Evaluate @a expr.  If it yields an error, return that error from the
00259  * current function.  Otherwise, continue.
00260  *
00261  * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
00262  * but it makes this macro syntactically equivalent to the expression
00263  * statement it resembles.  Without it, statements like
00264  *
00265  * @code
00266  *   if (a)
00267  *     SVN_ERR (some operation);
00268  *   else
00269  *     foo;
00270  * @endcode
00271  *
00272  * would not mean what they appear to.
00273  */
00274 #define SVN_ERR(expr)                           \
00275   do {                                          \
00276     svn_error_t *svn_err__temp = (expr);        \
00277     if (svn_err__temp)                          \
00278       return svn_err__temp;                     \
00279   } while (0)
00280 
00281 /**
00282  * A macro for wrapping an error in a source-location trace message.
00283  *
00284  * This macro can be used when directly returning an already created
00285  * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure
00286  * that the call stack is recorded correctly.
00287  *
00288  * @since New in 1.7.
00289  */
00290 #ifdef SVN_ERR__TRACING
00291 svn_error_t *
00292 svn_error__trace(const char *file, long line, svn_error_t *err);
00293 
00294 #define svn_error_trace(expr)  svn_error__trace(__FILE__, __LINE__, (expr))
00295 #else
00296 #define svn_error_trace(expr)  (expr)
00297 #endif
00298 
00299 /** A statement macro, very similar to @c SVN_ERR.
00300  *
00301  * This macro will wrap the error with the specified text before
00302  * returning the error.
00303  */
00304 #define SVN_ERR_W(expr, wrap_msg)                           \
00305   do {                                                      \
00306     svn_error_t *svn_err__temp = (expr);                    \
00307     if (svn_err__temp)                                      \
00308       return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
00309   } while (0)
00310 
00311 
00312 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
00313  *
00314  * Evaluate @a expr. If it yields an error, handle that error and
00315  * return @c EXIT_FAILURE.
00316  */
00317 #define SVN_INT_ERR(expr)                                        \
00318   do {                                                           \
00319     svn_error_t *svn_err__temp = (expr);                         \
00320     if (svn_err__temp) {                                         \
00321       svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: ");  \
00322       svn_error_clear(svn_err__temp);                            \
00323       return EXIT_FAILURE; }                                     \
00324   } while (0)
00325 
00326 /** @} */
00327 
00328 /**
00329  * Return TRUE if @a err is an error specifically related to locking a
00330  * path in the repository, FALSE otherwise.
00331  *
00332  * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
00333  * that can be thrown when attempting to lock an item.
00334  *
00335  * @since New in 1.2.
00336  */
00337 #define SVN_ERR_IS_LOCK_ERROR(err)                          \
00338   (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED ||        \
00339    err->apr_err == SVN_ERR_FS_OUT_OF_DATE)                  \
00340 
00341 /**
00342  * Return TRUE if @a err is an error specifically related to unlocking
00343  * a path in the repository, FALSE otherwise.
00344  *
00345  * @since New in 1.2.
00346  */
00347 #define SVN_ERR_IS_UNLOCK_ERROR(err)                        \
00348   (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED ||            \
00349    err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN ||             \
00350    err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH ||        \
00351    err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK ||               \
00352    err->apr_err == SVN_ERR_RA_NOT_LOCKED ||                 \
00353    err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
00354 
00355 /** Report that an internal malfunction has occurred, and possibly terminate
00356  * the program.
00357  *
00358  * Act as determined by the current "malfunction handler" which may have
00359  * been specified by a call to svn_error_set_malfunction_handler() or else
00360  * is the default handler as specified in that function's documentation. If
00361  * the malfunction handler returns, then cause the function using this macro
00362  * to return the error object that it generated.
00363  *
00364  * @note The intended use of this macro is where execution reaches a point
00365  * that cannot possibly be reached unless there is a bug in the program.
00366  *
00367  * @since New in 1.6.
00368  */
00369 #define SVN_ERR_MALFUNCTION()                                      \
00370   do {                                                             \
00371     return svn_error__malfunction(TRUE, __FILE__, __LINE__, NULL); \
00372   } while (0)
00373 
00374 /** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning
00375  * an error to the calling function.
00376  *
00377  * If possible you should use SVN_ERR_MALFUNCTION() instead.
00378  *
00379  * @since New in 1.6.
00380  */
00381 #define SVN_ERR_MALFUNCTION_NO_RETURN()                      \
00382   do {                                                       \
00383     svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \
00384     abort();                                                 \
00385   } while (1)
00386 
00387 /** Check that a condition is true: if not, report an error and possibly
00388  * terminate the program.
00389  *
00390  * If the Boolean expression @a expr is true, do nothing. Otherwise,
00391  * act as determined by the current "malfunction handler" which may have
00392  * been specified by a call to svn_error_set_malfunction_handler() or else
00393  * is the default handler as specified in that function's documentation. If
00394  * the malfunction handler returns, then cause the function using this macro
00395  * to return the error object that it generated.
00396  *
00397  * @note The intended use of this macro is to check a condition that cannot
00398  * possibly be false unless there is a bug in the program.
00399  *
00400  * @note The condition to be checked should not be computationally expensive
00401  * if it is reached often, as, unlike traditional "assert" statements, the
00402  * evaluation of this expression is not compiled out in release-mode builds.
00403  *
00404  * @since New in 1.6.
00405  */
00406 #define SVN_ERR_ASSERT(expr)                                            \
00407   do {                                                                  \
00408     if (!(expr))                                                        \
00409       SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \
00410   } while (0)
00411 
00412 /** Similar to SVN_ERR_ASSERT(), but without the option of returning
00413  * an error to the calling function.
00414  *
00415  * If possible you should use SVN_ERR_ASSERT() instead.
00416  *
00417  * @since New in 1.6.
00418  */
00419 #define SVN_ERR_ASSERT_NO_RETURN(expr)                          \
00420   do {                                                          \
00421     if (!(expr)) {                                              \
00422       svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \
00423       abort();                                                  \
00424     }                                                           \
00425   } while (0)
00426 
00427 
00428 /** A helper function for the macros that report malfunctions. Handle a
00429  * malfunction by calling the current "malfunction handler" which may have
00430  * been specified by a call to svn_error_set_malfunction_handler() or else
00431  * is the default handler as specified in that function's documentation.
00432  *
00433  * Pass all of the parameters to the handler. The error occurred in the
00434  * source file @a file at line @a line, and was an assertion failure of the
00435  * expression @a expr, or, if @a expr is null, an unconditional error.
00436  *
00437  * If @a can_return is true, the handler can return an error object
00438  * that is returned by the caller. If @a can_return is false the
00439  * method should never return. (The caller will call abort())
00440  *
00441  * @since New in 1.6.
00442  */
00443 svn_error_t *
00444 svn_error__malfunction(svn_boolean_t can_return,
00445                        const char *file,
00446                        int line,
00447                        const char *expr);
00448 
00449 /** A type of function that handles an assertion failure or other internal
00450  * malfunction detected within the Subversion libraries.
00451  *
00452  * The error occurred in the source file @a file at line @a line, and was an
00453  * assertion failure of the expression @a expr, or, if @a expr is null, an
00454  * unconditional error.
00455  *
00456  * If @a can_return is false a function of this type must never return.
00457  *
00458  * If @a can_return is true a function of this type must do one of:
00459  *   - Return an error object describing the error, using an error code in
00460  *     the category SVN_ERR_MALFUNC_CATEGORY_START.
00461  *   - Never return.
00462  *
00463  * The function may alter its behaviour according to compile-time
00464  * and run-time and even interactive conditions.
00465  *
00466  * @since New in 1.6.
00467  */
00468 typedef svn_error_t *(*svn_error_malfunction_handler_t)
00469   (svn_boolean_t can_return, const char *file, int line, const char *expr);
00470 
00471 /** Cause subsequent malfunctions to be handled by @a func.
00472  * Return the handler that was previously in effect.
00473  *
00474  * @a func may not be null.
00475  *
00476  * @note The default handler is svn_error_abort_on_malfunction().
00477  *
00478  * @note This function must be called in a single-threaded context.
00479  *
00480  * @since New in 1.6.
00481  */
00482 svn_error_malfunction_handler_t
00483 svn_error_set_malfunction_handler(svn_error_malfunction_handler_t func);
00484 
00485 /** Handle a malfunction by returning an error object that describes it.
00486  *
00487  * When @a can_return is false, abort()
00488  *
00489  * This function implements @c svn_error_malfunction_handler_t.
00490  *
00491  * @since New in 1.6.
00492  */
00493 svn_error_t *
00494 svn_error_raise_on_malfunction(svn_boolean_t can_return,
00495                                const char *file,
00496                                int line,
00497                                const char *expr);
00498 
00499 /** Handle a malfunction by printing a message to stderr and aborting.
00500  *
00501  * This function implements @c svn_error_malfunction_handler_t.
00502  *
00503  * @since New in 1.6.
00504  */
00505 svn_error_t *
00506 svn_error_abort_on_malfunction(svn_boolean_t can_return,
00507                                const char *file,
00508                                int line,
00509                                const char *expr);
00510 
00511 
00512 #ifdef __cplusplus
00513 }
00514 #endif /* __cplusplus */
00515 
00516 #endif /* SVN_ERROR_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines