MAN page from Old RedHat 5.X mod_perl-1.11-3.i386.rpm

Apache

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Apache - Perl interface to the Apache server API

SYNOPSIS

   use Apache ();

DESCRIPTION

This module provides a Perl interface the Apache API. It is heremainly for mod_perl, but may be used for other Apache modules thatwish to embed a Perl interpreter. We suggest that you also consultthe description of the Apache C API at http://www.apache.org/docs/.

THE REQUEST OBJECT

The request object holds all the information that the server needs toservice a request. Apache Perl*Handlers will be given a reference to therequest object as parameter and may choose update or use it in variousways. Most of the methods described below obtain information from orupdates the request object.The perl version of the request object will be blessed into the Apache package, it is really a request_rec* in disguise.

Apache->request([$r]): The Apache->request method will return a reference to the request object.
Perl*Handlers can obtain a reference to the request object when itis passed to them via @_. However, scripts that run under Apache::Registry, for example, need a way to access the request object.Apache::Registry will make a request object available to these scriptsby passing an object reference to Apache->request($r).If handlers use modules such as CGI::Apache that need to accessApache->request, they too should do this (e.g. Apache::Status).
$r->as_string: Returns a string representation of the request object. Mainly usefulfor debugging.
$r->main: If the current request is a sub-request, this method returns a blessedreference to the main request structure. If the current request isthe main request, then this method returns undef.
$r->prev: This method returns a blessed reference to the previous (internal) requeststructure or undef if there is no previous request.
$r->next: This method returns a blessed reference to the next (internal) requeststructure or undef if there is no next request.
$r->is_main: Returns true if the current request object is for the main request.(Should give the same result as !$r->main, but will be more efficient.)
$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.

SUB REQUESTS

Apache provides a sub-request mechanism to lookup a uri or filename,performing all access checks, etc., without actually running theresponse phase of the given request. Notice, we have dropped thesub_req_ prefix here. The request_rec* returned by the lookupmethods is blessed into the Apache::SubRequest class. This way,destroy_sub_request() is called automatically duringApache::SubRequest->DESTROY when the object goes out of scope. TheApache::SubRequest class inherits all the methods from theApache class.

$r->lookup_uri($uri)

   my $subr = $r->lookup_uri($uri);   my $filename = $subr->filename;

   unless(-e $filename) {       warn "can't stat $filename!\n";   }

$r->lookup_file($filename)

   my $subr = $r->lookup_file($filename);

$subr->run

   if($subr->run != OK) {       $subr->log_error("something went wrong!");   }

CLIENT REQUEST PARAMETERS

In this section we will take a look at various methods that can be used toretrieve the request parameters sent from the client.In the following examples, $r is a request object blessed into the Apache class, obtained by the first parameter passed to a handler subroutineor Apache->request

$r->method( [$meth] )

The $r->method method will return the request method. It will be astring such as ``GET'', ``HEAD'' or ``POST''.Passing an argument will set the method, mainly used for internal redirects.

$r->method_number( [$num] )

The $r->method_number method will return the request method number.The method numbers are defined by the M_GET, M_POST,... constantsavailable from the Apache::Constants module. Passing an argumentwill set the method_number, mainly used for internal redirects andtesting authorization restriction masks.

$r->bytes_sent

The number of bytes sent to the client, handy for logging, etc.

$r->the_request

The request line send by the client, handy for logging, etc.

$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 PerlTransHandler.

$r->header_only

Returns true if the client is asking for headers only, e.g. if the request method was HEAD.

$r->protocol

The $r->protocol method will return a string identifying the protocolthat the client speaks. Typical values will be ``HTTP/1.0'' or``HTTP/1.1''.

$r->uri( [$uri] )

The $r->uri method will return the requested URI, optionally changingit with the first argument.

$r->filename( [$filename] )

The $r->filename method will return the result of the URI -->filename translation, optionally changing it with the first argumentif you happen to be doing the translation.

$r->path_info( [$path_info] )

