src/TortoiseMerge/svninclude/svn_error.h

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