← Back to branch summary

~svn/ubuntu/oneiric/subversion/ppa

« back to all changes in this revision

Viewing changes to subversion/include/svn_error.h

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-12-05 01:26:14 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051205012614-qom4xfypgtsqc2xq
Tags: 1.2.3dfsg1-3ubuntu1
Merge with the final Debian release of 1.2.3dfsg1-3, bringing in
fixes to the clean target, better documentation of the libdb4.3
upgrade and build fixes to work with swig1.3_1.3.27.

Show diffs side-by-side

added added

removed removed

Lines of Context:
subversion/include/svn_error.h
 
1
/**
 
2
 * @copyright
 
3
 * ====================================================================
 
4
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 
5
 *
 
6
 * This software is licensed as described in the file COPYING, which
 
7
 * you should have received as part of this distribution.  The terms
 
8
 * are also available at http://subversion.tigris.org/license-1.html.
 
9
 * If newer versions of this license are posted there, you may use a
 
10
 * newer version instead, at your option.
 
11
 *
 
12
 * This software consists of voluntary contributions made by many
 
13
 * individuals.  For exact contribution history, see the revision
 
14
 * history and logs, available at http://subversion.tigris.org/.
 
15
 * ====================================================================
 
16
 * @endcopyright
 
17
 *
 
18
 * @file svn_error.h
 
19
 * @brief Common exception handling for Subversion.
 
20
 */
 
21
 
 
22
 
 
23
 
 
24
 
 
25
#ifndef SVN_ERROR_H
 
26
#define SVN_ERROR_H
 
27
 
 
28
#include <apr.h>
 
29
#include <apr_errno.h>     /* APR's error system */
 
30
#include <apr_pools.h>
 
31
 
 
32
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
33
#define APR_WANT_STDIO
 
34
#endif
 
35
#include <apr_want.h>
 
36
 
 
37
#include "svn_types.h"
 
38
 
 
39
#ifdef __cplusplus
 
