=head1 NAME APR::Status - Perl Interface to the APR_STATUS_IS_* macros =head1 Synopsis use APR::Status (); eval { $obj->mp_method() }; if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) { # APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied } =head1 Description An interface to F composite error codes. As discussed in the C> manpage, it is possible to handle APR/Apache/mod_perl exceptions in the following way: eval { $obj->mp_method() }; if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code) warn "handled exception: $@"; } However, in cases where C<$some_code> is an L, there may be more than one condition satisfying the intent of this exception. For this purpose the APR C library provides in F a series of macros, C, which are the recommended way to check for such conditions. For example, the C macro is defined as #define APR_STATUS_IS_EAGAIN(s) ((s) == APR_EAGAIN \ || (s) == APR_OS_START_SYSERR + ERROR_NO_DATA \ || (s) == APR_OS_START_SYSERR + SOCEWOULDBLOCK \ || (s) == APR_OS_START_SYSERR + ERROR_LOCK_VIOLATION) The purpose of C is to provide functions corresponding to these macros. =head1 Functions =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_EACCES($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back An example of using C is when reading the contents of a file where access may be forbidden: eval { $obj->slurp_filename(0) }; if ($@) { return Apache2::Const::FORBIDDEN if ref $@ eq 'APR::Error' && APR::Status::is_EACCES($@); die $@; } Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_EAGAIN($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back For example, here is how you may want to handle socket read exceptions and do retries: use APR::Status (); # .... my $tries = 0; my $buffer; RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) }; if ($@ && ref($@) && APR::Status::is_EAGAIN($@)) { if ($tries++ < 3) { goto RETRY; } else { # do something else } } else { die "eval block has failed: $@"; } Notice that just checking against C> may work on some Unices, but then it will certainly break on win32. Thefore make sure to use this macro and not C unless you know what you are doing. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_ENOENT($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back An example of using C is when reading the contents of a file which may not exist: eval { $obj->slurp_filename(0) }; if ($@) { return Apache2::Const::NOT_FOUND if ref $@ eq 'APR::Error' && APR::Status::is_ENOENT($@); die $@; } Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_EOF($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_ECONNABORTED($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_ECONNRESET($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head2 C Check if the error is matching C and its variants (corresponds to the C macro). $status = APR::Status::is_TIMEUP($error_code); =over 4 =item arg1: C<$error_code> (integer or C> ) The error code or to check, normally C<$@> blessed into C>. =item ret: C<$status> ( boolean ) =item since: 2.0.00 =back Due to possible variants in conditions matching C, the use of this function is recommended for checking error codes against this value, rather than just using C> directly. =head1 See Also L. =head1 Copyright mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0. =head1 Authors L. =cut