The Apache API is a set of routines that C programmers can use to write Apache modules. One of the most powerful features of mod_perl is its Perl API, which gives Perl programmers access to the Apache API. For information on how to program Apache modules in Perl, see Writing Apache Modules in Perl and C by Lincoln Stein and Doug MacEachern (O'Reilly).
The following methods are defined for the Perl API to Apache.
aborted |
$c->aborted
Returns true if the client aborted the transaction.
allow_options |
$r->allow_options
Checks the options allowed for this request.
allowed |
$r->allowed($bitmask)
Gets or sets the "allowed methods" bitmask.
args |
$r->args( [$query_string] )
Returns the query string portion of the URI either as a string (scalar context) or as a list of key/value pairs (list context).
as_string |
$r->as_string
Returns a string representation of the request object.
auth_name |
$r->auth_name
Returns a reference to the value of the AuthName directive.
auth_type |
$c->auth_type
Returns the authentication scheme.
auth_type |
$r->auth_type
Returns a reference to the value of the AuthType directive.
bytes_sent |
$r->bytes_sent
Returns the number of bytes sent to the client.
connection |
$c = $r->connection
Returns a reference to the request connection object.
content |
$r->content
If the request content type is application/x-www-form-urlencoded, returns the entity body either as a string (scalar context) or as a list of key/value pairs (list context).
content_encoding |
$r->content_encoding( [$value] )
Returns the content encoding of the entity.
content_languages |
$r->content_languages( [$ref] )
Returns the content language(s) of the entity as an array reference.
content_type |
$r->content_type( [$value] )
Returns the content type of the entity.
current_callback |
$r->current_callback
Returns the name of the current handler.
custom_response |
$r->custom_response($code, $uri)
Creates a custom response for the specified response code.
dir_config |
$r->dir_config( $key )
Returns the value associated with $key as specified by the PerlSetVar directive.
dir_config |
$s->dir_config( $key )
Same as Apache::dir_config.
document_root |
$r->document_root ( [$docroot] )
Returns a reference to the value of the DocumentRoot directive.
err_header_out |
$r->err_header_out( $header, [$value] )
Retrieves a specific response header when an error is encountered.
err_headers_out |
$r->err_headers_out
Returns a hash of server response headers when an error is encountered.
filename |
$r->filename( [$filename] )
Returns the filename that the URI resolves to.
fileno |
$c->fileno( [$n] )
Returns either the client output file descriptor, or the input file descriptor if an argument of 0 is given.
get |
$r->dir_config->get( $key )
Returns the value associated with $key as specified by the PerlAddVar directive.
get_basic_auth_pw |
$r->get_basic_auth_pw
Reports whether the request uses Basic authentication, or returns a value such as AUTH_REQUIRED that needs to be conveyed back to the client.
get_handlers |
$r->get_handlers( $phase )
Returns a reference to a list of handlers enabled for the specified request phase.
get_remote_host |
$r->get_remote_host
Returns the client's DNS hostname.
get_remote_logname |
$r->get_remote_logname
Returns the client's login name.
get_server_port |
$r->get_server_port
Returns server's port number.
gid |
$s->gid
Returns the group ID under the server uses.
handler |
$r->handler( [$meth] )
Specifies the handler for the request.
hard_timeout |
$r->hard_timeout($string)
Performs a hard timeout with the specified message.
header_only |
$r->header_only
Returns true if the request method is HEAD.
header_out |
$r->header_out( $header, $value )
Retrieves a specific response header.
headers_in |
$r->headers_in
Returns a hash of client request headers.
headers_out |
$r->headers_out
Returns a hash of server response headers.
hostname |
$r->hostname
Returns the server hostname.
internal_redirect |
$r->internal_redirect( $location )
Redirects transparently to a different location on the server.
internal_redirect_handler |
$r->internal_redirect_handler( $location )
Redirects transparently to a different location on the server, preserving the handler.
is_initial_req |
$r->is_initial_req
Returns true if the current request is the first request.
is_main |
$r->is_main
Returns true if the main request is current.
is_virtual |
$s->is_virtual
Returns true for virtual servers.
kill_timeout |
$r->kill_timeout
Performs a kill timeout.
last |
$r->last
Returns a reference to the last request structure.
local_addr |
$c->local_addr
Returns the port and address on the local host.
location |
$r->location
Returns the location that the current Perl handler is being called from.
log_error |
$r->log_error($message)
Logs a message to the error log.
log_error |
$s->log_error
Same as Apache::log_error.
log_reason |
$r->log_reason($message, $logfile)
Logs a message to the specified error log.
loglevel |
$s->loglevel
Returns the current LogLevel.
lookup_file |
$r->lookup_file($filename)
Looks up the specified file.
lookup_uri |
$r->lookup_uri($uri)
Looks up the specified URI.
main |
$r->main
Returns a reference to the main request, or undef if the current request is the main request.
method |
$r->method( [$meth] )
Returns the request method.
method_number |
$r->method_number( [$num] )
Returns the request method number as defined by the M_GET and M_POST,... constants available from the Apache::Constants module.
names |
$s->names
Returns aliases for the server.
next |
$r->next
Returns a reference to the next request or undef if there is none.
no_cache |
$r->no_cache( $boolean )
Specifies whether the returned data should be cached.
note_basic_auth_failure |
$r->note_basic_auth_failure
Sets the HTTP headers requesting authentication for the realm.
notes |
$r->notes( $key, [$value] )
Returns (or sets) a value from the Apache notes table. See also pnotes.
path_info |
$r->path_info( [$path_info] )
Returns the path_info portion of the URI.
perl_hook |
Apache::perl_hook($hook)
Reports whether the specified callback hook is in effect.
pnotes |
$r->pnotes( $key, [$value] )
Returns (or sets) a value from the Apache notes table, taking any scalar as $value. The value is cleaned up after every request.
port |
$s->port
Returns the server's port number.
post_connection |
$r->post_connection($code_ref)
Registers a cleanup function.
prev |
$r->prev
Returns a reference to the previous request or undef if there is none.
$r->print( @list )
Sends the specified data to the client.
protocol |
$r->protocol
Returns the HTTP protocol that the client uses.
proxyreq |
$r->proxyreq
Returns true if the request is a proxy request.
push_handlers |
$r->push_handlers( $phase, \&handler )
Specifies a new handler to be called for the specified request phase.
read |
$r->read($buf, $num_bytes, [$offset])
Reads data from the client starting at the optional $offset until it reaches $num_bytes or reaches a timeout.
register_cleanup |
$r->register_cleanup($code_ref)
Registers a cleanup function.
remote_addr |
$c->remote_addr
Returns the port and address on the remote host.
remote_host |
$c->remote_host
Returns the client's hostname.
remote_ip |
$c->remote_ip
Returns the client's IP address.
remote_logname |
$c->remote_logname
Returns the remote user's login name.
request |
Apache->request([$r])
Returns a reference to the request object.
request_time |
$r->request_time
Returns the timestamp of the request.
requires |
$r->requires
Returns an array reference with information relating to the require directive.
reset_timeout |
$r->reset_timeout
Resets the current timeout.
run |
$subr->run
Executes the subroutine.
send_cgi_header |
$r->send_cgi_header()
Specifies CGI headers and calls send_http_header().
send_fd |
$r->send_fd( $filehandle )
Sends the specified file to the client.
send_http_header |
$r->send_http_header( [$content_type] )
Sends the http header to the client.
server |
$s = $r->server
Return a reference to the server info object. Can also be used without a request object (i.e,, Apache->server) for startup files.
server_admin |
$s->server_admin
Returns the webmaster's email address.
server_hostname |
$s->server_hostname
Returns the server's hostname.
server_root_relative |
$r->server_root_relative( [$path] )
Returns the value of the ServerRoot directory, or concatenates $path to that value. Can also be used without a request object (i.e., Apache->server_root_relative) for startup files.
set_handlers |
$r->set_handlers( $phase, [\&handler, ... ] )
Specifies the handlers to be called for the specified request phase.
soft_timeout |
$r->soft_timeout($string)
Performs a soft timeout with the specified message.
status |
$r->status( $integer )
Returns the 3-digit response status code for the request.
status_line |
$r->status_line( $string )
Returns the response status string for the request.
subprocess_env |
$r->subprocess_env( $key, [$value] )
Returns (or sets) a value from the Apache subprocess_env table.
the_request |
$r->the_request
Returns the request line sent by the client.
uid |
$s->uid
Returns the user ID the server uses.
unescape_url |
Apache::unescape_url($string)
Removes escapes for the specified URL.
unescape_url_info |
Apache::unescape_url_info($string)
Removes escapes from the specified form data.
uri |
$r->uri( [$uri] )
Returns the requested URI.
user |
$c->user( [$user] )
Returns the authenticated user name.
warn |
$r->warn($message)
Logs a message to the error log. Only works if the LogLevel is "warn" or higher under Apache 1.3 and later.
Copyright © 2003 O'Reilly & Associates. All rights reserved.