The $r->path_info method will return what is left in the path after theURI --> filename translation, optionally changing it with the first argument if you happen to be doing the translation.

$r->args

The $r->args method will return the contents of the URI querystring. When called in a scalar context, the entire string isreturned. When called in a list context, a list of parsed key =>value pairs are returned, i.e. it can be used like this:

   $query = $r->args;   %in    = $r->args;

$r->headers_in

The $r->headers_in method will return a %hash of client requestheaders. This can be used to initialize a perl hash, or one could usethe $r->header_in() method (described below) to retrieve a specificheader value directly.

$r->header_in( $header_name, [$value] )

Return the value of a client header. Can be used like this:

   $ct = $r->header_in("Content-type");   $r->header_in($key, $val); #set the value of header '$key'

$r->content

The $r->content method will return the entity body read from theclient, but only if the request content type isapplication/x-www-form-urlencoded.When called in a scalar context, the entire string isreturned. When called in a list context, a list of parsed key =>value pairs are returned. *NOTE*: you can only ask for this once,as the entire body is read from the client.

$r->read_client_block($buf, $bytes_to_read)

Read from the entity body sent by the client. Example of use:

   $r->read_client_block($buf, $r->header_in('Content-length'));

$r->read($buf, $bytes_to_read)

This method uses read_client_block() to read data from the client, looping until it gets all of $bytes_to_read or a timeout happens.

In addition, this method sets a timeout before reading with$r->hard_timeout

$r->get_remote_host

Lookup the client's DNS hostname. If the configuration directiveHostNameLookups is set to off, this returns the dotted decimalrepresentation of the client's IP address instead. Might returnundef if the hostname is not known.

$r->get_remote_logname

Lookup the remote user's system name. Might return undef if theremote system is not running an RFC 1413 server or if the configurationdirective IdentityCheck is not turned on.

More information about the client can be obtained from theApache::Connection object, as described below.

$c = $r->connection

The $r->connection method will return a reference to the requestconnection object (blessed into the Apache::Connection package).This is really a conn_rec* in disguise. The following methods canbe used on the connection object:

$c->remote_host

If the configuration directive HostNameLookups is set to on: thenthe first time $r->get_remote_host is called the server does a DNSlookup to get the remote client's host name. The result is cached in$c->remote_host then returned. If the server was unable to resolvethe remote client's host name this will be set to "". Subsequent callsto $r->get_remote_host return this cached value.

If the configuration directive HostNameLookups is set to off: callsto $r->get_remote_host return a string that contains the dotteddecimal representation of the remote client's IP address. However thisstring is not cached, and $c->remote_host is undefined. So, it'sbest to to call $r->get_remote_host instead of directly accessingthis variable.

$c->remote_ip

The dotted decimal representation of the remote client's IP address.This is set by then server when the connection record is created sois always defined.

$c->local_addr

A packed SOCKADDR_IN in the same format as returned bythe pack_sockaddr_in entry in the Socket manpage, containing the port and address on thelocal host that the remote client is connected to. This is set bythe server when the connection record is created so it is alwaysdefined.

$c->remote_addr

A packed SOCKADDR_IN in the same format as returned bythe pack_sockaddr_in entry in the Socket manpage, containing the port and address on theremote host that the server is connected to. This is set by theserver when the connection record is created so it is always defined.

Among other things, this can be used, together with $c->local_addr, toperform RFC1413 ident lookups on the remote client even when theconfiguration directive IdentityCheck is turned off.

Can be used like:

   use Net::Ident qw (lookupFromInAddr);   ...   my $remoteuser = lookupFromInAddr ($c->local_addr,                                      $c->remote_addr, 2);

Note that the lookupFromInAddr interface does not currently exist inthe Net::Ident module, but the author is planning on adding itsoon.

$c->remote_logname

If the configuration directive IdentityCheck is set to on: then thefirst time $r->get_remote_logname is called the server does an RFC1413 (ident) lookup to get the remote users system name. Generally forUNI* systems this is their login. The result is cached in $c->remote_lognamethen returned. Subsequent calls to $r->get_remote_host return thecached value.

