/usr/include/subversion-1/svn_error.h is in libsvn-dev 1.6.17dfsg-3ubuntu3.5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 | /**
* @copyright
* ====================================================================
* Copyright (c) 2000-2004, 2008 CollabNet. All rights reserved.
*
* This software is licensed as described in the file COPYING, which
* you should have received as part of this distribution. The terms
* are also available at http://subversion.tigris.org/license-1.html.
* If newer versions of this license are posted there, you may use a
* newer version instead, at your option.
*
* This software consists of voluntary contributions made by many
* individuals. For exact contribution history, see the revision
* history and logs, available at http://subversion.tigris.org/.
* ====================================================================
* @endcopyright
*
* @file svn_error.h
* @brief Common exception handling for Subversion.
*/
#ifndef SVN_ERROR_H
#define SVN_ERROR_H
#include <apr.h> /* for apr_size_t */
#include <apr_errno.h> /* APR's error system */
#include <apr_pools.h> /* for apr_pool_t */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define APR_WANT_STDIO
#endif
#include <apr_want.h> /* for FILE* */
#include "svn_types.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/** the best kind of (@c svn_error_t *) ! */
#define SVN_NO_ERROR 0
/* The actual error codes are kept in a separate file; see comments
there for the reasons why. */
#include "svn_error_codes.h"
/** Set the error location for debug mode. */
void
svn_error__locate(const char *file,
long line);
/** Put an English description of @a statcode into @a buf and return @a buf,
* NULL-terminated. @a statcode is either an svn error or apr error.
*/
char *
svn_strerror(apr_status_t statcode,
char *buf,
apr_size_t bufsize);
/** If @a err has a custom error message, return that, otherwise
* store the generic error string associated with @a err->apr_err into
* @a buf (terminating with NULL) and return @a buf.
*
* @since New in 1.4.
*
* @note @a buf and @a bufsize are provided in the interface so that
* this function is thread-safe and yet does no allocation.
*/
const char *svn_err_best_message(svn_error_t *err,
char *buf,
apr_size_t bufsize);
/** SVN error creation and destruction.
*
* @defgroup svn_error_error_creation_destroy Error creation and destruction
* @{
*/
/** Create a nested exception structure.
*
* Input: an APR or SVN custom error code,
* a "child" error to wrap,
* a specific message
*
* Returns: a new error structure (containing the old one).
*
* @note Errors are always allocated in a subpool of the global pool,
* since an error's lifetime is generally not related to the
* lifetime of any convenient pool. Errors must be freed
* with svn_error_clear(). The specific message should be @c NULL
* if there is nothing to add to the general message associated
* with the error code.
*
* If creating the "bottommost" error in a chain, pass @c NULL for
* the child argument.
*/
svn_error_t *
svn_error_create(apr_status_t apr_err,
svn_error_t *child,
const char *message);
/** Wrapper macro to collect file and line information */
#define svn_error_create \
(svn_error__locate(__FILE__,__LINE__), (svn_error_create))
/** Create an error structure with the given @a apr_err and @a child,
* with a printf-style error message produced by passing @a fmt, using
* apr_psprintf().
*/
svn_error_t *
svn_error_createf(apr_status_t apr_err,
svn_error_t *child,
const char *fmt,
...)
__attribute__ ((format(printf, 3, 4)));
/** Wrapper macro to collect file and line information */
#define svn_error_createf \
(svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
/** Wrap a @a status from an APR function. If @a fmt is NULL, this is
* equivalent to svn_error_create(status,NULL,NULL). Otherwise,
* the error message is constructed by formatting @a fmt and the
* following arguments according to apr_psprintf(), and then
* appending ": " and the error message corresponding to @a status.
* (If UTF-8 translation of the APR error message fails, the ": " and
* APR error are not appended to the error message.)
*/
svn_error_t *
svn_error_wrap_apr(apr_status_t status,
const char *fmt,
...)
__attribute__((format(printf, 2, 3)));
/** Wrapper macro to collect file and line information */
#define svn_error_wrap_apr \
(svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
/** A quick n' easy way to create a wrapped exception with your own
* message, before throwing it up the stack. (It uses all of the
* @a child's fields.)
*/
svn_error_t *
svn_error_quick_wrap(svn_error_t *child,
const char *new_msg);
/** Wrapper macro to collect file and line information */
#define svn_error_quick_wrap \
(svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
/** Compose two errors, returning the composition as a brand new error
* and consuming the original errors. Either or both of @a err1 and
* @a err2 may be @c SVN_NO_ERROR. If both are not @c SVN_NO_ERROR,
* @a err2 will follow @a err1 in the chain of the returned error.
*
* @since New in 1.6.
*/
svn_error_t *
svn_error_compose_create(svn_error_t *err1,
svn_error_t *err2);
/** Add @a new_err to the end of @a chain's chain of errors. The @a new_err
* chain will be copied into @a chain's pool and destroyed, so @a new_err
* itself becomes invalid after this function.
*/
void
svn_error_compose(svn_error_t *chain,
svn_error_t *new_err);
/** Return the root cause of @a err by finding the last error in its
* chain (e.g. it or its children). @a err may be @c SVN_NO_ERROR, in
* which case @c SVN_NO_ERROR is returned.
*
* @since New in 1.5.
*/
svn_error_t *
svn_error_root_cause(svn_error_t *err);
/** Create a new error that is a deep copy of @a err and return it.
*
* @since New in 1.2.
*/
svn_error_t *
svn_error_dup(svn_error_t *err);
/** Free the memory used by @a error, as well as all ancestors and
* descendants of @a error.
*
* Unlike other Subversion objects, errors are managed explicitly; you
* MUST clear an error if you are ignoring it, or you are leaking memory.
* For convenience, @a error may be @c NULL, in which case this function does
* nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to
* ignore errors.
*/
void
svn_error_clear(svn_error_t *error);
/**
* Very basic default error handler: print out error stack @a error to the
* stdio stream @a stream, with each error prefixed by @a prefix; quit and
* clear @a error iff the @a fatal flag is set. Allocations are performed
* in the @a error's pool.
*
* If you're not sure what prefix to pass, just pass "svn: ". That's
* what code that used to call svn_handle_error() and now calls
* svn_handle_error2() does.
*
* @since New in 1.2.
*/
void
svn_handle_error2(svn_error_t *error,
FILE *stream,
svn_boolean_t fatal,
const char *prefix);
/** Like svn_handle_error2() but with @c prefix set to "svn: "
*
* @deprecated Provided for backward compatibility with the 1.1 API.
*/
SVN_DEPRECATED
void
svn_handle_error(svn_error_t *error,
FILE *stream,
svn_boolean_t fatal);
/**
* Very basic default warning handler: print out the error @a error to the
* stdio stream @a stream, prefixed by @a prefix. Allocations are
* performed in the error's pool.
*
* @since New in 1.2.
*/
void
svn_handle_warning2(FILE *stream,
svn_error_t *error,
const char *prefix);
/** Like svn_handle_warning2() but with @c prefix set to "svn: "
*
* @deprecated Provided for backward compatibility with the 1.1 API.
*/
SVN_DEPRECATED
void
svn_handle_warning(FILE *stream,
svn_error_t *error);
/** A statement macro for checking error values.
*
* Evaluate @a expr. If it yields an error, return that error from the
* current function. Otherwise, continue.
*
* The <tt>do { ... } while (0)</tt> wrapper has no semantic effect,
* but it makes this macro syntactically equivalent to the expression
* statement it resembles. Without it, statements like
*
* @code
* if (a)
* SVN_ERR (some operation);
* else
* foo;
* @endcode
*
* would not mean what they appear to.
*/
#define SVN_ERR(expr) \
do { \
svn_error_t *svn_err__temp = (expr); \
if (svn_err__temp) \
return svn_err__temp; \
} while (0)
/** A statement macro, very similar to @c SVN_ERR.
*
* This macro will wrap the error with the specified text before
* returning the error.
*/
#define SVN_ERR_W(expr, wrap_msg) \
do { \
svn_error_t *svn_err__temp = (expr); \
if (svn_err__temp) \
return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
} while (0)
/** A statement macro, similar to @c SVN_ERR, but returns an integer.
*
* Evaluate @a expr. If it yields an error, handle that error and
* return @c EXIT_FAILURE.
*/
#define SVN_INT_ERR(expr) \
do { \
svn_error_t *svn_err__temp = (expr); \
if (svn_err__temp) { \
svn_handle_error2(svn_err__temp, stderr, FALSE, "svn: "); \
svn_error_clear(svn_err__temp); \
return EXIT_FAILURE; } \
} while (0)
/** @} */
/**
* Return TRUE if @a err is an error specifically related to locking a
* path in the repository, FALSE otherwise.
*
* SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
* that can be thrown when attempting to lock an item.
*
* @since New in 1.2.
*/
#define SVN_ERR_IS_LOCK_ERROR(err) \
(err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED || \
err->apr_err == SVN_ERR_FS_OUT_OF_DATE) \
/**
* Return TRUE if @a err is an error specifically related to unlocking
* a path in the repository, FALSE otherwise.
*
* @since New in 1.2.
*/
#define SVN_ERR_IS_UNLOCK_ERROR(err) \
(err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED || \
err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN || \
err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH || \
err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK || \
err->apr_err == SVN_ERR_RA_NOT_LOCKED || \
err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
/** Report that an internal malfunction has occurred, and possibly terminate
* the program.
*
* Act as determined by the current "malfunction handler" which may have
* been specified by a call to svn_error_set_malfunction_handler() or else
* is the default handler as specified in that function's documentation. If
* the malfunction handler returns, then cause the function using this macro
* to return the error object that it generated.
*
* @note The intended use of this macro is where execution reaches a point
* that cannot possibly be reached unless there is a bug in the program.
*
* @since New in 1.6.
*/
#define SVN_ERR_MALFUNCTION() \
do { \
return svn_error__malfunction(TRUE, __FILE__, __LINE__, NULL); \
} while (0)
/** Similar to SVN_ERR_MALFUNCTION(), but without the option of returning
* an error to the calling function.
*
* If possible you should use SVN_ERR_MALFUNCTION() instead.
*
* @since New in 1.6.
*/
#define SVN_ERR_MALFUNCTION_NO_RETURN() \
do { \
svn_error__malfunction(FALSE, __FILE__, __LINE__, NULL); \
abort(); \
} while (1)
/** Check that a condition is true: if not, report an error and possibly
* terminate the program.
*
* If the Boolean expression @a expr is true, do nothing. Otherwise,
* act as determined by the current "malfunction handler" which may have
* been specified by a call to svn_error_set_malfunction_handler() or else
* is the default handler as specified in that function's documentation. If
* the malfunction handler returns, then cause the function using this macro
* to return the error object that it generated.
*
* @note The intended use of this macro is to check a condition that cannot
* possibly be false unless there is a bug in the program.
*
* @note The condition to be checked should not be computationally expensive
* if it is reached often, as, unlike traditional "assert" statements, the
* evaluation of this expression is not compiled out in release-mode builds.
*
* @since New in 1.6.
*/
#define SVN_ERR_ASSERT(expr) \
do { \
if (!(expr)) \
SVN_ERR(svn_error__malfunction(TRUE, __FILE__, __LINE__, #expr)); \
} while (0)
/** Similar to SVN_ERR_ASSERT(), but without the option of returning
* an error to the calling function.
*
* If possible you should use SVN_ERR_ASSERT() instead.
*
* @since New in 1.6.
*/
#define SVN_ERR_ASSERT_NO_RETURN(expr) \
do { \
if (!(expr)) { \
svn_error__malfunction(FALSE, __FILE__, __LINE__, #expr); \
abort(); \
} \
} while (0)
/** A helper function for the macros that report malfunctions. Handle a
* malfunction by calling the current "malfunction handler" which may have
* been specified by a call to svn_error_set_malfunction_handler() or else
* is the default handler as specified in that function's documentation.
*
* Pass all of the parameters to the handler. The error occurred in the
* source file @a file at line @a line, and was an assertion failure of the
* expression @a expr, or, if @a expr is null, an unconditional error.
*
* If @a can_return is true, the handler can return an error object
* that is returned by the caller. If @a can_return is false the
* method should never return. (The caller will call abort())
*
* @since New in 1.6.
*/
svn_error_t *
svn_error__malfunction(svn_boolean_t can_return,
const char *file,
int line,
const char *expr);
/** A type of function that handles an assertion failure or other internal
* malfunction detected within the Subversion libraries.
*
* The error occurred in the source file @a file at line @a line, and was an
* assertion failure of the expression @a expr, or, if @a expr is null, an
* unconditional error.
*
* If @a can_return is false a function of this type must never return.
*
* If @a can_return is true a function of this type must do one of:
* - Return an error object describing the error, using an error code in
* the category SVN_ERR_MALFUNC_CATEGORY_START.
* - Never return.
*
* The function may alter its behaviour according to compile-time
* and run-time and even interactive conditions.
*
* @since New in 1.6.
*/
typedef svn_error_t *(*svn_error_malfunction_handler_t)
(svn_boolean_t can_return, const char *file, int line, const char *expr);
/** Cause subsequent malfunctions to be handled by @a func.
* Return the handler that was previously in effect.
*
* @a func may not be null.
*
* @note The default handler is svn_error_abort_on_malfunction().
*
* @note This function must be called in a single-threaded context.
*
* @since New in 1.6.
*/
svn_error_malfunction_handler_t
svn_error_set_malfunction_handler(svn_error_malfunction_handler_t func);
/** Handle a malfunction by returning an error object that describes it.
*
* When @a can_return is false, abort()
*
* This function implements @c svn_error_malfunction_handler_t.
*
* @since New in 1.6.
*/
svn_error_t *
svn_error_raise_on_malfunction(svn_boolean_t can_return,
const char *file,
int line,
const char *expr);
/** Handle a malfunction by printing a message to stderr and aborting.
*
* This function implements @c svn_error_malfunction_handler_t.
*
* @since New in 1.6.
*/
svn_error_t *
svn_error_abort_on_malfunction(svn_boolean_t can_return,
const char *file,
int line,
const char *expr);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* SVN_ERROR_H */
|