=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<apr_errno.h> composite error codes.

As discussed in the C<L<APR::Error|docs::2.0::api::APR::Error>>
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<APR::Const
constant|docs::2.0::api::APR::Const>, there may be more than one
condition satisfying the intent of this exception. For this purpose
the APR C library provides in F<apr_errno.h> a series of macros,
C<APR_STATUS_IS_*>, which are the recommended way to check for such
conditions. For example, the C<APR_STATUS_IS_EAGAIN> 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<APR::Status> is to provide functions corresponding
to these macros.






=head1 Functions




=head2 C<is_EACCES>

Check if the error is matching C<EACCES> and its variants (corresponds
to the C<APR_STATUS_IS_EACCES> macro).

  $status = APR::Status::is_EACCES($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

An example of using C<is_EACCES> 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<EACCES>,
the use of this function is recommended for checking error codes
against this value, rather than just using
C<L<APR::Const::EACCES|docs::2.0::api::APR::Const/C_APR__Const__EACCES_>>
directly.







=head2 C<is_EAGAIN>

Check if the error is matching C<EAGAIN> and its variants (corresponds
to the C<APR_STATUS_IS_EAGAIN> macro).

  $status = APR::Status::is_EAGAIN($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=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<L<APR::Const::EAGAIN|docs::2.0::api::APR::Const/C_APR__Const__EAGAIN_>>
may work on some Unices, but then it will certainly break on
win32. Thefore make sure to use this macro and not
C<APR::Const::EAGAIN> unless you know what you are doing.










=head2 C<is_ENOENT>

Check if the error is matching C<ENOENT> and its variants (corresponds
to the C<APR_STATUS_IS_ENOENT> macro).

  $status = APR::Status::is_ENOENT($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

An example of using C<is_ENOENT> 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<ENOENT>,
the use of this function is recommended for checking error codes
against this value, rather than just using
C<L<APR::Const::ENOENT|docs::2.0::api::APR::Const/C_APR__Const__ENOENT_>>
directly.









=head2 C<is_EOF>

Check if the error is matching C<EOF> and its variants (corresponds
to the C<APR_STATUS_IS_EOF> macro).

  $status = APR::Status::is_EOF($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

Due to possible variants in conditions matching C<EOF>,
the use of this function is recommended for checking error codes
against this value, rather than just using
C<L<APR::Const::EOF|docs::2.0::api::APR::Const/C_APR__Const__EOF_>>
directly.














=head2 C<is_ECONNABORTED>

Check if the error is matching C<ECONNABORTED> and its variants (corresponds
to the C<APR_STATUS_IS_ECONNABORTED> macro).

  $status = APR::Status::is_ECONNABORTED($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

Due to possible variants in conditions matching C<ECONNABORTED>,
the use of this function is recommended for checking error codes
against this value, rather than just using
C<L<APR::Const::ECONNABORTED|docs::2.0::api::APR::Const/C_APR__Const__ECONNABORTED_>> directly.







=head2 C<is_ECONNRESET>

Check if the error is matching C<ECONNRESET> and its variants
(corresponds to the C<APR_STATUS_IS_ECONNRESET> macro).

  $status = APR::Status::is_ECONNRESET($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

Due to possible variants in conditions matching C<ECONNRESET>, the use
of this function is recommended for checking error codes against this
value, rather than just using
C<L<APR::Const::ECONNRESET|docs::2.0::api::APR::Const/C_APR__Const__ECONNRESET_>>
directly.










=head2 C<is_TIMEUP>

Check if the error is matching C<TIMEUP> and its variants (corresponds
to the C<APR_STATUS_IS_TIMEUP> macro).

  $status = APR::Status::is_TIMEUP($error_code);

=over 4

=item arg1: C<$error_code> (integer or C<L<APR::Error
object|docs::2.0::api::APR::Error>> )

The error code or to check, normally C<$@> blessed into C<L<APR::Error
object|docs::2.0::api::APR::Error>>.

=item ret: C<$status> ( boolean )

=item since: 2.0.00

=back

Due to possible variants in conditions matching C<TIMEUP>,
the use of this function is recommended for checking error codes
against this value, rather than just using
C<L<APR::Const::TIMEUP|docs::2.0::api::APR::Const/C_APR__Const__TIMEUP_>>
directly.


=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.


=head1 Copyright

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



=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut