svn_error.h File Reference

Common exception handling for Subversion. More...

`#include <apr.h>`
`#include <apr_errno.h>`
`#include <apr_pools.h>`
`#include <apr_want.h>`
`#include "svn_types.h"`
`#include "svn_error_codes.h"`

Go to the source code of this file.

## Macros

#define | SVN_NO_ERROR 0
| the best kind of (`svn_error_t` *) !
#define | SVN_ERR(expr)
| A statement macro for checking error values. More...
#define | svn_error_trace(expr) (expr)
| A macro for wrapping an error in a source-location trace message. More...
#define | SVN_ERR_W(expr, wrap_msg)
| A statement macro, very similar to `SVN_ERR`. More...
#define | SVN_INT_ERR(expr)
| A statement macro intended for the main() function of the 'svn' program. More...
#define | SVN_ERR_IS_LOCK_ERROR(err)
| Return TRUE if err is an error specifically related to locking a path in the repository, FALSE otherwise. More...
#define | SVN_ERR_IS_UNLOCK_ERROR(err)
| Return TRUE if err is an error specifically related to unlocking a path in the repository, FALSE otherwise. More...
#define | SVN_ERROR_IN_CATEGORY(apr_err, category) ((category) == ((apr_err) / SVN_ERR_CATEGORY_SIZE) * SVN_ERR_CATEGORY_SIZE)
| Evaluates to `TRUE` iff apr_err (of type apr_status_t) is in the given category, which should be one of the `SVN_ERR_*_CATEGORY_START` constants. More...
#define | SVN_ERR_MALFUNCTION()
| Report that an internal malfunction has occurred, and possibly terminate the program. More...
#define | SVN_ERR_MALFUNCTION_NO_RETURN()
| Similar to SVN_ERR_MALFUNCTION(), but without the option of returning an error to the calling function. More...
#define | SVN_ERR_ASSERT_E(expr, err)
| Like SVN_ERR_ASSERT(), but append ERR to the returned error chain. More...
#define | SVN_ERR_ASSERT(expr)
| Check that a condition is true: if not, report an error and possibly terminate the program. More...
#define | SVN_ERR_ASSERT_NO_RETURN(expr)
| Similar to SVN_ERR_ASSERT(), but without the option of returning an error to the calling function. More...
#define | SVN__NOT_IMPLEMENTED() return svn_error__malfunction(TRUE, __FILE__, __LINE__, "Not implemented.")
| Report a "Not implemented" malfunction. More...

## Typedefs

