Apache Portable Runtime
apr_errno.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef APR_ERRNO_H
18 #define APR_ERRNO_H
19 
20 /**
21  * @file apr_errno.h
22  * @brief APR Error Codes
23  */
24 
25 #include "apr.h"
26 
27 #if APR_HAVE_ERRNO_H
28 #include <errno.h>
29 #endif
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif /* __cplusplus */
34 
35 /**
36  * @defgroup apr_errno Error Codes
37  * @ingroup APR
38  * @{
39  */
40 
41 /**
42  * Type for specifying an error or status code.
43  */
44 typedef int apr_status_t;
45 
46 /**
47  * Return a human readable string describing the specified error.
48  * @param statcode The error code to get a string for.
49  * @param buf A buffer to hold the error string.
50  * @param bufsize Size of the buffer to hold the string.
51  */
52 APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf,
53  apr_size_t bufsize);
54 
55 #if defined(DOXYGEN)
56 /**
57  * @def APR_FROM_OS_ERROR(os_err_type syserr)
58  * Fold a platform specific error into an apr_status_t code.
59  * @return apr_status_t
60  * @param e The platform os error code.
61  * @warning macro implementation; the syserr argument may be evaluated
62  * multiple times.
63  */
64 #define APR_FROM_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e + APR_OS_START_SYSERR)
65 
66 /**
67  * @def APR_TO_OS_ERROR(apr_status_t statcode)
68  * @return os_err_type
69  * Fold an apr_status_t code back to the native platform defined error.
70  * @param e The apr_status_t folded platform os error code.
71  * @warning macro implementation; the statcode argument may be evaluated
72  * multiple times. If the statcode was not created by apr_get_os_error
73  * or APR_FROM_OS_ERROR, the results are undefined.
74  */
75 #define APR_TO_OS_ERROR(e) (e == 0 ? APR_SUCCESS : e - APR_OS_START_SYSERR)
76 
77 /** @def apr_get_os_error()
78  * @return apr_status_t the last platform error, folded into apr_status_t, on most platforms
79  * @remark This retrieves errno, or calls a GetLastError() style function, and
80  * folds it with APR_FROM_OS_ERROR. Some platforms (such as OS2) have no
81  * such mechanism, so this call may be unsupported. Do NOT use this
82  * call for socket errors from socket, send, recv etc!
83  */
84 
85 /** @def apr_set_os_error(e)
86  * Reset the last platform error, unfolded from an apr_status_t, on some platforms
87  * @param e The OS error folded in a prior call to APR_FROM_OS_ERROR()
88  * @warning This is a macro implementation; the statcode argument may be evaluated
89  * multiple times. If the statcode was not created by apr_get_os_error
90  * or APR_FROM_OS_ERROR, the results are undefined. This macro sets
91  * errno, or calls a SetLastError() style function, unfolding statcode
92  * with APR_TO_OS_ERROR. Some platforms (such as OS2) have no such
93  * mechanism, so this call may be unsupported.
94  */
95 
96 /** @def apr_get_netos_error()
97  * Return the last socket error, folded into apr_status_t, on all platforms
98  * @remark This retrieves errno or calls a GetLastSocketError() style function,
99  * and folds it with APR_FROM_OS_ERROR.
100  */
101 
102 /** @def apr_set_netos_error(e)
103  * Reset the last socket error, unfolded from an apr_status_t
104  * @param e The socket error folded in a prior call to APR_FROM_OS_ERROR()
105  * @warning This is a macro implementation; the statcode argument may be evaluated
106  * multiple times. If the statcode was not created by apr_get_os_error
107  * or APR_FROM_OS_ERROR, the results are undefined. This macro sets
108  * errno, or calls a WSASetLastError() style function, unfolding
109  * socketcode with APR_TO_OS_ERROR.
110  */
111 
112 #endif /* defined(DOXYGEN) */
113 
114 /**
115  * APR_OS_START_ERROR is where the APR specific error values start.
116  */
117 #define APR_OS_START_ERROR 20000
118 /**
119  * APR_OS_ERRSPACE_SIZE is the maximum number of errors you can fit
120  * into one of the error/status ranges below -- except for
121  * APR_OS_START_USERERR, which see.
122  */
123 #define APR_OS_ERRSPACE_SIZE 50000
124 /**
125  * APR_UTIL_ERRSPACE_SIZE is the size of the space that is reserved for
126  * use within apr-util. This space is reserved above that used by APR
127  * internally.
128  * @note This number MUST be smaller than APR_OS_ERRSPACE_SIZE by a
129  * large enough amount that APR has sufficient room for its
130  * codes.
131  */
132 #define APR_UTIL_ERRSPACE_SIZE 20000
133 /**
134  * APR_OS_START_STATUS is where the APR specific status codes start.
135  */
136 #define APR_OS_START_STATUS (APR_OS_START_ERROR + APR_OS_ERRSPACE_SIZE)
137 /**
138  * APR_UTIL_START_STATUS is where APR-Util starts defining its
139  * status codes.
140  */
141 #define APR_UTIL_START_STATUS (APR_OS_START_STATUS + \
142  (APR_OS_ERRSPACE_SIZE - APR_UTIL_ERRSPACE_SIZE))
143 /**
144  * APR_OS_START_USERERR are reserved for applications that use APR that
145  * layer their own error codes along with APR's. Note that the
146  * error immediately following this one is set ten times farther
147  * away than usual, so that users of apr have a lot of room in
148  * which to declare custom error codes.
149  *
150  * In general applications should try and create unique error codes. To try
151  * and assist in finding suitable ranges of numbers to use, the following
152  * ranges are known to be used by the listed applications. If your
153  * application defines error codes please advise the range of numbers it
154  * uses to dev@apr.apache.org for inclusion in this list.
155  *
156  * Ranges shown are in relation to APR_OS_START_USERERR
157  *
158  * Subversion - Defined ranges, of less than 100, at intervals of 5000
159  * starting at an offset of 5000, e.g.
160  * +5000 to 5100, +10000 to 10100
161  *
162  * Apache HTTPD - +2000 to 2999
163  */
164 #define APR_OS_START_USERERR (APR_OS_START_STATUS + APR_OS_ERRSPACE_SIZE)
165 /**
166  * APR_OS_START_USEERR is obsolete, defined for compatibility only.
167  * Use APR_OS_START_USERERR instead.
168  */
169 #define APR_OS_START_USEERR APR_OS_START_USERERR
170 /**
171  * APR_OS_START_CANONERR is where APR versions of errno values are defined
172  * on systems which don't have the corresponding errno.
173  */
174 #define APR_OS_START_CANONERR (APR_OS_START_USERERR \
175  + (APR_OS_ERRSPACE_SIZE * 10))
176 /**
177  * APR_OS_START_EAIERR folds EAI_ error codes from getaddrinfo() into
178  * apr_status_t values.
179  */
180 #define APR_OS_START_EAIERR (APR_OS_START_CANONERR + APR_OS_ERRSPACE_SIZE)
181 /**
182  * APR_OS_START_SYSERR folds platform-specific system error values into
183  * apr_status_t values.
184  */
185 #define APR_OS_START_SYSERR (APR_OS_START_EAIERR + APR_OS_ERRSPACE_SIZE)
186 
187 /**
188  * @defgroup APR_ERROR_map APR Error Space
189  * <PRE>
190  * The following attempts to show the relation of the various constants
191  * used for mapping APR Status codes.
192  *
193  * 0
194  *
195  * 20,000 APR_OS_START_ERROR
196  *
197  * + APR_OS_ERRSPACE_SIZE (50,000)
198  *
199  * 70,000 APR_OS_START_STATUS
200  *
201  * + APR_OS_ERRSPACE_SIZE - APR_UTIL_ERRSPACE_SIZE (30,000)
202  *
203  * 100,000 APR_UTIL_START_STATUS
204  *
205  * + APR_UTIL_ERRSPACE_SIZE (20,000)
206  *
207  * 120,000 APR_OS_START_USERERR
208  *
209  * + 10 x APR_OS_ERRSPACE_SIZE (50,000 * 10)
210  *
211  * 620,000 APR_OS_START_CANONERR
212  *
213  * + APR_OS_ERRSPACE_SIZE (50,000)
214  *
215  * 670,000 APR_OS_START_EAIERR
216  *
217  * + APR_OS_ERRSPACE_SIZE (50,000)
218  *
219  * 720,000 APR_OS_START_SYSERR
220  *
221  * </PRE>
222  */
223 
224 /** no error. */
225 #define APR_SUCCESS 0
226 
227 /**
228  * @defgroup APR_Error APR Error Values
229  * <PRE>
230  * <b>APR ERROR VALUES</b>
231  * APR_ENOSTAT APR was unable to perform a stat on the file
232  * APR_ENOPOOL APR was not provided a pool with which to allocate memory
233  * APR_EBADDATE APR was given an invalid date
234  * APR_EINVALSOCK APR was given an invalid socket
235  * APR_ENOPROC APR was not given a process structure
236  * APR_ENOTIME APR was not given a time structure
237  * APR_ENODIR APR was not given a directory structure
238  * APR_ENOLOCK APR was not given a lock structure
239  * APR_ENOPOLL APR was not given a poll structure
240  * APR_ENOSOCKET APR was not given a socket
241  * APR_ENOTHREAD APR was not given a thread structure
242  * APR_ENOTHDKEY APR was not given a thread key structure
243  * APR_ENOSHMAVAIL There is no more shared memory available
244  * APR_EDSOOPEN APR was unable to open the dso object. For more
245  * information call apr_dso_error().
246  * APR_EGENERAL General failure (specific information not available)
247  * APR_EBADIP The specified IP address is invalid
248  * APR_EBADMASK The specified netmask is invalid
249  * APR_ESYMNOTFOUND Could not find the requested symbol
250  * APR_ENOTENOUGHENTROPY Not enough entropy to continue
251  * </PRE>
252  *
253  * <PRE>
254  * <b>APR STATUS VALUES</b>
255  * APR_INCHILD Program is currently executing in the child
256  * APR_INPARENT Program is currently executing in the parent
257  * APR_DETACH The thread is detached
258  * APR_NOTDETACH The thread is not detached
259  * APR_CHILD_DONE The child has finished executing
260  * APR_CHILD_NOTDONE The child has not finished executing
261  * APR_TIMEUP The operation did not finish before the timeout
262  * APR_INCOMPLETE The operation was incomplete although some processing
263  * was performed and the results are partially valid
264  * APR_BADCH Getopt found an option not in the option string
265  * APR_BADARG Getopt found an option that is missing an argument
266  * and an argument was specified in the option string
267  * APR_EOF APR has encountered the end of the file
268  * APR_NOTFOUND APR was unable to find the socket in the poll structure
269  * APR_ANONYMOUS APR is using anonymous shared memory
270  * APR_FILEBASED APR is using a file name as the key to the shared memory
271  * APR_KEYBASED APR is using a shared key as the key to the shared memory
272  * APR_EINIT Ininitalizer value. If no option has been found, but
273  * the status variable requires a value, this should be used
274  * APR_ENOTIMPL The APR function has not been implemented on this
275  * platform, either because nobody has gotten to it yet,
276  * or the function is impossible on this platform.
277  * APR_EMISMATCH Two passwords do not match.
278  * APR_EABSOLUTE The given path was absolute.
279  * APR_ERELATIVE The given path was relative.
280  * APR_EINCOMPLETE The given path was neither relative nor absolute.
281  * APR_EABOVEROOT The given path was above the root path.
282  * APR_EBUSY The given lock was busy.
283  * APR_EPROC_UNKNOWN The given process wasn't recognized by APR
284  * </PRE>
285  * @{
286  */
287 /** @see APR_STATUS_IS_ENOSTAT */
288 #define APR_ENOSTAT (APR_OS_START_ERROR + 1)
289 /** @see APR_STATUS_IS_ENOPOOL */
290 #define APR_ENOPOOL (APR_OS_START_ERROR + 2)
291 /* empty slot: +3 */
292 /** @see APR_STATUS_IS_EBADDATE */
293 #define APR_EBADDATE (APR_OS_START_ERROR + 4)
294 /** @see APR_STATUS_IS_EINVALSOCK */
295 #define APR_EINVALSOCK (APR_OS_START_ERROR + 5)
296 /** @see APR_STATUS_IS_ENOPROC */
297 #define APR_ENOPROC (APR_OS_START_ERROR + 6)
298 /** @see APR_STATUS_IS_ENOTIME */
299 #define APR_ENOTIME (APR_OS_START_ERROR + 7)
300 /** @see APR_STATUS_IS_ENODIR */
301 #define APR_ENODIR (APR_OS_START_ERROR + 8)
302 /** @see APR_STATUS_IS_ENOLOCK */
303 #define APR_ENOLOCK (APR_OS_START_ERROR + 9)
304 /** @see APR_STATUS_IS_ENOPOLL */
305 #define APR_ENOPOLL (APR_OS_START_ERROR + 10)
306 /** @see APR_STATUS_IS_ENOSOCKET */
307 #define APR_ENOSOCKET (APR_OS_START_ERROR + 11)
308 /** @see APR_STATUS_IS_ENOTHREAD */
309 #define APR_ENOTHREAD (APR_OS_START_ERROR + 12)
310 /** @see APR_STATUS_IS_ENOTHDKEY */
311 #define APR_ENOTHDKEY (APR_OS_START_ERROR + 13)
312 /** @see APR_STATUS_IS_EGENERAL */
313