stas 02/05/11 21:52:34 Modified: src/docs/1.0/api Changes.pod config.cfg src/docs/1.0/api/Apache Constants.pod Include.pod Log.pod Options.pod PerlRun.pod PerlSections.pod Registry.pod RegistryLoader.pod Resource.pod StatINC.pod Status.pod Symbol.pod Symdump.pod Table.pod Added: src/docs/1.0/api/Apache Debug.pod FakeRequest.pod Leak.pod URI.pod Util.pod httpd_conf.pod src.pod Log: add more API files and correct links Submitted by: Per Einar Ellefsen <[EMAIL PROTECTED]> Revision Changes Path 1.4 +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.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- Changes.pod 20 Apr 2002 10:38:50 -0000 1.3 +++ Changes.pod 12 May 2002 04:52:33 -0000 1.4 @@ -9,7 +9,7 @@ The most recent changes are listed first. -=head1 Sat Apr 20 11:41:00 CET 2002 +=head1 ??? Per Einar Ellefsen: @@ -17,6 +17,15 @@ the content, added right tags and indentation where needed. * Apache::File: added synopsis. + +* Added various other modules that were left-over. Some don't have + much documentation, but that doesn't matter, the synopsis is usually + enough. + +* Fixed all module names in "See Also" sections to link to the correct + place if possible. + +* Reorganized everything into groups. =head1 Thu Apr 18 12:28:00 CET 2002 1.6 +36 -6 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.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- config.cfg 21 Apr 2002 07:26:37 -0000 1.5 +++ config.cfg 12 May 2002 04:52:33 -0000 1.6 @@ -13,26 +13,56 @@ bot => 'index_bot.html', }, + + group => 'Access to the Apache API', chapters => [qw( Apache.pod Apache/Constants.pod + Apache/Options.pod Apache/Table.pod Apache/File.pod - Apache/Include.pod Apache/Log.pod + Apache/URI.pod + Apache/Util.pod + Apache/Include.pod + )], + + group => 'Run CGI scripts under mod_perl', + chapters => [qw( Apache/Registry.pod - Apache/RegistryLoader.pod Apache/PerlRun.pod + Apache/RegistryLoader.pod + )], + + group => 'Development/Debugging help', + chapters => [qw( Apache/StatINC.pod Apache/test.pod - Apache/Options.pod + Apache/Symdump.pod + Apache/src.pod + Apache/Leak.pod + Apache/FakeRequest.pod + Apache/Debug.pod + Apache/Symbol.pod + Apache/SIG.pod + )], + + group => 'Apache configuration', + chapters => [qw( Apache/PerlSections.pod + Apache/httpd_conf.pod Apache/Status.pod - Apache/Symbol.pod + )], + + group => 'Server Maintenance', + chapters => [qw( Apache/Resource.pod Apache/SizeLimit.pod - Apache/SIG.pod - Apache/Symdump.pod + )], + + group => 'Miscellaneous', + chapters => [qw( Changes.pod )], ); +1; \ No newline at end of file 1.2 +36 -0 modperl-docs/src/docs/1.0/api/Apache/Constants.pod Index: Constants.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Constants.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Constants.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Constants.pod 12 May 2002 04:52:33 -0000 1.2 @@ -14,6 +14,7 @@ B<httpd.h> and other header files, this module gives Perl access to those constants. + =head1 Export Tags =over 4 @@ -178,6 +179,41 @@ NO_ARGS =back + +=head1 Warnings + +You should be aware of the issues relating to using constant +subroutines in Perl. For example, look at this example: + + $r->custom_response(FORBIDDEN => "File size exceeds quota."); + +This will not set a custom response for C<FORBIDDEN>, but for the +string C<"FORBIDDEN">, which clearly isn't what is expected. You'll +get an error like this: + + [Tue Apr 23 19:46:14 2002] null: Argument "FORBIDDEN" isn't numeric in subroutine entry at ... + +Therefore, you can avoid this by not using the hash notation for +things that don't require it. + + $r->custom_response(FORBIDDEN, "File size exceeds quota."); + +Another important note is that you should be using the correct +constants defined here, and not direct HTTP codes. For example: + + sub handler { + return 200; + } + +Is not correct. The correct use is: + + use Apache::Constants qw(OK); + + sub handler { + return OK; + } + +Also remember that C<OK != HTTP_OK>. =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Include.pod Index: Include.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Include.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Include.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Include.pod 12 May 2002 04:52:33 -0000 1.2 @@ -41,7 +41,7 @@ =head1 See Also -perl(1), mod_perl(3), mod_include +perl, mod_perl, mod_include =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Log.pod Index: Log.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Log.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Log.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Log.pod 12 May 2002 04:52:33 -0000 1.2 @@ -63,6 +63,6 @@ =head1 See Also -mod_perl(3), Apache(3). +mod_perl, L<Apache>. =cut 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Options.pod Index: Options.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Options.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Options.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Options.pod 12 May 2002 04:52:33 -0000 1.2 @@ -52,6 +52,6 @@ =head1 See Also -L<Apache>, L<Apache::Constants|docs::1.0::api::Apache::Constants> +L<Apache>, L<Apache::Constants> =cut 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/PerlRun.pod Index: PerlRun.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/PerlRun.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- PerlRun.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ PerlRun.pod 12 May 2002 04:52:33 -0000 1.2 @@ -48,7 +48,7 @@ =head1 See Also -perl(1), mod_perl(3), Apache::Registry(3) +perl, mod_perl, L<Apache::Registry> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/PerlSections.pod Index: PerlSections.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/PerlSections.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- PerlSections.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ PerlSections.pod 12 May 2002 04:52:33 -0000 1.2 @@ -112,7 +112,7 @@ =head1 See Also -mod_perl(1), Data::Dumper(3), Devel::Symdump(3) +mod_perl, C<Data::Dumper>, C<Devel::Symdump> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Registry.pod Index: Registry.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Registry.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Registry.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Registry.pod 12 May 2002 04:52:33 -0000 1.2 @@ -110,7 +110,7 @@ =head1 See Also -perl(1), mod_perl(3), Apache(3), Apache::Debug(3) +perl, mod_perl, L<Apache>, L<Apache::Debug> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/RegistryLoader.pod Index: RegistryLoader.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/RegistryLoader.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- RegistryLoader.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ RegistryLoader.pod 12 May 2002 04:52:33 -0000 1.2 @@ -98,6 +98,6 @@ =head1 See Also -Apache::Registry(3), Apache(3), mod_perl(3) +L<Apache::Registry>, L<Apache>, mod_perl =cut 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Resource.pod Index: Resource.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Resource.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Resource.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Resource.pod 12 May 2002 04:52:33 -0000 1.2 @@ -69,6 +69,6 @@ =head1 SEE ALSO -BSD::Resource(3), setrlimit(2) +C<BSD::Resource>, C<setrlimit(2)> =cut 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/StatINC.pod Index: StatINC.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/StatINC.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- StatINC.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ StatINC.pod 12 May 2002 04:52:33 -0000 1.2 @@ -70,7 +70,7 @@ =head1 SEE ALSO -mod_perl(3) +mod_perl =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Status.pod Index: Status.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Status.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Status.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Status.pod 12 May 2002 04:52:33 -0000 1.2 @@ -142,7 +142,7 @@ =head1 See Also -perl(1), Apache(3), Devel::Symdump(3), Data::Dumper(3), B(3), B::Graph(3) +perl, L<Apache>, C<Devel::Symdump>, C<Data::Dumper>, C<B>, C<B::Graph> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Symbol.pod Index: Symbol.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Symbol.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Symbol.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Symbol.pod 12 May 2002 04:52:33 -0000 1.2 @@ -94,7 +94,7 @@ =head1 See Also -perlsub(1), Devel::Symdump(3) +perlsub, C<Devel::Symdump> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Symdump.pod Index: Symdump.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Symdump.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Symdump.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Symdump.pod 12 May 2002 04:52:33 -0000 1.2 @@ -28,7 +28,7 @@ =head1 See Also -Devel::Symdump(3), Apache::Leak(3) +C<Devel::Symdump>, L<Apache::Leak> =head1 Maintainers 1.2 +1 -1 modperl-docs/src/docs/1.0/api/Apache/Table.pod Index: Table.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache/Table.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- Table.pod 21 Apr 2002 07:26:37 -0000 1.1 +++ Table.pod 12 May 2002 04:52:33 -0000 1.2 @@ -121,6 +121,6 @@ =head1 See Also -Apache(3), mod_perl(3) +L<Apache>, mod_perl =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/Debug.pod Index: Debug.pod =================================================================== =head1 NAME Apache::Debug - Utilities for debugging embedded perl code =head1 Synopsis use Apache::Debug (); Apache::Debug::dump($r, SERVER_ERROR, "Uh Oh!"); =head1 Description This module sends what may be helpful debugging info to the client rather that the error log. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. The L<mod_perl docs list|maillist::list-docs-dev>. =head1 Authors =over =item * Rob Hartill =back Only the major authors are listed above. For contributors see the Changes file. =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/FakeRequest.pod Index: FakeRequest.pod =================================================================== =head1 NAME Apache::FakeRequest - fake request object for debugging =head1 Synopsis use Apache::FakeRequest; my $request = Apache::FakeRequest->new(method_name => 'value', ...); =head1 Description C<Apache::FakeRequest> is used to set up an empty Apache request object that can be used for debugging. The C<Apache::FakeRequest> methods just set internal variables of the same name as the method and return the value of the internal variables. Initial values for methods can be specified when the object is created. The C<print> method prints to STDOUT. Subroutines for Apache constants are also defined so that using C<Apache::Constants> while debugging works, although the values of the constants are hard-coded rather than extracted from the Apache source code. #!/usr/bin/perl use Apache::FakeRequest (); use mymodule (); my $request = Apache::FakeRequest->new('get_remote_host'=>'foobar.com'); mymodule::handler($request); =head1 Authors Doug MacEachern, with contributions from Andrew Ford E<lt>[EMAIL PROTECTED]<gt>. =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/Leak.pod Index: Leak.pod =================================================================== =head1 NAME Apache::Leak - Module for tracking memory leaks in mod_perl code =head1 Synopsis use Apache::Leak; leak_test { my $obj = Foo->new; $obj->thingy; }; #now look in error_log for results =head1 Description C<Apache::Leak> is a module built to track memory leaks in mod_perl code. =head1 See Also C<Devel::Leak> =head1 Author Doug MacEachern Leak.xs was derived from Nick Ing-Simmons' Devel::Leak =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/URI.pod Index: URI.pod =================================================================== =head1 NAME Apache::URI - URI component parsing and unparsing =head1 Synopsis use Apache::URI (); my $uri = $r->parsed_uri; my $uri = Apache::URI->parse($r, "http://perl.apache.org/"); =head1 Description This module provides an interface to the Apache I<util_uri> module and the I<uri_components> structure. =head1 Methods =over 4 =item Apache::parsed_uri Apache will have already parsed the requested uri components, which can be obtained via the I<parsed_uri> method defined in the I<Apache> class. This method returns an object blessed into the I<Apache::URI> class. my $uri = $r->parsed_uri; =item parse This method will parse a URI string into uri components which are stashed in the I<Apache::URI> object it returns. my $uri = Apache::URI->parse($r, "http://www.foo.com/path/file.html?query+string"); This method is considerably faster than using I<URI::URL>: timethese(5000, { C => sub { Apache::URI->parse($r, $test_uri) }, Perl => sub { URI::URL->new($test_uri) }, }); Benchmark: timing 5000 iterations of C, Perl... C: 1 secs ( 0.62 usr 0.04 sys = 0.66 cpu) Perl: 6 secs ( 6.21 usr 0.08 sys = 6.29 cpu) =item unparse This method will join the uri components back into a string version. my $string = $uri->unparse; =item scheme my $scheme = $uri->scheme; =item hostinfo my $hostinfo = $uri->hostinfo; =item user my $user = $uri->user; =item password my $password = $uri->password; =item hostname my $hostname = $uri->hostname; =item port my $port = $uri->port; =item path my $path = $uri->path; =item rpath Returns the I<path> minus I<path_info>. my $path = $uri->rpath; =item query my $query = $uri->query; =item fragment my $fragment = $uri->fragment; =back =head1 Author Doug MacEachern =head1 See Also perl. =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/Util.pod Index: Util.pod =================================================================== =head1 NAME Apache::Util - Interface to Apache C util functions =head1 Synopsis use Apache::Util qw(:all); =head1 Description This module provides a Perl interface to some of the C utility functions available in Apache. The same functionality is avaliable in libwww-perl, but the C versions are faster: use Benchmark; timethese(1000, { C => sub { my $esc = Apache::Util::escape_html($html) }, Perl => sub { my $esc = HTML::Entities::encode($html) }, }); Benchmark: timing 1000 iterations of C, Perl... C: 0 secs ( 0.17 usr 0.00 sys = 0.17 cpu) Perl: 15 secs (15.06 usr 0.04 sys = 15.10 cpu) use Benchmark; timethese(10000, { C => sub { my $esc = Apache::Util::escape_uri($uri) }, Perl => sub { my $esc = URI::Escape::uri_escape($uri) }, }); Benchmark: timing 10000 iterations of C, Perl... C: 0 secs ( 0.55 usr 0.01 sys = 0.56 cpu) Perl: 2 secs ( 1.78 usr 0.01 sys = 1.79 cpu) =head1 Functions =over 4 =item escape_html This routine replaces unsafe characters in $string with their entity representation. my $esc = Apache::Util::escape_html($html); This function will correctly escape US-ASCII output. If you are using a different character set such as UTF8, or need more control on the escaping process, use HTML::Entities. =item escape_uri This function replaces all unsafe characters in the $string with their escape sequence and returns the result. my $esc = Apache::Util::escape_uri($uri); =item unescape_uri This function decodes all %XX hex escape sequences in the given URI. my $unescaped = Apache::Util::unescape_uri($safe_uri); =item unescape_uri_info This function is similar to unescape_uri() but is specialized to remove escape sequences from the query string portion of the URI. The main difference is that it translates the ``+'' character into spaces as well as recognizing and translating the hex escapes. Example: $string = $r->uri->query; my %data = map { Apache::Util::unescape_uri_info($_) } split /[=&]/, $string, -1; This would correctly translate the query string ``name=Fred+Flintstone&town=Bedrock'' into the hash: data => 'Fred Flintstone', town => 'Bedrock' =item parsedate Parses an HTTP date in one of three standard forms: Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format Example: my $secs = Apache::Util::parsedate($date_str); =item ht_time Format a time string. Examples: my $str = Apache::Util::ht_time(time); my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z"); my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z", 0); =item size_string Converts the given file size into a formatted string. The size given in the string will be in units of bytes, kilobytes, or megabytes, depending on the size. my $size = Apache::Util::size_string -s $r->finfo; =item validate_password Validate a plaintext password against a smashed one. Use either crypt() (if available), ap_MD5Encode() or ap_SHA1Encode depending upon the format of the smashed input password. Returns true if they match, false otherwise. if (Apache::Util::validate_password("slipknot", "aXYx4GnaCrDQc")) { print "password match\n"; } else { print "password mismatch\n"; } =back =head1 Author Doug MacEachern =head1 See Also perl. =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/httpd_conf.pod Index: httpd_conf.pod =================================================================== =head1 NAME Apache::httpd_conf - Generate an httpd.conf file =head1 Synopsis use Apache::httpd_conf (); Apache::httpd_conf->write(Port => 8888); =head1 Description The Apache::httpd_conf module will generate a tiny httpd.conf file, which pulls itself back in via a C<E<lt>PerlE<gt>> section. Any additional arguments passed to the C<write> method will be added to the generated httpd.conf file, and will override those defaults set in the C<E<lt>PerlE<gt>> section. This module is handy mostly for starting httpd servers to test mod_perl scripts and modules. =head1 Author Doug MacEachern =head1 See Also mod_perl, L<Apache::PerlSections> =cut 1.1 modperl-docs/src/docs/1.0/api/Apache/src.pod Index: src.pod =================================================================== =head1 NAME Apache::src - Methods for locating and parsing bits of Apache source code =head1 Synopsis use Apache::src (); my $src = Apache::src->new; =head1 Description This module provides methods for locating and parsing bits of Apache source code. =head1 Methods =over 4 =item new Create an object blessed into the B<Apache::src> class. my $src = Apache::src->new; =item dir Top level directory where source files are located. my $dir = $src->dir; -d $dir or die "can't stat $dir $!\n"; =item main Apache's source tree was reorganized during development of version 1.3. So, common header files such as C<httpd.h> are in different directories between versions less than 1.3 and those equal to or greater. This method will return the right directory. Example: -e join "/", $src->main, "httpd.h" or die "can't stat httpd.h\n"; =item find Searches for apache source directories, return a list of those found. Example: for my $dir ($src->find) { my $yn = prompt "Configure with $dir ?", "y"; ... } =item inc Print include paths for MakeMaker's B<INC> argument to C<WriteMakefile>. Example: use ExtUtils::MakeMaker; use Apache::src (); WriteMakefile( 'NAME' => 'Apache::Module', 'VERSION' => '0.01', 'INC' => Apache::src->new->inc, ); =item module_magic_number Return the B<MODULE_MAGIC_NUMBER> defined in the apache source. Example: my $mmn = $src->module_magic_number; =item httpd_version Return the server version. Example: my $v = $src->httpd_version; =item otherldflags Return other ld flags for MakeMaker's B<dynamic_lib> argument to C<WriteMakefile>. This might be needed on systems like AIX that need special flags to the linker to be able to reference mod_perl or httpd symbols. Example: use ExtUtils::MakeMaker; use Apache::src (); WriteMakefile( 'NAME' => 'Apache::Module', 'VERSION' => '0.01', 'INC' => Apache::src->new->inc, 'dynamic_lib' => { 'OTHERLDFLAGS' => Apache::src->new->otherldflags, }, ); =back =head1 Author Doug MacEachern =cut
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]