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 __attribute__((format(printf, 2, 3))); 00117 00118 /** Wrapper macro to collect file and line information */ 00119 #define svn_error_wrap_apr \ 00120 (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) 00121 00122 /** A quick n' easy way to create a wrappered exception with your own 00123 * message, before throwing it up the stack. (It uses all of the 00124 * child's fields.) 00125 */ 00126 svn_error_t *svn_error_quick_wrap (svn_error_t *child, const char *new_msg); 00127 00128 /** Wrapper macro to collect file and line information */ 00129 #define svn_error_quick_wrap \ 00130 (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) 00131 00132 /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err 00133 * chain will be copied into @a chain's pool and destroyed, so @a new_err 00134 * itself becomes invalid after this function. 00135 */ 00136 void svn_error_compose (svn_error_t *chain, svn_error_t *new_err); 00137 00138 /** @since New in 1.2. 00139 * 00140 * Create a new error that is a deep copy of err and return it. */ 00141 svn_error_t *svn_error_dup (svn_error_t *err); 00142 00143 /** Free the memory used by @a error, as well as all ancestors and 00144 * descendants of @a error. 00145 * 00146 * Unlike other Subversion objects, errors are managed explicitly; you 00147 * MUST clear an error if you are ignoring it, or you are leaking memory. 00148 * For convenience, @a error may be @c NULL, in which case this function does 00149 * nothing; thus, @c svn_error_clear(svn_foo(...)) works as an idiom to 00150 * ignore errors. 00151 */ 00152 void svn_error_clear (svn_error_t *error); 00153 00154 00155 /** @since New in 1.2 00156 * 00157 * Very basic default error handler: print out error stack @a error to the 00158 * stdio stream @a stream, with each error prefixed by @a prefix, and quit 00159 * iff the @a fatal flag is set. Allocations are performed in the error's 00160 * pool. 00161 */ 00162 void svn_handle_error2 (svn_error_t *error, 00163 FILE *stream, 00164 svn_boolean_t fatal, 00165 const char *prefix); 00166 00167 /** Like @c svn_handle_error2 but with @c prefix set to "svn: " 00168 */ 00169 void svn_handle_error (svn_error_t *error, 00170 FILE *stream, 00171 svn_boolean_t fatal); 00172 00173 /** @since New in 1.2 00174 * 00175 * Very basic default warning handler: print out the error @a error to the 00176 * stdio stream @a stream, prefixed by @a prefix. Allocations are 00177 * performed in the error's pool. 00178 */ 00179 void svn_handle_warning2 (FILE *stream, svn_error_t *error, const char *prefix); 00180 00181 /** Like @c svn_handle_warning2 but with @c prefix set to "svn: " 00182 */ 00183 void svn_handle_warning (FILE *stream, svn_error_t *error); 00184 00185 00186 /** A statement macro for checking error return values. 00187 * 00188 * Evaluate @a expr. If it yields an error, return that error from the 00189 * current function. Otherwise, continue. 00190 * 00191 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 00192 * but it makes this macro syntactically equivalent to the expression 00193 * statement it resembles. Without it, statements like 00194 * 00195 * <tt> 00196 * if (a) 00197 * SVN_ERR (some operation); 00198 * else 00199 * foo; 00200 * </tt> 00201 * 00202 * would not mean what they appear to. 00203 */ 00204 #define SVN_ERR(expr) \ 00205 do { \ 00206 svn_error_t *svn_err__temp = (expr); \ 00207 if (svn_err__temp) \ 00208 return svn_err__temp; \ 00209 } while (0) 00210 00211 00212 /** A statement macro, very similar to @c SVN_ERR. 00213 * 00214 * This macro will wrap the error with the specified text before 00215 * returning the error. 00216 */ 00217 #define SVN_ERR_W(expr, wrap_msg) \ 00218 do { \ 00219 svn_error_t *svn_err__temp = (expr); \ 00220 if (svn_err__temp) \ 00221 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ 00222 } while (0) 00223 00224 00225 /** A statement macro, similar to @c SVN_ERR, but returns an integer. 00226 * 00227 * Evaluate @a expr. If it yields an error, handle that error and 00228 * return @c EXIT_FAILURE. 00229 */ 00230 #define SVN_INT_ERR(expr) \ 00231 do { \ 00232 svn_error_t *svn_err__temp = (expr); \ 00233 if (svn_err__temp) { \ 00234 svn_handle_error (svn_err__temp, stderr, FALSE); \ 00235 svn_error_clear (svn_err__temp); \ 00236 return EXIT_FAILURE; } \ 00237 } while (0) 00238 00239 /** @} */ 00240 00241 /** 00242 * @since New in 1.2. 00243 * 00244 * Return TRUE if @a err is an error specifically related to locking a 00245 * path in the repository, FALSE otherwise. 00246 * 00247 * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error 00248 * that can be thrown when attempting to lock an item. 00249 */ 00250 #define SVN_ERR_IS_LOCK_ERROR(err) \ 00251 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \ 00252 err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \ 00253 00254 /** 00255 * @since New in 1.2. 00256 * 00257 * Return TRUE if @a err is an error specifically related to unlocking 00258 * a path in the repository, FALSE otherwise. */ 00259 #define SVN_ERR_IS_UNLOCK_ERROR(err) \ 00260 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \ 00261 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 00262 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \ 00263 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \ 00264 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \ 00265 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED) 00266 00267 00268 #ifdef __cplusplus 00269 } 00270 #endif /* __cplusplus */ 00271 00272 #endif /* SVN_ERROR_H */