Main Page   Modules   Data Structures   File List   Data Fields  

svn_error.h

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 
00061 /** SVN error creation and destruction. 
00062  *
00063  * @defgroup svn_error_error_creation_destroy error creation and destruction
00064  * @{
00065  */
00066 
00067 /** Create a nested exception structure.
00068  *
00069  * Input:  an APR or SVN custom error code,
00070  *         a "child" error to wrap,
00071  *         a specific message
00072  *
00073  * Returns:  a new error structure (containing the old one).
00074  *
00075  * Notes: Errors are always allocated in a subpool of the global pool,
00076  *        since an error's lifetime is generally not related to the
00077  *        lifetime of any convenient pool.  Errors must be freed
00078  *        with @c svn_error_clear().  The specific message should be NULL
00079  *        if there is nothing to add to the general message associated
00080  *        with the error code.
00081  *
00082  *        If creating the "bottommost" error in a chain, pass @c NULL for
00083  *        the child argument.
00084  */
00085 svn_error_t *svn_error_create (apr_status_t apr_err,
00086                                svn_error_t *child,
00087                                const char *message);
00088 
00089 /** Wrapper macro to collect file and line information */
00090 #define svn_error_create \
00091   (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
00092 
00093 /** Create an error structure with the given @a apr_err and @a child,
00094  * with a printf-style error message produced by passing @a fmt, using
00095  * @c apr_psprintf.
00096  */
00097 svn_error_t *svn_error_createf (apr_status_t apr_err,
00098                                 svn_error_t *child,
00099                                 const char *fmt, 
00100                                 ...)
00101        __attribute__ ((format (printf, 3, 4)));
00102 
00103 /** Wrapper macro to collect file and line information */
00104 #define svn_error_createf \
00105   (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
00106 
00107 /** Wrap a status from an APR function.  If @a fmt is NULL, this is
00108  * equivalent to @c svn_error_create(status, NULL, NULL).  Otherwise,
00109  * the error message is constructed by formatting @a fmt and the
00110  * following arguments according to @c apr_psprintf, and then
00111  * appending ": " and the error message corresponding to @a status.
00112  * (If UTF-8 translation of the APR error message fails, the ": " and
00113  * APR error are not appended to the error message.)
00114  */
00115 svn_error_t *svn_error_wrap_apr (apr_status_t status, const char *fmt, ...);
00116 
00117 /** Wrapper macro to collect file and line information */
00118 #define svn_error_wrap_apr \
00119   (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
00120 
00121 /** A quick n' easy way to create a wrappered exception with your own
00122  * message, before throwing it up the stack.  (It uses all of the
00123  * child's fields.)
00124  */
00125 svn_error_t *svn_error_quick_wrap (svn_error_t *child, const char *new_msg);
00126 
00127 /** Wrapper macro to collect file and line information */
00128 #define svn_error_quick_wrap \
00129   (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
00130 
00131 /** Add @a new_err to the end of @a chain's chain of errors.  The @a new_err 
00132  * chain will be copied into @a chain's pool and destroyed, so @a new_err 
00133  * itself becomes invalid after this function.
00134  */
00135 void svn_error_compose (svn_error_t *chain, svn_error_t *new_err);
00136 
00137 
00138 /** Free the memory used by @a error, as well as all ancestors and
00139  * descendants of @a error. 
00140  *
00141  * Unlike other Subversion objects, errors are managed explicitly; you 
00142  * MUST clear an error if you are ignoring it, or you are leaking memory. 
00143  * For convenience, @a error may be @c NULL, in which case this function does 
00144  * nothing; thus, @c svn_error_clear(svn_foo(...)) works as an idiom to 
00145  * ignore errors.
00146  */
00147 void svn_error_clear (svn_error_t *error);
00148 
00149 
00150 /** Very basic default error handler: print out error stack, and quit
00151  * iff the @a fatal flag is set.
00152  */
00153 void svn_handle_error (svn_error_t *error,
00154                        FILE *stream,
00155                        svn_boolean_t fatal);
00156 
00157 /** Basic, default warning handler.
00158  *
00159  * Just prints @a error to the stdio stream given in @a stream. Allocations
00160  * are performed in the error's pool.
00161  */
00162 void svn_handle_warning (FILE *stream, svn_error_t *error);
00163 
00164 
00165 /** A statement macro for checking error return values.
00166  *
00167  * Evaluate @a expr.  If it yields an error, return that error from the
00168  * current function.  Otherwise, continue.
00169  *
00170  * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 
00171  * but it makes this macro syntactically equivalent to the expression
00172  * statement it resembles.  Without it, statements like
00173  *
00174  * <tt>
00175  *   if (a)
00176  *     SVN_ERR (some operation);
00177  *   else
00178  *     foo;
00179  * </tt>
00180  *
00181  * would not mean what they appear to.
00182  */
00183 #define SVN_ERR(expr)                           \
00184   do {                                          \
00185     svn_error_t *svn_err__temp = (expr);        \
00186     if (svn_err__temp)                          \
00187       return svn_err__temp;                     \
00188   } while (0)
00189 
00190 
00191 /** A statement macro, very similar to @c SVN_ERR.
00192  *
00193  * This macro will wrap the error with the specified text before 
00194  * returning the error.
00195  */
00196 #define SVN_ERR_W(expr, wrap_msg)                           \
00197   do {                                                      \
00198     svn_error_t *svn_err__temp = (expr);                    \
00199     if (svn_err__temp)                                      \
00200       return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
00201   } while (0)
00202 
00203 
00204 /** A statement macro, similar to @c SVN_ERR, but returns an integer.
00205  *
00206  * Evaluate @a expr. If it yields an error, handle that error and
00207  * return @c EXIT_FAILURE.
00208  */
00209 #define SVN_INT_ERR(expr)                                   \
00210   do {                                                      \
00211     svn_error_t *svn_err__temp = (expr);                    \
00212     if (svn_err__temp) {                                    \
00213       svn_handle_error (svn_err__temp, stderr, FALSE);      \
00214       svn_error_clear (svn_err__temp);                      \
00215       return EXIT_FAILURE; }                                \
00216   } while (0)
00217 
00218 /** @} */
00219 
00220 #ifdef __cplusplus
00221 }
00222 #endif /* __cplusplus */
00223 
00224 #endif /* SVN_ERROR_H */

Generated on Tue Oct 19 09:49:47 2004 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002