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 /** If @a err has a custom error message, return that, otherwise 00061 * store the generic error string associated with @a err->apr_err into 00062 * @a buf (terminating with NULL) and return @a buf. 00063 * 00064 * @since New in 1.4. 00065 * 00066 * @note @a buf and @a bufsize are provided in the interface so that 00067 * this function is thread-safe and yet does no allocation. 00068 */ 00069 const char *svn_err_best_message(svn_error_t *err, 00070 char *buf, apr_size_t bufsize); 00071 00072 00073 00074 /** SVN error creation and destruction. 00075 * 00076 * @defgroup svn_error_error_creation_destroy Error creation and destruction 00077 * @{ 00078 */ 00079 00080 /** Create a nested exception structure. 00081 * 00082 * Input: an APR or SVN custom error code, 00083 * a "child" error to wrap, 00084 * a specific message 00085 * 00086 * Returns: a new error structure (containing the old one). 00087 * 00088 * @note Errors are always allocated in a subpool of the global pool, 00089 * since an error's lifetime is generally not related to the 00090 * lifetime of any convenient pool. Errors must be freed 00091 * with svn_error_clear(). The specific message should be @c NULL 00092 * if there is nothing to add to the general message associated 00093 * with the error code. 00094 * 00095 * If creating the "bottommost" error in a chain, pass @c NULL for 00096 * the child argument. 00097 */ 00098 svn_error_t *svn_error_create(apr_status_t apr_err, 00099 svn_error_t *child, 00100 const char *message); 00101 00102 /** Wrapper macro to collect file and line information */ 00103 #define svn_error_create \ 00104 (svn_error__locate(__FILE__,__LINE__), (svn_error_create)) 00105 00106 /** Create an error structure with the given @a apr_err and @a child, 00107 * with a printf-style error message produced by passing @a fmt, using 00108 * apr_psprintf(). 00109 */ 00110 svn_error_t *svn_error_createf(apr_status_t apr_err, 00111 svn_error_t *child, 00112 const char *fmt, 00113 ...) 00114 __attribute__ ((format(printf, 3, 4))); 00115 00116 /** Wrapper macro to collect file and line information */ 00117 #define svn_error_createf \ 00118 (svn_error__locate(__FILE__,__LINE__), (svn_error_createf)) 00119 00120 /** Wrap a @a status from an APR function. If @a fmt is NULL, this is 00121 * equivalent to svn_error_create(status,NULL,NULL). Otherwise, 00122 * the error message is constructed by formatting @a fmt and the 00123 * following arguments according to apr_psprintf(), and then 00124 * appending ": " and the error message corresponding to @a status. 00125 * (If UTF-8 translation of the APR error message fails, the ": " and 00126 * APR error are not appended to the error message.) 00127 */ 00128 svn_error_t *svn_error_wrap_apr(apr_status_t status, const char *fmt, ...) 00129 __attribute__((format(printf, 2, 3))); 00130 00131 /** Wrapper macro to collect file and line information */ 00132 #define svn_error_wrap_apr \ 00133 (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) 00134 00135 /** A quick n' easy way to create a wrapped exception with your own 00136 * message, before throwing it up the stack. (It uses all of the 00137 * @a child's fields.) 00138 */ 00139 svn_error_t *svn_error_quick_wrap(svn_error_t *child, const char *new_msg); 00140 00141 /** Wrapper macro to collect file and line information */ 00142 #define svn_error_quick_wrap \ 00143 (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) 00144 00145 /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err 00146 * chain will be copied into @a chain's pool and destroyed, so @a new_err 00147 * itself becomes invalid after this function. 00148 */ 00149 void svn_error_compose(svn_error_t *chain, svn_error_t *new_err); 00150 00151 /** Return the root cause of @a err by finding the last error in its 00152 * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in 00153 * which case @c SVN_NO_ERROR is returned. 00154 * 00155 * @since New in 1.5. 00156 */ 00157 svn_error_t *svn_error_root_cause(svn_error_t *err); 00158 00159 /** Create a new error that is a deep copy of @a err and return it. 00160 * 00161 * @since New in 1.2. 00162 */ 00163 svn_error_t *svn_error_dup(svn_error_t *err); 00164 00165 /** Free the memory used by @a error, as well as all ancestors and 00166 * descendants of @a error. 00167 * 00168 * Unlike other Subversion objects, errors are managed explicitly; you 00169 * MUST clear an error if you are ignoring it, or you are leaking memory. 00170 * For convenience, @a error may be @c NULL, in which case this function does 00171 * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to 00172 * ignore errors. 00173 */ 00174 void svn_error_clear(svn_error_t *error); 00175 00176 00177 /** 00178 * Very basic default error handler: print out error stack @a error to the 00179 * stdio stream @a stream, with each error prefixed by @a prefix, and quit 00180 * iff the @a fatal flag is set. Allocations are performed in the @a error's 00181 * pool. 00182 * 00183 * If you're not sure what prefix to pass, just pass "svn: ". That's 00184 * what code that used to call svn_handle_error() and now calls 00185 * svn_handle_error2() does. 00186 * 00187 * @since New in 1.2. 00188 */ 00189 void svn_handle_error2(svn_error_t *error, 00190 FILE *stream, 00191 svn_boolean_t fatal, 00192 const char *prefix); 00193 00194 /** Like svn_handle_error2() but with @c prefix set to "svn: " 00195 * 00196 * @deprecated Provided for backward compatibility with the 1.1 API. 00197 */ 00198 void svn_handle_error(svn_error_t *error, 00199 FILE *stream, 00200 svn_boolean_t fatal); 00201 00202 /** 00203 * Very basic default warning handler: print out the error @a error to the 00204 * stdio stream @a stream, prefixed by @a prefix. Allocations are 00205 * performed in the error's pool. 00206 * 00207 * @since New in 1.2. 00208 */ 00209 void svn_handle_warning2(FILE *stream, svn_error_t *error, const char *prefix); 00210 00211 /** Like svn_handle_warning2() but with @c prefix set to "svn: " 00212 */ 00213 void svn_handle_warning(FILE *stream, svn_error_t *error); 00214 00215 00216 /** A statement macro for checking error values. 00217 * 00218 * Evaluate @a expr. If it yields an error, return that error from the 00219 * current function. Otherwise, continue. 00220 * 00221 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 00222 * but it makes this macro syntactically equivalent to the expression 00223 * statement it resembles. Without it, statements like 00224 * 00225 * @code 00226 * if (a) 00227 * SVN_ERR (some operation); 00228 * else 00229 * foo; 00230 * @endcode 00231 * 00232 * would not mean what they appear to. 00233 */ 00234 #define SVN_ERR(expr) \ 00235 do { \ 00236 svn_error_t *svn_err__temp = (expr); \ 00237 if (svn_err__temp) \ 00238 return svn_err__temp; \ 00239 } while (0) 00240 00241 00242 /** A statement macro, very similar to @c SVN_ERR. 00243 * 00244 * This macro will wrap the error with the specified text before 00245 * returning the error. 00246 */ 00247 #define SVN_ERR_W(expr, wrap_msg) \ 00248 do { \ 00249 svn_error_t *svn_err__temp = (expr); \ 00250 if (svn_err__temp) \ 00251 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ 00252 } while (0) 00253 00254 00255 /** A statement macro, similar to @c SVN_ERR, but returns an integer. 00256 * 00257 * Evaluate @a expr. If it yields an error, handle that error and 00258 * return @c EXIT_FAILURE. 00259 */ 00260 #define SVN_INT_ERR(expr) \ 00261 do { \ 00262 svn_error_t *svn_err__temp = (expr); \ 00263 if (svn_err__temp) { \ 00264 svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \ 00265 svn_error_clear(svn_err__temp); \ 00266 return EXIT_FAILURE; } \ 00267 } while (0) 00268 00269 /** @} */ 00270 00271 /** 00272 * Return TRUE if @a err is an error specifically related to locking a 00273 * path in the repository, FALSE otherwise. 00274 * 00275 * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error 00276 * that can be thrown when attempting to lock an item. 00277 * 00278 * @since New in 1.2. 00279 */ 00280 #define SVN_ERR_IS_LOCK_ERROR(err) \ 00281 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \ 00282 err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \ 00283 00284 /** 00285 * Return TRUE if @a err is an error specifically related to unlocking 00286 * a path in the repository, FALSE otherwise. 00287 * 00288 * @since New in 1.2. 00289 */ 00290 #define SVN_ERR_IS_UNLOCK_ERROR(err) \ 00291 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \ 00292 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 00293 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \ 00294 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \ 00295 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \ 00296 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED) 00297 00298 00299 #ifdef __cplusplus 00300 } 00301 #endif /* __cplusplus */ 00302 00303 #endif /* SVN_ERROR_H */