perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject 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
Date Sat, 20 Apr 2002 10:38:51 GMT
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 <per.einar@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


Mime
View raw message