view release on metacpan or  search on metacpan

src/subversion/subversion/include/svn_error.h  view on Meta::CPAN

/**
 * @copyright
 * ====================================================================
 *    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.
 * ====================================================================
 * @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 */


/* For the Subversion developers, this #define turns on extended "stack
   traces" of any errors that get thrown. See the SVN_ERR() macro.  */
#ifdef SVN_DEBUG
#define SVN_ERR__TRACING
#endif


/** 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"

/** 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);


/**
 * 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 @c 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 @em incorrectly if the @c apr_status_t
 * value originates in another library (such as libserf) which also uses APR.
 * (This is a theoretical concern only: the @c apr_err member of #svn_error_t
 * should never contain a "foreign" @c apr_status_t value, and
 * in any case Subversion and Serf use non-overlapping subsets of the
 * @c APR_OS_START_USERERR range.)
 *
 * Support for error codes returned by APR itself (i.e., not in the
 * @c 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.
 */
const char *
svn_error_symbolic_name(apr_status_t statcode);


/** 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);

/** 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)));

/** 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)));

/** A quick n' easy way to create a wrapped exception with your own