svn_error.h revision 299742
1178354Ssam/** 2178354Ssam * @copyright 3178354Ssam * ==================================================================== 4206358Srpaulo * Licensed to the Apache Software Foundation (ASF) under one 5178354Ssam * or more contributor license agreements. See the NOTICE file 6178354Ssam * distributed with this work for additional information 7178354Ssam * regarding copyright ownership. The ASF licenses this file 8178354Ssam * to you under the Apache License, Version 2.0 (the 9178354Ssam * "License"); you may not use this file except in compliance 10178354Ssam * with the License. You may obtain a copy of the License at 11178354Ssam * 12178354Ssam * http://www.apache.org/licenses/LICENSE-2.0 13178354Ssam * 14178354Ssam * Unless required by applicable law or agreed to in writing, 15178354Ssam * software distributed under the License is distributed on an 16178354Ssam * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17178354Ssam * KIND, either express or implied. See the License for the 18178354Ssam * specific language governing permissions and limitations 19178354Ssam * under the License. 20178354Ssam * ==================================================================== 21178354Ssam * @endcopyright 22178354Ssam * 23178354Ssam * @file svn_error.h 24178354Ssam * @brief Common exception handling for Subversion. 25178354Ssam */ 26178354Ssam 27178354Ssam#ifndef SVN_ERROR_H 28178354Ssam#define SVN_ERROR_H 29178354Ssam 30178354Ssam#include <apr.h> /* for apr_size_t */ 31178354Ssam#include <apr_errno.h> /* APR's error system */ 32178354Ssam#include <apr_pools.h> /* for apr_pool_t */ 33178354Ssam 34178354Ssam#ifndef DOXYGEN_SHOULD_SKIP_THIS 35178354Ssam#define APR_WANT_STDIO 36178354Ssam#endif 37178354Ssam#include <apr_want.h> /* for FILE* */ 38178354Ssam 39178354Ssam#include "svn_types.h" 40178354Ssam 41178354Ssam#ifdef __cplusplus 42178354Ssamextern "C" { 43178354Ssam#endif /* __cplusplus */ 44178354Ssam 45178354Ssam 46206358Srpaulo/* For the Subversion developers, this #define turns on extended "stack 47178354Ssam traces" of any errors that get thrown. See the SVN_ERR() macro. */ 48178354Ssam#ifdef SVN_DEBUG 49178354Ssam#define SVN_ERR__TRACING 50178354Ssam#endif 51178354Ssam 52178354Ssam 53178354Ssam/** the best kind of (@c svn_error_t *) ! */ 54178354Ssam#define SVN_NO_ERROR 0 55178354Ssam 56178354Ssam/* The actual error codes are kept in a separate file; see comments 57178354Ssam there for the reasons why. */ 58178354Ssam#include "svn_error_codes.h" 59178354Ssam 60178354Ssam/** Put an English description of @a statcode into @a buf and return @a buf, 61178354Ssam * NULL-terminated. @a statcode is either an svn error or apr error. 62178354Ssam */ 63178354Ssamchar * 64178354Ssamsvn_strerror(apr_status_t statcode, 65178354Ssam char *buf, 66178354Ssam apr_size_t bufsize); 67178354Ssam 68178354Ssam 69178354Ssam/** 70178354Ssam * Return the symbolic name of an error code. If the error code 71178354Ssam * is in svn_error_codes.h, return the name of the macro as a string. 72178354Ssam * If the error number is not recognised, return @c NULL. 73178354Ssam * 74178354Ssam * An error number may not be recognised because it was defined in a future 75178354Ssam * version of Subversion (e.g., a 1.9.x server may transmit a defined-in-1.9.0 76206358Srpaulo * error number to a 1.8.x client). 77206358Srpaulo * 78206358Srpaulo * An error number may be recognised @em incorrectly if the @c apr_status_t 79206358Srpaulo * value originates in another library (such as libserf) which also uses APR. 80206358Srpaulo * (This is a theoretical concern only: the @c apr_err member of #svn_error_t 81206358Srpaulo * should never contain a "foreign" @c apr_status_t value, and 82206358Srpaulo * in any case Subversion and Serf use non-overlapping subsets of the 83206358Srpaulo * @c APR_OS_START_USERERR range.) 84206358Srpaulo * 85206358Srpaulo * Support for error codes returned by APR itself (i.e., not in the 86206358Srpaulo * @c APR_OS_START_USERERR range, as defined in apr_errno.h) may be implemented 87206358Srpaulo * in the future. 88206358Srpaulo * 89206358Srpaulo * @note In rare cases, a single numeric code has more than one symbolic name. 90206358Srpaulo * (For example, #SVN_ERR_WC_NOT_DIRECTORY and #SVN_ERR_WC_NOT_WORKING_COPY). 91178354Ssam * In those cases, it is not guaranteed which symbolic name is returned. 92178354Ssam * 93178354Ssam * @since New in 1.8. 94178354Ssam */ 95206358Srpauloconst char * 96206358Srpaulosvn_error_symbolic_name(apr_status_t statcode); 97206358Srpaulo 98206358Srpaulo 99206358Srpaulo/** If @a err has a custom error message, return that, otherwise 100206358Srpaulo * store the generic error string associated with @a err->apr_err into 101206358Srpaulo * @a buf (terminating with NULL) and return @a buf. 102206358Srpaulo * 103206358Srpaulo * @since New in 1.4. 104206358Srpaulo * 105206358Srpaulo * @note @a buf and @a bufsize are provided in the interface so that 106206358Srpaulo * this function is thread-safe and yet does no allocation. 107206358Srpaulo */ 108206358Srpauloconst char *svn_err_best_message(const svn_error_t *err, 109206358Srpaulo char *buf, 110206358Srpaulo apr_size_t bufsize); 111206358Srpaulo 112206358Srpaulo 113178354Ssam 114206358Srpaulo/** SVN error creation and destruction. 115178354Ssam * 116178354Ssam * @defgroup svn_error_error_creation_destroy Error creation and destruction 117178354Ssam * @{ 118178354Ssam */ 119178354Ssam 120178354Ssam/** Create a nested exception structure. 121178354Ssam * 122178354Ssam * Input: an APR or SVN custom error code, 123206358Srpaulo * a "child" error to wrap, 124206358Srpaulo * a specific message 125178354Ssam * 126206358Srpaulo * Returns: a new error structure (containing the old one). 127206358Srpaulo * 128206358Srpaulo * @note Errors are always allocated in a subpool of the global pool, 129206358Srpaulo * since an error's lifetime is generally not related to the 130206358Srpaulo * lifetime of any convenient pool. Errors must be freed 131206419Srpaulo * with svn_error_clear(). The specific message should be @c NULL 132206419Srpaulo * if there is nothing to add to the general message associated 133206419Srpaulo * with the error code. 134206419Srpaulo * 135206419Srpaulo * If creating the "bottommost" error in a chain, pass @c NULL for 136206419Srpaulo * the child argument. 137178354Ssam */ 138206358Srpaulosvn_error_t * 139206358Srpaulosvn_error_create(apr_status_t apr_err, 140178354Ssam svn_error_t *child, 141178354Ssam const char *message); 142206358Srpaulo 143206358Srpaulo/** Create an error structure with the given @a apr_err and @a child, 144178354Ssam * with a printf-style error message produced by passing @a fmt, using 145206358Srpaulo * apr_psprintf(). 146178354Ssam */ 147178354Ssamsvn_error_t * 148178354Ssamsvn_error_createf(apr_status_t apr_err, 149178354Ssam svn_error_t *child, 150178354Ssam const char *fmt, 151178354Ssam ...) 152178354Ssam __attribute__ ((format(printf, 3, 4))); 153178354Ssam 154178354Ssam/** Wrap a @a status from an APR function. If @a fmt is NULL, this is 155178354Ssam * equivalent to svn_error_create(status,NULL,NULL). Otherwise, 156178354Ssam * the error message is constructed by formatting @a fmt and the 157178354Ssam * following arguments according to apr_psprintf(), and then 158178354Ssam * appending ": " and the error message corresponding to @a status. 159178354Ssam * (If UTF-8 translation of the APR error message fails, the ": " and 160178354Ssam * APR error are not appended to the error message.) 161178354Ssam */ 162178354Ssamsvn_error_t * 163178354Ssamsvn_error_wrap_apr(apr_status_t status, 164206358Srpaulo const char *fmt, 165206358Srpaulo ...) 166178354Ssam __attribute__((format(printf, 2, 3))); 167206358Srpaulo 168206419Srpaulo/** A quick n' easy way to create a wrapped exception with your own 169206419Srpaulo * message, before throwing it up the stack. (It uses all of the 170178354Ssam * @a child's fields.) 171178354Ssam */ 172207323Srpaulosvn_error_t * 173207323Srpaulosvn_error_quick_wrap(svn_error_t *child, 174207323Srpaulo const char *new_msg); 175207323Srpaulo 176207323Srpaulo/** A quick n' easy way to create a wrapped exception with your own 177207323Srpaulo * printf-style error message produced by passing @a fmt, using 178207323Srpaulo * apr_psprintf(), before throwing it up the stack. (It uses all of the 179207323Srpaulo * @a child's fields.) 180207323Srpaulo * 181207323Srpaulo * @since New in 1.9. 182207323Srpaulo */ 183178354Ssamsvn_error_t * 184178354Ssamsvn_error_quick_wrapf(svn_error_t *child, 185178354Ssam const char *fmt, 186178354Ssam ...) 187178354Ssam __attribute__((format(printf, 2, 3))); 188178354Ssam 189178354Ssam/** Compose two errors, returning the composition as a brand new error 190178354Ssam * and consuming the original errors. Either or both of @a err1 and 191178354Ssam * @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR, 192178354Ssam * @a err2 will follow @a err1 in the chain of the returned error. 193178354Ssam * 194178354Ssam * Either @a err1 or @a err2 can be functions that return svn_error_t* 195178354Ssam * but if both are functions they can be evaluated in either order as 196178354Ssam * per the C language rules. 197178354Ssam * 198178354Ssam * @since New in 1.6. 199206358Srpaulo */ 200206358Srpaulosvn_error_t * 201206358Srpaulosvn_error_compose_create(svn_error_t *err1, 202206358Srpaulo svn_error_t *err2); 203206358Srpaulo 204206358Srpaulo/** Add @a new_err to the end of @a chain's chain of errors. The @a new_err 205206358Srpaulo * chain will be copied into @a chain's pool and destroyed, so @a new_err 206178354Ssam * itself becomes invalid after this function. 207178354Ssam * 208178354Ssam * Either @a chain or @a new_err can be functions that return svn_error_t* 209178354Ssam * but if both are functions they can be evaluated in either order as 210178354Ssam * per the C language rules. 211178354Ssam */ 212178354Ssamvoid 213178354Ssamsvn_error_compose(svn_error_t *chain, 214178354Ssam svn_error_t *new_err); 215178354Ssam 216178354Ssam/** Return the root cause of @a err by finding the last error in its 217178354Ssam * chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in 218178354Ssam * which case @c SVN_NO_ERROR is returned. The returned error should 219178354Ssam * @em not be cleared as it shares memory with @a err. 220178354Ssam * 221206358Srpaulo * @since New in 1.5. 222206358Srpaulo */ 223178354Ssamsvn_error_t * 224206358Srpaulosvn_error_root_cause(svn_error_t *err); 225206358Srpaulo 226178354Ssam/** Return the first error in @a err's chain that has an error code @a 227178354Ssam * apr_err or #SVN_NO_ERROR if there is no error with that code. The 228178354Ssam * returned error should @em not be cleared as it shares memory with @a err. 229178354Ssam * 230178354Ssam * If @a err is #SVN_NO_ERROR, return #SVN_NO_ERROR. 231178354Ssam * 232178354Ssam * @since New in 1.7. 233178354Ssam */ 234178354Ssamsvn_error_t * 235178354Ssamsvn_error_find_cause(svn_error_t *err, apr_status_t apr_err); 236178354Ssam 237178354Ssam/** Create a new error that is a deep copy of @a err and return it. 238178354Ssam * 239178354Ssam * @since New in 1.2. 240178354Ssam */ 241178354Ssamsvn_error_t * 242178354Ssamsvn_error_dup(const svn_error_t *err); 243178354Ssam 244178354Ssam/** Free the memory used by @a error, as well as all ancestors and 245178354Ssam * descendants of @a error. 246178354Ssam * 247178354Ssam * Unlike other Subversion objects, errors are managed explicitly; you 248178354Ssam * MUST clear an error if you are ignoring it, or you are leaking memory. 249178354Ssam * For convenience, @a error may be @c NULL, in which case this function does 250178354Ssam * nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to 251178354Ssam * ignore errors. 252178354Ssam */ 253178354Ssamvoid 254178354Ssamsvn_error_clear(svn_error_t *error); 255178354Ssam 256178354Ssam 257178354Ssam#if defined(SVN_ERR__TRACING) 258178354Ssam/** Set the error location for debug mode. */ 259178354Ssamvoid 260206358Srpaulosvn_error__locate(const char *file, 261206358Srpaulo long line); 262178354Ssam 263178354Ssam/* Wrapper macros to collect file and line information */ 264178354Ssam#define svn_error_create \ 265178354Ssam (svn_error__locate(__FILE__,__LINE__), (svn_error_create)) 266178354Ssam#define svn_error_createf \ 267178354Ssam (svn_error__locate(__FILE__,__LINE__), (svn_error_createf)) 268178354Ssam#define svn_error_wrap_apr \ 269178354Ssam (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr)) 270178354Ssam#define svn_error_quick_wrap \ 271178354Ssam (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap)) 272178354Ssam#define svn_error_quick_wrapf \ 273178354Ssam (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrapf)) 274178354Ssam#endif 275178354Ssam 276178354Ssam 277178354Ssam/** 278178354Ssam * Very basic default error handler: print out error stack @a error to the 279178354Ssam * stdio stream @a stream, with each error prefixed by @a prefix; quit and 280206358Srpaulo * clear @a error iff the @a fatal flag is set. Allocations are performed 281206358Srpaulo * in the @a error's pool. 282178354Ssam * 283178354Ssam * If you're not sure what prefix to pass, just pass "svn: ". That's 284178354Ssam * what code that used to call svn_handle_error() and now calls 285178354Ssam * svn_handle_error2() does. 286178354Ssam * 287178354Ssam * Note that this should only be used from commandline specific code, or 288178354Ssam * code that knows that @a stream is really where the application wants 289178354Ssam * to receive its errors on. 290178354Ssam * 291178354Ssam * @since New in 1.2. 292178354Ssam */ 293178354Ssamvoid 294178354Ssamsvn_handle_error2(svn_error_t *error, 295178354Ssam FILE *stream, 296178354Ssam svn_boolean_t fatal, 297178354Ssam const char *prefix); 298178354Ssam 299178354Ssam/** Like svn_handle_error2() but with @c prefix set to "svn: " 300178354Ssam * 301178354Ssam * @deprecated Provided for backward compatibility with the 1.1 API. 302178354Ssam */ 303178354SsamSVN_DEPRECATED 304178354Ssamvoid 305178354Ssamsvn_handle_error(svn_error_t *error, 306178354Ssam FILE *stream, 307178354Ssam svn_boolean_t fatal); 308206358Srpaulo 309206358Srpaulo/** 310206358Srpaulo * Very basic default warning handler: print out the error @a error to the 311206358Srpaulo * stdio stream @a stream, prefixed by @a prefix. Allocations are 312206358Srpaulo * performed in the error's pool. 313206358Srpaulo * 314206358Srpaulo * @a error may not be @c NULL. 315206358Srpaulo * 316206358Srpaulo * @note This does not clear @a error. 317206358Srpaulo * 318206358Srpaulo * @since New in 1.2. 319206358Srpaulo */ 320206358Srpaulovoid 321206358Srpaulosvn_handle_warning2(FILE *stream, 322206358Srpaulo const svn_error_t *error, 323206358Srpaulo const char *prefix); 324206358Srpaulo 325206358Srpaulo/** Like svn_handle_warning2() but with @c prefix set to "svn: " 326178354Ssam * 327178354Ssam * @deprecated Provided for backward compatibility with the 1.1 API. 328178354Ssam */ 329206358SrpauloSVN_DEPRECATED 330206358Srpaulovoid 331178354Ssamsvn_handle_warning(FILE *stream, 332178354Ssam svn_error_t *error); 333178354Ssam 334178354Ssam 335178354Ssam/** A statement macro for checking error values. 336178354Ssam * 337206358Srpaulo * Evaluate @a expr. If it yields an error, return that error from the 338178354Ssam * current function. Otherwise, continue. 339178354Ssam * 340178354Ssam * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 341178354Ssam * but it makes this macro syntactically equivalent to the expression 342206358Srpaulo * statement it resembles. Without it, statements like 343178354Ssam * 344178354Ssam * @code 345178354Ssam * if (a) 346178354Ssam * SVN_ERR(some operation); 347206358Srpaulo * else 348178354Ssam * foo; 349178354Ssam * @endcode 350 * 351 * would not mean what they appear to. 352 */ 353#define SVN_ERR(expr) \ 354 do { \ 355 svn_error_t *svn_err__temp = (expr); \ 356 if (svn_err__temp) \ 357 return svn_error_trace(svn_err__temp); \ 358 } while (0) 359 360/** 361 * A macro for wrapping an error in a source-location trace message. 362 * 363 * This macro can be used when directly returning an already created 364 * error (when not using SVN_ERR, svn_error_create(), etc.) to ensure 365 * that the call stack is recorded correctly. 366 * 367 * @since New in 1.7. 368 */ 369#ifdef SVN_ERR__TRACING 370svn_error_t * 371svn_error__trace(const char *file, long line, svn_error_t *err); 372 373#define svn_error_trace(expr) svn_error__trace(__FILE__, __LINE__, (expr)) 374#else 375#define svn_error_trace(expr) (expr) 376#endif 377 378/** 379 * Returns an error chain that is based on @a err's error chain but 380 * does not include any error tracing placeholders. @a err is not 381 * modified, except for any allocations using its pool. 382 * 383 * The returned error chain is allocated from @a err's pool and shares 384 * its message and source filename character arrays. The returned 385 * error chain should *not* be cleared because it is not a fully 386 * fledged error chain, only clearing @a err should be done to clear 387 * the returned error chain. If @a err is cleared, then the returned 388 * error chain is unusable. 389 * 390 * @a err can be #SVN_NO_ERROR. If @a err is not #SVN_NO_ERROR, then 391 * the last link in the error chain must be a non-tracing error, i.e, 392 * a real error. 393 * 394 * @since New in 1.7. 395 */ 396svn_error_t *svn_error_purge_tracing(svn_error_t *err); 397 398 399/** A statement macro, very similar to @c SVN_ERR. 400 * 401 * This macro will wrap the error with the specified text before 402 * returning the error. 403 */ 404#define SVN_ERR_W(expr, wrap_msg) \ 405 do { \ 406 svn_error_t *svn_err__temp = (expr); \ 407 if (svn_err__temp) \ 408 return svn_error_quick_wrap(svn_err__temp, wrap_msg); \ 409 } while (0) 410 411 412/** A statement macro intended for the main() function of the 'svn' program. 413 * 414 * Evaluate @a expr. If it yields an error, display the error on stdout 415 * and return @c EXIT_FAILURE. 416 * 417 * @note Not for use in the library, as it prints to stderr. This macro 418 * no longer suits the needs of the 'svn' program, and is not generally 419 * suitable for third-party use as it assumes the program name is 'svn'. 420 * 421 * @deprecated Provided for backward compatibility with the 1.8 API. Consider 422 * using svn_handle_error2() or svn_cmdline_handle_exit_error() instead. 423 */ 424#define SVN_INT_ERR(expr) \ 425 do { \ 426 svn_error_t *svn_err__temp = (expr); \ 427 if (svn_err__temp) { \ 428 svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \ 429 svn_error_clear(svn_err__temp); \ 430 return EXIT_FAILURE; } \ 431 } while (0) 432 433/** @} */ 434 435 436/** Error groups 437 * 438 * @defgroup svn_error_error_groups Error groups 439 * @{ 440 */ 441 442/** 443 * Return TRUE if @a err is an error specifically related to locking a 444 * path in the repository, FALSE otherwise. 445 * 446 * SVN_ERR_FS_OUT_OF_DATE and SVN_ERR_FS_NOT_FOUND are in here because it's a 447 * non-fatal error that can be thrown when attempting to lock an item. 448 * 449 * SVN_ERR_REPOS_HOOK_FAILURE refers to the pre-lock hook. 450 * 451 * @since New in 1.2. 452 */ 453#define SVN_ERR_IS_LOCK_ERROR(err) \ 454 (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \ 455 err->apr_err == SVN_ERR_FS_NOT_FOUND || \ 456 err->apr_err == SVN_ERR_FS_OUT_OF_DATE || \ 457 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 458 err->apr_err == SVN_ERR_REPOS_HOOK_FAILURE || \ 459 err->apr_err == SVN_ERR_FS_NO_SUCH_REVISION || \ 460 err->apr_err == SVN_ERR_FS_OUT_OF_DATE || \ 461 err->apr_err == SVN_ERR_FS_NOT_FILE) 462 463/** 464 * Return TRUE if @a err is an error specifically related to unlocking 465 * a path in the repository, FALSE otherwise. 466 * 467 * SVN_ERR_REPOS_HOOK_FAILURE refers to the pre-unlock hook. 468 * 469 * @since New in 1.2. 470 */ 471#define SVN_ERR_IS_UNLOCK_ERROR(err) \ 472 (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \ 473 err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \ 474 err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \ 475 err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \ 476 err->apr_err == SVN_ERR_RA_NOT_LOCKED || \ 477 err->apr_err == SVN_ERR_FS_LOCK_EXPIRED || \ 478 err->apr_err == SVN_ERR_REPOS_HOOK_FAILURE) 479 480/** Evaluates to @c TRUE iff @a apr_err (of type apr_status_t) is in the given 481 * @a category, which should be one of the @c SVN_ERR_*_CATEGORY_START 482 * constants. 483 * 484 * @since New in 1.7. 485 */ 486#define SVN_ERROR_IN_CATEGORY(apr_err, category) \ 487 ((category) == ((apr_err) / SVN_ERR_CATEGORY_SIZE) * SVN_ERR_CATEGORY_SIZE) 488 489 490/** @} */ 491 492 493/** Internal malfunctions and assertions 494 * 495 * @defgroup svn_error_malfunction_assertion Malfunctions and assertions 496 * @{ 497 */ 498 499/** Report that an internal malfunction has occurred, and possibly terminate 500 * the program. 501 * 502 * Act as determined by the current "malfunction handler" which may have 503 * been specified by a call to svn_error_set_malfunction_handler() or else 504 * is the default handler as specified in that function's documentation. If 505 * the malfunction handler returns, then cause the function using this macro 506 * to return the error object that it generated. 507 * 508 * @note The intended use of this macro is where execution reaches a point 509 * that cannot possibly be reached unless there is a bug in the program. 510 * 511 * @since New in 1.6. 512 */ 513#define SVN_ERR_MALFUNCTION() \ 514 do { \ 515 return svn_error_trace(svn_error__malfunction( \ 516 TRUE, __FILE__, __LINE__, NULL)); \ 517 } while (0) 518 519/** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning 520 * an error to the calling function. 521 * 522 * If possible you should use SVN_ERR_MALFUNCTION() instead. 523 * 524 * @since New in 1.6. 525 */ 526#define SVN_ERR_MALFUNCTION_NO_RETURN() \ 527 do { \ 528 svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \ 529 abort(); \ 530 } while (1) 531 532/** Like SVN_ERR_ASSERT(), but append ERR to the returned error chain. 533 * 534 * If EXPR is false, return a malfunction error whose chain includes ERR. 535 * If EXPR is true, do nothing. (In particular, this does not clear ERR.) 536 * 537 * Types: (svn_boolean_t expr, svn_error_t *err) 538 * 539 * @since New in 1.8. 540 */ 541#ifdef __clang_analyzer__ 542#include <assert.h> 543/* Just ignore ERR. If the assert triggers, it'll be our least concern. */ 544#define SVN_ERR_ASSERT_E(expr, err) assert((expr)) 545#else 546#define SVN_ERR_ASSERT_E(expr, err) \ 547 do { \ 548 if (!(expr)) { \ 549 return svn_error_compose_create( \ 550 svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr), \ 551 (err)); \ 552 } \ 553 } while (0) 554#endif 555 556 557/** Check that a condition is true: if not, report an error and possibly 558 * terminate the program. 559 * 560 * If the Boolean expression @a expr is true, do nothing. Otherwise, 561 * act as determined by the current "malfunction handler" which may have 562 * been specified by a call to svn_error_set_malfunction_handler() or else 563 * is the default handler as specified in that function's documentation. If 564 * the malfunction handler returns, then cause the function using this macro 565 * to return the error object that it generated. 566 * 567 * @note The intended use of this macro is to check a condition that cannot 568 * possibly be false unless there is a bug in the program. 569 * 570 * @note The condition to be checked should not be computationally expensive 571 * if it is reached often, as, unlike traditional "assert" statements, the 572 * evaluation of this expression is not compiled out in release-mode builds. 573 * 574 * @since New in 1.6. 575 * 576 * @see SVN_ERR_ASSERT_E() 577 */ 578#ifdef __clang_analyzer__ 579#include <assert.h> 580#define SVN_ERR_ASSERT(expr) assert((expr)) 581#else 582#define SVN_ERR_ASSERT(expr) \ 583 do { \ 584 if (!(expr)) \ 585 SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \ 586 } while (0) 587#endif 588 589/** Similar to SVN_ERR_ASSERT(), but without the option of returning 590 * an error to the calling function. 591 * 592 * If possible you should use SVN_ERR_ASSERT() instead. 593 * 594 * @since New in 1.6. 595 */ 596#define SVN_ERR_ASSERT_NO_RETURN(expr) \ 597 do { \ 598 if (!(expr)) { \ 599 svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \ 600 abort(); \ 601 } \ 602 } while (0) 603 604/** Report a "Not implemented" malfunction. Internal use only. */ 605#define SVN__NOT_IMPLEMENTED() \ 606 return svn_error__malfunction(TRUE, __FILE__, __LINE__, "Not implemented.") 607 608/** A helper function for the macros that report malfunctions. Handle a 609 * malfunction by calling the current "malfunction handler" which may have 610 * been specified by a call to svn_error_set_malfunction_handler() or else 611 * is the default handler as specified in that function's documentation. 612 * 613 * Pass all of the parameters to the handler. The error occurred in the 614 * source file @a file at line @a line, and was an assertion failure of the 615 * expression @a expr, or, if @a expr is null, an unconditional error. 616 * 617 * If @a can_return is true, the handler can return an error object 618 * that is returned by the caller. If @a can_return is false the 619 * method should never return. (The caller will call abort()) 620 * 621 * @since New in 1.6. 622 */ 623svn_error_t * 624svn_error__malfunction(svn_boolean_t can_return, 625 const char *file, 626 int line, 627 const char *expr); 628 629/** A type of function that handles an assertion failure or other internal 630 * malfunction detected within the Subversion libraries. 631 * 632 * The error occurred in the source file @a file at line @a line, and was an 633 * assertion failure of the expression @a expr, or, if @a expr is null, an 634 * unconditional error. 635 * 636 * If @a can_return is false a function of this type must never return. 637 * 638 * If @a can_return is true a function of this type must do one of: 639 * - Return an error object describing the error, using an error code in 640 * the category SVN_ERR_MALFUNC_CATEGORY_START. 641 * - Never return. 642 * 643 * The function may alter its behaviour according to compile-time 644 * and run-time and even interactive conditions. 645 * 646 * @see SVN_ERROR_IN_CATEGORY() 647 * 648 * @since New in 1.6. 649 */ 650typedef svn_error_t *(*svn_error_malfunction_handler_t) 651 (svn_boolean_t can_return, const char *file, int line, const char *expr); 652 653/** Cause subsequent malfunctions to be handled by @a func. 654 * Return the handler that was previously in effect. 655 * 656 * @a func may not be null. 657 * 658 * @note The default handler is svn_error_abort_on_malfunction(). 659 * 660 * @note This function must be called in a single-threaded context. 661 * 662 * @since New in 1.6. 663 */ 664svn_error_malfunction_handler_t 665svn_error_set_malfunction_handler(svn_error_malfunction_handler_t func); 666 667/** Return the malfunction handler that is currently in effect. 668 * @since New in 1.9. */ 669svn_error_malfunction_handler_t 670svn_error_get_malfunction_handler(void); 671 672/** Handle a malfunction by returning an error object that describes it. 673 * 674 * When @a can_return is false, abort() 675 * 676 * This function implements @c svn_error_malfunction_handler_t. 677 * 678 * @since New in 1.6. 679 */ 680svn_error_t * 681svn_error_raise_on_malfunction(svn_boolean_t can_return, 682 const char *file, 683 int line, 684 const char *expr); 685 686/** Handle a malfunction by printing a message to stderr and aborting. 687 * 688 * This function implements @c svn_error_malfunction_handler_t. 689 * 690 * @since New in 1.6. 691 */ 692svn_error_t * 693svn_error_abort_on_malfunction(svn_boolean_t can_return, 694 const char *file, 695 int line, 696 const char *expr); 697 698/** @} */ 699 700 701#ifdef __cplusplus 702} 703#endif /* __cplusplus */ 704 705#endif /* SVN_ERROR_H */ 706