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 * Notes: 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 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 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 wrappered exception with your own 00136 * message, before throwing it up the stack. (It uses all of the 00137 * 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 /** Create a new error that is a deep copy of err and return it. 00152 * 00153 * @since New in 1.2. 00154 */ 00155 svn_error_t *svn_error_dup(svn_error_t *err); 00156 00157 /** Free the memory used by @a error, as well as all ancestors and 00158 * descendants of @a error. 00159 * 00160 * Unlike other Subversion objects, errors are managed explicitly; you 00161 * MUST clear an error if you are ignoring it, or you are leaking memory. 00162 * For convenience, @a error may be @c NULL, in which case this function does 00163 * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to 00164 * ignore errors. 00165 */ 00166 void svn_error_clear(svn_error_t *error); 00167 00168 00169 /** 00170 * Very basic default error handler: print out error stack @a error to the 00171 * stdio stream @a stream, with each error prefixed by @a prefix, and quit 00172 * iff the @a fatal flag is set. Allocations are performed in the error's 00173 * pool. 00174 * 00175 * If you're not sure what prefix to pass, just pass "svn: ". That's 00176 * what code that used to call svn_handle_error() and now calls 00177 * svn_handle_error2() does. 00178 * 00179 * @since New in 1.2. 00180 */ 00181 void svn_handle_error2(svn_error_t *error, 00182 FILE *stream, 00183 svn_boolean_t fatal, 00184 const char *prefix); 00185 00186 /** Like svn_handle_error2() but with @c prefix set to "svn: " 00187 * 00188 * @deprecated Provided for backward compatibility with the 1.1 API. 00189 */ 00190 void svn_handle_error(svn_error_t *error, 00191 FILE *stream, 00192 svn_boolean_t fatal); 00193 00194 /** 00195 * Very basic default warning handler: print out the error @a error to the 00196 * stdio stream @a stream, prefixed by @a prefix. Allocations are 00197 * performed in the error's pool. 00198 * 00199 * @since New in 1.2. 00200 */ 00201 void svn_handle_warning2(FILE *stream, svn_error_t *error, const char *prefix); 00202 00203 /** Like svn_handle_warning2() but with @c prefix set to "svn: " 00204 */ 00205 void svn_handle_warning(FILE *stream, svn_error_t *error); 00206 00207 00208 /** A statement macro for checking error values. 00209 * 00210 * Evaluate @a expr. If it yields an error, return that error from the 00211 * current function. Otherwise, continue. 00212 * 00213 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 00214 * but it makes this macro syntactically equivalent to the expression 00215 * statement it resembles. Without it, statements like 00216 * 00217 * <tt> 00218 * if (a) 00219 * SVN_ERR (some operation); 00220 * else 00221 * foo; 00222 * </tt> 00223 * 00224 * would not mean what they appear to. 00225 */ 00226 #define SVN_ERR(expr) \ 00227 do { \ 00228 svn_error_t *svn_err__temp = (expr); \ 00229 if (svn_err__temp) \ 00230 return svn_err__temp; \ 00231 } while (0) 00232 00233 00234 /** A statement macro, very similar to @c SVN_ERR. 00235 * 00236 * This macro will wrap the error with the specified text before 00237 * returning the error. 00238 */ 00239 #define SVN_ERR_W(expr, wrap_msg) \ 00240 do { \ 00241 svn_error_t *svn_err__temp = (expr); \ 00242 if (svn_err__temp) \ 00243 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ 00244 } while (0) 00245 00246 00247 /** A statement macro, similar to @c SVN_ERR, but returns an integer. 00248 * 00249 * Evaluate @a expr. If it yields an error, handle that error and 00250 * return @c EXIT_FAILURE. 00251 */ 00252 #define SVN_INT_ERR(expr) \ 00253 do { \ 00254 svn_error_t *svn_err__temp = (expr); \ 00255 if (svn_err__temp) { \ 00256 svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \ 00257 svn_error_clear(svn_err__temp); \ 00258 return EXIT_FAILURE; } \ 00259 } while (0) 00260 00261 /** @} */ 00262 00263 /** 00264 * Return TRUE if @a err is an error specifically related to locking a 00265 * path in the repository, FALSE otherwise. 00266 * 00267 * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error 00268 * that can be thrown when attempting to lock an item. 00269 * 00270 * @since New in 1.2. 00271 */ 00272 #define SVN_ERR_IS_LOCK_ERROR(err) \ 00273 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \ 00274 err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \ 00275 00276 /** 00277 * Return TRUE if @a err is an error specifically related to unlocking 00278 * a path in the repository, FALSE otherwise. 00279 * 00280 * @since New in 1.2. 00281 */ 00282 #define SVN_ERR_IS_UNLOCK_ERROR(err) \ 00283 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \ 00284 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 00285 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \ 00286 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \ 00287 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \ 00288 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED) 00289 00290 00291 #ifdef __cplusplus 00292 } 00293 #endif /* __cplusplus */ 00294 00295 #endif /* SVN_ERROR_H */