B.17 Core Apache Modules

B.17.1 Apache::Module—Interface to Apache C Module Structures

This module provides an interface to the list of Apache modules configured with your httpd server and their module * structures.

Available from CPAN. See the module manpage for more information.

B.17.2 Apache::ShowRequest—Show Phases and Module Participation

Part of the Apache::Module package. This module allows you to see the all phases of the request and what modules are participating in each of the phases.

Available from CPAN. See the module manpage for more information.

B.17.3 Apache::SubProcess—Interface to Apache Subprocess API

The output of system( ), exec( ), and open(PIPE,"|program") calls will not be sent to the browser unless your Perl interpreter was configured with sfio.

One workaround is to use backticks:

print `command here`;

But a cleaner solution is provided by the Apache::SubProcess module. It overrides the exec( ) and system( ) calls with calls that work correctly under mod_perl.

Let's look at a few examples. This example overrides the built-in system( ) function and sends the output to the browser:

use Apache::SubProcess qw(system);
my $r = shift;
$r->send_http_header('text/plain');

system "/bin/echo hi there";

This example overrides the built-in exec( ) function and sends the output to the browser. As you can guess, the print statement after the exec( ) call will never be executed.

use Apache::SubProcess qw(exec);
my $r = shift;
$r->send_http_header('text/plain');

exec "/usr/bin/cal"; 

print "NOT REACHED\n";

The env( ) function sets an environment variable that can be seen by the main process and subprocesses, then it executes the /bin/env program via call_exec( ). The main code spawns a process, and tells it to execute the env( ) function. This call returns an output file handle from the spawned child process. Finally, it takes the output generated by the child process and sends it to the browser via send_fd( ), which expects the file handle as an argument:

use Apache::SubProcess ( );
my $r = shift;
$r->send_http_header('text/plain');

my $efh = $r->spawn_child(\&env);
$r->send_fd($efh);

sub env {
    my $fh = shift;
    $fh->subprocess_env(HELLO => 'world');
    $fh->filename("/bin/env");
    $fh->call_exec;
}

This example is very similar to the previous example, but it shows how you can pass arguments to the external process. It passes the string to print as a banner via a subprocess:

use Apache::SubProcess ( );
my $r = shift;
$r->send_http_header('text/plain');

my $fh = $r->spawn_child(\&banner);
$r->send_fd($fh);

sub banner {
    my $fh = shift;
    # /usr/games/banner on many Unices
    $fh->filename("/usr/bin/banner");
    $fh->args("-w40+Hello%20World");
    $fh->call_exec;
}

The last example shows how you can have full access to the STDIN, STDOUT, and STDERR streams of the spawned subprocess, so that you can pipe data to a program and send its output to the browser:

use Apache::SubProcess ( );
my $r = shift;
$r->send_http_header('text/plain');

use vars qw($string);
$string = "hello world";
my($out, $in, $err) = $r->spawn_child(\&echo);
print $out $string;
$r->send_fd($in);

sub echo {
    my $fh = shift;
    $fh->subprocess_env(CONTENT_LENGTH => length $string);
    $fh->filename("/tmp/pecho");
    $fh->call_exec;
}

The echo( ) function is similar to the earlier example's env( ) function. /tmp/pecho is as follows:

#!/usr/bin/perl 
read STDIN, $buf, $ENV{CONTENT_LENGTH}; 
print "STDIN: '$buf' ($ENV{CONTENT_LENGTH})\n";

In the last example, a string is defined as a global variable, so its length could be calculated in the echo( ) function. The subprocess reads from STDIN, to which the main process writes the string ("hello world"). It reads only the number of bytes specified by the CONTENT_LENGTH environment variable. Finally, the external program prints the data that it read to STDOUT, and the main program intercepts it and sends it to the client's socket (i.e., to the browser).

This module is also discussed in Chapter 10.

Available from CPAN. See the module manpage for more information.

B.17.4 Apache::Connection—Interface to the Apache conn_rec Data Structure

This module provides the Perl interface to the conn_rec data structure, which includes various records unique to each connection, such as the state of a connection, server and base server records, child number, etc. See include/httpd.h for a complete description of this data structure.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.5 Apache::Constants—Constants Defined in httpd.h

Server constants (OK, DENIED, NOT_FOUND, etc.) used by Apache modules are defined in httpd.h and other header files. This module gives Perl access to those constants.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.6 Apache::ExtUtils—Utilities for Apache C/Perl Glue

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.7 Apache::File—Advanced Functions for Manipulating Files on the Server Side

Apache::File does two things. First, it provides an object-oriented interface to file handles, similar to Perl's standard IO::File class. While the Apache::File module does not provide all the functionality of IO::File, its methods are approximately twice as fast as the equivalent IO::File methods. Secondly, when you use Apache::File, it adds to the Apache class several new methods that provide support for handling files under the HTTP/1.1 protocol.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.8 Apache::Log—Interface to Apache Logging

The Apache::Log module provides an interface to Apache's ap_log_error( ) and ap_log_rerror( ) routines.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.9 Apache::LogFile—Interface to Apache's Logging Routines

The PerlLogFile directive from this package can be used to hook a Perl file handle to a piped logger or to a file open for appending. If the first character of the filename is a "|", the file handle is opened as a pipe to the given program. The file or program can be relative to the ServerRoot.

So if httpd.conf contains these settings:

PerlModule Apache::LogFile
PerlLogFile |perl/mylogger.pl My::Logger

in your code you can log to the My::Logger file handle:

print My::Logger "a message to the Log"

and it'll be piped through the perl/mylogger.pl script.

Available from CPAN. See the module manpage for more information.

B.17.10 Apache::Scoreboard—Perl Interface to Apache's scoreboard.h

Apache keeps track of server activity in a structure known as the scoreboard. There is a slot in the scoreboard for each child server, containing information such as status, access count, bytes served, and CPU time. This information is also used by mod_status to provide server statistics in a human-readable form.

Available from CPAN. See the module manpage for more information.

B.17.11 Apache::Server—Perl Interface to the Apache server_rec Struct

The Apache::Server class contains information about the server's configuration. Using this class it's possible to retrieve any data set in httpd.conf and <Perl> sections.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.12 Apache::Table—Perl Interface to the Apache Table Struct

This module provides tied interfaces to Apache data structures. By using it you can add, merge, and clear entries in headers_in, headers_out, err_headers_out, notes, dir_config, and subprocess_env.

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.13 Apache::URI—URI Component Parsing and Unparsing

This module provides an interface to the Apache util_uri module and the uri_components structure. The available methods are: parsed_uri( ), parse( ), unparse( ), scheme( ), hostinfo( ), user( ), password( ), hostname( ), port( ), path( ), rpath( ), query( ), and fragment( ).

Supplied with the mod_perl distribution. See the module manpage for more information.

B.17.14 Apache::Util—Perl Interface to Apache C Utility Functions

This module provides a Perl interface to some of the C utility functions available in Apache. The same functionality is avaliable in libwww-perl, but the C versions are faster: escape_html( ), escape_uri( ), unescape_uri( ), unescape_uri_info( ), parsedate( ), ht_time( ), size_string( ), and validate_password( ).

Supplied with the mod_perl distribution. See the module manpage for more information.