typedef svn_error_t *(* | svn_error_malfunction_handler_t) (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. More...

## Functions

char * | svn_strerror (apr_status_t statcode, char *buf, apr_size_t bufsize)
| Put an English description of statcode into buf and return buf, NULL-terminated. More...
const char * | svn_error_symbolic_name (apr_status_t statcode)
| Return the symbolic name of an error code. More...
const char * | svn_err_best_message (const svn_error_t *err, char *buf, apr_size_t bufsize)
| If err has a custom error message, return that, otherwise store the generic error string associated with err->apr_err into buf (terminating with NULL) and return buf. More...
svn_error_t * | svn_error_create (apr_status_t apr_err, svn_error_t *child, const char *message)
| Create a nested exception structure. More...
svn_error_t * | svn_error_createf (apr_status_t apr_err, svn_error_t *child, const char *fmt,...)
| Create an error structure with the given apr_err and child, with a printf-style error message produced by passing fmt, using apr_psprintf().
svn_error_t * | svn_error_wrap_apr (apr_status_t status, const char *fmt,...)
| Wrap a status from an APR function. More...
svn_error_t * | svn_error_quick_wrap (svn_error_t *child, const char *new_msg)
| If child is SVN_NO_ERROR, return SVN_NO_ERROR. More...
svn_error_t * | svn_error_quick_wrapf (svn_error_t *child, const char *fmt,...)
| Like svn_error_quick_wrap(), but with format string support. More...
svn_error_t * | svn_error_compose_create (svn_error_t *err1, svn_error_t *err2)
| Compose two errors, returning the composition as a brand new error and consuming the original errors. More...
void | svn_error_compose (svn_error_t *chain, svn_error_t *new_err)
| Add new_err to the end of chain's chain of errors. More...
svn_error_t * | svn_error_root_cause (svn_error_t *err)
| Return the root cause of err by finding the last error in its chain (e.g. More...
svn_error_t * | svn_error_find_cause (svn_error_t *err, apr_status_t apr_err)
| Return the first error in err's chain that has an error code apr_err or SVN_NO_ERROR if there is no error with that code. More...
svn_error_t * | svn_error_dup (const svn_error_t *err)
| Create a new error that is a deep copy of err and return it. More...
void | svn_error_clear (svn_error_t *error)
| Free the memory used by error, as well as all ancestors and descendants of error. More...
void | svn_handle_error2 (svn_error_t *error, FILE *stream, svn_boolean_t fatal, const char *prefix)
| Very basic default error handler: print out error stack error to the stdio stream stream, with each error prefixed by prefix; quit and clear error iff the fatal flag is set. More...
void | svn_handle_error (svn_error_t *error, FILE *stream, svn_boolean_t fatal)
| Like svn_handle_error2() but with `prefix` set to "svn: ". More...
void | svn_handle_warning2 (FILE *stream, const svn_error_t *error, const char *prefix)
| Very basic default warning handler: print out the error error to the stdio stream stream, prefixed by prefix. More...
void | svn_handle_warning (FILE *stream, svn_error_t *error)
| Like svn_handle_warning2() but with `prefix` set to "svn: ". More...
svn_error_t * | svn_error_purge_tracing (svn_error_t *err)
| Returns an error chain that is based on err's error chain but does not include any error tracing placeholders. More...
svn_error_t * | svn_error__malfunction (svn_boolean_t can_return, const char *file, int line, const char *expr)
| A helper function for the macros that report malfunctions. More...
svn_error_malfunction_handler_t | svn_error_set_malfunction_handler (svn_error_malfunction_handler_t func)
| Cause subsequent malfunctions to be handled by func. More...
svn_error_malfunction_handler_t | svn_error_get_malfunction_handler (void)
| Return the malfunction handler that is currently in effect. More...
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 returning an error object that describes it. More...
svn_error_t * | svn_error_abort_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. More...

## Detailed Description

Common exception handling for Subversion.

# @if copyrights

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations

# under the License.

Definition in file svn_error.h.

## Function Documentation

## svn_err_best_message()

const char* svn_err_best_message | ( | const svn_error_t * | err,
|  | char * | buf,
|  | apr_size_t | bufsize
| ) |  |

If err has a custom error message, return that, otherwise store the generic error string associated with err->apr_err into buf (terminating with NULL) and return buf.

Since
  New in 1.4.

Note
  buf and bufsize are provided in the interface so that this function is thread-safe and yet does no allocation.

## svn_error_symbolic_name()

const char* svn_error_symbolic_name | ( | apr_status_t | statcode | ) |

Return the symbolic name of an error code.

If the error code is in svn_error_codes.h, return the name of the macro as a string. If the error number is not recognised, return `NULL`.

An error number may not be recognised because it was defined in a future version of Subversion (e.g., a 1.9.x server may transmit a defined-in-1.9.0 error number to a 1.8.x client).

An error number may be recognised incorrectly if the `apr_status_t` value originates in another library (such as libserf) which also uses APR. (This is a theoretical concern only: the `apr_err` member of svn_error_t should never contain a "foreign" `apr_status_t` value, and in any case Subversion and Serf use non-overlapping subsets of the `APR_OS_START_USERERR` range.)

Support for error codes returned by APR itself (i.e., not in the `APR_OS_START_USERERR` range, as defined in apr_errno.h) may be implemented in the future.

Note
  In rare cases, a single numeric code has more than one symbolic name. (For example, SVN_ERR_WC_NOT_DIRECTORY and SVN_ERR_WC_NOT_WORKING_COPY). In those cases, it is not guaranteed which symbolic name is returned.

Since
  New in 1.8.

## svn_strerror()

char* svn_strerror | ( | apr_status_t | statcode,
|  | char * | buf,
|  | apr_size_t | bufsize
| ) |  |

Put an English description of statcode into buf and return buf, NULL-terminated.

statcode is either an svn error or apr error.