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