.\" Automatically generated by Pod::Man version 1.15
.\" Fri Nov  7 16:35:46 2003
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "Apache 3"
.TH Apache 3 "perl v5.6.1" "2001-01-29" "User Contributed Perl Documentation"
.UC
.SH "NAME"
Apache \- Perl interface to the Apache server \s-1API\s0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Apache ();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a Perl interface the Apache \s-1API\s0.  It is here
mainly for \fBmod_perl\fR, but may be used for other Apache modules that
wish to embed a Perl interpreter.  We suggest that you also consult
the description of the Apache C \s-1API\s0 at http://www.apache.org/docs/.
.SH "THE REQUEST OBJECT"
.IX Header "THE REQUEST OBJECT"
The request object holds all the information that the server needs to
service a request.  Apache \fBPerl*Handler\fRs will be given a reference to the
request object as parameter and may choose to update or use it in various
ways.  Most of the methods described below obtain information from or
update the request object.
The perl version of the request object will be blessed into the \fBApache\fR 
package, it is really a \f(CW\*(C`request_rec*\*(C'\fR in disguise.
.Ip "Apache->request([$r])" 4
.IX Item "Apache->request([$r])"
The Apache->request method will return a reference to the request object.
.Sp
\&\fBPerl*Handler\fRs can obtain a reference to the request object when it
is passed to them via \f(CW\*(C`@_\*(C'\fR.  However, scripts that run under 
\&\fBApache::Registry\fR, for example, need a way to access the request object.
\&\fBApache::Registry\fR will make a request object available to these scripts
by passing an object reference to \f(CW\*(C`Apache\->request($r)\*(C'\fR.
If handlers use modules such as \fB\s-1CGI:\s0:Apache\fR that need to access
\&\f(CW\*(C`Apache\->request\*(C'\fR, they too should do this (e.g. \fBApache::Status\fR).
.Ip "$r->as_string" 4
.IX Item "$r->as_string"
Returns a string representation of the request object.  Mainly useful
for debugging.
.Ip "$r->main" 4
.IX Item "$r->main"
If the current request is a sub-request, this method returns a blessed
reference to the main request structure.  If the current request is
the main request, then this method returns \f(CW\*(C`undef\*(C'\fR.
.Ip "$r->prev" 4
.IX Item "$r->prev"
This method returns a blessed reference to the previous (internal) request
structure or \f(CW\*(C`undef\*(C'\fR if there is no previous request.
.Ip "$r->next" 4
.IX Item "$r->next"
This method returns a blessed reference to the next (internal) request
structure or \f(CW\*(C`undef\*(C'\fR if there is no next request.
.Ip "$r->last" 4
.IX Item "$r->last"
This method returns a blessed reference to the last (internal) request
structure.  Handy for logging modules.
.Ip "$r->is_main" 4
.IX Item "$r->is_main"
Returns true if the current request object is for the main request.
(Should give the same result as \f(CW\*(C`!$r\->main\*(C'\fR, but will be more efficient.)
.Ip "$r->is_initial_req" 4
.IX Item "$r->is_initial_req"
Returns true if the current request is the first internal request,
returns false if the request is a sub-request or internal redirect.
.SH "SUB REQUESTS"
.IX Header "SUB REQUESTS"
Apache provides a sub-request mechanism to lookup a uri or filename,
performing all access checks, etc., without actually running the
response phase of the given request.  Notice, we have dropped the
\&\f(CW\*(C`sub_req_\*(C'\fR prefix here.  The \f(CW\*(C`request_rec*\*(C'\fR returned by the lookup
methods is blessed into the \fBApache::SubRequest\fR class.  This way,
\&\f(CW\*(C`destroy_sub_request()\*(C'\fR is called automatically during
\&\f(CW\*(C`Apache::SubRequest\->DESTROY\*(C'\fR when the object goes out of scope.  The
\&\fBApache::SubRequest\fR class inherits all the methods from the
\&\fBApache\fR class.
.Ip "$r->lookup_uri($uri)" 4
.IX Item "$r->lookup_uri($uri)"
.Vb 2
\&   my $subr = $r->lookup_uri($uri);
\&   my $filename = $subr->filename;
.Ve
.Vb 3
\&   unless(-e $filename) {
\&       warn "can't stat $filename!\en";
\&   }
.Ve
.Ip "$r->lookup_file($filename)" 4
.IX Item "$r->lookup_file($filename)"
.Vb 1
\&   my $subr = $r->lookup_file($filename);
.Ve
.Ip "$subr->run" 4
.IX Item "$subr->run"
.Vb 3
\&   if($subr->run != OK) {
\&       $subr->log_error("something went wrong!");
\&   }
.Ve
.SH "CLIENT REQUEST PARAMETERS"
.IX Header "CLIENT REQUEST PARAMETERS"
In this section we will take a look at various methods that can be used to
retrieve the request parameters sent from the client.
In the following examples, \fB$r\fR is a request object blessed into the 
\&\fBApache\fR class, obtained by the first parameter passed to a handler subroutine
or \fIApache->request\fR
.Ip "$r->method( [$meth] )" 4
.IX Item "$r->method( [$meth] )"
The \f(CW$r\fR->method method will return the request method.  It will be a
string such as \*(L"\s-1GET\s0\*(R", \*(L"\s-1HEAD\s0\*(R" or \*(L"\s-1POST\s0\*(R".
Passing an argument will set the method, mainly used for internal redirects.
.Ip "$r->method_number( [$num] )" 4
.IX Item "$r->method_number( [$num] )"
The \f(CW$r\fR->method_number method will return the request method number.
The method numbers are defined by the M_GET, M_POST,... constants
available from the \fBApache::Constants\fR module.  Passing an argument
will set the method_number, mainly used for internal redirects and
testing authorization restriction masks.
.Ip "$r->bytes_sent" 4
.IX Item "$r->bytes_sent"
The number of bytes sent to the client, handy for logging, etc.
.Ip "$r->the_request" 4
.IX Item "$r->the_request"
The request line sent by the client, handy for logging, etc.
.Ip "$r->proxyreq" 4
.IX Item "$r->proxyreq"
Returns true if the request is proxy http.
Mainly used during the filename translation stage of the request, 
which may be handled by a \f(CW\*(C`PerlTransHandler\*(C'\fR.
.Ip "$r->header_only" 4
.IX Item "$r->header_only"
Returns true if the client is asking for headers only, 
e.g. if the request method was \fB\s-1HEAD\s0\fR.
.Ip "$r->protocol" 4
.IX Item "$r->protocol"
The \f(CW$r\fR->protocol method will return a string identifying the protocol
that the client speaks.  Typical values will be \*(L"\s-1HTTP/1\s0.0\*(R" or
\&\*(L"\s-1HTTP/1\s0.1\*(R".
.Ip "$r->hostname" 4
.IX Item "$r->hostname"
Returns the server host name, as set by full \s-1URI\s0 or Host: header.
.Ip "$r->request_time" 4
.IX Item "$r->request_time"
Returns the time that the request was made.  The time is the local unix
time in seconds since the epoch.
.Ip "$r->uri( [$uri] )" 4
.IX Item "$r->uri( [$uri] )"
The \f(CW$r\fR->uri method will return the requested \s-1URI\s0 minus optional query
string, optionally changing it with the first argument.
.Ip "$r->filename( [$filename] )" 4
.IX Item "$r->filename( [$filename] )"
The \f(CW$r\fR->filename method will return the result of the \fI\s-1URI\s0 \-->
filename\fR translation, optionally changing it with the first argument
if you happen to be doing the translation.
.Ip "$r->path_info( [$path_info] )" 4
.IX Item "$r->path_info( [$path_info] )"
The \f(CW$r\fR->path_info method will return what is left in the path after the
\&\fI\s-1URI\s0 \--> filename\fR translation, optionally changing it with the first 
argument if you happen to be doing the translation.
.Ip "$r->args( [$query_string] )" 4
.IX Item "$r->args( [$query_string] )"
The \f(CW$r\fR->args method will return the contents of the \s-1URI\s0 \fIquery
string\fR.  When called in a scalar context, the entire string is
returned.  When called in a list context, a list of parsed \fIkey\fR =>
\&\fIvalue\fR pairs are returned, i.e. it can be used like this:
.Sp
.Vb 2
\&   $query = $r->args;
\&   %in    = $r->args;
.Ve
$r->args can also be used to set the \fIquery string\fR. This can be useful
when redirecting a \s-1POST\s0 request.
.Ip "$r->headers_in" 4
.IX Item "$r->headers_in"
The \f(CW$r\fR->headers_in method will return a \f(CW%hash\fR of client request
headers.  This can be used to initialize a perl hash, or one could use
the \f(CW$r\fR->\fIheader_in()\fR method (described below) to retrieve a specific
header value directly.
.Sp
Will return a \fI\s-1HASH\s0\fR reference blessed into the \fIApache::Table\fR
class when called in a scalar context with no \*(L"key\*(R" argument. This
requires \fIApache::Table\fR.
.Ip "$r->header_in( \f(CW$header_name\fR, [$value] )" 4
.IX Item "$r->header_in( $header_name, [$value] )"
Return the value of a client header.  Can be used like this:
.Sp
.Vb 2
\&   $ct = $r->header_in("Content-type");
\&   $r->header_in($key, $val); #set the value of header '$key'
.Ve
.Ip "$r->content" 4
.IX Item "$r->content"
The \f(CW$r\fR->content method will return the entity body read from the
client, but only if the request content type is
\&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR.
When called in a scalar context, the entire string is
returned.  When called in a list context, a list of parsed \fIkey\fR =>
\&\fIvalue\fR pairs are returned.  *NOTE*: you can only ask for this once,
as the entire body is read from the client.
.Ip "$r->read($buf, \f(CW$bytes_to_read\fR, [$offset])" 4
.IX Item "$r->read($buf, $bytes_to_read, [$offset])"
This method is used to read data from the client, 
looping until it gets all of \f(CW\*(C`$bytes_to_read\*(C'\fR or a timeout happens.
.Sp
An offset may be specified to place the read data at some other place
than the beginning of the string.
.Sp
In addition, this method sets a timeout before reading with
\&\f(CW\*(C`$r\->soft_timeout\*(C'\fR.
.Ip "$r->get_remote_host" 4
.IX Item "$r->get_remote_host"
Lookup the client's \s-1DNS\s0 hostname. If the configuration directive
\&\fBHostNameLookups\fR is set to off, this returns the dotted decimal
representation of the client's \s-1IP\s0 address instead. Might return
\&\fIundef\fR if the hostname is not known.
.Ip "$r->get_remote_logname" 4
.IX Item "$r->get_remote_logname"
Lookup the remote user's system name.  Might return \fIundef\fR if the
remote system is not running an \s-1RFC\s0 1413 server or if the configuration
directive \fBIdentityCheck\fR is not turned on.
.PP
More information about the client can be obtained from the
\&\fBApache::Connection\fR object, as described below.
.Ip "$c = \f(CW$r\fR->connection" 4
.IX Item "$c = $r->connection"
The \f(CW$r\fR->connection method will return a reference to the request
connection object (blessed into the \fBApache::Connection\fR package).
This is really a \f(CW\*(C`conn_rec*\*(C'\fR in disguise.  The following methods can
be used on the connection object:
.RS 4
.Ip "$c->remote_host" 4
.IX Item "$c->remote_host"
If the configuration directive \fBHostNameLookups\fR is set to on:  then
the first time \f(CW\*(C`$r\->get_remote_host\*(C'\fR is called the server does a \s-1DNS\s0
lookup to get the remote client's host name.  The result is cached in
\&\f(CW\*(C`$c\->remote_host\*(C'\fR then returned. If the server was unable to resolve
the remote client's host name this will be set to "". Subsequent calls
to \f(CW\*(C`$r\->get_remote_host\*(C'\fR return this cached value.
.Sp
If the configuration directive \fBHostNameLookups\fR is set to off: calls
to \f(CW\*(C`$r\->get_remote_host\*(C'\fR return a string that contains the dotted
decimal representation of the remote client's \s-1IP\s0 address. However this
string is not cached, and \f(CW\*(C`$c\->remote_host\*(C'\fR is undefined. So, it's
best to to call \f(CW\*(C`$r\->get_remote_host\*(C'\fR instead of directly accessing
this variable.
.Ip "$c->remote_ip" 4
.IX Item "$c->remote_ip"
The dotted decimal representation of the remote client's \s-1IP\s0 address.
This is set by the server when the connection record is created so
is always defined.
.Sp
You can also set this value by providing an argument to it. This is
helpful if your server is behind a squid accelerator proxy which adds
a X-Forwarded-For header.
.Ip "$c->local_addr" 4
.IX Item "$c->local_addr"
A packed \s-1SOCKADDR_IN\s0 in the same format as returned by
the pack_sockaddr_in entry in the Socket manpage, containing the port and address on the
local host that the remote client is connected to.  This is set by
the server when the connection record is created so it is always
defined.
.Ip "$c->remote_addr" 4
.IX Item "$c->remote_addr"
A packed \s-1SOCKADDR_IN\s0 in the same format as returned by
the pack_sockaddr_in entry in the Socket manpage, containing the port and address on the
remote host that the server is connected to.  This is set by the
server when the connection record is created so it is always defined.
.Sp
Among other things, this can be used, together with \f(CW\*(C`$c\->local_addr\*(C'\fR, to
perform \s-1RFC1413\s0 ident lookups on the remote client even when the
configuration directive \fBIdentityCheck\fR is turned off.
.Sp
Can be used like:
.Sp
.Vb 4
\&   use Net::Ident qw (lookupFromInAddr);
\&   ...
\&   my $remoteuser = lookupFromInAddr ($c->local_addr,
\&                                      $c->remote_addr, 2);
.Ve
Note that the lookupFromInAddr interface does not currently exist in
the \fBNet::Ident\fR module, but the author is planning on adding it
soon.
.Ip "$c->remote_logname" 4
.IX Item "$c->remote_logname"
If the configuration directive \fBIdentityCheck\fR is set to on:  then the
first time \f(CW\*(C`$r\->get_remote_logname\*(C'\fR is called the server does an \s-1RFC\s0
1413 (ident) lookup to get the remote users system name. Generally for
UNI* systems this is their login. The result is cached in \f(CW\*(C`$c\->remote_logname\*(C'\fR
then returned.  Subsequent calls to \f(CW\*(C`$r\->get_remote_host\*(C'\fR return the
cached value.
.Sp
If the configuration directive \fBIdentityCheck\fR is set to off: then 
\&\f(CW\*(C`$r\->get_remote_logname\*(C'\fR does nothing and \f(CW\*(C`$c\->remote_logname\*(C'\fR is
always undefined.
.Ip "$c->user( [$user] )" 4
.IX Item "$c->user( [$user] )"
If an authentication check was successful, the authentication handler
caches the user name here. Sets the user name to the optional first
argument.
.Ip "$c->auth_type" 4
.IX Item "$c->auth_type"
Returns the authentication scheme that successfully authenticate
\&\f(CW\*(C`$c\->user\*(C'\fR, if any.
.Ip "$c->aborted" 4
.IX Item "$c->aborted"
Returns true if the client stopped talking to us.
.Ip "$c->fileno( [$direction] )" 4
.IX Item "$c->fileno( [$direction] )"
Returns the client file descriptor. If \f(CW$direction\fR is 0, the input fd
is returned. If \f(CW$direction\fR is not null or ommitted, the output fd is
returned.
.Sp
This can be used to detect client disconnect without doing any I/O,
e.g. using \s-1IO:\s0:Select.
.RE
.RS 4
.RE
.SH "SERVER CONFIGURATION INFORMATION"
.IX Header "SERVER CONFIGURATION INFORMATION"
The following methods are used to obtain information from server
configuration and access control files.
.Ip "$r->dir_config( \f(CW$key\fR )" 4
.IX Item "$r->dir_config( $key )"
Returns the value of a per-directory variable specified by the 
\&\f(CW\*(C`PerlSetVar\*(C'\fR directive.
.Sp
.Vb 3
\&   # <Location /foo/bar>
\&   # PerlSetVar  Key  Value
\&   # </Location>
.Ve
.Vb 1
\&   my $val = $r->dir_config('Key');
.Ve
Keys are case-insensitive.
.Sp
Will return a \fI\s-1HASH\s0\fR reference blessed into the
\&\fIApache::Table\fR class when called in a scalar context with no
\&\*(L"key\*(R" argument. See \fIApache::Table\fR.
.Ip "$r->dir_config->get( \f(CW$key\fR )" 4
.IX Item "$r->dir_config->get( $key )"
Returns the value of a per-directory array variable specified by the
\&\f(CW\*(C`PerlAddVar\*(C'\fR directive.
.Sp
.Vb 4
\&   # <Location /foo/bar>
\&   # PerlAddVar  Key  Value1
\&   # PerlAddVar  Key  Value2
\&   # </Location>
.Ve
.Vb 1
\&   my @val = $r->dir_config->get('Key');
.Ve
Alternatively in your code you can extend the setting with:
.Sp
.Vb 1
\&  $r->dir_config->add(Key => 'Value3');
.Ve
Keys are case-insensitive.
.Sp
Will return a \fI\s-1HASH\s0\fR reference blessed into the
\&\fIApache::Table\fR class when called in a scalar context with no
\&\*(L"key\*(R" argument. See \fIApache::Table\fR.
.Ip "$r->requires" 4
.IX Item "$r->requires"
Returns an array reference of hash references, containing information
related to the \fBrequire\fR directive.  This is normally used for access
control, see the Apache::AuthzAge manpage for an example.
.Ip "$r->auth_type" 4
.IX Item "$r->auth_type"
Returns a reference to the current value of the per directory
configuration directive \fBAuthType\fR. Normally this would be set to
\&\f(CW\*(C`Basic\*(C'\fR to use the basic authentication scheme defined in \s-1RFC\s0 1945,
\&\fIHypertext Transfer Protocol \*(-- \s-1HTTP/1\s0.0\fR. However, you could set to
something else and implement your own authentication scheme.
.Ip "$r->auth_name" 4
.IX Item "$r->auth_name"
Returns a reference to the current value of the per directory
configuration directive \fBAuthName\fR.  The AuthName directive creates
protection realm within the server document space. To quote \s-1RFC\s0 1945
\&\*(L"These realms allow the protected resources on a server to be
partitioned into a set of protection spaces, each with its own
authentication scheme and/or authorization database.\*(R" The client uses
the root \s-1URL\s0 of the server to determine which authentication
credentials to send with each \s-1HTTP\s0 request. These credentials are
tagged with the name of the authentication realm that created them.
Then during the authentication stage the server uses the current
authentication realm, from \f(CW\*(C`$r\->auth_name\*(C'\fR, to determine which set of
credentials to authenticate.
.Ip "$r->document_root" 4
.IX Item "$r->document_root"
Returns a reference to the current value of the per server
configuration directive \fBDocumentRoot\fR. To quote the Apache server
documentation, \*(L"Unless matched by a directive like Alias, the server
appends the path from the requested \s-1URL\s0 to the document root to make
the path to the document.\*(R"  This same value is passed to \s-1CGI\s0
scripts in the \f(CW\*(C`DOCUMENT_ROOT\*(C'\fR environment variable.
.Ip "$r->allow_options" 4
.IX Item "$r->allow_options"
The \f(CW\*(C`$r\->allow_options\*(C'\fR method can be used for
checking if it is \s-1OK\s0 to run a perl script.  The \fBApache::Options\fR
module provides the constants to check against.
.Sp
.Vb 4
\&   if(!($r->allow_options & OPT_EXECCGI)) {
\&       $r->log_reason("Options ExecCGI is off in this directory", 
\&                      $filename);
\&   }
.Ve
.Ip "$r->get_server_port" 4
.IX Item "$r->get_server_port"
Returns the port number on which the server is listening.
.Ip "$s = \f(CW$r\fR->server" 4
.IX Item "$s = $r->server"
Return a reference to the server info object (blessed into the
\&\fBApache::Server\fR package).  This is really a \f(CW\*(C`server_rec*\*(C'\fR in
disguise.  The following methods can be used on the server object:
.Ip "$s = Apache->server" 4
.IX Item "$s = Apache->server"
Same as above, but only available during server startup for use in
<Perl> sections, \fBPerlScript\fR or \fBPerlModule\fR.
.Ip "$s->server_admin" 4
.IX Item "$s->server_admin"
Returns the mail address of the person responsible for this server.
.Ip "$s->server_hostname" 4
.IX Item "$s->server_hostname"
Returns the hostname used by this server.
.Ip "$s->port" 4
.IX Item "$s->port"
Returns the port that this servers listens too.
.Ip "$s->is_virtual" 4
.IX Item "$s->is_virtual"
Returns true if this is a virtual server.
.Ip "$s->names" 4
.IX Item "$s->names"
Returns the wild-carded names for ServerAlias servers. 
.Ip "$s->dir_config( \f(CW$key\fR )" 4
.IX Item "$s->dir_config( $key )"
Alias for Apache::dir_config.
.Ip "$s->warn" 4
.IX Item "$s->warn"
Alias for Apache::warn.
.Ip "$s->log_error" 4
.IX Item "$s->log_error"
Alias for Apache::log_error.
.Ip "$s->uid" 4
.IX Item "$s->uid"
Returns the numeric user id under which the server answers requests.
This is the value of the User directive.
.Ip "$s->gid" 4
.IX Item "$s->gid"
Returns the numeric group id under which the server answers requests.
This is the value of the Group directive.
.Ip "$s->loglevel" 4
.IX Item "$s->loglevel"
Get or set the value of the current LogLevel. This method is added by
the Apache::Log module, which needs to be pulled in.
.Sp
.Vb 3
\&    use Apache::Log;
\&    print "LogLevel = ", $s->loglevel;
\&    $s->loglevel(Apache::Log::DEBUG);
.Ve
If using Perl 5.005+, the following constants are defined (but not
exported):
.Sp
.Vb 8
\&    Apache::Log::EMERG
\&    Apache::Log::ALERT
\&    Apache::Log::CRIT
\&    Apache::Log::ERR
\&    Apache::Log::WARNING
\&    Apache::Log::NOTICE
\&    Apache::Log::INFO
\&    Apache::Log::DEBUG
.Ve
.Ip "$r->get_handlers( \f(CW$hook\fR )" 4
.IX Item "$r->get_handlers( $hook )"
Returns a reference to a list of handlers enabled for \f(CW$hook\fR. \f(CW$hook\fR is
a string representing the phase to handle. The returned list is a list
of references to the handler subroutines.
.Sp
.Vb 1
\&        $list = $r->get_handlers( 'PerlHandler' );
.Ve
.Ip "$r->set_handlers( \f(CW$hook\fR, [\e&handler, ... ] )" 4
.IX Item "$r->set_handlers( $hook, [&handler, ... ] )"
Sets the list if handlers to be called for \f(CW$hook\fR. \f(CW$hook\fR is a string
representing the phase to handle. The list of handlers is an anonymous
array of code references to the handlers to install for this request
phase. The special list [ \e&OK ] can be used to disable a particular
phase.
.Sp
.Vb 2
\&        $r->set_handlers( PerlLogHandler => [ \e&myhandler1, \e&myhandler2 ] );
\&        $r->set_handlers( PerlAuthenHandler => [ \e&OK ] );
.Ve
.Ip "$r->push_handlers( \f(CW$hook\fR, \e&handler )" 4
.IX Item "$r->push_handlers( $hook, &handler )"
Pushes a new handler to be called for \f(CW$hook\fR. \f(CW$hook\fR is a string
representing the phase to handle. The handler is a reference to a
subroutine to install for this request phase. This handler will be
called before any configured handlers.
.Sp
.Vb 1
\&        $r->push_handlers( PerlHandler => \e&footer);
.Ve
.SH "SETTING UP THE RESPONSE"
.IX Header "SETTING UP THE RESPONSE"
The following methods are used to set up and return the response back
to the client.  This typically involves setting up \f(CW$r\fR->\fIstatus()\fR, the
various content attributes and optionally some additional
\&\f(CW$r\fR->\fIheader_out()\fR calls before calling \f(CW$r\fR->\fIsend_http_header()\fR which will
actually send the headers to the client.  After this a typical
application will call the \f(CW$r\fR->\fIprint()\fR method to send the response
content to the client.
.Ip "$r->send_http_header( [$content_type] )" 4
.IX Item "$r->send_http_header( [$content_type] )"
Send the response line and all headers to the client.
Takes an optional parameter indicating the content-type of the
response, i.e. 'text/html'.
.Sp
This method will create headers from the \f(CW$r\fR->\fIcontent_xxx()\fR and
\&\f(CW$r\fR->\fIno_cache()\fR attributes (described below) and then append the
headers defined by \f(CW$r\fR->header_out (or \f(CW$r\fR->err_header_out if status
indicates an error).
.Ip "$r->get_basic_auth_pw" 4
.IX Item "$r->get_basic_auth_pw"
If the current request is protected by Basic authentication, 
this method will return 0, otherwise \-1.  
The second return value will be the decoded password sent by the client.
.Sp
.Vb 1
\&   ($ret, $sent_pw) = $r->get_basic_auth_pw;
.Ve
.Ip "$r->note_basic_auth_failure" 4
.IX Item "$r->note_basic_auth_failure"
Prior to requiring Basic authentication from the client, this method 
will set the outgoing \s-1HTTP\s0 headers asking the client to authenticate 
for the realm defined by the configuration directive \f(CW\*(C`AuthName\*(C'\fR.
.Ip "$r->handler( [$meth] )" 4
.IX Item "$r->handler( [$meth] )"
Set the handler for a request.
Normally set by the configuration directive \f(CW\*(C`AddHandler\*(C'\fR.
.Sp
.Vb 1
\&   $r->handler( "perl-script" );
.Ve
.Ip "$r->notes( \f(CW$key\fR, [$value] )" 4
.IX Item "$r->notes( $key, [$value] )"
Return the value of a named entry in the Apache \f(CW\*(C`notes\*(C'\fR table, or
optionally set the value of a named entry.  This table is used by Apache
modules to pass messages amongst themselves. Generally if you are
writing handlers in mod_perl you can use Perl variables for this.
.Sp
.Vb 2
\&   $r->notes("MY_HANDLER" => OK);
\&   $val = $r->notes("MY_HANDLER");
.Ve
Will return a \fI\s-1HASH\s0\fR reference blessed into the \fIApache::Table\fR
class when called in a scalar context with no \*(L"key\*(R" argument. This
requires \fIApache::Table\fR.
.Ip "$r->pnotes( \f(CW$key\fR, [$value] )" 4
.IX Item "$r->pnotes( $key, [$value] )"
Like \f(CW$r\fR->notes, but takes any scalar as an value.
.Sp
.Vb 3
\&   $r->pnotes("MY_HANDLER" => [qw(one two)]);
\&   my $val = $r->pnotes("MY_HANDLER");
\&   print $val->[0];     # prints "one"
.Ve
Advantage over just using a Perl variable is that \f(CW$r\fR->pnotes gets
cleaned up after every request.
.Ip "$r->subprocess_env( \f(CW$key\fR, [$value] )" 4
.IX Item "$r->subprocess_env( $key, [$value] )"
Return the value of a named entry in the Apache \f(CW\*(C`subprocess_env\*(C'\fR
table, or optionally set the value of a named entry. This table is
used by mod_include.  By setting some custom variables inside
a perl handler it is possible to combine perl with mod_include nicely.
If you say, e.g. in a PerlHeaderParserHandler
.Sp
.Vb 1
\&   $r->subprocess_env(MyLanguage => "de");
.Ve
you can then write in your .shtml document:
.Sp
.Vb 7
\&   <!--#if expr="$MyLanguage = en" -->
\&   English
\&   <!--#elif expr="$MyLanguage = de" -->
\&   Deutsch
\&   <!--#else -->
\&   Sorry
\&   <!--#endif -->
.Ve
Will return a \fI\s-1HASH\s0\fR reference blessed into the \fIApache::Table\fR
class when called in a scalar context with no \*(L"key\*(R" argument. This
requires \fIApache::Table\fR.
.Ip "$r->content_type( [$newval] )" 4
.IX Item "$r->content_type( [$newval] )"
Get or set the content type being sent to the client.  Content types
are strings like \*(L"text/plain\*(R", \*(L"text/html\*(R" or \*(L"image/gif\*(R".  This
corresponds to the \*(L"Content-Type\*(R" header in the \s-1HTTP\s0 protocol.  Example
of usage is:
.Sp
.Vb 2
\&   $previous_type = $r->content_type;
\&   $r->content_type("text/plain");
.Ve
.Ip "$r->content_encoding( [$newval] )" 4
.IX Item "$r->content_encoding( [$newval] )"
Get or set the content encoding.  Content encodings are string like
\&\*(L"gzip\*(R" or \*(L"compress\*(R".  This correspond to the \*(L"Content-Encoding\*(R"
header in the \s-1HTTP\s0 protocol.
.Ip "$r->content_languages( [$array_ref] )" 4
.IX Item "$r->content_languages( [$array_ref] )"
Get or set the content languages.  The content language corresponds to the
\&\*(L"Content-Language\*(R" \s-1HTTP\s0 header and is an array reference containing strings
such as \*(L"en\*(R" or \*(L"no\*(R".
.Ip "$r->status( \f(CW$integer\fR )" 4
.IX Item "$r->status( $integer )"
Get or set the reply status for the client request.  The
\&\fBApache::Constants\fR module provide mnemonic names for the status codes.
.Ip "$r->status_line( \f(CW$string\fR )" 4
.IX Item "$r->status_line( $string )"
Get or set the response status line.  The status line is a string like
\&\*(L"200 Document follows\*(R" and it will take precedence over the value specified
using the \f(CW$r\fR->\fIstatus()\fR described above.
.Ip "$r->headers_out" 4
.IX Item "$r->headers_out"
The \f(CW$r\fR->headers_out method will return a \f(CW%hash\fR of server response
headers.  This can be used to initialize a perl hash, or one could use
the \f(CW$r\fR->\fIheader_out()\fR method (described below) to retrieve or set a specific
header value directly.
.Sp
Will return a \fI\s-1HASH\s0\fR reference blessed into the \fIApache::Table\fR
class when called in a scalar context with no \*(L"key\*(R" argument. This
requires \fIApache::Table\fR.
.Ip "$r->header_out( \f(CW$header\fR, \f(CW$value\fR )" 4
.IX Item "$r->header_out( $header, $value )"
Change the value of a response header, or create a new one.  You
should not define any \*(L"Content-XXX\*(R" headers by calling this method,
because these headers use their own specific methods.  Example of use:
.Sp
.Vb 2
\&   $r->header_out("WWW-Authenticate" => "Basic");
\&   $val = $r->header_out($key);
.Ve
.Ip "$r->err_headers_out" 4
.IX Item "$r->err_headers_out"
The \f(CW$r\fR->err_headers_out method will return a \f(CW%hash\fR of server response
headers.  This can be used to initialize a perl hash, or one could use
the \f(CW$r\fR->\fIerr_header_out()\fR method (described below) to retrieve or set a specific
header value directly.
.Sp
The difference between headers_out and err_headers_out is that the
latter are printed even on error, and persist across internal redirects
(so the headers printed for ErrorDocument handlers will have them).
.Sp
Will return a \fI\s-1HASH\s0\fR reference blessed into the \fIApache::Table\fR
class when called in a scalar context with no \*(L"key\*(R" argument. This
requires \fIApache::Table\fR.
.Ip "$r->err_header_out( \f(CW$header\fR, [$value] )" 4
.IX Item "$r->err_header_out( $header, [$value] )"
Change the value of an error response header, or create a new one.
These headers are used if the status indicates an error.
.Sp
.Vb 2
\&   $r->err_header_out("Warning" => "Bad luck");
\&   $val = $r->err_header_out($key);
.Ve
.Ip "$r->no_cache( \f(CW$boolean\fR )" 4
.IX Item "$r->no_cache( $boolean )"
This is a flag that indicates that the data being returned is volatile
and the client should be told not to cache it.
.Ip "$r->print( \f(CW@list\fR )" 4
.IX Item "$r->print( @list )"
This method sends data to the client with \f(CW\*(C`$r\->write_client\*(C'\fR, but first
sets a timeout before sending with \f(CW\*(C`$r\->soft_timeout\*(C'\fR. This method is
called instead of \s-1CORE:\s0:print when you use \fIprint()\fR in your mod_perl programs.
.Sp
This method treats scalar references specially. If an item in \f(CW@list\fR is a
scalar reference, it will be dereferenced before printing. This is a
performance optimization which prevents unneeded copying of large strings,
and it is subtly different from Perl's standard \fIprint()\fR behavior.
.Sp
Example:
.Sp
.Vb 1
\&   $foo = \e"bar"; print($foo);
.Ve
The result is \*(L"bar\*(R", not the \*(L"SCALAR(0xDEADBEEF)\*(R" you might have expected. If
you really want the reference to be printed out, force it into a scalar
context by using \f(CW\*(C`print(scalar($foo))\*(C'\fR.
.Ip "$r->send_fd( \f(CW$filehandle\fR )" 4
.IX Item "$r->send_fd( $filehandle )"
Send the contents of a file to the client.  Can for instance be used
like this:
.Sp
.Vb 3
\&  open(FILE, $r->filename) || return 404;
\&  $r->send_fd(FILE);
\&  close(FILE);
.Ve
.Ip "$r->internal_redirect( \f(CW$newplace\fR )" 4
.IX Item "$r->internal_redirect( $newplace )"
Redirect to a location in the server namespace without 
telling the client. For instance:
.Sp
.Vb 1
\&   $r->internal_redirect("/home/sweet/home.html");
.Ve
.Ip "$r->internal_redirect_handler( \f(CW$newplace\fR )" 4
.IX Item "$r->internal_redirect_handler( $newplace )"
Same as \fIinternal_redirect\fR, but the \fIhandler\fR from \f(CW\*(C`$r\*(C'\fR is preserved.
.Ip "$r->custom_response($code, \f(CW$uri\fR)" 4
.IX Item "$r->custom_response($code, $uri)"
This method provides a hook into the \fBErrorDocument\fR mechanism,
allowing you to configure a custom response for a given response
code at request-time.
.Sp
Example:
.Sp
.Vb 1
\&    use Apache::Constants ':common';
.Ve
.Vb 2
\&    sub handler {
\&        my($r) = @_;
.Ve
.Vb 3
\&        if($things_are_ok) {
\&            return OK;
\&        }
.Ve
.Vb 3
\&        #<Location $r->uri>
\&        #ErrorDocument 401 /error.html
\&        #</Location>
.Ve
.Vb 1
\&        $r->custom_response(AUTH_REQUIRED, "/error.html");
.Ve
.Vb 4
\&        #can send a string too
\&        #<Location $r->uri>
\&        #ErrorDocument 401 "sorry, go away"
\&        #</Location>
.Ve
.Vb 1
\&        #$r->custom_response(AUTH_REQUIRED, "sorry, go away");
.Ve
.Vb 2
\&        return AUTH_REQUIRED;
\&    }
.Ve
.SH "SERVER CORE FUNCTIONS"
.IX Header "SERVER CORE FUNCTIONS"
.Ip "$r->soft_timeout($message)" 4
.IX Item "$r->soft_timeout($message)"
.PD 0
.Ip "$r->hard_timeout($message)" 4
.IX Item "$r->hard_timeout($message)"
.Ip "$r->kill_timeout" 4
.IX Item "$r->kill_timeout"
.Ip "$r->reset_timeout" 4
.IX Item "$r->reset_timeout"
.PD
(Documentation borrowed from http_main.h)
.Sp
There are two functions which modules can call to trigger a timeout
(with the per-virtual-server timeout duration); these are hard_timeout
and soft_timeout.
.Sp
The difference between the two is what happens when the timeout
expires (or earlier than that, if the client connection aborts) \-\-\-
a soft_timeout just puts the connection to the client in an
\&\*(L"aborted\*(R" state, which will cause http_protocol.c to stop trying to
talk to the client, but otherwise allows the code to continue normally.
\&\fIhard_timeout()\fR, by contrast, logs the request, and then aborts it
completely \-\-\- \fIlongjmp()\fRing out to the \fIaccept()\fR loop in http_main.
Any resources tied into the request resource pool will be cleaned up;
everything that is not will leak.
.Sp
\&\fIsoft_timeout()\fR is recommended as a general rule, because it gives your
code a chance to clean up.  However, \fIhard_timeout()\fR may be the most
convenient way of dealing with timeouts waiting for some external
resource other than the client, if you can live with the restrictions.
.Sp
When a hard timeout is in scope, critical sections can be guarded
with \fIblock_alarms()\fR and \fIunblock_alarms()\fR \-\-\- these are declared in
alloc.c because they are most often used in conjunction with
routines to allocate something or other, to make sure that the
cleanup does get registered before any alarm is allowed to happen
which might require it to be cleaned up; they * are, however,
implemented in http_main.c.
.Sp
\&\fIkill_timeout()\fR will disarm either variety of timeout.
.Sp
\&\fIreset_timeout()\fR resets the timeout in progress.
.Ip "$r->post_connection($code_ref)" 4
.IX Item "$r->post_connection($code_ref)"
.PD 0
.Ip "$r->register_cleanup($code_ref)" 4
.IX Item "$r->register_cleanup($code_ref)"
.PD
Register a cleanup function which is called just before \f(CW$r\fR->pool is
destroyed.
.Sp
.Vb 4
\&   $r->register_cleanup(sub {
\&       my $r = shift;
\&       warn "registered cleanup called for ", $r->uri, "\en";
\&   });
.Ve
Cleanup functions registered in the parent process (before forking)
will run once when the server is shut down:
.Sp
.Vb 3
\&   #PerlRequire startup.pl
\&   warn "parent pid is $$\en";
\&   Apache->server->register_cleanup(sub { warn "server cleanup in $$\en"});
.Ve
The \fIpost_connection\fR method is simply an alias for \fIregister_cleanup\fR, 
as this method may be used to run code after the client connection is closed,
which may not be a \fIcleanup\fR.
.SH "CGI SUPPORT"
.IX Header "CGI SUPPORT"
We also provide some methods that make it easier to support the \s-1CGI\s0
type of interface.
.Ip "$r->\fIsend_cgi_header()\fR" 4
.IX Item "$r->send_cgi_header()"
Take action on certain headers including \fIStatus:\fR, \fILocation:\fR and
\&\fIContent-type:\fR just as mod_cgi does, then calls
\&\f(CW$r\fR->\fIsend_http_header()\fR.  Example of use:
.Sp
.Vb 3
\&   $r->send_cgi_header(<<EOT);
\&   Location: /foo/bar
\&   Content-type: text/html
.Ve
.Vb 1
\&   EOT
.Ve
.SH "ERROR LOGGING"
.IX Header "ERROR LOGGING"
The following methods can be used to log errors. 
.Ip "$r->log_reason($message, \f(CW$file\fR)" 4
.IX Item "$r->log_reason($message, $file)"
The request failed, why??  Write a message to the server errorlog.
.Sp
.Vb 1
\&   $r->log_reason("Because I felt like it", $r->filename);
.Ve
.Ip "$r->log_error($message)" 4
.IX Item "$r->log_error($message)"
Uh, oh.  Write a message to the server errorlog.
.Sp
.Vb 1
\&   $r->log_error("Some text that goes in the error_log");
.Ve
.Ip "$r->warn($message)" 4
.IX Item "$r->warn($message)"
For pre-1.3 versions of apache, this is just an alias for
\&\f(CW\*(C`log_error\*(C'\fR.  With 1.3+ versions of apache, this message will only be
send to the error_log if \fBLogLevel\fR is set to \fBwarn\fR or higher. 
.SH "UTILITY FUNCTIONS"
.IX Header "UTILITY FUNCTIONS"
.Ip "Apache::unescape_url($string)" 4
.IX Item "Apache::unescape_url($string)"
Handy function for unescapes.  Use this one for filenames/paths.
Use unescape_url_info for the result of submitted form data.
.Ip "Apache::unescape_url_info($string)" 4
.IX Item "Apache::unescape_url_info($string)"
Handy function for unescapes submitted form data.
In opposite to unescape_url it translates the plus sign to space.
.Ip "Apache::perl_hook($hook)" 4
.IX Item "Apache::perl_hook($hook)"
Returns true if the specified callback hook is enabled:
.Sp
.Vb 5
\&   for (qw(Access Authen Authz ChildInit Cleanup Fixup
\&           HeaderParser Init Log Trans Type))
\&   {
\&       print "$_ hook enabled\en" if Apache::perl_hook($_);
\&   }
.Ve
.SH "GLOBAL VARIABLES"
.IX Header "GLOBAL VARIABLES"
.Ip "$Apache::Server::Starting" 4
.IX Item "$Apache::Server::Starting"
Set to true when the server is starting.
.Ip "$Apache::Server::ReStarting" 4
.IX Item "$Apache::Server::ReStarting"
Set to true when the server is starting.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1),
\&\fIApache::Constants\fR\|(3),
\&\fIApache::Registry\fR\|(3),
\&\fIApache::Debug\fR\|(3),
\&\fIApache::Options\fR\|(3),
\&\s-1CGI:\\fIs0:Apache\fR\|(3)
.PP
Apache C \s-1API\s0 notes at \f(CW\*(C`http://www.apache.org/docs/\*(C'\fR
.SH "AUTHORS"
.IX Header "AUTHORS"
Perl interface to the Apache C \s-1API\s0 written by Doug MacEachern
with contributions from Gisle Aas, Andreas Koenig, Eric Bartley, 
Rob Hartill, Gerald Richter, Salvador Ortiz and others. 
