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/2.0/api/Apache RequestIO.pod RequestUtil.pod ServerUtil.pod
Date Mon, 05 Jul 2004 01:40:31 GMT
stas        2004/07/04 18:40:31

  Modified:    src/docs/2.0/api/Apache RequestIO.pod RequestUtil.pod
                        ServerUtil.pod
  Log:
  work in progress
  
  Revision  Changes    Path
  1.6       +8 -8      modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod
  
  Index: RequestIO.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -u -r1.5 -r1.6
  --- RequestIO.pod	2 Jul 2004 23:17:53 -0000	1.5
  +++ RequestIO.pod	5 Jul 2004 01:40:31 -0000	1.6
  @@ -55,7 +55,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  @@ -88,7 +88,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<@msg> ( ARRAY )
   
  @@ -120,7 +120,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<$format> ( string )
   
  @@ -156,7 +156,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<@msg> ( ARRAY )
   
  @@ -192,7 +192,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<$buffer> ( SCALAR )
   
  @@ -235,7 +235,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item ret: no return value
   
  @@ -262,7 +262,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<$filename> ( string )
   
  @@ -316,7 +316,7 @@
   =over 4
   
   =item obj: C<$r>
  -( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   =item arg1: C<$buffer> ( SCALAR )
   
  
  
  
  1.19      +436 -288  modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod
  
  Index: RequestUtil.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod,v
  retrieving revision 1.18
  retrieving revision 1.19
  diff -u -u -r1.18 -r1.19
  --- RequestUtil.pod	23 Jun 2004 21:13:36 -0000	1.18
  +++ RequestUtil.pod	5 Jul 2004 01:40:31 -0000	1.19
  @@ -19,82 +19,112 @@
   
   =head1 Description
   
  -META: to be completed
  +C<Apache::RequestUtil> provides the L<Apache request
  +object|docs::2.0::api::Apache::RequestRec> utilities API.
   
   
   
  -=head1 Class methods API
   
  -=head2 C<request>
   
  -Retrieve the
  -(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) object
  -for the current request.
  +=head1 API
   
  -  $r = Apache->request;
  +
  +
  +
  +=head2 C<add_config>
  +
  +Dynamically add Apache configuration at request processing runtime:
  +
  +  $r->add_config($lines);
  +  $r->add_config($lines, $path);
  +  $r->add_config($lines, $path, $override);
   
   =over 4
   
  -=item obj: C<Apache> (class name)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -The Apache class
  +=item arg1: C<$lines> (ARRAY ref)
  +
  +An ARRAY reference containing configuration lines per element, without
  +the new line terminators.
  +
  +=item opt arg2: C<$path> ( SCALAR )
   
  -=item ret: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +This argument is only useful to tell whether a command is being called
  +in a dir context. By default C<$r-E<gt>filename> is passed.
  +
  +=item opt arg3: C<$override> ( C<L<APR::Const status
  +constant|docs::2.0::api::APR::Const>> )
  +
  +Which allow-override bits are set
  +
  +Default value is:
  +C<L<Apache::OR_AUTHCFG|docs::2.0::api::Apache::Const/C_Apache__OR_AUTHCFG_>>
  +
  +=item ret: no return value
   
   =item since: 1.99_10
   
   =back
   
  -This method is only available if C<L<PerlOptions
  -+GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_>> is
  -in effect.
  +See also:
  +C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_add_config_>>
   
  +For example:
   
  -=head1 Methods API
  +  use Apache::ServerUtil ();
  +  $r->add_config(['require valid-user']);
   
   
   
  -=head2 C<default_type>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Retrieve the value of the DefaultType directive, or text/plain if not set
   
  -  $ret = $r->default_type();
   
  -=over 4
  +=head2 C<as_string>
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +Dump the request object as a string
   
  -The current request
  +  $dump = $r->as_string();
   
  -=item ret: C<$ret> (string)
  +=over 4
   
  -The default type
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item ret: C<$dump> ( string )
  +
  +=item since: 1.99_10
   
   =back
   
  +Dumps various request and response headers (mainly useful for
  +debugging)
   
   
   
   
  -=head2 C<document_root>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<default_type>
   
  -Retrieve the document root for this server
  +Retrieve the value of the DefaultType directive for the current
  +request. If not set C<text/plain> is returned.
   
  -  $ret = $r->document_root();
  +  $content_type = $r->default_type();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item ret: C<$ret> (string)
  +=item ret: C<$content_type> ( string )
   
  -The document root
  +The default type
  +
  +=item since: 1.99_10
   
   =back
   
  @@ -102,47 +132,104 @@
   
   
   
  -=head2 C<get_limit_req_body>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<dir_config>
   
  -Return the limit on bytes in request msg body
  +C<$r-E<gt>dir_config()> provides an interface for the per-directory
  +variable specified by the C<PerlSetVar> and C<PerlAddVar> directives,
  +and also can be manipulated via the
  +C<L<APR::Table|docs::2.0::api::APR::Table>> methods.
   
  -  $ret = $r->get_limit_req_body();
  +  $table  = $r->dir_config();
  +  $value  = $r->dir_config($key);
  +  @values = $r->dir_config($key);
  +  $r->dir_config($key, $val);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -The current request
  +=item opt arg2: C<$key> ( string )
   
  -=item ret: C<$ret> (integer)
  +Key string
   
  -the maximum number of bytes in the request msg body
  +=item opt arg3: C<$val> ( string )
  +
  +Value string
  +
  +=item ret: ...
  +
  +Depends on the passed arguments, see further discussion
  +
  +=item since: 1.99_10
   
   =back
   
  +The keys are case-insensitive.
   
  +  $apr_table = $r->dir_config();
   
  +dir_config() called in a scalar context without the C<$key> argument
  +returns a I<HASH> reference blessed into the
  +C<L<APR::Table|docs::2.0::api::APR::Table>> class. This object can be
  +manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
  +methods. For available methods see
  +the C<L<APR::Table|docs::2.0::api::APR::Table>> manpage.
   
  +  @values = $r->dir_config($key);
   
  -=head2 C<get_server_name>
  +If the C<$key> argument is passed in the list context a list of all
  +matching values will be returned. This method is ineffective for big
  +tables, as it does a linear search of the table. Thefore avoid using
  +this way of calling dir_config() unless you know that there could be
  +more than one value for the wanted key and all the values are wanted.
   
  -META: Autogenerated - needs to be reviewed/completed
  +  $value = $r->dir_config($key);
  +
  +If the C<$key> argument is passed in the scalar context only a single
  +value will be returned. Since the table preserves the insertion order,
  +if there is more than one value for the same key, the oldest value
  +assosiated with the desired key is returned. Calling in the scalar
  +context is also much faster, as it'll stop searching the table as soon
  +as the first match happens.
  +
  +  $r->dir_config($key => $val);
   
  -Get the current server name from the request
  +If the C<$key> and the C<$val> arguments are used, the set() operation
  +will happen: all existing values associated with the key C<$key> (and
  +the key itself) will be deleted and C<$value> will be placed instead.
  +
  +  $r->dir_config($key => undef);
   
  -  $ret = $r->get_server_name();
  +If C<$val> is I<undef> the unset() operation will happen: all existing
  +values associated with the key C<$key> (and the key itself) will be
  +deleted.
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<document_root>
  +
  +Retrieve the document root for this server
  +
  +  $docroot = $r->document_root();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item ret: C<$ret> (string)
  +=item ret: C<$docroot> ( string )
   
  -the server name
  +The document root
  +
  +=item since: 1.99_10
   
   =back
   
  @@ -150,49 +237,65 @@
   
   
   
  -=head2 C<get_server_port>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Get the current server port
   
  -  $ret = $r->get_server_port();
  +=head2 C<get_handlers>
  +
  +Returns a reference to a list of handlers enabled for a given phase.
  +
  +  $handlers_list = $r->get_handlers($hook_name);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  +=item arg1: C<$hook_name> ( string )
   
  +a string representing the phase to handle (e.g. C<PerlLogHandler>)
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$handlers_list> (ref to an ARRAY of CODE refs)
  +
  +a list of handler subroutines CODE references
   
  -The server's port
  +=item since: 1.99_10
   
   =back
   
  +See also:
  +C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_get_handlers_>>
   
  +For example:
   
  +A list of handlers configured to run at the response phase:
  +
  +  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
   
   
  -=head2 C<get_status_line>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Return the Status-Line for a given status code (excluding the
  -HTTP-Version field). If an invalid or unknown status code is
  -passed, "500 Internal Server Error" will be returned.
   
  -  $ret = get_status_line($status);
  +
  +
  +=head2 C<get_limit_req_body>
  +
  +Return the limit on bytes in request msg body
  +
  +  $limit = $r->get_limit_req_body();
   
   =over 4
   
  -=item obj: C<$status> (integer)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -The HTTP status code
  +The current request
   
  -=item ret: C<$ret> (string)
  +=item ret: C<$limit> (integer)
   
  -The Status-Line
  +the maximum number of bytes in the request msg body
  +
  +=item since: 1.99_10
   
   =back
   
  @@ -200,314 +303,392 @@
   
   
   
  -=head2 C<is_initial_req>
  -
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<get_server_name>
   
  -Determine if the current request is the main request or a sub requests
  +Get the current request's server name
   
  -  $ret = $r->is_initial_req();
  +  $server = $r->get_server_name();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$server> ( string )
   
  +the server name
   
  +=item since: 1.99_10
   
   =back
   
  +For example, consruct a hostport string:
   
  +  use Apache::RequestUtil ();
  +  my $hostport = join ':', $r->get_server_name, $r->get_server_port;
   
   
   
  -=head2 C<method_register>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Register a new request method, and return the offset that will be
  -associated with that method.
  +=head2 C<get_server_port>
   
  -  $ret = $p->method_register($methname);
  +Get the current server port
  +
  +  $port = $r->get_server_port();
   
   =over 4
   
  -=item obj: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -The pool to create registered method numbers from.
  +The current request
   
  -=item arg1: C<$methname> (string)
  +=item ret: C<$port> ( integer )
   
  -The name of the new method to register.
  +The server's port number
   
  -=item ret: C<$ret> (integer)
  -
  -Ab int value representing an offset into a bitmask.
  +=item since: 1.99_10
   
   =back
   
  +For example, consruct a hostport string:
   
  +  use Apache::RequestUtil ();
  +  my $hostport = join ':', $r->get_server_name, $r->get_server_port;
   
   
   
  -=head2 C<add_config>
   
  -META: Autogenerated - needs to be reviewed/completed
   
   
   
  -  $ret = $r->add_config($lines, $path, $override);
  +=head2 C<get_status_line>
  +
  +Return the C<Status-Line> for a given status code (excluding the
  +HTTP-Version field).
  +
  +  $status_line = Apache::RequestUtil::get_status_line($status);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$status> (integer)
   
  -=item arg1: C<$lines> (ARRAY ref)
  +The HTTP status code
   
  -=item opt arg3: C<$path> (scalar)
  +=item ret: C<$status_line> ( string )
   
  -=item opt arg4: C<$override> (string)
  +The Status-Line
   
  -=item ret: C<$ret> (string)
  +If an invalid or unknown status code is passed, C<"500 Internal Server
  +Error"> will be returned.
  +
  +=item since: 1.99_15
   
   =back
   
  -See also:
  -C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_add_config_>>
  +For example:
   
  +  use Apache::RequestUtil ();
  +  print Apache::RequestUtil::get_status_line(400);
   
  -=head2 C<location>
  +will print:
  +
  +  400 Bad Request
   
  -META: Autogenerated - needs to be reviewed/completed
   
   
   
  -  $location = $r->location($location);
  +
  +=head2 C<is_initial_req>
  +
  +Determine whether the current request is the main request or a
  +sub-request
  +
  +  $is_initial = $r->is_initial_req();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item opt arg2: C<$location> (string)
  +A request or a sub-request object
   
  -=item ret: C<$location> (integer)
  +=item ret: C<$is_initial> ( true/false )
  +
  +If true -- it's the main request, otherwise it's a sub-request
  +
  +=item since: 1.99_10
   
   =back
   
   
   
   
  -=head2 C<location_merge>
   
  -META: Autogenerated - needs to be reviewed/completed
   
   
  +=head2 C<is_perl_option_enabled>
   
  -  $ret = $r->location_merge($location);
  +check whether a directory level C<PerlOptions> flag is enabled or not.
  +
  +  $result = $r->is_perl_option_enabled($flag);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item arg1: C<$location> (string)
  +=item arg1: C<$flag> ( string )
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$result> ( true/false )
  +
  +=item since: 1.99_10
   
   =back
   
  +For example to check whether the C<SetupEnv> option is enabled for the
  +current request (which can be disabled with C<PerlOptions -SetupEnv>)
  +and populate the environment variables table if disabled:
   
  +  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
   
  -=head2 C<pnotes>
  +See also:
  +L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> and
  +L<the equivalent function for server level PerlOptions
  +flags|docs::2.0::api::Apache::ServerUtil/C_is_perl_option_enabled_>.
   
  -Share Perl variables between Perl HTTP handlers
   
  -  $old_val  = $r->pnotes($key => $val);
  -  $val      = $r->pnotes($key);
  -  $hash_ref = $r->pnotes();
  +
  +
  +
  +=head2 C<location>
  +
  +Get the path of the E<lt>LocationE<gt> section from which the current
  +C<Perl*Handler> is being called.
  +
  +  $location = $r->location();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item opt arg1: C<$key> ( string )
  +=item ret: C<$location> ( string )
   
  -A key value
  +=item since: 1.99_10
   
  -=item opt arg2: C<$val> ( SCALAR )
  +=back
   
  -Any scalar value (e.g. a reference to an array)
   
  -=item ret: (3 different possible values)
   
  -if both, C<$key> and C<$val> are passed the previous value for C<$key>
  -is returned if such existed, otherwise C<undef> is returned.
   
  -if only C<$key> is passed, the current value for the given key is
  -returned.
   
  -if no arguments are passed, a hash reference is returned, which can
  -then be directly accessed without going through the C<pnotes()>
  -interface.
  +
  +=head2 C<location_merge>
  +
  +  $ret = $r->location_merge($location);
  +
  +=over 4
  +
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<$location> ( string )
  +
  +=item ret: C<$ret> (integer)
   
   =item since: 1.99_10
   
   =back
   
  -Similar to
  -(C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec/C_notes_>>),
  -but values can be any Perl variables. That also means that it can be
  -used only between Perl modules.
   
  -The values get reset automatically at the end of each HTTP request.
   
  -META: Examples (t/response/TestModperl/pnotes.pm)
   
   
  -=head2 C<no_cache>
  +=head2 C<method_register>
   
   META: Autogenerated - needs to be reviewed/completed
   
  +Register a new request method, and return the offset that will be
  +associated with that method.
   
  -  $ret = $r->no_cache($flag);
  +  $ret = $p->method_register($methname);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>> )
   
  -=item arg1: C<$flag> (number)
  +The pool to create registered method numbers from.
  +
  +=item arg1: C<$methname> ( string )
  +
  +The name of the new method to register.
   
   =item ret: C<$ret> (integer)
   
  -=back
  +An int value representing an offset into a bitmask.
   
  +=item since: 1.99_10
  +
  +=back
   
   
   
  -=head2 C<as_string>
  +=head2 C<new>
   
   META: Autogenerated - needs to be reviewed/completed
   
  -  $string = $r->as_string();
  +
  +  $ret = $r->new(classname, c, base_pool));
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item ret: C<$string> (string)
  +=item arg1: C<$flag> (number)
   
  -=back
  +=item ret: C<$ret> (integer)
   
  +=item since: 1.99_10
   
  +=back
   
   
  -=head2 C<get_handlers>
  +=head2 C<no_cache>
   
  -Returns a reference to a list of handlers enabled for
  -a given phase.
  +META: Autogenerated - needs to be reviewed/completed
   
  -  $handlers_list = $r->get_handlers($hook_name);
   
  -=over 4
  +  $ret = $r->no_cache($flag);
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=over 4
   
  -=item arg1: C<$hook_name> (string)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -a string representing the phase to handle.
  +=item arg1: C<$flag> (number)
   
  -=item ret: C<@handlers> (CODE ref or ref to ARRAY of CODE refs)
  +=item ret: C<$ret> (integer)
   
  -a list of handler subroutines CODE references
  +=item since: 1.99_10
   
   =back
   
  -For example:
   
  -A list of handlers configured to run at the response phase:
  -
  -  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };
   
  +=head2 C<pnotes>
   
  +Share Perl variables between Perl HTTP handlers
   
  +  $old_val  = $r->pnotes($key => $val);
  +  $val      = $r->pnotes($key);
  +  $hash_ref = $r->pnotes();
   
  -=head2 C<push_handlers>
  +=over 4
   
  -Add one or more handlers to a list of handlers to be called for a
  -given phase.
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -  $r->push_handlers($hook_name => \&handler);
  -  $r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
  +=item opt arg1: C<$key> ( string )
   
  -=over 4
  +A key value
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item opt arg2: C<$val> ( SCALAR )
   
  -=item arg1: C<$hook_name> (string)
  +Any scalar value (e.g. a reference to an array)
   
  -a string representing the phase to handle.
  +=item ret: (3 different possible values)
   
  -=item arg2: C<$handlers> (CODE ref or SUB name or ref to an ARRAY of CODE refs)
  +if both, C<$key> and C<$val> are passed the previous value for C<$key>
  +is returned if such existed, otherwise C<undef> is returned.
   
  -a single handler CODE reference or just a name of the subroutine
  -(fully qualified unless defined in the current package).
  +if only C<$key> is passed, the current value for the given key is
  +returned.
   
  -if more than one passed, use a reference to an array of CODE refs
  -and/or subroutine names.
  +if no arguments are passed, a hash reference is returned, which can
  +then be directly accessed without going through the C<pnotes()>
  +interface.
   
  -=item ret: no return value
  +=item since: 1.99_10
   
   =back
   
  -Examples:
  +Similar to
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec/C_notes_>> ),
  +but values can be any Perl variables. That also means that it can be
  +used only between Perl modules.
   
  -A single handler:
  +The values get reset automatically at the end of each HTTP request.
   
  -  $r->push_handlers(PerlResponseHandler => \&handler);
  +META: Examples (t/response/TestModperl/pnotes.pm)
   
  -Multiple handlers:
   
  -  $r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
   
  -Anonymous functions:
   
  -  $r->push_handlers(PerlLogHandler => sub { return Apache::OK });
  +=head2 C<request>
   
  +Retrieve the
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> ) object
  +for the current request.
   
  +  $r = Apache->request;
   
  +=over 4
   
  -=head2 C<set_handlers>
  +=item obj: C<Apache> (class name)
   
  -Set a list of handlers to be called for a given phase. Any previously
  -set handlers are forgotten.
  +The Apache class
   
  -  $r->set_handlers($hook_name => \&handler);
  -  $r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
  -  $r->set_handlers($hook_name => []);
  -  $r->set_handlers($hook_name => undef);
  +=item ret: C<$r> ( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +This method is only available if C<L<PerlOptions
  ++GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_>> is
  +in effect.
  +
  +
  +
  +
  +=head2 C<push_handlers>
  +
  +Add one or more handlers to a list of handlers to be called for a
  +given phase.
  +
  +  $ok = $r->push_handlers($hook_name => \&handler);
  +  $ok = $r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item arg1: C<$hook_name> (string)
  +=item arg1: C<$hook_name> ( string )
   
  -a string representing the phase to handle.
  +the phase to add the handlers to
   
  -=item arg2: C<$handlers> (CODE ref or SUB name or ref to an ARRAY of CODE refs)
  +=item arg2: C<$handlers> ( CODE ref or SUB name or an ARRAY ref )
   
  -a reference to a single handler CODE reference or just a name of the
  -subroutine (fully qualified unless defined in the current package).
  +a single handler CODE reference or just a name of the subroutine
  +(fully qualified unless defined in the current package).
   
   if more than one passed, use a reference to an array of CODE refs
   and/or subroutine names.
   
  -if the argument is C<undef> or [] the list of handlers is reset to
  -zero.
  +=item ret: C<$ok> ( true/false )
   
  -=item ret: no return value
  +returns a true value on success, otherwise a false value
  +
  +=item since: 1.99_10
  +
  +See also:
  +C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_push_handlers_>>
   
   =back
   
  @@ -515,23 +696,15 @@
   
   A single handler:
   
  -  $r->set_handlers(PerlResponseHandler => \&handler);
  +  $r->push_handlers(PerlResponseHandler => \&handler);
   
   Multiple handlers:
   
  -  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
  +  $r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
   
   Anonymous functions:
   
  -  $r->set_handlers(PerlLogHandler => sub { return Apache::OK });
  -
  -Reset any previously set handlers:
  -
  -  $r->set_handlers(PerlCleanupHandler => []);
  -
  -or
  -
  -  $r->set_handlers(PerlCleanupHandler => undef);
  +  $r->push_handlers(PerlLogHandler => sub { return Apache::OK });
   
   
   
  @@ -546,148 +719,123 @@
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item arg1: C<$username> (string)
  +=item arg1: C<$username> ( string )
   
  -=item arg2: C<$password> (string)
  +=item arg2: C<$password> ( string )
   
   =item ret: no return value
   
  -=back
  -
  -
  -
  +=item since: 1.99_10
   
  +=back
   
  -=head2 C<slurp_filename>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  +=head2 C<set_handlers>
   
  -Return a reference to contents of C<$r-E<gt>filename>.
  +Set a list of handlers to be called for a given phase. Any previously
  +set handlers are forgotten.
   
  -  $content = $r->slurp_filename($tainted);
  +  $ok = $r->set_handlers($hook_name => \&handler);
  +  $ok = $r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
  +  $ok = $r->set_handlers($hook_name => []);
  +  $ok = $r->set_handlers($hook_name => undef);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -=item arg1: C<$tainted> (number)
  +=item arg1: C<$hook_name> ( string )
   
  -By default the returned data is tainted (if run under C<-T>). If an
  -optional C<$tainted> flag is set to zero, the data will be marked as
  -non-tainted. Do not set this flag to zero unless you know what you are
  -doing, you may create a security hole in your program if you do. For
  -more information see the I<perlsec> manpage. If you wonder why this
  -option is available, it is used internally by the
  -C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> handler and
  -friends, because the CGI scripts that it reads are considered safe
  -(you could just as well C<require()> them).
  +the phase to set the handlers in
   
  -=item ret: C<$content> (scalar)
  +=item arg2: C<$handlers> (CODE ref or SUB name or an ARRAY ref)
   
  -=back
  -
  -
  -=head2 C<is_perl_option_enabled>
  -
  -check whether a directory level PerlOptions flag is enabled or not.
  -
  -  $result = $r->is_perl_option_enabled($flag);
  +a reference to a single handler CODE reference or just a name of the
  +subroutine (fully qualified unless defined in the current package).
   
  +if more than one passed, use a reference to an array of CODE refs
  +and/or subroutine names.
   
  -=over 4
  +if the argument is C<undef> or C<[]> the list of handlers is reset to
  +zero.
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item ret: C<$ok> ( true/false )
   
  -=item arg1: C<$flag> (string)
  +returns a true value on success, otherwise a false value
   
  -=item ret: C<$result> (integer)
  +=item since: 1.99_10
   
   =back
   
  -For example to check whether the C<SetupEnv> option is enabled for the
  -current request (which can be disabled with C<PerlOptions -SetupEnv>)
  -and populate the environment variables table if disabled:
  +See also:
  +C<L<$s-E<gt>add_config|docs::2.0::api::Apache::ServerUtil/C_set_handlers_>>
   
  -  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');
  +Examples:
   
  -See also:
  -L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> and
  -L<the equivalent function for server level PerlOptions
  -flags|docs::2.0::api::Apache::ServerUtil/C_is_perl_option_enabled_>.
  +A single handler:
   
  +  $r->set_handlers(PerlResponseHandler => \&handler);
   
  +Multiple handlers:
   
  +  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
   
  +Anonymous functions:
   
  -=head2 C<dir_config>
  +  $r->set_handlers(PerlLogHandler => sub { return Apache::OK });
   
  -dir_config() provides an interface for the per-directory variable
  -specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
  -can be manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
  -methods.
  +Reset any previously set handlers:
   
  -  $table  = $r->dir_config();
  -  $value  = $r->dir_config($key);
  -  @values = $r->dir_config($key);
  -  $r->dir_config($key, $val);
  +  $r->set_handlers(PerlCleanupHandler => []);
   
  -=over 4
  +or
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +  $r->set_handlers(PerlCleanupHandler => undef);
   
  -=item opt arg2: C<$key> (string)
   
  -=item opt arg3: C<$val> (string)
   
  -=item ret: C<$ret> (scalar)
   
  -Depends on the passed arguments, see further discussion
   
  -=back
   
   
  -The keys are case-insensitive.
  +=head2 C<slurp_filename>
   
  -  $apr_table = $r->dir_config();
  +Return a reference to contents of C<$r-E<gt>filename>.
   
  -dir_config() called in a scalar context without the C<$key> argument
  -returns a I<HASH> reference blessed into the
  -C<L<APR::Table|docs::2.0::api::APR::Table>> class. This object can be
  -manipulated via the C<L<APR::Table|docs::2.0::api::APR::Table>>
  -methods. For available methods see
  -the C<L<APR::Table|docs::2.0::api::APR::Table>> manpage.
  +  $content = $r->slurp_filename($tainted);
   
  -  @values = $r->dir_config($key);
  +=over 4
   
  -If the C<$key> argument is passed in the list context a list of all
  -matching values will be returned. This method is ineffective for big
  -tables, as it does a linear search of the table. Thefore avoid using
  -this way of calling dir_config() unless you know that there could be
  -more than one value for the wanted key and all the values are wanted.
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  -  $value = $r->dir_config($key);
  +=item arg1: C<$tainted> (number)
   
  -If the C<$key> argument is passed in the scalar context only a single
  -value will be returned. Since the table preserves the insertion order,
  -if there is more than one value for the same key, the oldest value
  -assosiated with the desired key is returned. Calling in the scalar
  -context is also much faster, as it'll stop searching the table as soon
  -as the first match happens.
  +If the server is run under the tainting mode (C<-T>) which we hope you
  +do, by default the returned data is tainted. If an optional
  +C<$tainted> flag is set to zero, the data will be marked as
  +non-tainted.
  +
  +Do B<not> set this flag to zero unless you know what you are doing,
  +you may create a security hole in your program if you do. For more
  +information see the I<perlsec> manpage.
  +
  +If you wonder why this option is available, it is used internally by
  +the C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> handler
  +and friends, because the CGI scripts that it reads are considered safe
  +(you could just as well C<require()> them).
   
  -  $r->dir_config($key => $val);
  +=item ret: C<$content> ( string )
   
  -If the C<$key> and the C<$val> arguments are used, the set() operation
  -will happen: all existing values associated with the key C<$key> (and
  -the key itself) will be deleted and C<$value> will be placed instead.
  +=item since: 1.99_10
   
  -  $r->dir_config($key => undef);
  +=back
   
  -If C<$val> is I<undef> the unset() operation will happen: all existing
  -values associated with the key C<$key> (and the key itself) will be
  -deleted.
   
   
   
  
  
  
  1.21      +258 -146  modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod
  
  Index: ServerUtil.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod,v
  retrieving revision 1.20
  retrieving revision 1.21
  diff -u -u -r1.20 -r1.21
  --- ServerUtil.pod	22 May 2004 02:03:27 -0000	1.20
  +++ ServerUtil.pod	5 Jul 2004 01:40:31 -0000	1.21
  @@ -48,33 +48,6 @@
   
   
   
  -
  -=head2 C<add_config>
  -
  -META: Autogenerated - needs to be reviewed/completed
  -
  -  $ret = $s->add_config($lines, $path, $override);
  -
  -=over 4
  -
  -=item obj: C<$r> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  -
  -=item arg1: C<$lines> (ARRAY ref)
  -
  -=item opt arg3: C<$path> (scalar)
  -
  -=item opt arg4: C<$override> (string)
  -
  -=item ret: C<$ret> (string)
  -
  -=back
  -
  -See also:
  -C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
  -
  -
  -
  -
   =head2 C<add_version_component>
   
   META: Autogenerated - needs to be reviewed/completed
  @@ -96,6 +69,8 @@
   
   =item ret: no return value
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -118,6 +93,8 @@
   
   true if defined, false otherwise
   
  +=item since: 1.99_10
  +
   =back
   
   For example:
  @@ -142,6 +119,8 @@
   
   The server build time string
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -159,6 +138,8 @@
   
   The server version string
   
  +=item since: 1.99_10
  +
   =back
   
   
  @@ -169,89 +150,54 @@
   
   
   
  -=head2 server_root_relative()
  +=head2 C<add_config>
   
  -Returns the canonical form of the filename made absolute to
  -C<ServerRoot>:
  +Dynamically add Apache configuration:
   
  -  $path = $s->server_root_relative($fname);
  +  $s->add_config($lines);
   
   =over 4
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
   
  -=item opt arg2: C<$fname> (string)
  -
  -=item ret: C<$path> (string)
  -
  -=back
  -
  -C<$fname> is appended to the value of C<ServerRoot> and returned. For
  -example:
  -
  -  my $log_dir = Apache::server_root_relative($r->pool, 'logs');
  -
  -If C<$fname> is not specified, the value of C<ServerRoot> is returned
  -with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
  -value).
  -
  -Also see the C<L<Apache::server_root|/C_Apache__server_root_>>
  -constant.
  -
  -
  -
  -
  -=head2 C<error_log2stderr>
  -
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Convert stderr to the error log
  -
  -  $s->error_log2stderr();
  -
  -=over 4
  +=item arg1: C<$lines> (ARRAY ref)
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  -
  -The current server
  +An ARRAY reference containing configuration lines per element, without
  +the new line terminators.
   
   =item ret: no return value
   
  -=back
  -
  -
  -
  -=head2 C<psignature>
  -
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Get HTML describing the address and (optionally) admin of the server.
  -
  -  $sig = $r->psignature($prefix);
  -
  -=over 4
  -
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  -
  -=item arg1: C<$prefix> (string)
  +=item since: 1.99_10
   
  -Text which is prepended to the return value
  -
  -=item ret: C<$sig> (string)
  +=back
   
  -HTML describing the server
  +See also:
  +C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
   
  -=back
  +For example:
   
  +Add a configuration section at the server startup (e.g. from
  +I<startup.pl>):
   
  +  use Apache::ServerUtil ();
  +  my $conf = <<'EOC';
  +  PerlModule Apache::MyExample
  +  <Location /perl>
  +    SetHandler perl-script
  +    PerlResponseHandler Apache::MyExample
  +  </Location>
  +  EOC
  +  Apache->server->add_config([split /\n/, $conf]);
   
   
   
   =head2 C<dir_config>
   
  -dir_config() provides an interface for the per-server variables
  -specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
  -can be manipulated via the C<APR::Table> methods.
  +C<$s-E<gt>dir_config()> provides an interface for the per-server
  +variables specified by the C<PerlSetVar> and C<PerlAddVar> directives,
  +and also can be manipulated via the
  +C<L<APR::Table|docs::2.0::api::APR::Table>> methods.
   
     $table  = $s->dir_config();
     $value  = $s->dir_config($key);
  @@ -260,16 +206,23 @@
   
   =over 4
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
   
   =item opt arg2: C<$key> (string)
   
  +Key string
  +
   =item opt arg3: C<$val> (string)
   
  -=item ret: C<$ret> (scalar)
  +Value string
  +
  +=item ret: ...
   
   Depends on the passed arguments, see further discussion
   
  +=item since: 1.99_10
  +
   =back
   
   The keys are case-insensitive.
  @@ -314,34 +267,30 @@
   
   
   
  -=head2 C<is_perl_option_enabled>
   
  -check whether a server level PerlOptions flag is enabled or not.
  +=head2 C<error_log2stderr>
   
  -  $result = $s->is_perl_option_enabled($flag);
  +Start sending STDERR to the error_log file
   
  +  $s->error_log2stderr();
   
   =over 4
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
   
  -=item arg1: C<$flag> (string)
  +The current server
   
  -=item ret: C<$result> (integer)
  +=item ret: no return value
  +
  +=item since: 1.99_10
   
   =back
   
  -For example to check whether the C<ChildExit> hook is enabled (which
  -can be disabled with C<PerlOptions -ChildExit>) and configure some
  -handlers to run if enabled:
  +This method may prove useful if you want to start redirecting STDERR
  +to the error_log file before Apache does that on the startup.
   
  -  $s->push_handlers(ChildExit => \&child_exit)
  -      if $s->is_perl_option_enabled('ChildExit');
   
  -See also:
  -L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> and
  -L<the equivalent function for directory level PerlOptions
  -flags|docs::2.0::api::Apache::RequestUtil/C_is_perl_option_enabled_>.
   
   
   
  @@ -351,99 +300,156 @@
   Returns a reference to a list of handlers enabled for
   a given phase.
   
  -  @handlers = $s->get_handlers($hook_name);
  +  $handlers_list = $s->get_handlers($hook_name);
   
   =over 4
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
   
   =item arg1: C<$hook_name> (string)
   
   a string representing the phase to handle.
   
  -=item ret: C<@handlers> (CODE ref or ref to ARRAY of CODE refs)
  +=item ret: C<$handlers_list> (ref to an ARRAY of CODE refs)
   
   a list of references to the handler subroutines
   
  +=item since: 1.99_10
  +
   =back
   
  +See also:
  +C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_get_handlers_>>
  +
   For example:
   
  -  @handlers = $s->get_handlers('PerlResponseHandler');
  +A list of handlers configured to run at the I<child_exit> phase:
   
  +  @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};
   
   
   
  -=head2 C<push_handlers>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Add one or more handlers to a list of handlers to be called for a
  -given phase.
   
  -  $s->push_handlers($hook_name => \&handler);
  -  $s->push_handlers($hook_name => [\&handler, \&handler2]);
   
  -=over 4
  +=head2 C<is_perl_option_enabled>
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +check whether a server level C<PerlOptions> flag is enabled or not.
   
  -=item arg1: C<$hook_name> (string)
  +  $result = $s->is_perl_option_enabled($flag);
   
  -a string representing the phase to handle. 
  +=over 4
   
  -=item arg2: C<$handlers> (CODE ref or ref to ARRAY of CODE refs)
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
   
  -a reference to a list of references to the handler subroutines, or a
  -single reference to a handler subroutine
  +=item arg1: C<$flag> ( string )
   
  -=item ret: no return value
  +=item ret: C<$result> ( true/false )
  +
  +=item since: 1.99_10
   
   =back
   
  -Examples:
  +For example to check whether the C<ChildExit> hook is enabled (which
  +can be disabled with C<PerlOptions -ChildExit>) and configure some
  +handlers to run if enabled:
  +
  +  $s->push_handlers(ChildExit => \&child_exit)
  +      if $s->is_perl_option_enabled('ChildExit');
  +
  +See also:
  +L<PerlOptions|docs::2.0::user::config::config/C_PerlOptions_> and
  +L<the equivalent function for directory level PerlOptions
  +flags|docs::2.0::api::Apache::RequestUtil/C_is_perl_option_enabled_>.
  +
   
  -  $s->push_handlers(PerlResponseHandler => \&handler);
  -  $s->push_handlers(PerlResponseHandler => [\&handler, \&handler2]);
   
  -  # XXX: not implemented yet
  -  $s->push_handlers(PerlResponseHandler => sub {...});
   
   
   
  -=head2 C<set_handlers>
  +
  +=head2 C<psignature>
   
   META: Autogenerated - needs to be reviewed/completed
   
  -Set a list of handlers to be called for a given phase.
  +Get HTML describing the address and (optionally) admin of the server.
   
  -  $s->set_handlers($hook_name => \&handler);
  -  $s->set_handlers($hook_name => [\&handler, \&handler2]);
  +  $sig = $rXXXX->psignature($prefix);
   
   =over 4
   
  -=item obj: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item obj: C<$rXXX> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -=item arg1: C<$hook_name> (string)
  +=item arg1: C<$prefix> (string)
   
  -a string representing the phase to handle.
  +Text which is prepended to the return value
   
  -=item arg2: C<$handlers> (CODE ref or ref to ARRAY of CODE refs)
  +=item ret: C<$sig> (string)
   
  -a reference to a list of references to the handler subroutines, or a
  -single reference to a handler subroutine
  +HTML describing the server
   
  -=item ret: no return value
  +=item since: 1.99_10
   
   =back
   
  +
  +
  +
  +
  +
  +=head2 C<push_handlers>
  +
  +Add one or more handlers to a list of handlers to be called for a
  +given phase.
  +
  +  $ok = $s->push_handlers($hook_name => \&handler);
  +  $ok = $s->push_handlers($hook_name => [\&handler, \&handler2]);
  +
  +=over 4
  +
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
  +
  +=item arg1: C<$hook_name> ( string )
  +
  +the phase to add the handlers to
  +
  +=item arg2: C<$handlers> ( CODE ref or SUB name or an ARRAY ref )
  +
  +a single handler CODE reference or just a name of the subroutine
  +(fully qualified unless defined in the current package).
  +
  +if more than one passed, use a reference to an array of CODE refs
  +and/or subroutine names.
  +
  +=item ret: C<$ok> ( true/false )
  +
  +returns a true value on success, otherwise a false value
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +See also:
  +C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_push_handlers_>>
  +
   Examples:
   
  -  $s->set_handlers(PerlResponseHandler => \&handler);
  -  $s->set_handlers(PerlResponseHandler => [\&handler, \&handler2]);
  +A single handler:
  +
  +  $s->push_handlers(PerlChildExitHandler => \&handler);
  +
  +Multiple handlers:
  +
  +  $s->push_handlers(PerlChildExitHandler => ['Foo::Bar::handler', \&handler2]);
  +
  +Anonymous functions:
  +
  +  $s->push_handlers(PerlLogHandler => sub { return Apache::OK });
   
  -  # XXX: not implemented yet
  -  $s->set_handlers(PerlResponseHandler => sub {...});
   
   
   
  @@ -460,9 +466,115 @@
   
   =item obj: C<Apache> (class name)
   
  -=item ret: C<$main_s> (C<L<Apache::Server|docs::2.0::api::Apache::Server>>)
  +=item ret: C<$main_s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +
  +
  +=head2 C<server_root_relative>
  +
  +Returns the canonical form of the filename made absolute to
  +C<ServerRoot>:
  +
  +  $path = $s->server_root_relative($fname);
  +
  +=over 4
  +
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
  +
  +=item opt arg2: C<$fname> (string)
  +
  +=item ret: C<$path> (string)
  +
  +=item since: 1.99_10
   
   =back
  +
  +C<$fname> is appended to the value of C<ServerRoot> and returned. For
  +example:
  +
  +  my $log_dir = Apache::server_root_relative($r->pool, 'logs');
  +
  +If C<$fname> is not specified, the value of C<ServerRoot> is returned
  +with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
  +value).
  +
  +Also see the C<L<Apache::server_root|/C_Apache__server_root_>>
  +constant.
  +
  +
  +
  +
  +=head2 C<set_handlers>
  +
  +Set a list of handlers to be called for a given phase. Any previously
  +set handlers are forgotten.
  +
  +  $ok = $s->set_handlers($hook_name => \&handler);
  +  $ok = $s->set_handlers($hook_name => [\&handler, \&handler2]);
  +  $ok = $s->set_handlers($hook_name => []);
  +  $ok = $s->set_handlers($hook_name => undef);
  +
  +=over 4
  +
  +=item obj: C<$s>
  +( C<L<Apache::Server object|docs::2.0::api::Apache::Server>> )
  +
  +=item arg1: C<$hook_name> ( string )
  +
  +the phase to set the handlers in
  +
  +=item arg2: C<$handlers> ( CODE ref or SUB name or an ARRAY ref )
  +
  +a reference to a single handler CODE reference or just a name of the
  +subroutine (fully qualified unless defined in the current package).
  +
  +if more than one passed, use a reference to an array of CODE refs
  +and/or subroutine names.
  +
  +if the argument is C<undef> or C<[]> the list of handlers is reset to
  +zero.
  +
  +=item ret: C<$ok> ( true/false )
  +
  +returns a true value on success, otherwise a false value
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +See also:
  +C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_set_handlers_>>
  +
  +Examples:
  +
  +A single handler:
  +
  +  $r->set_handlers(PerlChildExitHandler => \&handler);
  +
  +Multiple handlers:
  +
  +  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);
  +
  +Anonymous functions:
  +
  +  $r->set_handlers(PerlLogHandler => sub { return Apache::OK });
  +
  +Reset any previously set handlers:
  +
  +  $r->set_handlers(PerlCleanupHandler => []);
  +
  +or
  +
  +  $r->set_handlers(PerlCleanupHandler => undef);
  +
  +
  +
   
   
   
  
  
  

---------------------------------------------------------------------
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