If the configuration directive IdentityCheck is set to off: then $r->get_remote_logname does nothing and $c->remote_logname isalways undefined.

$c->user

If an authentication check was successful, the authentication handlercaches the user name here.

$c->auth_type

Returns the authentication scheme that successfully authenticate$c->user, if any.

$c->aborted

Returns true if the client stopped talking to us.

SERVER CONFIGURATION INFORMATION

The following methods are used to obtain information from serverconfiguration and access control files.

$r->dir_config( $key )

Returns the value of a per-directory variable specified by the PerlSetVar directive.

   # <Location /foo/bar>   # SetPerlVar  Key  Value   # </Location>

   my $val = $r->dir_config('Key');

$r->requires

Returns an array reference of hash references, containing informationrelated to the require directive. This is normally used for accesscontrol, see the Apache::AuthzAge manpage for an example.

$r->auth_type

Returns a reference to the current value of the per directoryconfiguration directive AuthType. Normally this would be set toBasic to use the basic authentication scheme defined in RFC 1945,Hypertext Transfer Protocol -- HTTP/1.0. However, you could set tosomething else and implement your own authentication scheme.

$r->auth_name

Returns a reference to the current value of the per directoryconfiguration directive AuthName. The AuthName directive createsprotection realm within the server document space. To quote RFC 1945``These realms allow the protected resources on a server to bepartitioned into a set of protection spaces, each with its ownauthentication scheme and/or authorization database.'' The client usesthe root URL of the server to determine which authenticationcredentials to send with each HTTP request. These credentials aretagged with the name of the authentication realm that created them.Then during the authentication stage the server uses the currentauthentication realm, from $r->auth_name, to determine which set ofcredentials to authenticate.

$r->document_root

Returns a reference to the current value of the per serverconfiguration directive DocumentRoot. To quote the Apache serverdocumentation, ``Unless matched by a directive like Alias, the serverappends the path from the requested URL to the document root to makethe path to the document.'' This same value is passed to CGIscripts in the DOCUMENT_ROOT environment variable.

$r->allow_options

The $r->allow_options method can be used forchecking if it is OK to run a perl script. The Apache::Optionsmodule provides the constants to check against.

   if(!($r->allow_options & OPT_EXECCGI)) {       $r->log_reason("Options ExecCGI is off in this directory",                       $filename);   }

$s = $r->server

Return a reference to the server info object (blessed into theApache::Server package). This is really a server_rec* indisguise. The following methods can be used on the server object:

$s = Apache->server

Same as above, but only available during server startup for use in<Perl> sections, PerlScript or PerlModule.

$s->server_admin

Returns the mail address of the person responsible for this server.

$s->server_hostname

Returns the hostname used by this server.

$s->port

Returns the port that this servers listens too.

$s->is_virtual

Returns true if this is a virtual server.

$s->names

Returns the wild-carded names for HostAlias servers.

$s->warn

Alias for Apache::warn.

$s->log_error

Alias for Apache::log_error.

SETTING UP THE RESPONSE

The following methods are used to set up and return the response backto the client. This typically involves setting up $r->status(), thevarious content attributes and optionally some additional$r->header_out() calls before calling $r->send_http_header() which willactually send the headers to the client. After this a typicalapplication will call the $r->print() method to send the responsecontent to the client.

$r->send_http_header

Send the response line and all headers to the client.

This method will create headers from the $r->content_xxx() and$r->no_cache() attributes (described below) and then append theheaders defined by $r->header_out (or $r->err_header_out if statusindicates an error).

$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.

   ($ret, $sent_pw) = $r->get_basic_auth_pw;

$r->note_basic_auth_failure

Prior to requiring Basic authentication from the client, this method will set the outgoing HTTP headers asking the client to authenticate for the realm defined by the configuration directive AuthName.

$r->handler( [$meth] )

Set the handler for a request.Normally set by the configuration directive AddHandler.

$r->handler( ``perl-script'' );

