This document provides a quick reference for the mod_perl Apache module. It includes: 1) An overview of mod_perl and how it embeds a Perl interpreter in the Apache server. 2) A listing of common Apache and mod_perl functions organized by category like client request methods, server response methods, and logging functions. 3) Descriptions of Apache configuration directives added by mod_perl. 4) Tables of HTTP 1.1 header fields and Apache constants for things like status codes and methods.

1.
mod perl Quick Reference Card $r->send_http_header( $content_type ); ¡ $aref = $r->get_handlers( $str );
Revision 1.0 for mod perl version 1.19 Server core functions Apache->httpd_conf( $str );
Andrew Ford refcards.com TM $r->chdir_file( $file ); $bool = $r->module( $name );
$r->child_terminate(); $bool = Apache->perl_hook( $name );
mod perl is an Apache module, created by Doug MacEachern, $r->post_connection( $code_ref );
that embeds a Perl interpreter within the server. It provides a Perl $r->hard_timeout( $msg );
$r->internal_redirect( $newplace ); $r->push_handlers( $str => $code_ref );
API to Apache and adds a number of Apache configuration direc- $r = Apache->request( $r ); ¡
tives. Scripts using mod perl should import the Apache module, $r->internal_redirect_handler( $newplace );
$bool = $r->is_initial_req(); $r->set_handlers( $str => $aref );
Apache::Constants, and other Apache:: modules. A reference to
the request object (denoted below by $r) is passed to Perl handlers $bool = $r->is_main(); Apache::SubRequest class
when they are invoked. $r->kill_timeout(); $subr = $r->lookup_uri($uri);
$str = $r->location(); $subr = $r->lookup_file($filename);
Client request methods $req = $r->last(); $rc = $subr->run();
$r = Apache->request(); $req = $r->main();
$str = $r->args(); # or %hash = ... Apache::Server class
$req = $r->next();
$c = $r->connection # see Apache::Connection $str = $r->notes( $k ,$v ); # or $tab = $r->notes()
¡ $s = Apache->server # or $r->server
$str = $r->content(); # or %hash = ... $req = $r->prev(); $bool = $s->is_virtual();
$str = $r->filename( $newval ); ¡ $r->register_cleanup( $code_ref ); $s->log_error();
$r->finfo(); $r->reset_timeout(); $aref = $s->names();
$str = $r->get_remote_host( $lookup_type ); ¡ $r->soft_timeout( $msg ); $s = $s->next();
# use Apache::Constants :remotehost tag $num = $s->port();
$str = $r->subprocess_env( $k , $v ); ¡¡ $str = $s->server_admin();
$str = $r->get_remote_logname();
$str = $r->header_in( $hdr , $newval ); ¡ Server configuration methods $str = $s->server_hostname();
$str = $r->dir_config($k); #or $tab = $r->dir_config()
$bool = $r->header_only(); $num = $s->timeout( $newval ); ¡
$href = $r->headers_in(); # or %hash = ... $str = $r->document_root(); $s->warn();
$str = $r->get_server_name();
$str = $r->method( $newval ); ¡ Apache::Connection class
$num = $r->method_number( $nv ); # use :methods tag ¡ $num = $r->get_server_port();
$str = $r->server_root_relative( $obj ); ¡ $bool = $c->aborted();
$u = $r->parsed_uri(); # see Apache::URI $str = $c->auth_type();
$str = $r->path_info( $newval ); ¡ Logging and the Apache::Log class $addr = $c->local_addr();
$str = $r->protocol(); $str = $r->as_string();
$addr = $c->remote_addr( $addr ); ¡
$bool = $r->proxyreq( $newval ); ¡ $r->log_reason( $message, $file ); $str = $c->remote_host();
$r->read( $buf, $bytes_to_read ); $r->log_error( $message );
$str = $c->remote_ip( $ip ); ¡
$s = $r->server # see Apache::Server $r->warn( $message ); $str = $c->remote_logname();
$str = $r->the_request(); $log = $r->log();
$log = $s->log(); $str = $c->user( $username ); ¡
$str = $r->uri( $newval ); ¡
$log->emerg ( $str ... $code_ref );
¢ £ ¤ Apache::Table class
Server response methods
$log->alert ( $msg ... $code_ref );
¢ £ ¤ $tab = Apache::Table->new( $r , $size ); ¡
$num = $r->bytes_sent(); $tab->add( $key, $str_or_aref );
$r->cgi_header_out( $hdr , $newval ); ¡ $log->crit ( $msg ... $code_ref );
¢ £ ¤
$log->error ( $msg ... $code_ref );
¢ £ ¤ $tab->clear();
$str = $r->content_encoding( $newval ); ¡ $tab->do( $code_ref );
$aref = $r->content_languages( $newval ); ¡ $log->warn ( $msg ... $code_ref );
¢ £ ¤ $tab->merge( $key, $str_or_aref );
$log->notice( $msg ... $code_ref );
¢ £ ¤ $tab->set( $key, $str );
$str = $r->content_type( $newval ); ¡
$r->custom_response( $code, $uri ); $log->info ( $msg ... $code_ref );
¢ £ ¤ $str = $tab->get( $key ); # or @list = ...
$log->debug ( $msg ... $code_ref );
¢ £ ¤ $tab->unset($key);
$str = $r->err_header_out( $hdr , $newval ); ¡
$href = $r->err_headers_out();
# or %hash = ... Access control methods Apache::URI class
$str = $r->handler( $newval ); ¡ $opts = $r->allow_options(); # use :options tag $uri = Apache::URI->parse( $r , $string_uri ); ¡
$str = $r->header_out( $hdr , $newval ); ¡ $str = $r->auth_name( $newval ); ¡ $str = $uri->unparse();
$href = $r->headers_out(); # or %hash = ... $str = $r->auth_type(); $str = $uri->component( $newval ); ¡
$bool = $r->no_cache( $newval ); ¡ ($rc, $pw) = $r->get_basic_auth_pw(); (where component is one of: fragment, hostinfo, hostname,
$num = $r->request_time();
$r->note_basic_auth_failure(); password, path_info, path, port, query, rpath, scheme, user)
$num = $r->status( $newval ); ¡ $aref = $r->requires(); Apache::Util class
$str = $r->status_line( $newval ); ¡ $flag = $r->satisfies(); # use :satisfies tag $str = Apache::Util::escape_html( $html );
Sending data to the client $bool = $r->some_auth_required(); $str = Apache::Util::escape_uri( $uri );
mod_perl specific methods
$r->print( @list ); # checks $| $str = Apache::Util::ht_time($time , $fmt , $bool ); ¡¡
$r->printf( $format, @args ); $str = $r->current_callback(); $secs = Apache::Util::parsedate( $date_str );
$r->rflush(); $bool = $r->define( $name ); $num = Apache::Util::size_string( $num );
$r->send_cgi_header( $str ); Apache->exit( $code ); ¡ $str = Apache::Util::unescape_uri( $uri );
$len = $r->send_fd( $filehandle ); $fh = Apache->gensym(); $str = Apache::Util::unescape_uri_info( $uri );
1 2 3

