Error creation and destruction

SVN error creation and destruction. More...

## Macros

#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...

## Functions

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...

## Detailed Description

SVN error creation and destruction.

## Macro Definition Documentation

## SVN_ERR

#define SVN_ERR | ( |  | expr | ) |

Value:
do { \
svn_error_t *svn_err__temp = (expr); \
if (svn_err__temp) \
return svn_error_trace(svn_err__temp); \
} while (0)
svn_error_trace
#define svn_error_trace(expr)
A macro for wrapping an error in a source-location trace message.
Definition: svn_error.h:373

A statement macro for checking error values.

Evaluate expr. If it yields an error, return that error from the current function. Otherwise, continue.

The `do { ... } while (0)` wrapper has no semantic effect, but it makes this macro syntactically equivalent to the expression statement it resembles. Without it, statements like

if (a)
SVN_ERR(some operation);
else
foo;
SVN_ERR
#define SVN_ERR(expr)
A statement macro for checking error values.
Definition: svn_error.h:351

would not mean what they appear to.

Definition at line 351 of file svn_error.h.

## SVN_ERR_W

#define SVN_ERR_W | ( |  | expr,
|  |  | wrap_msg
| ) |  |

Value:
do { \
svn_error_t *svn_err__temp = (expr); \
if (svn_err__temp) \
return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
} while (0)
svn_error_quick_wrap
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.

A statement macro, very similar to `SVN_ERR`.

This macro will wrap the error with the specified text before returning the error.

Definition at line 402 of file svn_error.h.

## svn_error_trace

#define svn_error_trace | ( |  | expr | ) | (expr)

A macro for wrapping an error in a source-location trace message.

This macro can be used when directly returning an already created error (when not using SVN_ERR, svn_error_create(), etc.) to ensure that the call stack is recorded correctly.

Since
  New in 1.7.

Definition at line 373 of file svn_error.h.

## SVN_INT_ERR

#define SVN_INT_ERR | ( |  | expr | ) |

Value:
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)
FALSE
#define FALSE
uhh...
Definition: svn_types.h:150

A statement macro intended for the main() function of the 'svn' program.

Evaluate expr. If it yields an error, display the error on stdout and return `EXIT_FAILURE`.

Note
  Not for use in the library, as it prints to stderr. This macro no longer suits the needs of the 'svn' program, and is not generally suitable for third-party use as it assumes the program name is 'svn'.

Deprecated:
  Provided for backward compatibility with the 1.8 API. Consider using svn_handle_error2() or svn_cmdline_handle_exit_error() instead.

Definition at line 422 of file svn_error.h.

## Function Documentation

## svn_error_clear()

void svn_error_clear | ( | svn_error_t * | error | ) |

Free the memory used by error, as well as all ancestors and descendants of 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, error may be `NULL`, in which case this function does nothing; thus, svn_error_clear(svn_foo(...)) works as an idiom to ignore errors.

## svn_error_compose()

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.

The new_err chain will be copied into chain's pool and destroyed, so new_err itself becomes invalid after this function.

Either chain or new_err can be functions that return svn_error_t* but if both are functions they can be evaluated in either order as per the C language rules.

## svn_error_compose_create()

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.

Either or both of err1 and err2 may be `SVN_NO_ERROR`. If both are not `SVN_NO_ERROR`, err2 will follow err1 in the chain of the returned error.

Either err1 or err2 can be functions that return svn_error_t* but if both are functions they can be evaluated in either order as per the C language rules.

Since
  New in 1.6.

## svn_error_create()

svn_error_t* svn_error_create | ( | apr_status_t | apr_err,
|  | svn_error_t * | child,
|  | const char * | message
| ) |  |

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 `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 `NULL` for the child argument.

## svn_error_dup()

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.

Since
  New in 1.2.

## svn_error_find_cause()

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.

The returned error should not be cleared as it shares memory with err.

If err is SVN_NO_ERROR, return SVN_NO_ERROR.

Since
  New in 1.7.

## svn_error_purge_tracing()

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.

err is not modified, except for any allocations using its pool.

The returned error chain is allocated from err's pool and shares its message and source filename character arrays. The returned error chain should not be cleared because it is not a fully fledged error chain, only clearing err should be done to clear the returned error chain. If err is cleared, then the returned error chain is unusable.

err can be SVN_NO_ERROR. If err is not SVN_NO_ERROR, then the last link in the error chain must be a non-tracing error, i.e, a real error.

Since
  New in 1.7.

## svn_error_quick_wrap()

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.

Else, prepend a new error to the error chain of child. The new error uses new_msg as error message but all other error attributes (such as the error code) are copied from child.

## svn_error_quick_wrapf()

svn_error_t* svn_error_quick_wrapf | ( | svn_error_t * | child,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Like svn_error_quick_wrap(), but with format string support.

Since
  New in 1.9.

## svn_error_root_cause()

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.

it or its children). err may be `SVN_NO_ERROR`, in which case `SVN_NO_ERROR` is returned. The returned error should not be cleared as it shares memory with err.

Since
  New in 1.5.

## svn_error_wrap_apr()

svn_error_t* svn_error_wrap_apr | ( | apr_status_t | status,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Wrap a status from an APR function.

If fmt is NULL, this is equivalent to svn_error_create(status,NULL,NULL). Otherwise, the error message is constructed by formatting fmt and the following arguments according to apr_psprintf(), and then appending ": " and the error message corresponding to status. (If UTF-8 translation of the APR error message fails, the ": " and APR error are not appended to the error message.)

## svn_handle_error()

void svn_handle_error | ( | svn_error_t * | error,
|  | FILE * | stream,
|  | svn_boolean_t | fatal
| ) |  |

Like svn_handle_error2() but with `prefix` set to "svn: ".

Deprecated:
  Provided for backward compatibility with the 1.1 API.

## svn_handle_error2()

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.

Allocations are performed in the 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.

Note that this should only be used from commandline specific code, or code that knows that stream is really where the application wants to receive its errors on.

Since
  New in 1.2.

## svn_handle_warning()

void svn_handle_warning | ( | FILE * | stream,
|  | svn_error_t * | error
| ) |  |

Like svn_handle_warning2() but with `prefix` set to "svn: ".

Deprecated:
  Provided for backward compatibility with the 1.1 API.

## svn_handle_warning2()

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.

Allocations are performed in the error's pool.

error may not be `NULL`.

Note
  This does not clear error.

Since
  New in 1.2.