APR::Status(3pm)

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

Copyright

206       mod_perl 2.0 and its core modules are copyrighted under The Apache
207       Software License, Version 2.0.
208

Authors

210       The mod_perl development team and numerous contributors.
211
212
213
214perl v5.36.0                      2023-01-19         docs::api::APR::Status(3)

NAME

Synopsis

Description

Functions

See Also

Copyright

Authors