2. Apache::Constants class HTTP 1.1 headers Apache mod perl configuration directives
The following export tag groups are defined (HTTP status code mod perl enables Apache to be configured using Perl statements
synonyms are given in brackets): that are contained within <Perl>. . . </Perl> sections and adds the
Apache configuration directives listed below. Each directive is
:common : OK, DECLINED , DONE, NOT_FOUND , FORBIDDEN , Syntax Category given with its arguments; defaults are given where appropriate in
AUTH_REQUIRED (HTTP_UNAUTHORIZED ), SERVER_ERROR Accept: media-types ;q=qvalue , ... ¥ ¦ ¥ §¦ REQUEST parentheses at the end of the line, followed by the symbol y to
Accept-Charset: charset ;q=qvalue , ... ¥ ¥
§¦ ¦ REQUEST mark directives only valid in a directory section or .htaccess file.
:response : DOCUMENT_FOLLOWS (HTTP_OK ),
Accept-Encoding: encoding ;q=qvalue , ... ¥ ¥§¦ ¦ REQUEST
MOVED (HTTP_MOVED_PERMANENTLY),
Accept-Language: lang ;q=qvalue , ... ¥ ¦ ¥¨¦ REQUEST
PerlAccessHandler handler
REDIRECT (HTTP_MOVED_TEMPORARILY),
Accept-Ranges: bytes none © RESPONSE
PerlAuthenHandler handler
USE_LOCAL_COPY (HTTP_NOT_MODIFIED ),
Age: seconds RESPONSE
PerlAuthzHandler handler
BAD_REQUEST , BAD_GATEWAY , NOT_IMPLEMENTED ,
Allow: method , ... ¥ ¦ ENTITY
CONTINUE , NOT_AUTHORITATIVE PerlChildExitHandler handler y
Authorization: scheme credentials REQUEST
PerlChildInitHandler handler y
:methods : M_CONNECT , M_COPY, M_DELETE , M_GET, M_INVALID , Cache-Control: directive GENERAL
PerlCleanupHandler handler
M_LOCK, M_MKCOL , M_MOVE, M_OPTIONS , M_PATCH , M_POST, Connection: close GENERAL
Content-Base: uri
PerlDispatchHandler handler
M_PROPFIND , M_PROPPATCH , M_PUT, M_TRACE , M_UNLOCK , METHODS ENTITY
PerlFixupHandler handler
Content-Encoding: enc ENTITY
:options : OPT_ALL OPT_NONE , OPT_INDEXES , OPT_INCLUDES , Content-Language: lang ENTITY
PerlFreshRestart On Off ¢ £ ¤ (On) y
OPT_SYM_LINKS , OPT_EXECCGI , OPT_UNSET , Content-Length: len ENTITY
PerlHandler handler
OPT_INCNOEXEC , OPT_SYM_OWNER , OPT_MULTI , Content-MD5: digest ENTITY
PerlHeaderParserHandler handler
Content-Range: bytes range/length ENTITY
PerlInitHandler handler
:satisfies : SATISFY_ALL , SATISFY_ANY , SATISFY_NOSPEC PerlLogHandler handler
Content-Type: media-type ENTITY
:server : MODULE_MAGIC_NUMBER , SERVER_BUILT , SERVER_VERSION Cookie: name=value ; ... ¥ ¦ REQUEST
PerlModule
Date: date GENERAL PerlPassEnv name ... y
:remotehost : REMOTE_HOST , REMOTE_NAME , REMOTE_NOLOOKUP , ETag: entity-tag RESPONSE PerlPostReadRequestHandler handler y
REMOTE_DOUBLE_REV Expect: expectation REQUEST PerlRequire script-file
Expires: date ENTITY PerlSendHeader On Off ¢ £ ¤ (Off)
:http includes only those HTTP status code constants shown below in PerlSetEnv name value
bold type (other HTTP constants may be imported explicitly): From: email-address REQUEST
Host: hostname :port ¥ ¦ REQUEST PerlSetVar name value
100 HTTP_CONTINUE 405 HTTP_METHOD_NOT_ALLOWED PerlSetupEnv On Off ¢ £ ¤ (Off)
If-Match: entity-tag REQUEST
101 HTTP_SWITCHING_PROTOCOLS 406 HTTP_NOT_ACCEPTABLE
If-Modified-Since: date REQUEST PerlTaintCheck On Off ¢ £ ¤ (Off) y
200 HTTP_OK 407 HTTP_PROXY_AUTHENTICATION_
If-None-Match: entity-tag REQUEST PerlTransHandler handler y
201 HTTP_CREATED REQUIRED
If-Range: entity tag date
© REQUEST PerlTypeHandler handler
202 HTTP_ACCEPTED 408 HTTP_REQUEST_TIMEOUT
203 HTTP_NON_AUTHORITATIVE 409 HTTP_CONFLICT
If-Unmodified-Since: date REQUEST PerlWarn On Off
¢ £ ¤ (Off) y
Last-Modified: date ENTITY
204 HTTP_NO_CONTENT 410 HTTP_GONE
Location: uri RESPONSE Resources
205 HTTP_RESET_CONTENT 411 HTTP_LENGTH REQUIRED
MIME-Version: version GENERAL
http://perl.apache.org The Apache/Perl Integration Project
206 HTTP_PARTIAL_CONTENT 412 HTTP_PRECONDITION_FAILED
Max-Forwards: number REQUEST
http://www.modperl.com Writing Apache Modules home page
300 HTTP_MULTIPLE_CHOICES 413 HTTP_REQUEST_ENTITY_TOO_LARGE
Pragma: no-cache extension-pragma
© GENERAL
http://www.apache.org Apache home page
301 HTTP_MOVED_PERMANENTLY 414 HTTP_REQUEST_URI_TOO_LARGE
Proxy-Authenticate: challenge RESPONSE
302 HTTP_MOVED_TEMPORARILY 415 HTTP_UNSUPPORTED_MEDIA_TYPE http://www.perl.com Perl home page
Proxy-Authorization: credentials REQUEST
303 HTTP_SEE_OTHER 500 HTTP_INTERNAL_SERVER_ERROR http://www.refcards.com Quick reference cards
Public: method ... RESPONSE
304 HTTP_NOT_MODIFIED 501 HTTP_NOT IMPLEMENTED
Range: bytes=n -m , ... ¥¨¦ ¥ ¦ REQUEST
305 HTTP_USE_PROXY 502 HTTP_BAD_GATEWAY
Referer: url REQUEST
400 HTTP_BAD_REQUEST 503 HTTP_SERVICE_UNAVAILABLE mod perl Quick Reference Card
Retry-After: date seconds
© RESPONSE
401 HTTP_UNAUTHORIZED 504 HTTP_GATEWAY_TIME_OUT A refcards.com TM quick reference card
Server: string RESPONSE
402 HTTP_PAYMENT_REQUIRED 505 HTTP_VERSION_NOT_SUPPORTED Revision 1.0 for mod perl version 1.19 [May 1999]
Set-Cookie: name=value ; options ¥ ¦ RESPONSE
403 HTTP_FORBIDDEN 506 HTTP_VARIANT_ALSO_VARIES c 1998, 1999 Ford Mason Ltd. All rights reserved.
TE: coding REQUEST
404 HTTP_NOT_FOUND Trailer: header GENERAL Permission is granted to print and duplicate this card for personal or in-
Transfer-Encoding: coding GENERAL dividual, internal business use. Copies of this card ( others) can be or-
Magic global variables Upgrade: protocol , ... ¥ ¦ GENERAL dered through our web site: http://www.refcards.com, which also has
$0, $^X, $|, $/, %@, %SIG, @INC, %INC, %ENV{MOD_PERL} , User-Agent: string REQUEST versions available for downloading.
%ENV{GATEWAY_INTERFACE}, %ENV{PERL_SEND_HEADER} Vary: header , ... ¥ ¦ RESPONSE Please send feedback to: feedback@refcards.com
Special package globals Via: protocol/ version (comment) , ...
¥ ¦ ¥ ¥ ¨¦ ¦ GENERAL refcards.com is a trademark of Ford Mason Ltd.
$Apache::Server::CWD $Apache::Server::SaveConfig WWW-Authenticate: scheme realm RESPONSE Use of the Camel for Perl is a trademark of O’Reilly Associates – used by permis-
$Apache::Server::ReStarting $Apache::Server::Starting Warning: code agent quot;textquot; date ¥ ¦ GENERAL sion.
4 5 6