cvs commit: modperl-docs/src/docs/2.0/user/porting compat.pod
stas2004/07/15 18:11:03
Modified:src/docs/2.0/api/Apache RequestUtil.pod ServerUtil.pod
src/docs/2.0/api/ModPerl RegistryLoader.pod
src/docs/2.0/user/handlers http.pod server.pod
src/docs/2.0/user/install install.pod
src/docs/2.0/user/performance prevent.pod
src/docs/2.0/user/porting compat.pod
Log:
sync with api changes
Revision ChangesPath
1.25 +35 -0 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.24
retrieving revision 1.25
diff -u -u -r1.24 -r1.25
--- RequestUtil.pod 15 Jul 2004 20:51:08 - 1.24
+++ RequestUtil.pod 16 Jul 2004 01:11:03 - 1.25
@@ -64,6 +64,9 @@
# share perl objects like $r->notes
$r->pnotes($key => [$obj1, $obj2]);
+ # get HTML signature
+ $sig = $r->psignature($prefix);
+
# get the global request object (requires PerlOptions +GlobalRequest)
$r = Apache->request;
@@ -767,6 +770,38 @@
interface:
delete $r->pnotes->{foo};
+
+
+
+
+
+
+
+
+=head2 C
+
+Get HTML describing the address and (optionally) admin of the server.
+
+ $sig = $r->psignature($prefix);
+
+=over 4
+
+=item obj: C<$r>
+( C> )
+
+=item arg1: C<$prefix> ( string )
+
+Text which is prepended to the return value
+
+=item ret: C<$sig> ( string )
+
+HTML text describing the server. Note that depending on the value of
+the C directive, the function may return the address,
+including the admin information or nothing at all.
+
+=item since: 1.99_15
+
+=back
1.25 +72 -45modperl-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.24
retrieving revision 1.25
diff -u -u -r1.24 -r1.25
--- ServerUtil.pod15 Jul 2004 20:51:08 - 1.24
+++ ServerUtil.pod16 Jul 2004 01:11:03 - 1.25
@@ -12,8 +12,8 @@
$s = Apache->server;
my $srv_cfg = $s->dir_config;
- # get 'conf/' dir path using $s
- my $conf_dir = $s->server_root_relative('conf');
+ # get 'conf/' dir path using (avoid using this function!)
+ my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'conf');
# server level PerlOptions flags lookup
$s->push_handlers(ChildExit => \&child_exit)
@@ -147,6 +147,9 @@
mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.9
configured -- resuming normal operations
+Also remember that the C directive value controls
+whether the component information is displayed or not.
+
@@ -456,36 +459,6 @@
-
-=head2 C
-
-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<$rXXX>
(C>)
-
-=item arg1: C<$prefix> ( string )
-
-Text which is prepended to the return value
-
-=item ret: C<$sig> ( string )
-
-HTML describing the server
-
-=item since: 1.99_10
-
-=back
-
-
-
-
-
-
=head2 C
Add one or more handlers to a list of handlers to be called for a
@@ -563,6 +536,8 @@
+
+
=head2 C
returns the value set by the top-level C directive.
@@ -584,25 +559,31 @@
-
-
-
=head2 C
Returns the canonical form of the filename made absolute to
C:
- $path = $s->server_root_relative($fname);
+ $path = Apache::ServerUtil::server_root_relative($pool, $fname);
=over 4
-=item obj: C<$s>
-( C> )
+=item arg1: C<$pool>
+( C> )
+
+Make sure that you read the following explanation and understand well
+which pool object you need to pass before using this function.
=item opt arg2: C<$fname> ( string )
=item ret: C<$path> ( string )
+The concatenation of C and the C<$fname>.
+
+If C<$fname> is not specified, the value of C is returned
+with a trailing C. (it's the same as using C<''> as C<$fname>'s
+value).
+
=item since: 1.99_10
=back
@@ -610,15 +591,61 @@
C<$fname> is appended to the value of C and returned. For
example:
- my $log_dir = Apache::server_root_relative($r->pool, 'logs');
+ my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'logs');
+
+You must be extra-careful when using this function. If you aren't sure
+what you are doing don't use it.
+
+It's much safer to build the path by yourself using use
+C>, For
+example:
+
+ use File::Spec::Functions qw(catfile);
+ my $path = catfile Apache::S
cvs commit: modperl-docs/src/docs/2.0/api/Apache ServerUtil.pod
stas2004/07/15 18:41:00
Modified:src/docs/2.0/api/Apache ServerUtil.pod
Log:
Apache::ServerUtil is complete
Revision ChangesPath
1.26 +67 -42modperl-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.25
retrieving revision 1.26
diff -u -u -r1.25 -r1.26
--- ServerUtil.pod16 Jul 2004 01:11:03 - 1.25
+++ ServerUtil.pod16 Jul 2004 01:41:00 - 1.26
@@ -8,13 +8,37 @@
=head1 Synopsis
use Apache::ServerUtil ();
-
$s = Apache->server;
+
+ # push config
+ $s->add_config(['ServerTokens off']);
+
+ # add components to the Server signature
+ $s->add_version_component("MyModule/1.234");
+
+ # access PerlSetVar/PerlAddVar values
my $srv_cfg = $s->dir_config;
- # get 'conf/' dir path using (avoid using this function!)
+ # check command line defines
+ print "this is mp2"
+ if Apache::ServerUtil::exists_config_define('MODPERL2');
+
+ # get PerlChildExitHandler configured handlers
+ @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};
+
+ # server build and version info:
+ $when_built = Apache::ServerUtil::get_server_built();
+ $version = Apache::ServerUtil::get_server_version();
+
+ # ServerRoot value
+ $server_root = Apache::ServerUtil::server_root();
+
+ # get 'conf/' dir path (avoid using this function!)
my $dir = Apache::ServerUtil::server_root_relative($r->pool, 'conf');
+ # set child_exit handlers
+ $r->set_handlers(PerlChildExitHandler => \&handler);
+
# server level PerlOptions flags lookup
$s->push_handlers(ChildExit => \&child_exit)
if $s->is_perl_option_enabled('ChildExit');
@@ -23,15 +47,13 @@
$s->method_register('NEWGET');
-META: to be completed
-
=head1 Description
C provides the L utilities API.
+object|docs::2.0::api::Apache::ServerRec> utilities API.
@@ -234,36 +256,6 @@
-
-=head2 C
-
-Start sending STDERR to the error_log file
-
- $s->error_log2stderr();
-
-=over 4
-
-=item obj: C<$s>
-( C> )
-
-The current server
-
-=item ret: no return value
-
-=item since: 1.99_10
-
-=back
-
-This method may prove useful if you want to start redirecting STDERR
-to the error_log file before Apache does that on the startup.
-
-
-
-
-
-
-
-
=head2 C
Check for a definition from the server startup command line
@@ -348,7 +340,7 @@
The server build time string
-=item since: 1.99_10
+=item since: 1.99_15
=back
@@ -370,7 +362,7 @@
The server version string
-=item since: 1.99_10
+=item since: 1.99_15
=back
@@ -548,7 +540,7 @@
=item ret: C<$server_root> ( string )
-=item since: 1.99_10
+=item since: 1.99_15
=back
@@ -584,7 +576,7 @@
with a trailing C. (it's the same as using C<''> as C<$fname>'s
value).
-=item since: 1.99_10
+=item since: 1.99_15
=back
@@ -647,9 +639,6 @@
-
-
-
=head2 C
Set a list of handlers to be called for a given phase. Any previously
@@ -712,6 +701,42 @@
or
$r->set_handlers(PerlCleanupHandler => undef);
+
+
+
+
+=head1 Unsupported API
+
+C also provides auto-generated Perl interface for
+a few other methods which aren't tested at the moment and therefore
+their API is a subject to change. These methods will be finalized
+later as a need arises. If you want to rely on any of the following
+methods please contact the L so we can help each other take the steps necessary
+to shift the method to an officially supported API.
+
+
+=head2 C
+
+Start sending STDERR to the error_log file
+
+ $s->error_log2stderr();
+
+=over 4
+
+=item obj: C<$s>
+( C> )
+
+The current server
+
+=item ret: no return value
+
+=item since: 1.99_10
+
+=back
+
+This method may prove useful if you want to start redirecting STDERR
+to the error_log file before Apache does that on the startup.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api config.cfg
stas2004/07/15 18:42:19 Modified:src/docs/2.0/api config.cfg Removed: src/docs/2.0/api/Apache Server.pod Log: Apache/Server.pod is gone Revision ChangesPath 1.39 +0 -1 modperl-docs/src/docs/2.0/api/config.cfg Index: config.cfg === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/config.cfg,v retrieving revision 1.38 retrieving revision 1.39 diff -u -u -r1.38 -r1.39 --- config.cfg10 Jul 2004 08:28:53 - 1.38 +++ config.cfg16 Jul 2004 01:42:19 - 1.39 @@ -35,7 +35,6 @@ Apache/RequestRec.pod Apache/RequestUtil.pod Apache/Response.pod -Apache/Server.pod Apache/ServerRec.pod Apache/ServerUtil.pod Apache/SubProcess.pod - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api/Apache PerlSections.pod
stas2004/07/15 18:53:20
Modified:src/docs/2.0/api/Apache PerlSections.pod
Log:
complete the manpages
Revision ChangesPath
1.13 +46 -21modperl-docs/src/docs/2.0/api/Apache/PerlSections.pod
Index: PerlSections.pod
===
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/PerlSections.pod,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -u -r1.12 -r1.13
--- PerlSections.pod 13 Jul 2004 03:59:46 - 1.12
+++ PerlSections.pod 16 Jul 2004 01:53:20 - 1.13
@@ -13,7 +13,7 @@
#run the server as whoever starts it
$User = getpwuid(>) || >;
- $Group = getgrgid()) || );
+ $Group = getgrgid()) || );
$ServerAdmin = $User;
@@ -110,18 +110,20 @@
-
-=head1 @PerlConfig and $PerlConfig
-This array and scalar can be used to introduce litteral configuration
+
+=head1 C<@PerlConfig> and C<$PerlConfig>
+
+This array and scalar can be used to introduce literal configuration
into the apache configuration. For example:
push @PerlConfig, 'Alias /foo /bar';
Or:
$PerlConfig .= "Alias /foo /bar\n";
-
-See also
Cadd_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
+
+See also
+Cadd_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
@@ -148,15 +150,17 @@
-=head1 PerlSections dumping
+=head1 PerlSections Dumping
+
+
=head2 Apache::PerlSections-Edump
This method will dump out all the configuration variables mod_perl
will be feeding to the apache config gears. The output is suitable to
-read back in via C
+read back in via C.
-Example:
+For example:
@@ -181,7 +185,7 @@
Allow => 'from foo.com',
},
},
- };
+ };
print Apache::PerlSections->dump;
@@ -218,11 +222,19 @@
1;
__END__
+
+
+
+
=head2 Apache::PerlSections-Estore
This method will call the C method, writing the output
to a file, suitable to be pulled in via C or C.
+
+
+
+
=head1 Advanced API
mod_perl 2.0 now introduces the same general concept of handlers to
@@ -234,7 +246,7 @@
$foo = 1;
-$bar = 2;
+$bar = 2;
And in My/PerlSection/Handler.pm:
@@ -246,25 +258,34 @@
So, when that given CPerl E> block in encountered, the code
within will first be evaluated, then the handler routine will be
-invoked with 3 arguments
+invoked with 3 arguments:
+
+=over
+
+=item arg1: C<$self>
+
+self-explanatory
+
+=item arg2: C<$parms>
+( C> )
-C<$self> is self-explanatory
+C<$parms> is specific for the current Container, for example, you
+might want to call C<$parms-Eserver()> to get the current server.
-C<$parms> is the
-C> for this
-Container, for example, you might want to call C<$parms>-Eserver()
-to get the current server.
+=item arg3: C<$args>
+( C>)
-C<$args> is an C> object of
-the section arguments, the 2 guaranteed ones will be:
+the table object of the section arguments. The 2 guaranteed ones will
+be:
$args->{'handler'} = 'My::PerlSection::Handler';
-
- $args->{'package'} = 'Apache::ReadConfig';
+ $args->{'package'} = 'Apache::ReadConfig';
Other C pairs given on the CPerl E> line will
also be included.
+=back
+
At this point, it's up to the handler routing to inspect the namespace
of the C<$args>-E{'package'} and chooses what to do.
@@ -312,9 +333,13 @@
+
+
=head1 See Also
L.
+
+
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api/Apache Process.pod
stas2004/07/16 14:36:52 Modified:src/docs/2.0/api/Apache Process.pod Log: Apache::Process manpage is complete Revision ChangesPath 1.4 +56 -19modperl-docs/src/docs/2.0/api/Apache/Process.pod Index: Process.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Process.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -u -r1.3 -r1.4 --- Process.pod 22 May 2004 02:03:27 - 1.3 +++ Process.pod 16 Jul 2004 21:36:52 - 1.4 @@ -1,6 +1,6 @@ =head1 NAME -Apache::Process - Perl API for XXX +Apache::Process - Perl API for Apache process record @@ -8,15 +8,31 @@ =head1 Synopsis use Apache::Process (); + use Apache::ServerRec (); + my $proc = $s->process; + + # global pool cleared on exit + my $global_pool = $proc->pool; + + # configuration pool cleared on restart + my $pconf = $proc->pconf; + + # short program name (e.g. httpd) + my $proc_name = $proc->short_name; + -META: to be completed =head1 Description -META: to be completed +C provides the API for the Apache process object, +which you can retrieve with +Cprocess|docs::2.0::api::Apache::ServerRec/C_process_>>: + + use Apache::ServerRec (); + $proc = $s->process; @@ -28,49 +44,60 @@ -=head2 C - -META: Autogenerated - needs to be reviewed/completed +=head2 C -Global pool. Cleared upon normal exit +Get configuration pool object. - $p = $proc->pool(); + $p = $proc->pconf(); =over 4 -=item obj: C<$proc> (C>) +=item obj: C<$proc> +( C> ) + +=item ret: C<$p> +( C> ) -=item ret: C<$p> (C>) +=item since: 1.99_15 =back +This pool object gets cleared on server restart. + + -=head2 C -META: Autogenerated - needs to be reviewed/completed +=head2 C -Configuration pool. Cleared upon restart +Get the global pool object. - $p = $proc->pconf($newval); + $p = $proc->pool(); =over 4 -=item obj: C<$proc> (C>) +=item obj: C<$proc> +( C> ) + +=item ret: C<$p> +( C> ) -=item ret: C<$p> (C>) +=item since: 1.99_15 =back +This pool object gets cleared only on (normal) server exit + + -=head2 C -META: Autogenerated - needs to be reviewed/completed + +=head2 C The name of the program used to execute the program @@ -78,11 +105,21 @@ =over 4 -=item obj: C<$proc> (C>) +=item obj: C<$proc> +( C> ) =item ret: C<$short_name> (string) +e.g. C + +=item since: 1.99_15 + =back + + + + + - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/general/testing testing.pod
theory 2004/07/16 14:46:11 Modified:src/docs/general/testing testing.pod Log: Remove empty list item. Revision ChangesPath 1.34 +0 -2 modperl-docs/src/docs/general/testing/testing.pod Index: testing.pod === RCS file: /home/cvs/modperl-docs/src/docs/general/testing/testing.pod,v retrieving revision 1.33 retrieving revision 1.34 diff -u -r1.33 -r1.34 --- testing.pod 1 May 2004 23:53:19 - 1.33 +++ testing.pod 16 Jul 2004 21:46:11 - 1.34 @@ -748,8 +748,6 @@ % t/TEST -proxy -=item * - =back The debugging options I<-debug> and I<-breakpoint> are covered in the - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api/Apache Process.pod SubProcess.pod
stas2004/07/16 15:45:17 Modified:src/docs/2.0/api/Apache Process.pod SubProcess.pod Log: Apache::SubProcess manpage polish Revision ChangesPath 1.5 +1 -1 modperl-docs/src/docs/2.0/api/Apache/Process.pod Index: Process.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Process.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -u -r1.4 -r1.5 --- Process.pod 16 Jul 2004 21:36:52 - 1.4 +++ Process.pod 16 Jul 2004 22:45:17 - 1.5 @@ -29,7 +29,7 @@ C provides the API for the Apache process object, which you can retrieve with -Cprocess|docs::2.0::api::Apache::ServerRec/C_process_>>: +Cprocess|docs::2.0::api::Apache::ServerRec/C_process_>>: use Apache::ServerRec (); $proc = $s->process; 1.4 +43 -14modperl-docs/src/docs/2.0/api/Apache/SubProcess.pod Index: SubProcess.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/SubProcess.pod,v retrieving revision 1.3 retrieving revision 1.4 diff -u -u -r1.3 -r1.4 --- SubProcess.pod22 May 2004 02:03:27 - 1.3 +++ SubProcess.pod16 Jul 2004 22:45:17 - 1.4 @@ -1,6 +1,10 @@ =head1 NAME -Apache::SubProcess -- Executing SubProcesses from mod_perl +Apache::SubProcess -- Executing SubProcesses under mod_perl + + + + =head1 Synopsis @@ -47,6 +51,11 @@ C provides the Perl API for running and communicating with processes spawned from mod_perl handlers. +At the moment it's possible to spawn only external program in a new +process. It's possible to provide other interfaces, e.g. executing a +sub-routine reference (via C) and may be spawn a new +program in a thread (since the APR api includes API for spawning +threads, e.g. that's how it's running mod_cgi on win32). =head1 API @@ -54,18 +63,38 @@ =head2 C - $out_fh = - Apache::SubProcess::spawn_proc_prog($r, $command, [EMAIL PROTECTED]); - ($in_fh, $out_fh, $err_fh) = - Apache::SubProcess::spawn_proc_prog($r, $command, [EMAIL PROTECTED]); +Spawn a sub-process and return STD communication pipes: + + $out_fh= $r->spawn_proc_prog($command); + $out_fh= $r->spawn_proc_prog($command, [EMAIL PROTECTED]); + ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command); + ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command, [EMAIL PROTECTED]); + +=over 4 + +=item obj: C<$r> +( C> ) -spawn_proc_prog() spawns a sub-process which exec()'s C<$command> and -returns the output pipe filehandle in the scalar context, or input, -output and error pipe filehandles in the list context. Using these -three pipes it's possible to communicate with the spawned process. +=item arg1: C<$command> ( string ) -The third optional argument is a reference to an array which if passed -becomes ARGV to the spawned program. +The command to be C<$exec()>'ed. + +=item opt arg2: C<[EMAIL PROTECTED]> ( ARRAY ref ) + +A reference to an array of arguments to be passed to the process as +the process' C. + +=item ret: ... + +In SCALAR context returns the output filehandle of the spawned +process. + +In LIST context returns the input, outpur and error filehandles of the +spawned process. + +=item since: 1.99_15 + +=back It's possible to pass environment variables as well, by calling: @@ -88,10 +117,10 @@ Therefore to write a portable code, you want to use select for perlio-disabled Perl and do nothing for perlio-enabled Perl, hence you -can use something similar to the read_data() wrapper shown in the -L section. - +can use something similar to the C wrapper shown in the +L section. +Several examples appear in the L section. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
cvs commit: modperl-docs/src/docs/2.0/api/Apache SubProcess.pod
stas2004/07/16 15:51:37 Modified:src/docs/2.0/api/Apache SubProcess.pod Log: fix the syntax Revision ChangesPath 1.5 +3 -4 modperl-docs/src/docs/2.0/api/Apache/SubProcess.pod Index: SubProcess.pod === RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/SubProcess.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -u -r1.4 -r1.5 --- SubProcess.pod16 Jul 2004 22:45:17 - 1.4 +++ SubProcess.pod16 Jul 2004 22:51:37 - 1.5 @@ -16,19 +16,18 @@ # pass @ARGV / read from the process $command = "/tmp/argv.pl"; @argv = qw(foo bar); - $out_fh = Apache::SubProcess::spawn_proc_prog($r, $command, [EMAIL PROTECTED]); + $out_fh = $r->spawn_proc_prog($command, [EMAIL PROTECTED]); $output = read_data($out_fh); # pass environment / read from the process $command = "/tmp/env.pl"; $r->subprocess_env->set(foo => "bar"); - $out_fh = Apache::SubProcess::spawn_proc_prog($r, $command); + $out_fh = $r->spawn_proc_prog($command); $output = read_data($out_fh); # write to/read from the process $command = "/tmp/in_out_err.pl"; - ($in_fh, $out_fh, $err_fh) = - Apache::SubProcess::spawn_proc_prog($r, $command); + ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command); print $in_fh "hello\n"; $output = read_data($out_fh); $error = read_data($err_fh); - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
