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

  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
  }

An interface to apr_errno.h composite error codes.

As discussed in the CWAPR::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 CW$some_code is an APR::Const constant, there may be more than one condition satisfying the intent of this exception. For this purpose the APR C library provides in apr_errno.h a series of macros, CWAPR_STATUS_IS_*, which are the recommended way to check for such conditions. For example, the CWAPR_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 CWAPR::Status is to provide functions corresponding to these macros.

Check if the error is matching CWEACCES and its variants (corresponds to the CWAPR_STATUS_IS_EACCES macro).

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

since: 2.0.00

An example of using CWis_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 CWEACCES, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::EACCES directly. Check if the error is matching CWEAGAIN and its variants (corresponds to the CWAPR_STATUS_IS_EAGAIN macro).

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

since: 2.0.00

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 CWAPR::Const::EAGAIN may work on some Unices, but then it will certainly break on win32. Thefore make sure to use this macro and not CWAPR::Const::EAGAIN unless you know what you are doing. Check if the error is matching CWENOENT and its variants (corresponds to the CWAPR_STATUS_IS_ENOENT macro).

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

since: 2.0.00

An example of using CWis_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 CWENOENT, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::ENOENT directly. Check if the error is matching CWEOF and its variants (corresponds to the CWAPR_STATUS_IS_EOF macro).

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

since: 2.0.00

Due to possible variants in conditions matching CWEOF, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::EOF directly. Check if the error is matching CWECONNABORTED and its variants (corresponds to the CWAPR_STATUS_IS_ECONNABORTED macro).

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

since: 2.0.00

Due to possible variants in conditions matching CWECONNABORTED, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::ECONNABORTED directly. Check if the error is matching CWECONNRESET and its variants (corresponds to the CWAPR_STATUS_IS_ECONNRESET macro).

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

since: 2.0.00

Due to possible variants in conditions matching CWECONNRESET, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::ECONNRESET directly. Check if the error is matching CWTIMEUP and its variants (corresponds to the CWAPR_STATUS_IS_TIMEUP macro).

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

since: 2.0.00

Due to possible variants in conditions matching CWTIMEUP, the use of this function is recommended for checking error codes against this value, rather than just using CWAPR::Const::TIMEUP directly.

mod_perl 2.0 documentation.

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

The mod_perl development team and numerous contributors.