40
extern "C" {
 
41
#endif /* __cplusplus */
 
42
 
 
43
/** the best kind of (@c svn_error_t *) ! */
 
44
#define SVN_NO_ERROR   0
 
45
 
 
46
/* The actual error codes are kept in a separate file; see comments
 
47
   there for the reasons why. */
 
48
#include "svn_error_codes.h"
 
49
 
 
50
/** Set the error location for debug mode. */
 
51
void svn_error__locate (const char *file, long line);
 
52
 
 
53
 
 
54
/** Put an English description of @a statcode into @a buf and return @a buf,
 
55
 * null-terminated, @a statcode is either an svn error or apr error.
 
56
 */
 
57
char *svn_strerror (apr_status_t statcode, char *buf, apr_size_t bufsize);
 
58
 
 
59
 
 
60
 
 
61
/** SVN error creation and destruction. 
 
62
 *
 
63
 * @defgroup svn_error_error_creation_destroy error creation and destruction
 
64
 * @{
 
65
 */
 
66
 
 
67
/** Create a nested exception structure.
 
68
 *
 
69
 * Input:  an APR or SVN custom error code,
 
70
 *         a "child" error to wrap,
 
71
 *         a specific message
 
72
 *
 
73
 * Returns:  a new error structure (containing the old one).
 
74
 *
 
75
 * Notes: Errors are always allocated in a subpool of the global pool,
 
76
 *        since an error's lifetime is generally not related to the
 
77
 *        lifetime of any convenient pool.  Errors must be freed
 
78
 *        with @c svn_error_clear().  The specific message should be NULL
 
79
 *        if there is nothing to add to the general message associated
 
80
 *        with the error code.
 
81
 *
 
82
 *        If creating the "bottommost" error in a chain, pass @c NULL for
 
83
 *        the child argument.
 
84
 */
 
85
svn_error_t *svn_error_create (apr_status_t apr_err,
 
86
                               svn_error_t *child,
 
87
                               const char *message);
 
88
 
 
89
/** Wrapper macro to collect file and line information */
 
90
#define svn_error_create \
 
91
  (svn_error__locate(__FILE__,__LINE__), (svn_error_create))
 
92
 
 
93
/** Create an error structure with the given @a apr_err and @a child,
 
94
 * with a printf-style error message produced by passing @a fmt, using
 
95
 * @c apr_psprintf.
 
96
 */
 
97
svn_error_t *svn_error_createf (apr_status_t apr_err,
 
98
                                svn_error_t *child,
 
99
                                const char *fmt, 
 
100
                                ...)
 
101
       __attribute__ ((format (printf, 3, 4)));
 
102
 
 
103
/** Wrapper macro to collect file and line information */
 
104
#define svn_error_createf \
 
105
  (svn_error__locate(__FILE__,__LINE__), (svn_error_createf))
 
106
 
 
107
/** Wrap a status from an APR function.  If @a fmt is NULL, this is
 
108
 * equivalent to @c svn_error_create(status, NULL, NULL).  Otherwise,
 
109
 * the error message is constructed by formatting @a fmt and the
 
110
 * following arguments according to @c apr_psprintf, and then
 
111
 * appending ": " and the error message corresponding to @a status.
 
112
 * (If UTF-8 translation of the APR error message fails, the ": " and
 
113
 * APR error are not appended to the error message.)
 
114
 */
 
115
svn_error_t *svn_error_wrap_apr (apr_status_t status, const char *fmt, ...)
 
116
       __attribute__((format(printf, 2, 3)));
 
117
 
 
118
/** Wrapper macro to collect file and line information */
 
119
#define svn_error_wrap_apr \
 
120
  (svn_error__locate(__FILE__,__LINE__), (svn_error_wrap_apr))
 
121
 
 
122
/** A quick n' easy way to create a wrappered exception with your own
 
123
 * message, before throwing it up the stack.  (It uses all of the
 
124
 * child's fields.)
 
125
 */
 
126
svn_error_t *svn_error_quick_wrap (svn_error_t *child, const char *new_msg);
 
127
 
 
128
/** Wrapper macro to collect file and line information */
 
129
#define svn_error_quick_wrap \
 
130
  (svn_error__locate(__FILE__,__LINE__), (svn_error_quick_wrap))
 
131
 
 
132
/** Add @a new_err to the end of @a chain's chain of errors.  The @a new_err 
 
133
 * chain will be copied into @a chain's pool and destroyed, so @a new_err 
 
134
 * itself becomes invalid after this function.
 
135
 */
 
136
void svn_error_compose (svn_error_t *chain, svn_error_t *new_err);
 
137
 
 
138
/** @since New in 1.2.
 
139
 *
 
140
 * Create a new error that is a deep copy of err and return it. */
 
141
svn_error_t *svn_error_dup (svn_error_t *err);
 
142
 
 
143
/** Free the memory used by @a error, as well as all ancestors and
 
144
 * descendants of @a error. 
 
145
 *
 
146
 * Unlike other Subversion objects, errors are managed explicitly; you 
 
147
 * MUST clear an error if you are ignoring it, or you are leaking memory. 
 
148
 * For convenience, @a error may be @c NULL, in which case this function does 
 
149
 * nothing; thus, @c svn_error_clear(svn_foo(...)) works as an idiom to 
 
150
 * ignore errors.
 
151
 */
 
152
void svn_error_clear (svn_error_t *error);
 
153
 
 
154
 
 
155
/** @since New in 1.2
 
156
 *
 
157
 * Very basic default error handler: print out error stack @a error to the
 
158
 * stdio stream @a stream, with each error prefixed by @a prefix, and quit
 
159
 * iff the @a fatal flag is set.  Allocations are performed in the error's
 
160
 * pool.
 
161
 */
 
162
void svn_handle_error2 (svn_error_t *error,
 
163
                        FILE *stream,
 
164
                        svn_boolean_t fatal,
 
165
                        const char *prefix);
 
166
 
 
167
/** Like @c svn_handle_error2 but with @c prefix set to "svn: "
 
168
 */
 
169
void svn_handle_error (svn_error_t *error,
 
170
                       FILE *stream,
 
171
                       svn_boolean_t fatal);
 
172
 
 
173
/** @since New in 1.2
 
174
 *
 
175
 * Very basic default warning handler: print out the error @a error to the
 
176
 * stdio stream @a stream, prefixed by @a prefix.  Allocations are
 
177
 * performed in the error's pool.
 
178
 */
 
179
void svn_handle_warning2 (FILE *stream, svn_error_t *error, const char *prefix);
 
180
 
 
181
/** Like @c svn_handle_warning2 but with @c prefix set to "svn: "
 
182
 */
 
183
void svn_handle_warning (FILE *stream, svn_error_t *error);
 
184
 
 
185
 
 
186
/** A statement macro for checking error return values.
 
187
 *
 
188
 * Evaluate @a expr.  If it yields an error, return that error from the
 
189
 * current function.  Otherwise, continue.
 
190
 *
 
191
 * The <tt>do { ... } while (0)</tt> wrapper has no semantic effect, 
 
192
 * but it makes this macro syntactically equivalent to the expression
 
193
 * statement it resembles.  Without it, statements like
 
194
 *
 
195
 * <tt>
 
196
 *   if (a)
 
197
 *     SVN_ERR (some operation);
 
198
 *   else
 
199
 *     foo;
 
200
 * </tt>
 
201
 *
 
202
 * would not mean what they appear to.
 
203
 */
 
204
#define SVN_ERR(expr)                           \
 
205
  do {                                          \
 
206
    svn_error_t *svn_err__temp = (expr);        \
 
207
    if (svn_err__temp)                          \
 
208
      return svn_err__temp;                     \
 
209
  } while (0)
 
210
 
 
211
 
 
212
/** A statement macro, very similar to @c SVN_ERR.
 
213
 *
 
214
 * This macro will wrap the error with the specified text before 
 
215
 * returning the error.
 
216
 */
 
217
#define SVN_ERR_W(expr, wrap_msg)                           \
 
218
  do {                                                      \
 
219
    svn_error_t *svn_err__temp = (expr);                    \
 
220
    if (svn_err__temp)                                      \
 
221
      return svn_error_quick_wrap(svn_err__temp, wrap_msg); \
 
222
  } while (0)
 
223
 
 
224
 
 
225
/** A statement macro, similar to @c SVN_ERR, but returns an integer.
 
226
 *
 
227
 * Evaluate @a expr. If it yields an error, handle that error and
 
228
 * return @c EXIT_FAILURE.
 
229
 */
 
230
#define SVN_INT_ERR(expr)                                   \
 
231
  do {                                                      \
 
232
    svn_error_t *svn_err__temp = (expr);                    \
 
233
    if (svn_err__temp) {                                    \
 
234
      svn_handle_error (svn_err__temp, stderr, FALSE);      \
 
235
      svn_error_clear (svn_err__temp);                      \
 
236
      return EXIT_FAILURE; }                                \
 
237
  } while (0)
 
238
 
 
239
/** @} */
 
240
 
 
241
/**
 
242
 * @since New in 1.2.  
 
243
 *
 
244
 * Return TRUE if @a err is an error specifically related to locking a
 
245
 * path in the repository, FALSE otherwise. 
 
246
 *
 
247
 * SVN_ERR_FS_OUT_OF_DATE is in here because it's a non-fatal error
 
248
 * that can be thrown when attempting to lock an item.
 
249
 */
 
250
#define SVN_ERR_IS_LOCK_ERROR(err)                          \
 
251
  (err->apr_err == SVN_ERR_FS_PATH_ALREADY_LOCKED ||        \
 
252
   err->apr_err == SVN_ERR_FS_OUT_OF_DATE)                  \
 
253
 
 
254
/**
 
255
 * @since New in 1.2.  
 
256
 *
 
257
 * Return TRUE if @a err is an error specifically related to unlocking
 
258
 * a path in the repository, FALSE otherwise. */
 
259
#define SVN_ERR_IS_UNLOCK_ERROR(err)                        \
 
260
  (err->apr_err == SVN_ERR_FS_PATH_NOT_LOCKED ||            \
 
261
   err->apr_err == SVN_ERR_FS_BAD_LOCK_TOKEN ||             \
 
262
   err->apr_err == SVN_ERR_FS_LOCK_OWNER_MISMATCH ||        \
 
263
   err->apr_err == SVN_ERR_FS_NO_SUCH_LOCK ||               \
 
264
   err->apr_err == SVN_ERR_RA_NOT_LOCKED ||                 \
 
265
   err->apr_err == SVN_ERR_FS_LOCK_EXPIRED)
 
266
 
 
267
 
 
268
#ifdef __cplusplus
 
269
}
 
270
#endif /* __cplusplus */
 
271
 
 
272
#endif /* SVN_ERROR_H */