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 */