$r->notes( $key, [$value] )

Return the value of a named entry in the Apache notes table, oroptionally set the value of a named entry. This table is used by Apachemodules to pass messages amongst themselves. Generally if you arewriting handlers in mod_perl you can use Perl variables for this.

   $r->notes("MY_HANDLER", OK);   $val = $r->notes("MY_HANDLER");

$r->subprocess_env( $key, [$value] )

Return the value of a named entry in the Apache subprocess_envtable, or optionally set the value of a named entry. This table isused by mod_include. By setting some custom variables insidea perl handler it is possible to combine perl with mod_include nicely.If you say, e.g. in a PerlHeaderParserHandler

   $r->subprocess_env(MyLanguage => "de");

you can then write in your .shtml document:

   <!--#if expr="$MyLanguage = en" -->   English   <!--#elif expr="$MyLanguage = de" -->   Deutsch   <!--#else -->   Sorry   <!--#endif -->

$r->content_type( [$newval] )

Get or set the content type being sent to the client. Content typesare strings like ``text/plain'', ``text/html'' or ``image/gif''. Thiscorresponds to the ``Content-Type'' header in the HTTP protocol. Exampleof usage is:

   $previous_type = $r->content_type;   $r->content_type("text/plain");

$r->content_encoding( [$newval] )

Get or set the content encoding. Content encodings are string like``gzip'' or ``compress''. This correspond to the ``Content-Encoding''header in the HTTP protocol.

$r->content_languages( [$array_ref] )

Get or set the content languages. The content language corresponds to the``Content-Language'' HTTP header and is an array reference containing stringssuch as ``en'' or ``no''.

$r->status( $integer )

Get or set the reply status for the client request. TheApache::Constants module provide mnemonic names for the status codes.

$r->status_line( $string )

Get or set the response status line. The status line is a string like``200 Document follows'' and it will take precedence over the value specifiedusing the $r->status() described above.

$r->headers_out

The $r->headers_out method will return a %hash of server responseheaders. This can be used to initialize a perl hash, or one could usethe $r->header_out() method (described below) to retrieve or set a specificheader value directly.

$r->header_out( $header, $value )

Change the value of a response header, or create a new one. Youshould not define any ``Content-XXX'' headers by calling this method,because these headers use their own specific methods. Example of use:

   $r->header_out("WWW-Authenticate" => "Basic");   $val = $r->header_out($key);

$r->err_headers_out

The $r->err_headers_out method will return a %hash of server responseheaders. This can be used to initialize a perl hash, or one could usethe $r->err_header_out() method (described below) to retrieve or set a specificheader value directly.

The difference between headers_out and err_headers_out is that thelatter are printed even on error, and persist across internal redirects(so the headers printed for ErrorDocument handlers will have them).

$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.

   $r->err_header_out("Warning" => "Bad luck");   $val = $r->err_header_out($key);

$r->no_cache( $boolean )

This is a flag that indicates that the data being returned is volatileand the client should be told not to cache it.

$r->print( @list )

This method sends data to the client with $r->write_client, but firstsets a timeout before sending with $r->hard_timeout.

$r->send_fd( $filehandle )

Send the contents of a file to the client. Can for instance be usedlike this:

  open(FILE, $r->filename) || return 404;  $r->send_fd(FILE);  close(FILE);

$r->internal_redirect_handler( $newplace )

Redirect to a location in the server namespace without telling the client. For instance:

   $r->internal_redirect_handler("/home/sweet/home.html");

$r->custom_response($code, $uri)

This method provides a hook into the ErrorDocument mechanism,allowing you to configure a custom response for a given responsecode at request-time.

Example:

    use Apache::Constants ':common';

    sub handler {        my($r) = @_;

        if($things_are_ok) {            return OK;        }

        #<Location $r->uri>        #ErrorDocument 401 /error.html        #</Location>

        $r->custom_response(AUTH_REQUIRED, "/error.html");

        #can send a string too        #<Location $r->uri>        #ErrorDocument 401 "sorry, go away"        #</Location>

        #$r->custom_response(AUTH_REQUIRED, "sorry, go away");

        return AUTH_REQUIRED;    }

