You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/04/20 12:38:51 UTC
cvs commit: modperl-docs/src/docs/1.0/api Constants.pod File.pod Include.pod Log.pod Options.pod PerlRun.pod PerlSections.pod Registry.pod RegistryLoader.pod Resource.pod SIG.pod SizeLimit.pod StatINC.pod Status.pod Symbol.pod Symdump.pod Table.pod test.pod Changes.pod config.cfg
stas 02/04/20 03:38:51
Modified: src/docs/1.0/api Changes.pod config.cfg
Added: src/docs/1.0/api Constants.pod File.pod Include.pod Log.pod
Options.pod PerlRun.pod PerlSections.pod
Registry.pod RegistryLoader.pod Resource.pod
SIG.pod SizeLimit.pod StatINC.pod Status.pod
Symbol.pod Symdump.pod Table.pod test.pod
Log:
clean the pods from the rest of the 1.x API and add them to the /api/
Submitted by: Per Einar Ellefsen <pe...@skynet.be>
Revision Changes Path
1.3 +10 -1 modperl-docs/src/docs/1.0/api/Changes.pod
Index: Changes.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Changes.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Changes.pod 19 Apr 2002 16:02:22 -0000 1.2
+++ Changes.pod 20 Apr 2002 10:38:50 -0000 1.3
@@ -1,6 +1,6 @@
=head1 NAME
-CHANGES
+Changes
=head1 Description
@@ -8,6 +8,15 @@
documents, since you've read these last time.
The most recent changes are listed first.
+
+=head1 Sat Apr 20 11:41:00 CET 2002
+
+Per Einar Ellefsen:
+
+* Added C<Apache::*> modules from core to complete the API. Reviewed
+ the content, added right tags and indentation where needed.
+
+* Apache::File: added synopsis.
=head1 Thu Apr 18 12:28:00 CET 2002
1.4 +20 -2 modperl-docs/src/docs/1.0/api/config.cfg
Index: config.cfg
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/config.cfg,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- config.cfg 3 Apr 2002 07:46:13 -0000 1.3
+++ config.cfg 20 Apr 2002 10:38:50 -0000 1.4
@@ -5,8 +5,8 @@
title => "mod_perl 1.0 API",
abstract => <<EOB,
-This is only a partial API, the rest of the API documentation is in
-the source distribution
+Here is the documentation for the whole API provided with the mod_perl
+distribution, ie. of various Apache:: modules you will need to use.
EOB
body => {
@@ -15,6 +15,24 @@
chapters => [qw(
Apache.pod
+ Constants.pod
+ Table.pod
+ File.pod
+ Include.pod
+ Log.pod
+ Registry.pod
+ RegistryLoader.pod
+ PerlRun.pod
+ StatINC.pod
+ test.pod
+ Options.pod
+ PerlSections.pod
+ Status.pod
+ Symbol.pod
+ Resource.pod
+ SizeLimit.pod
+ SIG.pod
+ Symdump.pod
Changes.pod
)],
);
1.1 modperl-docs/src/docs/1.0/api/Constants.pod
Index: Constants.pod
===================================================================
=head1 NAME
Apache::Constants - Constants defined in apache header files
=head1 Synopsis
use Apache::Constants;
use Apache::Constants ':common';
use Apache::Constants ':response';
=head1 Description
Server constants used by apache modules are defined in
B<httpd.h> and other header files, this module gives Perl access
to those constants.
=head1 Export Tags
=over 4
=item common
This tag imports the most commonly used constants.
OK
DECLINED
DONE
NOT_FOUND
FORBIDDEN
AUTH_REQUIRED
SERVER_ERROR
=item response
This tag imports the B<common> response codes, plus these
response codes:
DOCUMENT_FOLLOWS
MOVED
REDIRECT
USE_LOCAL_COPY
BAD_REQUEST
BAD_GATEWAY
RESPONSE_CODES
NOT_IMPLEMENTED
CONTINUE
NOT_AUTHORITATIVE
B<CONTINUE> and B<NOT_AUTHORITATIVE> are aliases for B<DECLINED>.
=item methods
This are the method numbers, commonly used with
the Apache B<method_number> method.
METHODS
M_CONNECT
M_DELETE
M_GET
M_INVALID
M_OPTIONS
M_POST
M_PUT
M_TRACE
M_PATCH
M_PROPFIND
M_PROPPATCH
M_MKCOL
M_COPY
M_MOVE
M_LOCK
M_UNLOCK
=item options
These constants are most commonly used with
the Apache B<allow_options> method:
OPT_NONE
OPT_INDEXES
OPT_INCLUDES
OPT_SYM_LINKS
OPT_EXECCGI
OPT_UNSET
OPT_INCNOEXEC
OPT_SYM_OWNER
OPT_MULTI
OPT_ALL
=item satisfy
These constants are most commonly used with
the Apache B<satisfies> method:
SATISFY_ALL
SATISFY_ANY
SATISFY_NOSPEC
=item remotehost
These constants are most commonly used with
the Apache B<get_remote_host> method:
REMOTE_HOST
REMOTE_NAME
REMOTE_NOLOOKUP
REMOTE_DOUBLE_REV
=item http
This is the full set of HTTP response codes:
(NOTE: not all implemented here)
HTTP_OK
HTTP_MOVED_TEMPORARILY
HTTP_MOVED_PERMANENTLY
HTTP_METHOD_NOT_ALLOWED
HTTP_NOT_MODIFIED
HTTP_UNAUTHORIZED
HTTP_FORBIDDEN
HTTP_NOT_FOUND
HTTP_BAD_REQUEST
HTTP_INTERNAL_SERVER_ERROR
HTTP_NOT_ACCEPTABLE
HTTP_NO_CONTENT
HTTP_PRECONDITION_FAILED
HTTP_SERVICE_UNAVAILABLE
HTTP_VARIANT_ALSO_VARIES
=item server
These are constants related to server version:
MODULE_MAGIC_NUMBER
SERVER_VERSION
SERVER_BUILT
=item config
These are constants related to configuration directives:
DECLINE_CMD
=item types
These are constants related to internal request types:
DIR_MAGIC_TYPE
=item override
These constants are used to control and test the context of configuration
directives.
OR_NONE
OR_LIMIT
OR_OPTIONS
OR_FILEINFO
OR_AUTHCFG
OR_INDEXES
OR_UNSET
OR_ALL
ACCESS_CONF
RSRC_CONF
=item args_how
RAW_ARGS
TAKE1
TAKE2
TAKE12
TAKE3
TAKE23
TAKE123
ITERATE
ITERATE2
FLAG
NO_ARGS
=back
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=item * Gisle Aas
=item * h2xs
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/File.pod
Index: File.pod
===================================================================
=head1 NAME
Apache::File - advanced functions for manipulating files at the server side
=head1 Synopsis
use Apache::File ();
my $fh = Apache::File->new($filename);
print $fh 'Hello';
$fh->close;
my($name, $fh) = Apache::File->tmpfile;
if ((my $rc = $r->discard_request_body) != OK) {
return $rc;
}
if((my $rc = $r->meets_conditions) != OK) {
return $rc;
}
my $date_string = localtime $r->mtime;
$r->set_content_length;
$r->set_etag;
$r->update_mtime;
$r->set_last_modified;
=head1 Description
C<Apache::File> does two things: it provides an object-oriented
interface to filehandles similar to Perl's standard C<IO::File
class>. While the C<Apache::File> module does not provide all the
functionality of C<IO::File>, its methods are approximately twice as
fast as the equivalent C<IO::File> methods. Secondly, when you use
C<Apache::File>, it adds several new methods to the C<Apache> class
which provide support for handling files under the C<HTTP/1.1>
protocol.
=head1 Apache::File methods
=over 4
=item new()
This method creates a new filehandle, returning the filehandle object
on success, undef on failure. If an additional argument is given, it
will be passed to the C<open()> method automatically.
use Apache::File ();
my $fh = Apache::File->new;
my $fh = Apache::File->new($filename) or die "Can't open $filename $!";
=item open()
Given an Apache::File object previously created with C<new()>, this
method opens a file and associates it with the object. The C<open()>
method accepts the same types of arguments as the standard Perl
C<open()> function, including support for file modes.
$fh->open($filename);
$fh->open(">$out_file");
$fh->open("|$program");
=item close()
The C<close()> method is equivalent to the Perl builtin close
function, returns true upon success, false upon failure.
$fh->close or die "Can't close $filename $!";
=item tmpfile()
The C<tmpfile()> method is responsible for opening up a unique
temporary file. It is similar to the C<tmpnam()> function in the
C<POSIX> module, but doesn't come with all the memory overhead that
loading C<POSIX> does. It will choose a suitable temporary directory
(which must be writable by the Web server process). It then generates
a series of filenames using the current process ID and the C<$TMPNAM>
package global. Once a unique name is found, it is opened for writing,
using flags that will cause the file to be created only if it does not
already exist. This prevents race conditions in which the function
finds what seems to be an unused name, but someone else claims the
same name before it can be created.
As an added bonus, C<tmpfile()> calls the C<register_cleanup()> method
behind the scenes to make sure the file is unlinked after the
transaction is finished.
Called in a list context, C<tmpfile()> returns the temporary file name
and a filehandle opened for reading and writing. In a scalar context
only the filehandle is returned.
my($tmpnam, $fh) = Apache::File->tmpfile;
my $fh = Apache::File->tmpfile;
=back
=head1 Apache Methods added by Apache::File
When a handler pulls in C<Apache::File>, the module adds a number of
new methods to the Apache request object. These methods are generally
of interest to handlers that wish to serve static files from disk or
memory using the features of the C<HTTP/1.1> protocol that provide
increased performance through client-side document caching.
=over 4
=item $r-E<gt>discard_request_body()
This method tests for the existence of a request body and if present,
simply throws away the data. This discarding is especially important
when persistent connections are being used, so that the request body
will not be attached to the next request. If the request is malformed,
an error code will be returned, which the module handler should
propagate back to Apache.
if ((my $rc = $r->discard_request_body) != OK) {
return $rc;
}
=item $r-E<gt>meets_conditions()
In the interest of HTTP/1.1 compliance, the C<meets_conditions()>
method is used to implement ``conditional GET'' rules. These rules
include inspection of client headers, including C<If-Modified-Since>,
C<If-Unmodified-Since>, C<If-Match> and C<If-None-Match>.
As far as Apache modules are concerned, they need only check the
return value of this method before sending a request body. If the
return value is anything other than C<OK>, the module should return
from the handler with that value. A common return value other than
C<OK> is C<HTTP_NOT_MODIFIED>, which is sent when the document is
already cached on the client side, and has not changed since it was
cached.
if((my $rc = $r->meets_conditions) != OK) {
return $rc;
}
#else ... go and send the response body ...
=item $r-E<gt>mtime()
This method returns the last modified time of the requested file,
expressed as seconds since the epoch. The last modified time may also
be changed using this method, although C<update_mtime()> method is
better suited to this purpose.
my $date_string = localtime $r->mtime;
=item $r-E<gt>set_content_length()
This method sets the outgoing C<Content-length> header based on its
argument, which should be expressed in byte units. If no argument is
specified, the method will use the size returned by
C<$r-E<gt>filename>. This method is a bit faster and more concise than
setting C<Content-length> in the headers_out table yourself.
$r->set_content_length;
$r->set_content_length(-s $r->finfo); #same as above
$r->set_content_length(-s $filename);
=item $r-E<gt>set_etag()
This method is used to set the outgoing C<ETag> header corresponding to
the requested file. C<ETag> is an opaque string that identifies the
currrent version of the file and changes whenever the file is
modified. This string is tested by the C<meets_conditions()> method if
the client provide an C<If-Match> or C<If-None-Match> header.
$r->set_etag;
=item $r-E<gt>set_last_modified()
This method is used to set the outgoing C<Last-Modified header> from
the value returned by C<$r-E<gt>mtime>. The method checks that the
specified time is not in the future. In addition, using
C<set_last_modified()> is faster and more concise than setting
C<Last-Modified> in the C<headers_out> table yourself.
You may provide an optional time argument, in which case the method
will first call the C<update_mtime()> to set the file's last
modification date. It will then set the outgoing C<Last-Modified> header
as before.
$r->update_mtime((stat $r->finfo)[9]);
$r->set_last_modified;
$r->set_last_modified((stat $r->finfo)[9]); #same as the two lines above
=item $r-E<gt>update_mtime()
Rather than setting the request record mtime field directly, you can
use the C<update_mtime()> method to change the value of this field. It
will only be updated if the new time is more recent than the current
mtime. If no time argument is present, the default is the last
modified time of $r-E<gt>filename.
$r->update_mtime;
$r->update_mtime((stat $r->finfo)[9]); #same as above
$r->update_mtime(time);
=back
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Include.pod
Index: Include.pod
===================================================================
=head1 NAME
Apache::Include - Utilities for mod_perl/mod_include integration
=head1 Synopsis
<!--#perl sub="Apache::Include" arg="/perl/ssi.pl" -->
=head1 Description
The C<Apache::Include> module provides a handler, making it simple to
include C<Apache::Registry> scripts with the mod_include perl
directive.
C<Apache::Registry> scripts can also be used in mod_include parsed
documents using 'virtual include'.
=head1 Methods
=over 4
=item Apache::Include-E<gt>virtual($uri)
The C<virtual> method may be called to include the output of a given
uri in your Perl scripts. Example:
use Apache::Include ();
print "Content-type: text/html\n\n";
print "before include\n";
my $uri = "/perl/env.pl";
Apache::Include->virtual($uri);
print "after include\n";
=back
=head1 See Also
perl(1), mod_perl(3), mod_include
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Log.pod
Index: Log.pod
===================================================================
=head1 NAME
Apache::Log - Interface to Apache logging
=head1 Synopsis
use Apache::Log ();
my $rlog = $r->log;
$rlog->debug("You only see this if `LogLevel' is set to `debug'");
my $slog = $r->server->log;
=head1 Description
The C<Apache::Log> module provides an interface to Apache's
I<ap_log_error> and I<ap_log_rerror> routines.
The methods listed below can be called as
C<$rE<gt>>I<meth>C<($error)>, and the error message will appear in the
error log depending on the value of C<LogLevel>.
=over 4
=item emerg
=item alert
=item crit
=item error
=item warn
=item notice
=item info
=item debug
=back
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 See Also
mod_perl(3), Apache(3).
=cut
1.1 modperl-docs/src/docs/1.0/api/Options.pod
Index: Options.pod
===================================================================
=head1 NAME
Apache::Options - OPT_* defines from httpd_core.h
=head1 Synopsis
use Apache::Options;
=head1 Description
The C<Apache::Options> module will export the following bitmask
constants:
OPT_NONE
OPT_INDEXES
OPT_INCLUDES
OPT_SYMLINKS
OPT_EXECCGI
OPT_UNSET
OPT_INCNOEXEC
OPT_SYM_OWNER
OPT_MULTI
OPT_ALL
These constants can be used to check the return value from
C<Apache-E<gt>request-E<gt>allow_options()> method.
This module is simply a stub which imports from C<Apache::Constants>,
just as if you had said C<use Apache::Constants ':options';>.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 See Also
L<Apache>, L<Apache::Constants>
=cut
1.1 modperl-docs/src/docs/1.0/api/PerlRun.pod
Index: PerlRun.pod
===================================================================
=head1 NAME
Apache::PerlRun - Run unaltered CGI scripts under mod_perl
=head1 Synopsis
#in httpd.conf
Alias /cgi-perl/ /perl/apache/scripts/
PerlModule Apache::PerlRun
<Location /cgi-perl>
SetHandler perl-script
PerlHandler Apache::PerlRun
Options +ExecCGI
#optional
PerlSendHeader On
...
</Location>
=head1 Description
This module's C<handler> emulates the CGI environment, allowing
programmers to write scripts that run under CGI or mod_perl without
change. Unlike C<Apache::Registry>, the C<Apache::PerlRun> handler
does not cache the script inside of a subroutine. Scripts will be
"compiled" every request. After the script has run, it's namespace is
flushed of all variables and subroutines.
The C<Apache::Registry> handler is much faster than
C<Apache::PerlRun>. However, C<Apache::PerlRun> is much faster than
CGI as the fork is still avoided and scripts can use modules which
have been pre-loaded at server startup time. This module is meant for
"Dirty" CGI Perl scripts which relied on the single request lifetime
of CGI and cannot run under C<Apache::Registry> without cleanup.
=head1 Caveats
If your scripts still have problems running under the
C<Apache::PerlRun> handler, the C<PerlRunOnce> option can be used so
that the process running the script will be shutdown. Add this to
your httpd.conf:
<Location ...>
PerlSetVar PerlRunOnce On
...
</Location>
=head1 See Also
perl(1), mod_perl(3), Apache::Registry(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/PerlSections.pod
Index: PerlSections.pod
===================================================================
=head1 NAME
Apache::PerlSections - Utilities for work with Perl sections
=head1 Synopsis
use Apache::PerlSections ();
=head1 Description
It is possible to configure you server entirely in Perl using
C<E<lt>PerlE<gt>> sections in I<httpd.conf>. This module is here to
help you with such a task.
=head1 Methods
=over 4
=item dump
This method will dump out all the configuration variables mod_perl
will be feeding the the apache config gears. The output is suitable
to read back in via C<eval>.
Example:
<Perl>
use Apache::PerlSections ();
$Port = 8529;
$Location{"/perl"} = {
SetHandler => "perl-script",
PerlHandler => "Apache::Registry",
Options => "ExecCGI",
};
@DocumentIndex = qw(index.htm index.html);
$VirtualHost{"www.foo.com"} = {
DocumentRoot => "/tmp/docs",
ErrorLog => "/dev/null",
Location => {
"/" => {
Allowoverride => 'All',
Order => 'deny,allow',
Deny => 'from all',
Allow => 'from foo.com',
},
},
};
print Apache::PerlSections->dump;
</Perl>
This will print something like this:
package Apache::ReadConfig;
#scalars:
$Port = 8529;
#arrays:
@DocumentIndex = (
'index.htm',
'index.html'
);
#hashes:
%Location = (
'/perl' => {
PerlHandler => 'Apache::Registry',
SetHandler => 'perl-script',
Options => 'ExecCGI'
}
);
%VirtualHost = (
'www.foo.com' => {
Location => {
'/' => {
Deny => 'from all',
Order => 'deny,allow',
Allow => 'from foo.com',
Allowoverride => 'All'
}
},
DocumentRoot => '/tmp/docs',
ErrorLog => '/dev/null'
}
);
1;
__END__
=item store
This method will call the C<dump> method, writing the output
to a file, suitable to be pulled in via C<require>.
Example:
Apache::PerlSections->store("httpd_config.pl");
require 'httpd_config.pl';
=back
=head1 See Also
mod_perl(1), Data::Dumper(3), Devel::Symdump(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Registry.pod
Index: Registry.pod
===================================================================
=head1 NAME
Apache::Registry - Run unaltered CGI scrips under mod_perl
=head1 Synopsis
#in httpd.conf
Alias /perl/ /perl/apache/scripts/ #optional
PerlModule Apache::Registry
<Location /perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options ExecCGI
</Location>
=head1 Description
C<Apache::Registry> is the Apache module allowing you to run CGI
scripts very fast under mod_perl, by compiling all scripts once and
then caching them in memory.
URIs in the form of I<http://www.host.com/perl/file.pl> will be
compiled as the body of a perl subroutine and executed. Each server
process or 'child' will compile the subroutine once and store it in
memory. It will recompile it whenever the file is updated on disk.
Think of it as an object oriented server with each script implementing
a class loaded at runtime.
The file looks much like a "normal" script, but it is compiled or 'evaled'
into a subroutine.
Here's an example:
my $r = Apache->request;
$r->content_type("text/html");
$r->send_http_header;
$r->print("Hi There!");
This module emulates the CGI environment, allowing programmers to
write scripts that run under CGI or mod_perl without change. Existing
CGI scripts may require some changes, simply because a CGI script has
a very short lifetime of one HTTP request, allowing you to get away
with "quick and dirty" scripting. Using mod_perl and Apache::Registry
requires you to be more careful, but it also gives new meaning to the
word "quick"!
Be sure to read all mod_perl related documentation for more details,
including instructions for setting up an environment that looks
exactly like CGI:
print "Content-type: text/html\n\n";
print "Hi There!";
Note that each httpd process or "child" must compile each script once,
so the first request to one server may seem slow, but each request
there after will be faster. If your scripts are large and/or make use
of many Perl modules, this difference should be noticeable to the
human eye.
=head1 Security
C<Apache::Registry::handler> will preform the same checks as
C<mod_cgi> before running the script.
=head1 Environment
The Apache function C<exit> overrides the Perl core built-in function.
The environment variable C<GATEWAY_INTERFACE> is set to
C<CGI-Perl/1.1>.
=head1 Command Line Switches on the First Line
Normally when a Perl script is run from the command line or under CGI,
arguments on the C<#!> line are passed to the perl interpreter for
processing.
C<Apache::Registry> currently only honors the C<-w> switch and will
turn on warnings using the C<$^W> global variable. Another common
switch used with CGI scripts is C<-T> to turn on taint checking. This
can only be enabled when the server starts with the configuration
directive:
PerlTaintCheck On
However, if taint checking is not enabled, but the C<-T> switch is
seen, C<Apache::Registry> will write a warning to the I<error_log>.
=head1 Debugging
You may set the debug level with the C<$Apache::Registry::Debug> bitmask
1 => log recompile in errorlog
2 => Apache::Debug::dump in case of $@
4 => trace pedantically
=head1 Caveats
C<Apache::Registry> makes things look just the CGI environment,
however, you must understand that this B<is not CGI>. Each httpd
child will compile your script into memory and keep it there, whereas
CGI will run it once, cleaning out the entire process space. Many
times you have heard "always use C<-w>, always use C<-w> and C<use
strict>". This is more important here than anywhere else!
Your scripts cannot contain the C<__END__> or C<__DATA__> token to terminate
compilation.
=head1 See Also
perl(1), mod_perl(3), Apache(3), Apache::Debug(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Andreas J. Koenig
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/RegistryLoader.pod
Index: RegistryLoader.pod
===================================================================
=head1 NAME
Apache::RegistryLoader - Compile Apache::Registry scripts at server startup
=head1 Synopsis
#in your Perl Startup script:
use Apache::RegistryLoader ();
my $r = Apache::RegistryLoader->new;
$r->handler($uri, $filename);
$r->handler($uri, $filename, $virtual_hostname);
=head1 Description
This modules allows compilation of C<Apache::Registry> scripts at
server startup.
The script's handler routine is compiled by the parent server, of
which children get a copy. The C<Apache::RegistryLoader> C<handler>
method takes arguments of C<uri> and the C<filename>. URI to filename
translation normally doesn't happen until HTTP request time, so we're
forced to roll our own translation.
If filename is omitted and a C<trans> routine was not
defined, the loader will try using the I<uri> relative to
C<ServerRoot>. Example:
#in httpd.conf
ServerRoot /opt/www/apache
Alias /perl/ /opt/www/apache/perl
#in PerlScript
use Apache::RegistryLoader ();
#/opt/www/apache/perl/test.pl
#is the script loaded from disk here:
Apache::RegistryLoader->new->handler("/perl/test.pl");
To make the loader smarter about the uri-E<gt>filename translation,
you may provide the C<new> method with a C<trans> function to
translate the uri to filename.
The following example will pre-load all files ending with C<.pl> in
the I<perl-scripts/> directory relative to C<ServerRoot>. The example
code assumes the Location URI I</perl> is an C<Alias> to this
directory.
{
use Cwd ();
use Apache::RegistryLoader ();
use DirHandle ();
use strict;
my $dir = Apache->server_root_relative("perl-scripts/");
my $rl = Apache::RegistryLoader->new(trans => sub {
my $uri = shift;
$uri =~ s:^/perl/:/perl-scripts/:;
return Apache->server_root_relative($uri);
});
my $dh = DirHandle->new($dir) or die $!;
for my $file ($dh->read) {
next unless $file =~ /\.pl$/;
$rl->handler("/perl/$file");
}
}
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=item * Stas Bekman (Rewrote the C<handler()> to report and handle all
the possible erroneous conditions).
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 See Also
Apache::Registry(3), Apache(3), mod_perl(3)
=cut
1.1 modperl-docs/src/docs/1.0/api/Resource.pod
Index: Resource.pod
===================================================================
=head1 NAME
Apache::Resource - Limit resources used by httpd children
=head1 Synopsis
PerlModule Apache::Resource
#set child memory limit in megabytes
#default is 64 Meg
PerlSetEnv PERL_RLIMIT_DATA 32:48
#linux does not honor RLIMIT_DATA
#RLIMIT_AS (address space) will work to limit the size of a process
PerlSetEnv PERL_RLIMIT_AS 32:48
#set child cpu limit in seconds
#default is 360 seconds
PerlSetEnv PERL_RLIMIT_CPU 120
PerlChildInitHandler Apache::Resource
=head1 Description
C<Apache::Resource> uses the C<BSD::Resource> module, which
uses the C function C<setrlimit> to set limits on
system resources such as memory and cpu usage.
Any C<RLIMIT> operation available to limit on your system can be set
by defining that operation as an environment variable with a C<PERL_>
prefix. See your system C<setrlimit> manpage for available resources
which can be limited.
The following limit values are in megabytes: C<DATA>, C<RSS>, C<STACK>,
C<FSIZE>, C<CORE>, C<MEMLOCK>; all others are treated as their natural unit.
If the value of the variable is of the form C<S:H>, C<S> is treated as
the soft limit, and C<H> is the hard limit. If it is just a single
number, it is used for both soft and hard limits.
=head1 Defaults
To set reasonable defaults for all RLIMITs, add this to your
httpd.conf:
PerlSetEnv PERL_RLIMIT_DEFAULTS On
PerlModule Apache::Resource
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 SEE ALSO
BSD::Resource(3), setrlimit(2)
=cut
1.1 modperl-docs/src/docs/1.0/api/SIG.pod
Index: SIG.pod
===================================================================
=head1 NAME
Apache::SIG - Override apache signal handlers with Perl's
=head1 Synopsis
PerlFixupHandler Apache::SIG
=head1 Description
When a client drops a connection and apache is in the middle of a
write, a timeout will occur and httpd sends a C<SIGPIPE>. When
apache's C<SIGPIPE> handler is used, Perl may be left in the middle of
it's eval context, causing bizarre errors during subsequent requests
are handled by that child. When C<Apache::SIG> is used, it installs a
different C<SIGPIPE> handler which rewinds the context to make sure
Perl is back to normal state, preventing these bizarre errors.
If you would like to log when a request was cancelled by a C<SIGPIPE>
in your Apache I<access_log>, you can declare C<Apache::SIG> as a
handler (any C<Perl*Handler> will do, as long as it is run before
C<PerlHandler>, e.g. C<PerlFixupHandler>), and you must also define a
custom C<LogFormat> in your httpd.conf, like so:
PerlFixupHandler Apache::SIG
LogFormat "%h %l %u %t \"%r\" %s %b %{SIGPIPE}e"
If the server has noticed that the request was cancelled via a
C<SIGPIPE>, then the log line will end with C<1>, otherwise it will
just be a dash.
=head1 Caveats
The signal handler in this package uses the subprocess_env table of
the main request object to supply the C<SIGPIPE> "environment
variable" to the log handler. If you already use the key C<SIGPIPE> in
your C<subprocess_env> table, then you can redefine the key like this:
$Apache::SIG::PipeKey = 'my_SIGPIPE';
and log it like this:
LogFormat "%h %l %u %t \"%r\" %s %b %{my_SIGPIPE}e"
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=item * Doug Bagley
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 See Also
perlvar(1)
=cut
1.1 modperl-docs/src/docs/1.0/api/SizeLimit.pod
Index: SizeLimit.pod
===================================================================
=head1 NAME
Apache::SizeLimit - Because size does matter.
=head1 Synopsis
This module allows you to kill off Apache httpd processes if they grow too
large. You can choose to set up the process size limiter to check the
process size on every request:
# in your startup.pl:
use Apache::SizeLimit;
# sizes are in KB
$Apache::SizeLimit::MAX_PROCESS_SIZE = 10000; # 10MB
$Apache::SizeLimit::MIN_SHARE_SIZE = 1000; # 1MB
$Apache::SizeLimit::MAX_UNSHARED_SIZE = 12000; # 12MB
# in your httpd.conf:
PerlFixupHandler Apache::SizeLimit
# you can set this up as any Perl*Handler that handles part of the
# request, even the LogHandler will do.
Or you can just check those requests that are likely to get big, such
as CGI requests. This way of checking is also easier for those who
are mostly just running CGI.pm/Registry scripts:
# in your CGI:
use Apache::SizeLimit;
&Apache::SizeLimit::setmax(10000); # Max size in KB
&Apache::SizeLimit::setmin(1000); # Min share in KB
&Apache::SizeLimit::setmax_unshared(12000); # Max unshared size in KB
Since checking the process size can take a few system calls on some
platforms (e.g. linux), you may want to only check the process size
every I<N> times. To do so, put this in your I<startup.pl> or CGI:
$Apache::SizeLimit::CHECK_EVERY_N_REQUESTS = 2;
This will only check the process size every other time the process size
checker is called.
=head1 Description
This module allows you to kill off Apache httpd processes if they grow
too large.
This module is highly platform dependent, please read the Caveats
section.
This module was written in response to questions on the mod_perl
mailing list on how to tell the httpd process to exit if it gets too
big.
Actually there are two big reasons your httpd children will grow.
First, it could have a bug that causes the process to increase in size
dramatically, until your system starts swapping. Second, your process
just does stuff that requires a lot of memory, and the more different
kinds of requests your server handles, the larger the httpd processes
grow over time.
This module will not really help you with the first problem. For that
you should probably look into C<Apache::Resource> or some other means
of setting a limit on the data size of your program. BSD-ish systems
have C<setrlimit()> which will croak your memory gobbling processes.
However it is a little violent, terminating your process in
mid-request.
This module attempts to solve the second situation where your process
slowly grows over time. The idea is to check the memory usage after every
request, and if it exceeds a threshold, exit gracefully.
By using this module, you should be able to discontinue using the
Apache configuration directive C<MaxRequestsPerChild>, although for
some folks, using both in combination does the job. Personally, I
just use the technique shown in this module and set my
C<MaxRequestsPerChild> value to 6000.
=head1 Shared Memory Options
In addition to simply checking the total size of a process, this
module can factor in how much of the memory used by the process is
actually being shared by copy-on-write. If you don't understand how
memory is shared in this way, take a look at the mod_perl Guide at
http://perl.apache.org/guide/.
META: change link when site is live.
You can take advantage of the shared memory information by setting a
minimum shared size and/or a maximum unshared size. Experience on one
heavily trafficked mod_perl site showed that setting maximum unshared
size and leaving the others unset is the most effective policy. This
is because it only kills off processes that are truly using too much
physical RAM, allowing most processes to live longer and reducing the
process churn rate.
=head1 Caveats
This module is platform dependent, since finding the size of a process
is pretty different from OS to OS, and some platforms may not be
supported. In particular, the limits on minimum shared memory and
maximum shared memory are currently only supported on Linux and BSD.
If you can contribute support for another OS, please do.
Currently supported OSes:
=over 4
=item linux
For linux we read the process size out of I</proc/self/status>. This is
a little slow, but usually not too bad. If you are worried about
performance, try only setting up the the exit handler inside CGIs
(with the C<setmax> function), and see if the C<CHECK_EVERY_N_REQUESTS>
option is of benefit.
=item solaris 2.6 and above
For solaris we simply retrieve the size of I</proc/self/as>, which
contains the address-space image of the process, and convert to KB.
Shared memory calculations are not supported.
NOTE: This is only known to work for solaris 2.6 and above. Evidently
the I</proc> filesystem has changed between 2.5.1 and 2.6. Can anyone
confirm or deny?
=item *bsd*
Uses C<BSD::Resource::getrusage()> to determine process size. This is pretty
efficient (a lot more efficient than reading it from the I</proc> fs anyway).
=item AIX?
Uses C<BSD::Resource::getrusage()> to determine process size. Not sure if the
shared memory calculations will work or not. AIX users?
=back
If your platform is not supported, and if you can tell me how to check for
the size of a process under your OS (in KB), then I will add it to the list.
The more portable/efficient the solution, the better, of course.
=head1 Todo
Possibly provide a perl make/install so that the SizeLimit.pm is created at
build time with only the code you need on your platform.
If Apache was started in non-forking mode, should hitting the size limit
cause the process to exit?
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item *
Doug Bagley E<lt>doug+modperl (at) bagley.orgE<gt>, channeling Procrustes.
=item *
Brian Moseley E<lt>ix (at) maz.orgE<gt>: Solaris 2.6 support
=item *
Doug Steinwand and Perrin Harkins E<lt>perrin (at) elem.comE<gt>:
added support for shared memory and additional diagnostic info
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/StatINC.pod
Index: StatINC.pod
===================================================================
=head1 NAME
Apache::StatINC - Reload %INC files when updated on disk
=head1 Synopsis
#httpd.conf or some such
#can be any Perl*Handler
PerlInitHandler Apache::StatINC
=head1 Description
When Perl pulls a file via C<require>, it stores the filename in the
global hash C<%INC>. The next time Perl tries to C<require> the same
file, it sees the file in C<%INC> and does not reload from disk. This
module's handler iterates over C<%INC> and reloads the file if it has
changed on disk.
Note that StatINC operates on the current context of C<@INC>.
Which means, when called as a Perl*Handler it will not see C<@INC> paths
added or removed by Apache::Registry scripts, as the value of C<@INC> is
saved on server startup and restored to that value after each request.
In other words, if you want StatINC to work with modules that live in custom
C<@INC> paths, you should modify C<@INC> when the server is started.
Besides, C<use lib> in startup scripts, you can also set the C<PERL5LIB>
variable in the httpd's environment to include any non-standard 'lib'
directories that you choose. For example, you might use a
script called 'start_httpd' to start apache, and include a line like this:
PERL5LIB=/usr/local/foo/myperllibs; export PERL5LIB
When you have problems with modules not being reloaded, please refer
to the following lines in I<perlmodlib>:
"Always use C<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
Remember that you can add C<no strict qw(...);> to individual blocks
of code that need less strictness. Always use C<-w>. Always use C<-w>!
Follow the guidelines in the perlstyle(1) manual."
Warnings when running under mod_perl is enabled with C<PerlWarn On> in
your httpd.conf.
It will most likely help you to find the problem. Really.
=head1 Options
=over 4
=item StatINC_UndefOnReload
Normally, C<StatINC> will turn of warnings to avoid "Subroutine
redefined" warnings when it reloads a file. However, this does not
disable the Perl mandatory warning when re-defining C<constant>
subroutines (see perldoc perlsub). With this option On, StatINC will
invoke the C<Apache::Symbol> C<undef_functions> method to avoid these
mandatory warnings:
PerlSetVar StatINC_UndefOnReload On
=item StatINC_Debug
You can make C<StatINC> tell when it reloads a module by setting this
option to on.
PerlSetVar StatINC_Debug 1
The only used debug level is currently 1.
=back
=head1 SEE ALSO
mod_perl(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * Ask Bjoern Hanse E<lt>ask (at) netcetera.dkE<gt>
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=item * Ask Bjoern Hansen
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Status.pod
Index: Status.pod
===================================================================
=head1 NAME
Apache::Status - Embedded interpreter status information
=head1 Synopsis
<Location /perl-status>
SetHandler perl-script
PerlHandler Apache::Status
</Location>
=head1 Description
The C<Apache::Status> module provides some information about the
status of the Perl interpreter embedded in the server.
Configure like so:
<Location /perl-status>
SetHandler perl-script
PerlHandler Apache::Status
</Location>
Other modules can "plugin" a menu item like so:
Apache::Status->menu_item(
'DBI' => "DBI connections", #item for Apache::DBI module
sub {
my($r,$q) = @_; #request and CGI objects
my(@strings);
push @strings, "blobs of html";
return \@strings; #return an array ref
}
) if Apache->module("Apache::Status"); #only if Apache::Status is loaded
B<WARNING>: C<Apache::Status> must be loaded before these modules via
the C<PerlModule> or C<PerlRequire> directives.
=head1 Options
=over 4
=item StatusOptionsAll
This single directive will enable all of the options described below.
PerlSetVar StatusOptionsAll On
=item StatusDumper
When browsing symbol tables, the values of arrays, hashes ans calars
can be viewed via C<Data::Dumper> if this configuration variable is
set to On:
PerlSetVar StatusDumper On
=item StatusPeek
With this option I<On> and the C<Apache::Peek> module installed,
functions and variables can be viewed ala C<Devel::Peek> style:
PerlSetVar StatusPeek On
=item StatusLexInfo
With this option On and the C<B::LexInfo> module installed, subroutine
lexical variable information can be viewed.
PerlSetVar StatusLexInfo On
=item StatusDeparse
With this option On and C<B::Deparse> version 0.59 or higher (included
in Perl 5.005_59+), subroutines can be "deparsed".
PerlSetVar StatusDeparse On
Options can be passed to C<B::Deparse::new> like so:
PerlSetVar StatusDeparseOptions "-p -sC"
See the C<B::Deparse> manpage for details.
=item StatusTerse
With this option I<On>, text-based op tree graphs of subroutines can
be displayed, thanks to C<B::Terse>.
PerlSetVar StatusTerse On
=item StatusTerseSize
With this option On and the C<B::TerseSize> module installed,
text-based op tree graphs of subroutines and their size can be
displayed. See the C<B::TerseSize> docs for more info.
PerlSetVar StatusTerseSize On
=item StatusTerseSizeMainSummary
With this option On and the C<B::TerseSize> module installed, a
"Memory Usage" will be added to the C<Apache::Status> main menu. This
option is disabled by default, as it can be rather cpu intensive to
summarize memory usage for the entire server. It is strongly
suggested that this option only be used with a development server
running in C<-X> mode, as the results will be cached.
PerlSetVar StatusTerseSizeMainSummary On
=item StatusGraph
When C<StatusDumper> is enabled, another link "OP Tree Graph" will be
present with the dump if this configuration variable is set to On:
PerlSetVar StatusGraph
This requires the C<B> module (part of the Perl compiler kit) and
C<B::Graph> (version 0.03 or higher) module to be installed along with
the C<dot> program.
Dot is part of the graph visualization toolkit from AT&T:
http://www.research.att.com/sw/tools/graphviz/ ).
B<WARNING>: Some graphs may produce very large images, some graphs may
produce no image if C<B::Graph>'s output is incorrect.
=item Dot
Location of the dot program for C<StatusGraph>, if other than
I</usr/bin> or I</usr/local/bin>.
=item GraphDir
Directory where C<StatusGraph> should write it's temporary image
files. Default is I<$ServerRoot/logs/b_graphs>.
=back
=head1 Prerequisites
The C<Devel::Symdump> module, version B<2.00> or higher.
=head1 See Also
perl(1), Apache(3), Devel::Symdump(3), Data::Dumper(3), B(3), B::Graph(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Symbol.pod
Index: Symbol.pod
===================================================================
=head1 NAME
Apache::Symbol - Things for symbol things
=head1 Synopsis
use Apache::Symbol ();
@ISA = qw(Apache::Symbol);
=head1 Description
C<Apache::Symbol> helps mod_perl users avoid Perl warnings related
with redefined constant functions.
C<perlsub/Constant Functions> says:
If you redefine a subroutine which was eligible for inlining you'll
get a mandatory warning. (You can use this warning to tell whether
or not a particular subroutine is considered constant.) The warning
is considered severe enough not to be optional because previously
compiled invocations of the function will still be using the old
value of the function.
I<mandatory warning> means there is B<no> way to avoid this warning
no matter what tricks you pull in Perl. This is bogus for us mod_perl
users when restarting the server with C<PerlFreshRestart> on or when
C<Apache::StatINC> pulls in a module that has changed on disk.
You can, however, pull some tricks with XS to avoid this warning,
C<Apache::Symbol::undef_functions> does just that.
=head1 Arguments
C<undef_functions> takes two arguments: C<skip> and C<only_undef_exports>.
C<skip> is a regular expression indicating the function names to skip.
Use the C<only_undef_exports> flag to undef only those functions
which are listed in C<@EXPORT>, C<@EXPORT_OK>, C<%EXPORT_TAGS>, or
C<@EXPORT_EXTRAS>. C<@EXPORT_EXTRAS> is not used by the Exporter, it
is only exists to communicate with C<undef_functions>.
As a special case, if none of the C<EXPORT> variables are defined ignore
C<only_undef_exports>. This takes care of trivial modules that don't
use the Exporter.
=head1 Players
This module and the undefining of functions is optional, if you wish
to have this functionality enabled, there are one or more switches you
need to know about.
=over 4
=item PerlRestartHandler
C<Apache::Symbol> defines a C<PerlRestartHandler> which can be useful in
conjuction with C<PerlFreshRestart On> as it will avoid subroutine
redefinition messages. Configure like so:
PerlRestartHandler Apache::Symbol
=item Apache::Registry
By placing the I<SYNOPSIS> bit in you script, C<Apache::Registry> will
undefine subroutines in your script before it is re-compiled to avoid
"subroutine re-defined" warnings.
=item Apache::StatINC
See C<Apache::StatINC>'s docs.
=item APACHE_SYMBOL_UNIVERSAL
If this environment variable is true when Symbol.pm is compiled,
it will define C<UNIVERSAL::undef_functions>, which means all classes
will inherit B<Apache::Symbol::undef_functions>.
=item Others
Modules such as C<HTML::Embperl> and C<Apache::ePerl> which compile
and script cache scripts ala C<Apache::Registry> style can use
C<undef_functions> with this bit of code:
if($package->can('undef_functions')) {
$package->undef_functions;
}
Where C<$package> is the name of the package in which the script is
being re-compiled.
=back
=head1 See Also
perlsub(1), Devel::Symdump(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Symdump.pod
Index: Symdump.pod
===================================================================
=head1 NAME
Apache::Symdump - Symbol table snapshots
=head1 Synopsis
PerlLogHandler Apache::Symdump
=head1 Description
C<Apache::Symdump> will record snapshots of the Perl symbol table for you to look at later.
It records them in C<ServerRoot/logs/symdump.$$.$n>. Where C<$$> is
the process id and C<$n> is incremented each time the handler is run.
The C<diff> utility can be used to compare snapshots and get an idea
of what might be making a process grow. Normally, new symbols come
from modules or scripts that were not preloaded, the Perl method
cache, etc.
% diff -u symdump.$$.0 symdump.$$.1
=head1 Caveats
C<Apache::Symdump> does not cleanup up its snapshot files, do so
simply by:
% rm logs/symdump.* logs/incdump.*
=head1 See Also
Devel::Symdump(3), Apache::Leak(3)
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/api/Table.pod
Index: Table.pod
===================================================================
=head1 NAME
Apache::Table - Perl interface to the Apache table structure
=head1 Synopsis
use Apache::Table ();
my $headers_out = $r->headers_out;
while(my($key,$val) = each %$headers_out) {
...
}
my $table = $r->headers_out;
$table->set(From => 'dougm@perl.apache.org');
mod_perl needs to be compiled with at least one of the following options:
DYNAMIC=1
PERL_TABLE_API=1
EVERYTHING=1
=head1 Description
This module provides tied interfaces to Apache data structures.
=head2 Classes
=over 4
=item Apache::Table
The C<Apache::Table> class provides methods for interfacing with the
Apache C<table> structure. The following C<Apache> class methods,
when called in a scalar context with no "key" argument, will return a
I<HASH> reference blessed into the I<Apache::Table> class and where
I<HASH> is tied to C<Apache::Table>:
headers_in
headers_out
err_headers_out
notes
dir_config
subprocess_env
=back
=head2 Methods
=over 4
=item get
Corresponds to the C<ap_table_get> function.
my $value = $table->get($key);
my $value = $headers_out->{$key};
=item set
Corresponds to the C<ap_table_set> function.
$table->set($key, $value);
$headers_out->{$key} = $value;
=item unset
Corresponds to the C<ap_table_unset> function.
$table->unset($key);
delete $headers_out->{$key};
=item clear
Corresponds to the C<ap_table_clear> function.
$table->clear;
%$headers_out = ();
=item add
Corresponds to the C<ap_table_add> function.
$table->add($key, $value);
=item merge
Corresponds to the C<ap_table_merge> function.
$table->merge($key, $value);
=back
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=back
Only the major authors are listed above. For contributors see the
Changes file.
=head1 See Also
Apache(3), mod_perl(3)
=cut
1.1 modperl-docs/src/docs/1.0/api/test.pod
Index: test.pod
===================================================================
=head1 NAME
Apache::test - Facilitates testing of Apache::* modules
=head1 Synopsis
# In Makefile.PL
use Apache::test;
my %params = Apache::test->get_test_params();
Apache::test->write_httpd_conf(%params, include => $more_directives);
*MY::test = sub { Apache::test->MM_test(%params) };
# In t/*.t script (or test.pl)
use Apache::test qw(skip_test have_httpd);
skip_test unless have_httpd;
(Some more methods of Doug's that I haven't reviewed or documented yet)
=head1 Description
This module helps authors of C<Apache::*> modules write test suites
that can query an actual running Apache server with mod_perl and their
modules loaded into it.
Its functionality is generally separated into methods that go in a
I<Makefile.PL> to configure, start, and stop the server, and methods
that go in one of the test scripts to make HTTP queries and manage the
results.
=head1 Methods
=head2 get_test_params()
This will ask the user a few questions about where the httpd binary
is, and what user/group/port should be used when running the server.
It will return a hash of the information it discovers. This hash is
suitable for passing to the C<write_httpd_conf()> method.
=head2 write_httpd_conf(%params)
This will write a basic I<httpd.conf> file suitable for starting a
HTTP server during the C<make test> stage. A hash of key/value pairs
that affect the written file can be passed as arguments. The
following keys are recognized:
=over 4
=item * conf_file
The path to the file that will be created. Default is I<t/httpd.conf>.
=item * port
The port that the Apache server will listen on.
=item * user
The user that the Apache server will run as.
=item * group
The group that the Apache server will run as.
=item * include
Any additional text you want added at the end of the config file.
Typically you'll have some C<PerlModule> and C<Perl*Handler>
directives to pass control to the module you're testing. The C<blib/>
directories will be added to the C<@INC> path when searching for
modules, so that's nice.
=back
=head2 MM_test(%params)
This method helps write a Makefile that supports running a web server
during the C<make test> stage. When you execute C<make test>, C<make>
will run C<make start_httpd>, C<make run_tests>, and C<make
kill_httpd> in sequence. You can also run these commands
independently if you want.
Pass the hash of parameters returned by C<get_test_params()> as an
argument to C<MM_test()>.
To patch into the C<ExtUtils::MakeMaker> wizardry (voodoo?), typically
you'll do the following in your I<Makefile.PL>:
*MY::test = sub { Apache::test->MM_test(%params) };
=head2 fetch
Apache::test->fetch($request);
Apache::test->fetch($user_agent, $request);
Call this method in a test script in order to fetch a page from the
running web server. If you pass two arguments, the first should be an
C<LWP::UserAgent> object, and the second should specify the request to
make of the server. If you only pass one argument, it specifies the
request to make.
The request can be specified either by a simple string indicating the
URI to fetch, or by a hash reference, which gives you more control
over the request. The following keys are recognized in the hash:
=over 4
=item * uri
The URI to fetch from the server. If the URI does not begin with
C<http>, we prepend C<http://localhost:$PORT> so that we make requests
of the test server.
=item * method
The request method to use. Default is C<GET>.
=item * content
The request content body. Typically used to simulate HTML fill-out
form submission for C<POST> requests. Default is null.
=item * headers
A hash of headers you want sent with the request. You might use this
to send cookies or provide some application-specific header.
=back
If you don't provide a C<headers> parameter and you set the C<method>
to C<POST>, then we assume that you're trying to simulate HTML form
submission and we add a C<Content-Type> header with a value of
C<application/x-www-form-urlencoded>.
In a scalar context, C<fetch()> returns the content of the web server's
response. In a list context, C<fetch()> returns the content and the
C<HTTP::Response> object itself. This can be handy if you need to check
the response headers, or the HTTP return code, or whatever.
=head2 static_modules
Example: $mods = Apache::test->static_modules('/path/to/httpd');
This method returns a hashref whose keys are all the modules
statically compiled into the given httpd binary. The corresponding
values are all 1.
=head1 Examples
No good examples yet. Example submissions are welcome. In the meantime, see
http://forum.swarthmore.edu/~ken/modules/Apache-AuthCookie/ , which
I'm retrofitting to use C<Apache::test>.
=head1 To Do
The C<MM_test> method doesn't try to be very smart, it just writes the
text that seems to work in my configuration. I am morally against
using the C<make> command for installing Perl modules (though of course
I do it anyway), so I haven't looked into this very much. Send bug
reports or better (patches).
I've got lots of code in my C<Apache::AuthCookie> module (etc.) that
assists in actually making the queries of the running server. I plan
to add that to this module, but first I need to compare what's already
here that does the same stuff.
=head1 Kudos
To Doug MacEachern for writing the first version of this module.
To caelum@debian.org (Rafael Kitover) for contributing the code to
parse existing httpd.conf files for C<--enable-shared=max> and DSOs.
=head1 Caveats
Except for making sure that the mod_perl distribution itself can run
C<make test> okay, I haven't tried very hard to keep compatibility with
older versions of this module. In particular C<MM_test()> has changed
and probably isn't usable in the old ways, since some of its
assumptions are gone. But none of this was ever documented, and
C<MM_test()> doesn't seem to actually be used anywhere in the mod_perl
disribution, so I don't feel so bad about it.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item * The L<documentation mailing list|maillist::list-docs-dev>
=back
=head1 Authors
=over
=item * Doug MacEachern
=item * Ken Williams
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org