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
printstatement 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
STDERRstreams 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:
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).
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.
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_componentsstructure. 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.