SERVER CORE FUNCTIONS

$r->soft_timeout($message)

$r->hard_timeout($message)

$r->kill_timeout

$r->reset_timeout

(Documentation borrowed from http_main.h)

There are two functions which modules can call to trigger a timeout(with the per-virtual-server timeout duration); these are hard_timeoutand soft_timeout.

The difference between the two is what happens when the timeoutexpires (or earlier than that, if the client connection aborts) ---a soft_timeout just puts the connection to the client in an``aborted'' state, which will cause http_protocol.c to stop trying totalk to the client, but otherwise allows the code to continue normally.hard_timeout(), by contrast, logs the request, and then aborts itcompletely --- longjmp()ing out to the accept() loop in http_main.Any resources tied into the request resource pool will be cleaned up;everything that is not will leak.

soft_timeout() is recommended as a general rule, because it gives yourcode a chance to clean up. However, hard_timeout() may be the mostconvenient way of dealing with timeouts waiting for some externalresource other than the client, if you can live with the restrictions.

When a hard timeout is in scope, critical sections can be guardedwith block_alarms() and unblock_alarms() --- these are declared inalloc.c because they are most often used in conjunction withroutines to allocate something or other, to make sure that thecleanup does get registered before any alarm is allowed to happenwhich might require it to be cleaned up; they * are, however,implemented in http_main.c.

kill_timeout() will disarm either variety of timeout.

reset_timeout() resets the timeout in progress.

$r->register_cleanup($code_ref)

   $r->register_cleanup(sub {       my $r = shift;       warn "registered cleanup called for ", $r->uri, "\n";   });

CGI SUPPORT

We also provide some methods that make it easier to support the CGItype of interface.

$r->cgi_env

Return a %hash that can be used to set up a standard CGI environment.Typical usage would be:

   %ENV = $r->cgi_env

NOTE: The $ENV{GATEWAY_INTERFACE} is set to 'CGI-Perl/1.1' soyou can say:

   if($ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/) {       # do mod_perl stuff   }   else {       # do normal CGI stuff   }

When given a key => value pair, this will set an environment variable.

   $r->cgi_env(REMOTE_GROUP => "camels");

$r->cgi_var($key);

Calls $r->cgi_env($key) in a scalar context to prevent the mistakeof calling in a list context.

   my $doc_root = $r->cgi_env('DOCUMENT_ROOT');

$r->send_cgi_header()

Take action on certain headers including Status:, Location: andContent-type: just as mod_cgi does, then calls$r->send_http_header(). Example of use:

   $r->send_cgi_header(<<EOT);   Location: /foo/bar   Content-type: text/html       EOT

ERROR LOGGING

The following methods can be used to log errors.

$r->log_reason($message, $file)

The request failed, why?? Write a message to the server errorlog.

   $r->log_reason("Because I felt like it", $r->filename);

$r->log_error($message)

Uh, oh. Write a message to the server errorlog.

   $r->log_error("Some text that goes in the error_log");

$r->warn($message)

For pre-1.3 versions of apache, this is just an alias forlog_error. With 1.3+ versions of apache, this message will only besend to the error_log if LogLevel is set to warn or higher.

UTILITY FUNCTIONS

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.

Apache::unescape_url_info($string)

Handy function for unescapes submitted form data.In opposite to unescape_url it translates the plus sign to space.

Apache::perl_hook($hook)

Returns true if the specified callback hook is enabled:

   for (qw(Access Authen Authz ChildInit Cleanup Fixup           HeaderParser Init Log Trans Type))   {       print "$_ hook enabled\n" if Apache::perl_hook($_);   }

AUTHORS

Perl interface to the Apache C API written by Doug MacEachernwith contributions from Gisle Aas, Andreas Koenig, Eric Bartley, Rob Hartill, Gerald Richter, Salvador Garcia and others.

This document was created byman2html,using the manual pages.