1docs::api::APR::Status(U3s)er Contributed Perl Documentatdioocns::api::APR::Status(3)
2
3
4

NAME

6       APR::Status - Perl Interface to the APR_STATUS_IS_* macros
7

Synopsis

9         use APR::Status ();
10         eval { $obj->mp_method() };
11         if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
12             # APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
13         }
14

Description

16       An interface to apr_errno.h composite error codes.
17
18       As discussed in the "APR::Error" manpage, it is possible to handle
19       APR/Apache/mod_perl exceptions in the following way:
20
21         eval { $obj->mp_method() };
22         if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
23             warn "handled exception: $@";
24         }
25
26       However, in cases where $some_code is an APR::Const constant, there may
27       be more than one condition satisfying the intent of this exception. For
28       this purpose the APR C library provides in apr_errno.h a series of
29       macros, "APR_STATUS_IS_*", which are the recommended way to check for
30       such conditions. For example, the "APR_STATUS_IS_EAGAIN" macro is
31       defined as
32
33         #define APR_STATUS_IS_EAGAIN(s)         ((s) == APR_EAGAIN \
34                         ⎪⎪ (s) == APR_OS_START_SYSERR + ERROR_NO_DATA \
35                         ⎪⎪ (s) == APR_OS_START_SYSERR + SOCEWOULDBLOCK \
36                         ⎪⎪ (s) == APR_OS_START_SYSERR + ERROR_LOCK_VIOLATION)
37
38       The purpose of "APR::Status" is to provide functions corresponding to
39       these macros.
40

Functions

42       "is_EACCES"
43
44       Check if the error is matching "EACCES" and its variants (corresponds
45       to the "APR_STATUS_IS_EACCES" macro).
46
47         $status = APR::Status::is_EACCES($error_code);
48
49       arg1: $error_code (integer or "APR::Error object" )
50           The error code or to check, normally $@ blessed into "APR::Error
51           object".
52
53       ret: $status ( boolean )
54       since: 2.0.00
55
56       An example of using "is_EACCES" is when reading the contents of a file
57       where access may be forbidden:
58
59         eval { $obj->slurp_filename(0) };
60         if ($@) {
61             return Apache2::Const::FORBIDDEN
62                 if ref $@ eq 'APR::Error' && APR::Status::is_EACCES($@);
63             die $@;
64          }
65
66       Due to possible variants in conditions matching "EACCES", the use of
67       this function is recommended for checking error codes against this
68       value, rather than just using "APR::Const::EACCES" directly.
69
70       "is_EAGAIN"
71
72       Check if the error is matching "EAGAIN" and its variants (corresponds
73       to the "APR_STATUS_IS_EAGAIN" macro).
74
75         $status = APR::Status::is_EAGAIN($error_code);
76
77       arg1: $error_code (integer or "APR::Error object" )
78           The error code or to check, normally $@ blessed into "APR::Error
79           object".
80
81       ret: $status ( boolean )
82       since: 2.0.00
83
84       For example, here is how you may want to handle socket read exceptions
85       and do retries:
86
87         use APR::Status ();
88         # ....
89         my $tries = 0;
90         my $buffer;
91         RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
92         if ($@ && ref($@) && APR::Status::is_EAGAIN($@)) {
93             if ($tries++ < 3) {
94                 goto RETRY;
95             }
96             else {
97                 # do something else
98             }
99         }
100         else {
101             die "eval block has failed: $@";
102         }
103
104       Notice that just checking against "APR::Const::EAGAIN" may work on some
105       Unices, but then it will certainly break on win32. Thefore make sure to
106       use this macro and not "APR::Const::EAGAIN" unless you know what you
107       are doing.
108
109       "is_ENOENT"
110
111       Check if the error is matching "ENOENT" and its variants (corresponds
112       to the "APR_STATUS_IS_ENOENT" macro).
113
114         $status = APR::Status::is_ENOENT($error_code);
115
116       arg1: $error_code (integer or "APR::Error object" )
117           The error code or to check, normally $@ blessed into "APR::Error
118           object".
119
120       ret: $status ( boolean )
121       since: 2.0.00
122
123       An example of using "is_ENOENT" is when reading the contents of a file
124       which may not exist:
125
126         eval { $obj->slurp_filename(0) };
127         if ($@) {
128             return Apache2::Const::NOT_FOUND
129                 if ref $@ eq 'APR::Error' && APR::Status::is_ENOENT($@);
130             die $@;
131         }
132
133       Due to possible variants in conditions matching "ENOENT", the use of
134       this function is recommended for checking error codes against this
135       value, rather than just using "APR::Const::ENOENT" directly.
136
137       "is_EOF"
138
139       Check if the error is matching "EOF" and its variants (corresponds to
140       the "APR_STATUS_IS_EOF" macro).
141
142         $status = APR::Status::is_EOF($error_code);
143
144       arg1: $error_code (integer or "APR::Error object" )
145           The error code or to check, normally $@ blessed into "APR::Error
146           object".
147
148       ret: $status ( boolean )
149       since: 2.0.00
150
151       Due to possible variants in conditions matching "EOF", the use of this
152       function is recommended for checking error codes against this value,
153       rather than just using "APR::Const::EOF" directly.
154
155       "is_ECONNABORTED"
156
157       Check if the error is matching "ECONNABORTED" and its variants (corre‐
158       sponds to the "APR_STATUS_IS_ECONNABORTED" macro).
159
160         $status = APR::Status::is_ECONNABORTED($error_code);
161
162       arg1: $error_code (integer or "APR::Error object" )
163           The error code or to check, normally $@ blessed into "APR::Error
164           object".
165
166       ret: $status ( boolean )
167       since: 2.0.00
168
169       Due to possible variants in conditions matching "ECONNABORTED", the use
170       of this function is recommended for checking error codes against this
171       value, rather than just using "APR::Const::ECONNABORTED" directly.
172
173       "is_ECONNRESET"
174
175       Check if the error is matching "ECONNRESET" and its variants (corre‐
176       sponds to the "APR_STATUS_IS_ECONNRESET" macro).
177
178         $status = APR::Status::is_ECONNRESET($error_code);
179
180       arg1: $error_code (integer or "APR::Error object" )
181           The error code or to check, normally $@ blessed into "APR::Error
182           object".
183
184       ret: $status ( boolean )
185       since: 2.0.00
186
187       Due to possible variants in conditions matching "ECONNRESET", the use
188       of this function is recommended for checking error codes against this
189       value, rather than just using "APR::Const::ECONNRESET" directly.
190
191       "is_TIMEUP"
192
193       Check if the error is matching "TIMEUP" and its variants (corresponds
194       to the "APR_STATUS_IS_TIMEUP" macro).
195
196         $status = APR::Status::is_TIMEUP($error_code);
197
198       arg1: $error_code (integer or "APR::Error object" )
199           The error code or to check, normally $@ blessed into "APR::Error
200           object".
201
202       ret: $status ( boolean )
203       since: 2.0.00
204
205       Due to possible variants in conditions matching "TIMEUP", the use of
206       this function is recommended for checking error codes against this
207       value, rather than just using "APR::Const::TIMEUP" directly.
208

See Also

210       mod_perl 2.0 documentation.
211

213       mod_perl 2.0 and its core modules are copyrighted under The Apache
214       Software License, Version 2.0.
215

Authors

217       The mod_perl development team and numerous contributors.
218
219
220
221perl v5.8.8                       2006-11-19         docs::api::APR::Status(3)
Impressum