Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 9 - Perl API Reference Guide / Other Core Perl API Classes
The Apache::Constants Class

All of the HTTP status codes are defined in the httpd.h file, along with server-specific status codes such as OK, DECLINED, and DONE. The Apache::Constants class provides access to these codes as constant subroutines. As there are many of these constants, they are not all exported by default. By default, only those listed in the :common export tag are exported. A variety of export tags are defined, allowing you to bring in various sets of constants to suit your needs. You are also free to bring in individual constants, just as you can with any other Perl module.

Here are the status codes listed by export tag group:

:common

This tag imports the most commonly used constants:

OK	FORBIDDEN
DECLINED	AUTH_REQUIRED
DONE	SERVER_ERROR
NOT_FOUND

:response

This tag imports the :common response codes, plus these response codes:

DOCUMENT_FOLLOWS	BAD_GATEWAY
MOVED	RESPONSE_CODES
REDIRECT	NOT_IMPLEMENTED
USE_LOCAL_COPY	CONTINUE
BAD_REQUEST	NOT_AUTHORITATIVE

CONTINUE and NOT_AUTHORITATIVE are aliases for DECLINED.

:methods

These are the method numbers, commonly used with the Apache method_number() method:

METHODS	M_PROPFIND
M_GET	M_PROPPATCH
M_PUT	M_MKCOL
M_POST	M_COPY
M_DELETE	M_MOVE
M_CONNECT	M_LOCK
M_OPTIONS	M_UNLOCK
M_TRACE	M_INVALID
M_PATCH

Each of the M_ constants corresponds to an integer value, where M_GET..M_UNLOCK is 0..14. The METHODS constant is the number of M_ constants, 15 at the time of this writing. This is designed to accommodate support for other request methods.

for (my $i = 0; $i < METHODS; $i++) {
  ...
}

:options

These constants are most commonly used with the Apache allow_options() method:

OPT_NONE	OPT_UNSET
OPT_INDEXES	OPT_INCNOEXEC
OPT_INCLUDES	OPT_SYM_OWNER
OPT_SYM_LINKS	OPT_MULTI
OPT_EXECCGI	OPT_ALL

:satisfy

These constants are most commonly used with the Apache satisfy() method:

SATISFY_ALL

SATISFY_ANY

SATISFY_NOSPEC

:remotehost

These constants are most commonly used with the Apache get_remote_host method:

REMOTE_HOST

REMOTE_NAME

REMOTE_NOLOOKUP

REMOTE_DOUBLE_REV

:http

This is a set of common HTTP response codes:

HTTP_OK	HTTP_BAD_REQUEST
HTTP_MOVED_TEMPORARILY	HTTP_INTERNAL_SERVER_ERROR
HTTP_MOVED_PERMANENTLY	HTTP_NOT_ACCEPTABLE
HTTP_METHOD_NOT_ALLOWED	HTTP_NO_CONTENT
HTTP_NOT_MODIFIED	HTTP_PRECONDITION_FAILED
HTTP_UNAUTHORIZED	HTTP_SERVICE_UNAVAILABLE
HTTP_FORBIDDEN	HTTP_VARIANT_ALSO_VARIES
HTTP_NOT_FOUND

Note that this list is not definitive. See the Apache source code for the most up-to-date listing.

:server

These are constants related to the version of the Apache server software:

MODULE_MAGIC_NUMBER

SERVER_VERSION

SERVER_BUILT

:config

These are constants most commonly used with configuration directive handlers:

DECLINE_CMD

:types

These are constants which define internal request types:

DIR_MAGIC_TYPE

:override

These constants are used to control and test the context of configuration directives:

OR_NONE	OR_INDEXES
OR_LIMIT	OR_UNSET
OR_OPTIONS	OR_ALL
OR_FILEINFO	ACCESS_CONF
OR_AUTHCFG	RSRC_CONF

:args_how

These are the constants which define configuration directive prototypes:

RAW_ARGS	TAKE123
TAKE1	ITERATE
TAKE2	ITERATE2
TAKE12	FLAG
TAKE3	NO_ARGS
TAKE23

As you may notice, this list is shorter than the list defined in Apache's include/httpd.h header file. The missing constants are available as subroutines via Apache::Constants, they are just not exportable by default. The less frequently used constants were left out of this list to keep memory consumption at a reasonable level.

There are two options if you need to access a constant that is not exportable by default. One is simply to use the fully qualified subroutine name, for example:

return Apache::Constants::HTTP_MULTIPLE_CHOICES();

Or use the export method in a server startup file to add exportable names. The name will now become available to the use operator.

#startup script
Apache::Constants->export(qw( HTTP_MULTIPLE_CHOICES ));

#runtime module
use Apache::Constants qw(:common HTTP_MULTIPLE_CHOICES);

...
return HTTP_MULTIPLE_CHOICES;

While the HTTP constants generally use a return code from handler subroutines, it is also possible to use the built-in die() function to jump out of a handler with a status code that will be propagated back to Apache:

unless (-r _) {
   die FORBIDDEN;
}

Footnotes

5 At the time of this writing, URI::URL was scheduled to be replaced by URI.pm, which will be distributed separately from the libwww-perl package.