Subversion
|
00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004, 2008 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> /* for apr_size_t */ 00029 #include <apr_errno.h> /* APR's error system */ 00030 #include <apr_pools.h> /* for apr_pool_t */ 00031 00032 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00033 #define APR_WANT_STDIO 00034 #endif 00035 #include <apr_want.h> /* for FILE* */ 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 00052 svn_error__locate(const char *file, 00053 long line); 00054 00055 00056 /** Put an English description of @a statcode into @a buf and return @a buf, 00057 * NULL-terminated. @a statcode is either an svn error or apr error. 00058 */ 00059 char * 00060 svn_strerror(apr_status_t statcode, 00061 char *buf, 00062 apr_size_t bufsize); 00063 00064 00065 /** If @a err has a custom error message, return that, otherwise 00066 * store the generic error string associated with @a err->apr_err into 00067 * @a buf (terminating with NULL) and return @a buf. 00068 * 00069 * @since New in 1.4. 00070 * 00071 * @note @a buf and @a bufsize are provided in the interface so that 00072 * this function is thread-safe and yet does no allocation. 00073 */ 00074 const char *svn_err_best_message(svn_error_t *err, 00075 char *buf, 00076 apr_size_t bufsize); 00077 00078 00079 00080 /** SVN error creation and destruction. 00081 * 00082 * @defgroup svn_error_error_creation_destroy Error creation and destruction 00083 * @{ 00084 */ 00085 00086 /** Create a nested exception structure. 00087 * 00088 * Input: an APR or SVN custom error code, 00089 * a "child" error to wrap, 00090 * a specific message 00091 * 00092 * Returns: a new error structure (containing the old one). 00093 * 00094 * @note Errors are always allocated in a subpool of the global pool, 00095 * since an error's lifetime is generally not related to the 00096 * lifetime of any convenient pool. Errors must be freed 00097 * with svn_error_clear(). The specific message should be @c NULL 00098 * if there is nothing to add to the general message associated 00099 * with the error code. 00100 * 00101 * If creating the "bottommost" error in a chain, pass @c NULL for 00102 * the child argument. 00103 */ 00104 svn_error_t * 00105 svn_error_create(apr_status_t apr_err, 00106 svn_error_t *child, 00107 const char *message); 00108 00109 /** Wrapper macro to collect file and line information */ 00110 #define svn_error_create \ 00111 (svn_error__locate(__FILE__,__LINE__), (svn_error_create)) 00112 00113 /** Create an error structure with the given @a apr_err and @a child, 00114 * with a printf-style error message produced by passing @a fmt, using 00115 * apr_psprintf(). 00116 */ 00117 svn_error_t * 00118 svn_error_createf(apr_status_t apr_err, 00119 svn_error_t *child, 00120 const char *fmt, 00121 ...) 00122 __attribute__ ((format(printf, 3, 4))); 00123 00124 /** Wrapper macro to collect file and line information */ 00125 #define svn_error_createf \ 00126 (svn_error__locate(__FILE__,__LINE__), (svn_error_createf)) 00127 00128 /** Wrap a @a status from an APR function. If @a fmt is NULL, this is 00129 * equivalent to svn_error_create(status,NULL,NULL). Otherwise, 00130 * the error message is constructed by formatting @a fmt and the 00131 * following arguments according to apr_psprintf(), and then 00132 * appending ": " and the error message corresponding to @a status. 00133 * (If UTF-8 translation of the APR error message fails, the ": " and 00134 * APR error are not appended to the error message.) 00135 */ 00136 svn_error_t * 00137 svn_error_wrap_apr(apr_status_t status, 00138 const char *fmt, 00139 ...) 00140 __attribute__((format(printf, 2, 3))); 00141 00142 /** Wrapper macro to collect file and line information */ 00143 #define svn_error_wrap_apr \ 00144 (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) 00145 00146 /** A quick n' easy way to create a wrapped exception with your own 00147 * message, before throwing it up the stack. (It uses all of the 00148 * @a child's fields.) 00149 */ 00150 svn_error_t * 00151 svn_error_quick_wrap(svn_error_t *child, 00152 const char *new_msg); 00153 00154 /** Wrapper macro to collect file and line information */ 00155 #define svn_error_quick_wrap \ 00156 (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) 00157 00158 /** Compose two errors, returning the composition as a brand new error 00159 * and consuming the original errors. Either or both of @a err1 and 00160 * @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR, 00161 * @a err2 will follow @a err1 in the chain of the returned error. 00162 * 00163 * @since New in 1.6. 00164 */ 00165 svn_error_t * 00166 svn_error_compose_create(svn_error_t *err1, 00167 svn_error_t *err2); 00168 00169 /** Add @a new_err to the end of @a chain's chain of errors. The @a new_err 00170 * chain will be copied into @a chain's pool and destroyed, so @a new_err 00171 * itself becomes invalid after this function. 00172 */ 00173 void 00174 svn_error_compose(svn_error_t *chain, 00175 svn_error_t *new_err); 00176 00177 /** Return the root cause of @a err by finding the last error in its 00178 * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in 00179 * which case @c SVN_NO_ERROR is returned. 00180 * 00181 * @since New in 1.5. 00182 */ 00183 svn_error_t * 00184 svn_error_root_cause(svn_error_t *err); 00185 00186 /** Create a new error that is a deep copy of @a err and return it. 00187 * 00188 * @since New in 1.2. 00189 */ 00190 svn_error_t * 00191 svn_error_dup(svn_error_t *err); 00192 00193 /** Free the memory used by @a error, as well as all ancestors and 00194 * descendants of @a error. 00195 * 00196 * Unlike other Subversion objects, errors are managed explicitly; you 00197 * MUST clear an error if you are ignoring it, or you are leaking memory. 00198 * For convenience, @a error may be @c NULL, in which case this function does 00199 * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to 00200 * ignore errors. 00201 */ 00202 void 00203 svn_error_clear(svn_error_t *error); 00204 00205 00206 /** 00207 * Very basic default error handler: print out error stack @a error to the 00208 * stdio stream @a stream, with each error prefixed by @a prefix; quit and 00209 * clear @a error iff the @a fatal flag is set. Allocations are performed 00210 * in the @a error's pool. 00211 * 00212 * If you're not sure what prefix to pass, just pass "svn: ". That's 00213 * what code that used to call svn_handle_error() and now calls 00214 * svn_handle_error2() does. 00215 * 00216 * @since New in 1.2. 00217 */ 00218 void 00219 svn_handle_error2(svn_error_t *error, 00220 FILE *stream, 00221 svn_boolean_t fatal, 00222 const char *prefix); 00223 00224 /** Like svn_handle_error2() but with @c prefix set to "svn: " 00225 * 00226 * @deprecated Provided for backward compatibility with the 1.1 API. 00227 */ 00228 SVN_DEPRECATED 00229 void 00230 svn_handle_error(svn_error_t *error, 00231 FILE *stream, 00232 svn_boolean_t fatal); 00233 00234 /** 00235 * Very basic default warning handler: print out the error @a error to the 00236 * stdio stream @a stream, prefixed by @a prefix. Allocations are 00237 * performed in the error's pool. 00238 * 00239 * @since New in 1.2. 00240 */ 00241 void 00242 svn_handle_warning2(FILE *stream, 00243 svn_error_t *error, 00244 const char *prefix); 00245 00246 /** Like svn_handle_warning2() but with @c prefix set to "svn: " 00247 * 00248 * @deprecated Provided for backward compatibility with the 1.1 API. 00249 */ 00250 SVN_DEPRECATED 00251 void 00252 svn_handle_warning(FILE *stream, 00253 svn_error_t *error); 00254 00255 00256 /** A statement macro for checking error values. 00257 * 00258 * Evaluate @a expr. If it yields an error, return that error from the 00259 * current function. Otherwise, continue. 00260 * 00261 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 00262 * but it makes this macro syntactically equivalent to the expression 00263 * statement it resembles. Without it, statements like 00264 * 00265 * @code 00266 * if (a) 00267 * SVN_ERR (some operation); 00268 * else 00269 * foo; 00270 * @endcode 00271 * 00272 * would not mean what they appear to. 00273 */ 00274 #define SVN_ERR(expr) \ 00275 do { \ 00276 svn_error_t *svn_err__temp = (expr); \ 00277 if (svn_err__temp) \ 00278 return svn_err__temp; \ 00279 } while (0) 00280 00281 /** 00282 * A macro for wrapping an error in a source-location trace message. 00283 * 00284 * This macro can be used when directly returning an already created 00285 * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure 00286 * that the call stack is recorded correctly. 00287 * 00288 * @since New in 1.7. 00289 */ 00290 #ifdef SVN_ERR__TRACING 00291 svn_error_t * 00292 svn_error__trace(const char *file, long line, svn_error_t *err); 00293 00294 #define svn_error_trace(expr) svn_error__trace(__FILE__, __LINE__, (expr)) 00295 #else 00296 #define svn_error_trace(expr) (expr) 00297 #endif 00298 00299 /** A statement macro, very similar to @c SVN_ERR. 00300 * 00301 * This macro will wrap the error with the specified text before 00302 * returning the error. 00303 */ 00304 #define SVN_ERR_W(expr, wrap_msg) \ 00305 do { \ 00306 svn_error_t *svn_err__temp = (expr); \ 00307 if (svn_err__temp) \ 00308 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ 00309 } while (0) 00310 00311 00312 /** A statement macro, similar to @c SVN_ERR, but returns an integer. 00313 * 00314 * Evaluate @a expr. If it yields an error, handle that error and 00315 * return @c EXIT_FAILURE. 00316 */ 00317 #define SVN_INT_ERR(expr) \ 00318 do { \ 00319 svn_error_t *svn_err__temp = (expr); \ 00320 if (svn_err__temp) { \ 00321 svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \ 00322 svn_error_clear(svn_err__temp); \ 00323 return EXIT_FAILURE; } \ 00324 } while (0) 00325 00326 /** @} */ 00327 00328 /** 00329 * Return TRUE if @a err is an error specifically related to locking a 00330 * path in the repository, FALSE otherwise. 00331 * 00332 * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error 00333 * that can be thrown when attempting to lock an item. 00334 * 00335 * @since New in 1.2. 00336 */ 00337 #define SVN_ERR_IS_LOCK_ERROR(err) \ 00338 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \ 00339 err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \ 00340 00341 /** 00342 * Return TRUE if @a err is an error specifically related to unlocking 00343 * a path in the repository, FALSE otherwise. 00344 * 00345 * @since New in 1.2. 00346 */ 00347 #define SVN_ERR_IS_UNLOCK_ERROR(err) \ 00348 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \ 00349 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 00350 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \ 00351 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \ 00352 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \ 00353 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED) 00354 00355 /** Report that an internal malfunction has occurred, and possibly terminate 00356 * the program. 00357 * 00358 * Act as determined by the current "malfunction handler" which may have 00359 * been specified by a call to svn_error_set_malfunction_handler() or else 00360 * is the default handler as specified in that function's documentation. If 00361 * the malfunction handler returns, then cause the function using this macro 00362 * to return the error object that it generated. 00363 * 00364 * @note The intended use of this macro is where execution reaches a point 00365 * that cannot possibly be reached unless there is a bug in the program. 00366 * 00367 * @since New in 1.6. 00368 */ 00369 #define SVN_ERR_MALFUNCTION() \ 00370 do { \ 00371 return svn_error__malfunction(TRUE, __FILE__, __LINE__, NULL); \ 00372 } while (0) 00373 00374 /** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning 00375 * an error to the calling function. 00376 * 00377 * If possible you should use SVN_ERR_MALFUNCTION() instead. 00378 * 00379 * @since New in 1.6. 00380 */ 00381 #define SVN_ERR_MALFUNCTION_NO_RETURN() \ 00382 do { \ 00383 svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \ 00384 abort(); \ 00385 } while (1) 00386 00387 /** Check that a condition is true: if not, report an error and possibly 00388 * terminate the program. 00389 * 00390 * If the Boolean expression @a expr is true, do nothing. Otherwise, 00391 * act as determined by the current "malfunction handler" which may have 00392 * been specified by a call to svn_error_set_malfunction_handler() or else 00393 * is the default handler as specified in that function's documentation. If 00394 * the malfunction handler returns, then cause the function using this macro 00395 * to return the error object that it generated. 00396 * 00397 * @note The intended use of this macro is to check a condition that cannot 00398 * possibly be false unless there is a bug in the program. 00399 * 00400 * @note The condition to be checked should not be computationally expensive 00401 * if it is reached often, as, unlike traditional "assert" statements, the 00402 * evaluation of this expression is not compiled out in release-mode builds. 00403 * 00404 * @since New in 1.6. 00405 */ 00406 #define SVN_ERR_ASSERT(expr) \ 00407 do { \ 00408 if (!(expr)) \ 00409 SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \ 00410 } while (0) 00411 00412 /** Similar to SVN_ERR_ASSERT(), but without the option of returning 00413 * an error to the calling function. 00414 * 00415 * If possible you should use SVN_ERR_ASSERT() instead. 00416 * 00417 * @since New in 1.6. 00418 */ 00419 #define SVN_ERR_ASSERT_NO_RETURN(expr) \ 00420 do { \ 00421 if (!(expr)) { \ 00422 svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \ 00423 abort(); \ 00424 } \ 00425 } while (0) 00426 00427 00428 /** A helper function for the macros that report malfunctions. Handle a 00429 * malfunction by calling the current "malfunction handler" which may have 00430 * been specified by a call to svn_error_set_malfunction_handler() or else 00431 * is the default handler as specified in that function's documentation. 00432 * 00433 * Pass all of the parameters to the handler. The error occurred in the 00434 * source file @a file at line @a line, and was an assertion failure of the 00435 * expression @a expr, or, if @a expr is null, an unconditional error. 00436 * 00437 * If @a can_return is true, the handler can return an error object 00438 * that is returned by the caller. If @a can_return is false the 00439 * method should never return. (The caller will call abort()) 00440 * 00441 * @since New in 1.6. 00442 */ 00443 svn_error_t * 00444 svn_error__malfunction(svn_boolean_t can_return, 00445 const char *file, 00446 int line, 00447 const char *expr); 00448 00449 /** A type of function that handles an assertion failure or other internal 00450 * malfunction detected within the Subversion libraries. 00451 * 00452 * The error occurred in the source file @a file at line @a line, and was an 00453 * assertion failure of the expression @a expr, or, if @a expr is null, an 00454 * unconditional error. 00455 * 00456 * If @a can_return is false a function of this type must never return. 00457 * 00458 * If @a can_return is true a function of this type must do one of: 00459 * - Return an error object describing the error, using an error code in 00460 * the category SVN_ERR_MALFUNC_CATEGORY_START. 00461 * - Never return. 00462 * 00463 * The function may alter its behaviour according to compile-time 00464 * and run-time and even interactive conditions. 00465 * 00466 * @since New in 1.6. 00467 */ 00468 typedef svn_error_t *(*svn_error_malfunction_handler_t) 00469 (svn_boolean_t can_return, const char *file, int line, const char *expr); 00470 00471 /** Cause subsequent malfunctions to be handled by @a func. 00472 * Return the handler that was previously in effect. 00473 * 00474 * @a func may not be null. 00475 * 00476 * @note The default handler is svn_error_abort_on_malfunction(). 00477 * 00478 * @note This function must be called in a single-threaded context. 00479 * 00480 * @since New in 1.6. 00481 */ 00482 svn_error_malfunction_handler_t 00483 svn_error_set_malfunction_handler(svn_error_malfunction_handler_t func); 00484 00485 /** Handle a malfunction by returning an error object that describes it. 00486 * 00487 * When @a can_return is false, abort() 00488 * 00489 * This function implements @c svn_error_malfunction_handler_t. 00490 * 00491 * @since New in 1.6. 00492 */ 00493 svn_error_t * 00494 svn_error_raise_on_malfunction(svn_boolean_t can_return, 00495 const char *file, 00496 int line, 00497 const char *expr); 00498 00499 /** Handle a malfunction by printing a message to stderr and aborting. 00500 * 00501 * This function implements @c svn_error_malfunction_handler_t. 00502 * 00503 * @since New in 1.6. 00504 */ 00505 svn_error_t * 00506 svn_error_abort_on_malfunction(svn_boolean_t can_return, 00507 const char *file, 00508 int line, 00509 const char *expr); 00510 00511 00512 #ifdef __cplusplus 00513 } 00514 #endif /* __cplusplus */ 00515 00516 #endif /* SVN_ERROR_H */