This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Algorithm/Numerical/Shuffle, Next: Algorithm/Permute, Prev: Algorithm/Numerical/Sample, Up: Module List Shuffle a list. *************** NAME ==== Algorithm::Numerical::Shuffle - Shuffle a list. SYNOPSIS ======== use Algorithm::Numerical::Shuffle qw /shuffle/; @shuffled = shuffle (1, 2, 3, 4, 5, 6, 7); $in_situ = [qw /one two three four five six/]; shuffle $in_situ; DESCRIPTION =========== shuffle performs a one pass, fair shuffle on a list. If the list is passed as a reference to an array, the shuffle is done in situ. The subroutine returns the list in list context, and a reference to the list in scalar context. COMPLEXITY ========== The running time of the algorithm is linear in the size of the list. For an in situ shuffle, the memory overhead is constant; otherwise, linear extra memory is used. LITERATURE ========== The algorithm used is discussed by Knuth [3]. It was first published by Fisher and Yates [2], and later by Durstenfeld [1]. CAVEAT ====== Salfi [4] points to a big caveat. If the outcome of a random generator is solely based on the value of the previous outcome, like a linear congruential method, then the outcome of a shuffle depends on exactly three things: the shuffling algorithm, the input and the seed of the random generator. Hence, for a given list and a given algorithm, the outcome of the shuffle is purely based on the seed. Many modern computers have 32 bit random numbers, hence a 32 bit seed. Hence, there are at most 2^32 possible shuffles of a list, foreach of the possible algorithms. But for a list of n elements, there are n! possible permutations. Which means that a shuffle of a list of 13 elements will not generate certain permutations, as 13! > 2^32. REFERENCES ========== [1] R. Durstenfeld: *CACM*, 7, 1964. pp 420. [2] R. A. Fisher and F. Yates: *Statistical Tables*. London, 1938. Example 12. [3] D. E. Knuth: *The Art of Computer Programming*, Volume 2, Third edition. Section 3.4.2, Algorithm P, pp 145. Reading: Addison-Wesley, 1997. ISBN: 0-201-89684-2. [4] R. Salfi: *COMPSTAT 1974*. Vienna: 1974, pp 28 - 35. HISTORY ======= $Date: 2000/03/08 05:57:40 $ $Log: Shuffle.pm,v $ Revision 1.4 2000/03/08 05:57:40 abigail Fixed bug that prevented in situ shuffling. Changed the wording of the license once again. (MIT/X style) Revision 1.3 1999/03/01 20:54:06 abigail Changed package name to Algorithm::* Changed license. Revision 1.2 1998/09/09 20:48:12 abigail - Make shuffle() work with empty lists. - Changed license to Artistic only. Revision 1.1 1998/04/23 17:58:07 abigail Initial revision AUTHOR ====== This package was written by Abigail. COPYRIGHT ========= Copyright 1998, 1999, 2000 by Abigail. LICENSE ======= This program is copyright 1998-2000 by Abigail. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  File: pm.info, Node: Algorithm/Permute, Next: Algorithm/SISort, Prev: Algorithm/Numerical/Shuffle, Up: Module List Handy and fast permutation with object oriented interface ********************************************************* NAME ==== Algorithm::Permute - Handy and fast permutation with object oriented interface SYNOPSIS ======== use Algorithm::Permute; $p = new Algorithm::Permute(['a'..'d']); while (@res = $p->next) { print join(", ", @res), "\n"; } DESCRIPTION =========== This handy module makes performing permutation in Perl easy and fast, although perhaps its algorithm is not the fastest on the earth. Currently it only supports permutation n of n objects. No exported functions. This version is not backward compatible with the previous one, version 0.01. The old interface is no longer supported. METHODS ======= new [@list] Returns a permutor object for the given items. next Returns a list of the items in the next permutation. The order of the resulting permutation is the same as of the previous version of `Algorithm::Permute'. peek Returns the list of items which *will be returned* by next(), but *doesn't advance the sequence*. Could be useful if you wished to skip over just a few unwanted permutations. reset Resets the iterator to the start. May be used at any time, whether the entire set has been produced or not. Has no useful return value. COMPARISON ========== I've collected some Perl routines and modules which implement permutation, and do some simple benchmark. The result, which is of course predictable, and obvious, is the following. Permutation of *eight* scalars: Abigail's: 14 wallclock secs (13.21 usr + 0.49 sys = 13.70 CPU) Algorithm::Permute: 3 wallclock secs ( 2.96 usr + 0.02 sys = 2.98 CPU) List::Permutor: 9 wallclock secs ( 8.98 usr + 0.02 sys = 9.00 CPU) MJD's: 56 wallclock secs (55.54 usr + 0.18 sys = 55.72 CPU) perlfaq4: 65 wallclock secs (64.71 usr + 0.22 sys = 64.93 CPU) Permutation of *nine* scalars (the Abigail's routine is commented out, because it stores all of the result in memory, swallows all of my machine's memory): Algorithm::Permute: 14 wallclock secs (14.13 usr + 0.07 sys = 14.20 CPU) List::Permutor: 67 wallclock secs (65.78 usr + 0.47 sys = 66.25 CPU) MJD's: 530 wallclock secs (516.57 usr + 2.10 sys = 518.67 CPU) perlfaq4: 498 wallclock secs (490.49 usr + 1.65 sys = 492.14 CPU) The benchmark script is included in the bench directory. I understand that speed is not everything. So here is the list of URLs of the alternatives, in case you hate this module. * Mark Jason Dominus' technique is discussed in chapter 4 Perl Cookbook, so you can get it from O'Reilly: ftp://ftp.oreilly.com/published/oreilly/perl/cookbook * Abigail's: http://www.foad.org/~abigail/Perl * List::Permutor: http://www.cpan.org/modules/by-module/List * The classic way, usually used by Lisp hackers: perldoc perlfaq4 HISTORY ======= * September 2, 2000 - version 0.02. Major interface changes, now using object oriented interface similar to `List::Permutor''s. More efficient memory usage. Internal tweaking gives speed improvement - the list elements are no longer swapped, but only the indexes. * October 3, 1999 - Alpha release, version 0.01 AUTHOR ====== Edwin Pratomo, *ed.pratomo@computer.org*. The object oriented interface is taken from Tom Phoenix's `List::Permutor'. ACKNOWLEDGEMENT =============== Yustina Sri Suharini - my fiance, for providing the permutation problem to me. SEE ALSO ======== * *Data Structures, Algorithms, and Program Style Using C* - Korsh and Garrett * *Algorithms from P to NP, Vol. I* - Moret and Shapiro  File: pm.info, Node: Algorithm/SISort, Next: Alias, Prev: Algorithm/Permute, Up: Module List Implementation of Select And Insert sorting algorithm in C ********************************************************** NAME ==== Algorithm::SISort - Implementation of Select And Insert sorting algorithm in C SYNOPSIS ======== use Algorithm::SISort qw(Sort Sort_inplace); @sorted_list = Sort {$_[0] <=> $_[1]} @unsorted_list; # ... or ... Sort_inplace {$_[0] <=> $_[1]} @unsorted_list; DESCRIPTION =========== This module implements a sorting algorithm I saw in BIT 28 (1988) by István Beck and Stein Krogdahl. This implmentation is mainly intended to try out the Inline module by Brian Ingerson. The algorithim is a combination of *Straight Insertion Sort* and *Selection Sort*. While *Insertion Sort* and *Selection Sort* both are of complexity O(n**2), *Select and Insert Sort* should have complexitiy O(n**1.5). This module defines the functions Sort and `Sort_inplace', which have signatures similar to the internal sort function. The difference is that a codref defining a comparison is always required and that the two values to compare are always passed in `@_' and not as `$a' and $b. (Although I might change that later.) Sort returns a sorted copy if the array, but `Sort_inplace' sorts the array in place (as the name suggests) and returns the number of comparisons done. (Note that the sorting is always done in place, Sort just copies the array before calling the internal sort routine.) BUGS ==== This is the first serious (i.e. not "Hello World") C-extension I've done, so I suspect I've screwed around with the refcounts of the list entries. Until I've confirmed that there are no memory leaks, I caution people not to use this piece of code in any production system. Any bug-reports, comments and patches are very welcome at my email address below. SEE ALSO ======== *Note Inline: Inline,, *Note Inline/C: Inline/C,, and *A Select And Insert Sorting Algorithm* by István Beck and Stein Krogdahl in *BIT 28 (1988), 726-735*. AUTHOR ====== Hrafnkell F. Hlodversson, keli@shebang.dk COPYRIGHT ========= Copyright 2001, Hrafnkell F Hlodversson All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License. See http://www.perl.com/perl/misc/Artistic.html  File: pm.info, Node: Alias, Next: AltaVista/SearchSDK, Prev: Algorithm/SISort, Up: Module List declare symbolic aliases for perl data ************************************** NAME ==== alias - declare symbolic aliases for perl data attr - auto-declare hash attributes for convenient access const - define compile-time scalar constants SYNOPSIS ======== use Alias qw(alias const attr); alias TEN => $ten, Ten => \$ten, Ten => \&ten, Ten => \@ten, Ten => \%ten, TeN => \*ten; { local @Ten; my $ten = [1..10]; alias Ten => $ten; # local @Ten } const pi => 3.14, ten => 10; package Foo; use Alias; sub new { bless {foo => 1, _bar => [2, 3]}, $_[0] } sub a_method { my $s = attr shift; # $foo, @_bar are now local aliases for # $_[0]{foo}, @{$_[0]{_bar}} etc. } sub b_method { local $Alias::KeyFilter = "_"; local $Alias::AttrPrefix = "main::"; my $s = attr shift; # local @::_bar is now available, ($foo, $::foo are not) } sub c_method { local $Alias::KeyFilter = sub { $_ = shift; return (/^_/ ? 1 : 0) }; local $Alias::AttrPrefix = sub { $_ = shift; s/^_(.+)$/main::$1/; return $_ }; my $s = attr shift; # local @::bar is now available, ($foo, $::foo are not) } DESCRIPTION =========== Provides general mechanisms for aliasing perl data for convenient access. This module works by putting some values on the symbol table with user-supplied names. Values that are references will get dereferenced into their base types. This means that a value of `[1,2,3]' with a name of "foo" will be made available as `@foo', not `$foo'. The exception to this rule is the default behavior of the attr function, which will not dereference values which are blessed references (aka objects). See `$Alias::Deref' in this node for how to change this default behavior. Functions --------- alias Given a list of name => value pairs, declares aliases in the callers namespace. If the value supplied is a reference, the alias is created for the underlying value instead of the reference itself (there is no need to use this module to alias references-they are automatically "aliased" on assignment). This allows the user to alias most of the basic types. If the value supplied is a scalar compile-time constant, the aliases become read-only. Any attempt to write to them will fail with a run time error. Aliases can be dynamically scoped by pre-declaring the target variable as local. Using attr for this purpose is more convenient, and recommended. attr Given a hash reference, aliases the values of the hash to the names that correspond to the keys. It always returns the supplied value. The aliases are local to the enclosing block. If any of the values are unblessed references, they are available as their dereferenced types. Thus the action is similar to saying: alias %{$_[0]} but, in addition, also localizes the aliases, and does not dereference objects. Dereferencing of objects can be forced by setting the `Deref' option. See `$Alias::Deref' in this node. This can be used for convenient access to hash values and hash-based object attributes. Note that this makes available the semantics of local subroutines and methods. That makes for some nifty possibilities. We could make truly private methods by putting anonymous subs within an object. These subs would be available within methods where we use attr, and will not be visible to the outside world as normal methods. We could forbid recursion in methods by always putting an empty sub in the object hash with the same key as the method name. This would be useful where a method has to run code from other modules, but cannot be certain whether that module will call it back again. The default behavior is to create aliases for all the entries in the hash, in the callers namespace. This can be controlled by setting a few options. See `Configuration Variables' in this node for details. const This is simply a function alias for alias, described above. Provided on demand at use time, since it reads better for constant declarations. Note that hashes and arrays cannot be so constrained. Configuration Variables ----------------------- The following configuration variables can be used to control the behavior of the attr function. They are typically set after the `use Alias;' statement. Another typical usage is to localize them in a block so that their values are only effective within that block. $Alias::KeyFilter Specifies the key prefix used for determining which hash entries will be interned by attr. Can be a CODE reference, in which case it will be called with the key, and the boolean return value will determine if that hash entry is a candidate attribute. $Alias::AttrPrefix Specifies a prefix to prepend to the names of localized attributes created by attr. Can be a CODE reference, in which case it will be called with the key, and the result will determine the full name of the attribute. The value can have embedded package delimiters ("::" or "'"), which cause the attributes to be interned in that namespace instead of the callers own namespace. For example, setting it to "main::" makes `use strict 'vars';' somewhat more palatable (since we can refer to the attributes as `$::foo', etc., without actually declaring the attributes). $Alias::Deref Controls the implicit dereferencing behavior of attr. If it is set to "" or 0, attr will not dereference blessed references. If it is a true value (anything but "", 0, or a CODE reference), all references will be made available as their dereferenced types, including values that may be objects. The default is "". This option can be used as a filter if it is set to a CODE reference, in which case it will be called with the key and the value (whenever the value happens to be a reference), and the boolean return value will determine if that particular reference must be dereferenced. Exports ------- alias attr EXAMPLES ======== Run these code snippets and observe the results to become more familiar with the features of this module. use Alias qw(alias const attr); $ten = 10; alias TEN => $ten, Ten => \$ten, Ten => \&ten, Ten => \@ten, Ten => \%ten; alias TeN => \*ten; # same as *TeN = *ten # aliasing basic types $ten = 20; print "$TEN|$Ten|$ten\n"; # should print "20|20|20" sub ten { print "10\n"; } @ten = (1..10); %ten = (a..j); &Ten; # should print "10" print @Ten, "|", %Ten, "\n"; # this will fail at run time const _TEN_ => 10; eval { $_TEN_ = 20 }; print $@ if $@; # dynamically scoped aliases @DYNAMIC = qw(m n o); { my $tmp = [ qw(a b c d) ]; local @DYNAMIC; alias DYNAMIC => $tmp, PERM => $tmp; $DYNAMIC[2] = 'zzz'; # prints "abzzzd|abzzzd|abzzzd" print @$tmp, "|", @DYNAMIC, "|", @PERM, "\n"; @DYNAMIC = qw(p q r); # prints "pqr|pqr|pqr" print @$tmp, "|", @DYNAMIC, "|", @PERM, "\n"; } # prints "mno|pqr" print @DYNAMIC, "|", @PERM, "\n"; # named closures my($lex) = 'abcd'; $closure = sub { print $lex, "\n" }; alias NAMEDCLOSURE => \&$closure; NAMEDCLOSURE(); # prints "abcd" $lex = 'pqrs'; NAMEDCLOSURE(); # prints "pqrs" # hash/object attributes package Foo; use Alias; sub new { bless { foo => 1, bar => [2,3], buz => { a => 4}, privmeth => sub { "private" }, easymeth => sub { die "to recurse or to die, is the question" }, }, $_[0]; } sub easymeth { my $s = attr shift; # localizes $foo, @bar, %buz etc with values eval { $s->easymeth }; # should fail print $@ if $@; # prints "1|2|3|a|4|private|" print join '|', $foo, @bar, %buz, $s->privmeth, "\n"; } $foo = 6; @bar = (7,8); %buz = (b => 9); Foo->new->easymeth; # this will not recurse endlessly # prints "6|7|8|b|9|" print join '|', $foo, @bar, %buz, "\n"; # this should fail at run-time eval { Foo->new->privmeth }; print $@ if $@; NOTES ===== It is worth repeating that the aliases created by alias and const will be created in the callers namespace (we can use the `AttrPrefix' option to specify a different namespace for attr). If that namespace happens to be localized, the aliases created will be local to that block. attr localizes the aliases for us. Remember that references will be available as their dereferenced types. Aliases cannot be lexical, since, by neccessity, they live on the symbol table. Lexicals can be aliased. Note that this provides a means of reversing the action of anonymous type generators \, [] and `{}'. This allows us to anonymously construct data or code and give it a symbol-table presence when we choose. Any occurrence of `::' or `'' in names will be treated as package qualifiers, and the value will be interned in that namespace. Remember that aliases are very much like references, only we don't have to dereference them as often. Which means we won't have to pound on the dollars so much. We can dynamically make subroutines and named closures with this scheme. It is possible to alias packages, but that might be construed as abuse. Using this module will dramatically reduce noise characters in object-oriented perl code. BUGS ==== `use strict 'vars';' is not very usable, since we depend so much on the symbol table. You can declare the attributes with `use vars' to avoid warnings. Setting $Alias::AttrPrefix to "main::" is one way to avoid `use vars' and frustration. Tied variables cannot be aliased properly, yet. VERSION ======= Version 2.32 30 Apr 1999 AUTHOR ====== Gurusamy Sarathy gsar@umich.edu Copyright (c) 1995-99 Gurusamy Sarathy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1)  File: pm.info, Node: AltaVista/SearchSDK, Next: AnyDBM_File, Prev: Alias, Up: Module List Perl extension for AltaVista Search Software Development Kit ************************************************************ NAME ==== AltaVista::SearchSDK - Perl extension for AltaVista Search Software Development Kit SYNOPSIS ======== use AltaVista::SearchSDK; avs_adddate(idx, yr, mo, da, startloc) avs_addfield(idx, pFname, startloc, endloc) avs_addliteral(idx, pWord, loc) avs_addvalue(idx, valtype, value, loc) avs_addword(idx, pWords, loc, pNumWords) avs_buildmode(idx) avs_buildmode_ex(idx, ntiers) avs_close(idx) avs_compact(idx, bMore_p) avs_compactionneeded(idx) avs_compact_minor(idx, bMore_p) avs_count(idx, pWordPrefix, pCountsHdl) avs_count_close(CountsHdl) avs_count_getcount(CountsHdl) avs_countnext(CountsHdl) avs_count_getword(CountsHdl) avs_default_options(pOptions) avs_define_valtype(name, minval, maxval, valtype_p) avs_deletedocid(idx, pDocId, pCount) avs_enddoc(idx) avs_errmsg(code) avs_getindexmode(idx) avs_getindexversion(idx) avs_getindexversion_counts_v(countsHdl) avs_getindexversion_search_v(searchHdl) avs_getsearchresults(searchHdl, resultNum) avs_getsearchterms(psearchHdl, termNum, term, count) avs_lookup_valtype(name) avs_makestable(idx) avs_open(path, mode, pIdx) avs_querymode(idx) avs_release_valtypes() avs_search(idx, pQuery, pBoolQuery, pOptions, pDocsFound, pDocsReturned, pTermCount, pSearchHdl) avs_search_close(pSearchHdl) avs_search_ex(idx, pQuery, pBoolQuery, pOptions, searchsince, pDocsFound, pDocsReturned, pTermCount, pSearchHdl) avs_search_genrank(idx, pBoolQuery, pRankTerms, pRankSetup, pOptions, searchsince, pDocsFound, pDocsReturned, pSearchHdl) avs_search_getdata(searchHdl) avs_search_getdatalen(searchHdl) avs_search_getdate(psearchHdl, year, month, day) avs_search_getdocid(searchHdl) avs_search_getdocidlen(searchHdl) avs_search_getrelevance(psearchHdl) avs_setdocdata(idx, pDocData, len) avs_setdocdate(idx, year, month, day) avs_setdocdatetime(idx, year, month, day, hour, minute, second) avs_setparseflags(idx, parseflags) avs_setrankval(idx, valtype, value) avs_startdoc(idx, pDocId, flags, pStartLoc) avs_timer(current) avs_version() avs_create_options(limit, timeout, flags) DESCRIPTION =========== This set of extensions provides wrappers for all the C functionality of the AltaVista Search software development kit (SDK) except for a few functions that did not make sense to export to perl. All the functions of the 97 Rev B kit are available as advertised, except for the following: avs_add_ms_callback UNIMPLEMENTED It makes no sense to implement this function, since it would require being able to pass a C function handle through perl. avs_addrankterms UNIMPLEMENTED Internal function avs_newdoc UNIMPLEMENTED No easy way to provide filter function avs_search_getdata_copy UNIMPLEMENTED No need for this function avs_search_getdocid_copy UNIMPLEMENTED No need for this function avs_search_getrelevance RETURN ARGUMENT Relevance is returned as a string representation of the float PREREQUITES =========== Perl 5.004, the AltaVista SearchSDK 97 Rev B INSTALLATION ============ To install this module, move into the directory where this file is located. First copy avs.h and libavs97b.a from your AltaVista SearchSDK source hierarchy into this directory. Then type the following: perl Makefile.PL make make test make install This will install the module into the Perl library directory. AUTHOR ====== James M. Turner Copything (C) 1998 The Christian Science Publishing Society. All rights reserved This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), AltaVista Search SDK documentation. BUGS ==== This beta version has been tested in a live environment for certain conditions, but has by no means been extensively tested. In particular, it has not been tested on anything but Solaris 2.5 on an Ultra. Please let me know if you get it work under other platforms or operating systems.  File: pm.info, Node: AnyDBM_File, Next: AnyLoader, Prev: AltaVista/SearchSDK, Up: Module List provide framework for multiple DBMs *********************************** NAME ==== AnyDBM_File - provide framework for multiple DBMs NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File - various DBM implementations SYNOPSIS ======== use AnyDBM_File; DESCRIPTION =========== This module is a "pure virtual base class"-it has nothing of its own. It's just there to inherit from one of the various DBM packages. It prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See *Note DB_File: DB_File,), GDBM, SDBM (which is always there-it comes with Perl), and finally ODBM. This way old programs that used to use NDBM via dbmopen() can still do so, but new ones can reorder @ISA: BEGIN { @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File) } use AnyDBM_File; Having multiple DBM implementations makes it trivial to copy database formats: use POSIX; use NDBM_File; use DB_File; tie %newhash, 'DB_File', $new_filename, O_CREAT|O_RDWR; tie %oldhash, 'NDBM_File', $old_filename, 1, 0; %newhash = %oldhash; DBM Comparisons --------------- Here's a partial table of features the different packages offer: odbm ndbm sdbm gdbm bsd-db ---- ---- ---- ---- ------ Linkage comes w/ perl yes yes yes yes yes Src comes w/ perl no no yes no no Comes w/ many unix os yes yes[0] no no no Builds ok on !unix ? ? yes yes ? Code Size ? ? small big big Database Size ? ? small big? ok[1] Speed ? ? slow ok fast FTPable no no yes yes yes Easy to build N/A N/A yes yes ok[2] Size limits 1k 4k 1k[3] none none Byte-order independent no no no no yes Licensing restrictions ? ? no yes no [0] on mixed universe machines, may be in the bsd compat library, which is often shunned. [1] Can be trimmed if you compile for one access method. [2] See *Note DB_File: DB_File,. Requires symbolic links. [3] By default, but can be redefined. SEE ALSO ======== dbm(3), ndbm(3), DB_File(3), *Note Perldbmfilter: (perl.info)perldbmfilter,  File: pm.info, Node: AnyLoader, Next: Ao, Prev: AnyDBM_File, Up: Module List Automagically loads modules for fully qualified functions ********************************************************* NAME ==== AnyLoader - Automagically loads modules for fully qualified functions SYNOPSIS ======== use AnyLoader; Carp::croak("This is going to hurt the Perl community more than it ". "is going to hurt you!"); DESCRIPTION =========== AnyLoader will automagically load the module and import the function for any fully qualified function call. Essentially, this means you can just call functions without worrying about loading the module first. In the example above, AnyLoader does the equivalent of "require Carp" before the call to Carp::carp(). This should be useful for the many cases where one does: if($error) { require Carp; Carp::croak($error); } to avoid loading Carp at startup. AnyLoader is package scoped. Restricting what gets loaded. ----------------------------- You might not want to let *every* package be AnyLoaded, so ways of qualifying what gets loaded are provided. A list of modules can be given to `use AnyLoader' and only those modules will be AnyLoaded. use AnyLoader qw(Data::Dumper Carp); Data::Dumper::Dumper($foo); # This works. LWP::Simple::get($url); # This doesn't. If you wish to shut off AnyLoader, `no AnyLoader' will do so for the current package. `no AnyLoader' also takes a list of modules. These modules are those which are specifically not to be loaded. # AnyLoad anything but LWP and URI::URL. no AnyLoader qw(LWP URI::URL); The lists and effects are cumulative and package scoped (*not lexical*). BUGS and CAVEATS ================ The effects should really be lexically scoped, but I don't think I can pull that off. This module requires on the "Use of inherited AUTOLOAD for non-method" deprecated feature. $SIG{__WARN__} had to be used to suppress a warning about the deprecated feature. Defines UNIVERSAL::AUTOLOAD which may interfere with other modules. Despite what you'd think, AnyLoader *will* work with modules which employ an autoloader. AUTHORS ======= Arnar M. Hrafnkelsson and Michael G Schwern LICENSE ======= Copyright (c) 2000 Arnar M. Hrafnkelsson and Michael G Schwern. All Rights Reserved. You may distribute under the same license as Perl itself. SEE ALSO ======== *Note Autouse: autouse,  File: pm.info, Node: Ao, Next: Apache, Prev: AnyLoader, Up: Module List Perl extension for ao cross-platform audio library ************************************************** NAME ==== Ao - Perl extension for ao cross-platform audio library SYNOPSIS ======== use Ao; $ao_id1 = Ao::get_driver_id('oss'); %ao_info = %{Ao::get_driver_info($ao_id1)}; $ao_endian = Ao::is_big_endian(); $ao_dev1 = Ao::open($ao_id); Ao::play($ao_dev1, $buffer, $len); Ao::close($ao_dev1); $ao_id2 = Ao::get_driver_id('wav'); %ao_options = ('file' => 'out.wav'); $ao_dev2 = Ao::open($ao_id2, 16, 44100, 2, %ao_options); $ao_dev2->play($buffer, $len); $ao_dev2->close(); DESCRIPTION =========== This is a simple object-oriented wrapper around the ao audio library. Use Ao::get_driver_id to obtain an integer id from a short driver name. Currently supported drivers are oss, irix, solaris, esd, alsa and wav. A small hash of driver info (with fields name, short_name, author and comments) can be obtained with Ao::get_driver_info. Ao::is_big_endian can be used to test the byte-order of the machine. Open a device with Ao::open($driver_id, $bits_per_sample, $rate, $channels, %options) where the default values are 16 bits at 44100 Hz stereo, and no options. options is a hash of named parameters to pass to the specific driver. The wav driver defaults to writing output to the file output.wav - you can change this by passing the file option. Other options can be found in the ao documentation. Play to a device with Ao::play($device, $buffer, $len) where $device is the device returned from Ao::open, $buffer is a pointer to a buffer of sound input, and $len is the length of the buffered sound to play. To obtain sound input you will need to use a separate module such as Ogg::Vorbis. When you are done, close the device with Ao::close($device). Exported constants ================== AO_ALSA AO_BEOS AO_DRIVERS AO_ESD AO_IRIX AO_NULL AO_OSS AO_RAW AO_SOLARIS AO_WAV AO_WIN32 AUTHOR ====== Alex Shinn, foof@debian.org SEE ALSO ======== perl(1), Ogg::Vorbis(3pm), and the README distributed with ao.  File: pm.info, Node: Apache, Next: Apache/ASP, Prev: Ao, Up: Module List Perl interface to the Apache server API *************************************** NAME ==== Apache - Perl interface to the Apache server API SYNOPSIS ======== use Apache (); DESCRIPTION =========== This module provides a Perl interface the Apache API. It is here mainly for mod_perl, but may be used for other Apache modules that wish to embed a Perl interpreter. We suggest that you also consult the description of the Apache C API at http://www.apache.org/docs/. THE REQUEST OBJECT ================== The request object holds all the information that the server needs to service a request. Apache *Perl*Handler*s will be given a reference to the request object as parameter and may choose to update or use it in various ways. Most of the methods described below obtain information from or update the request object. The perl version of the request object will be blessed into the Apache package, it is really a `request_rec*' in disguise. Apache->request([$r]) The Apache->request method will return a reference to the request object. *Perl*Handler*s can obtain a reference to the request object when it is passed to them via `@_'. However, scripts that run under Apache::Registry, for example, need a way to access the request object. Apache::Registry will make a request object available to these scripts by passing an object reference to `Apache->request($r)'. If handlers use modules such as CGI::Apache that need to access `Apache->request', they too should do this (e.g. *Apache::Status*). $r->as_string Returns a string representation of the request object. Mainly useful for debugging. $r->main If the current request is a sub-request, this method returns a blessed reference to the main request structure. If the current request is the main request, then this method returns undef. $r->prev This method returns a blessed reference to the previous (internal) request structure or undef if there is no previous request. $r->next This method returns a blessed reference to the next (internal) request structure or undef if there is no next request. $r->last This method returns a blessed reference to the last (internal) request structure. Handy for logging modules. $r->is_main Returns true if the current request object is for the main request. (Should give the same result as `!$r->main', but will be more efficient.) $r->is_initial_req Returns true if the current request is the first internal request, returns false if the request is a sub-request or internal redirect. SUB REQUESTS ============ Apache provides a sub-request mechanism to lookup a uri or filename, performing all access checks, etc., without actually running the response phase of the given request. Notice, we have dropped the `sub_req_' prefix here. The `request_rec*' returned by the lookup methods is blessed into the *Apache::SubRequest* class. This way, `destroy_sub_request()' is called automatically during `Apache::SubRequest->DESTROY' when the object goes out of scope. The *Apache::SubRequest* class inherits all the methods from the Apache class. $r->lookup_uri($uri) my $subr = $r->lookup_uri($uri); my $filename = $subr->filename; unless(-e $filename) { warn "can't stat $filename!\n"; } $r->lookup_file($filename) my $subr = $r->lookup_file($filename); $subr->run if($subr->run != OK) { $subr->log_error("something went wrong!"); } CLIENT REQUEST PARAMETERS ========================= In this section we will take a look at various methods that can be used to retrieve the request parameters sent from the client. In the following examples, $r is a request object blessed into the Apache class, obtained by the first parameter passed to a handler subroutine or *Apache->request* $r->method( [$meth] ) The $r->method method will return the request method. It will be a string such as "GET", "HEAD" or "POST". Passing an argument will set the method, mainly used for internal redirects. $r->method_number( [$num] ) The $r->method_number method will return the request method number. The method numbers are defined by the M_GET, M_POST,... constants available from the *Apache::Constants* module. Passing an argument will set the method_number, mainly used for internal redirects and testing authorization restriction masks. $r->bytes_sent The number of bytes sent to the client, handy for logging, etc. $r->the_request The request line sent by the client, handy for logging, etc. $r->proxyreq Returns true if the request is proxy http. Mainly used during the filename translation stage of the request, which may be handled by a `PerlTransHandler'. $r->header_only Returns true if the client is asking for headers only, e.g. if the request method was HEAD. $r->protocol The $r->protocol method will return a string identifying the protocol that the client speaks. Typical values will be "HTTP/1.0" or "HTTP/1.1". $r->hostname Returns the server host name, as set by full URI or Host: header. $r->request_time Returns the time that the request was made. The time is the local unix time in seconds since the epoch. $r->uri( [$uri] ) The $r->uri method will return the requested URI minus optional query string, optionally changing it with the first argument. $r->filename( [$filename] ) The $r->filename method will return the result of the *URI -> filename* translation, optionally changing it with the first argument if you happen to be doing the translation. $r->path_info( [$path_info] ) The $r->path_info method will return what is left in the path after the *URI -> filename* translation, optionally changing it with the first argument if you happen to be doing the translation. $r->args( [$query_string] ) The $r->args method will return the contents of the URI *query string*. When called in a scalar context, the entire string is returned. When called in a list context, a list of parsed key => value pairs are returned, i.e. it can be used like this: $query = $r->args; %in = $r->args; $r->args can also be used to set the *query string*. This can be useful when redirecting a POST request. $r->headers_in The $r->headers_in method will return a %hash of client request headers. This can be used to initialize a perl hash, or one could use the $r->header_in() method (described below) to retrieve a specific header value directly. Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. This requires Apache::Table. $r->header_in( $header_name, [$value] ) Return the value of a client header. Can be used like this: $ct = $r->header_in("Content-type"); $r->header_in($key, $val); #set the value of header '$key' $r->content The $r->content method will return the entity body read from the client, but only if the request content type is `application/x-www-form-urlencoded'. When called in a scalar context, the entire string is returned. When called in a list context, a list of parsed key => value pairs are returned. *NOTE*: you can only ask for this once, as the entire body is read from the client. $r->read($buf, $bytes_to_read, [$offset]) This method is used to read data from the client, looping until it gets all of `$bytes_to_read' or a timeout happens. An offset may be specified to place the read data at some other place than the beginning of the string. In addition, this method sets a timeout before reading with `$r->soft_timeout'. $r->get_remote_host Lookup the client's DNS hostname. If the configuration directive *HostNameLookups* is set to off, this returns the dotted decimal representation of the client's IP address instead. Might return undef if the hostname is not known. $r->get_remote_logname Lookup the remote user's system name. Might return undef if the remote system is not running an RFC 1413 server or if the configuration directive *IdentityCheck* is not turned on. More information about the client can be obtained from the *Apache::Connection* object, as described below. $c = $r->connection The $r->connection method will return a reference to the request connection object (blessed into the *Apache::Connection* package). This is really a `conn_rec*' in disguise. The following methods can be used on the connection object: $c->remote_host If the configuration directive *HostNameLookups* is set to on: then the first time `$r->get_remote_host' is called the server does a DNS lookup to get the remote client's host name. The result is cached in `$c->remote_host' then returned. If the server was unable to resolve the remote client's host name this will be set to "". Subsequent calls to `$r->get_remote_host' return this cached value. If the configuration directive *HostNameLookups* is set to off: calls to `$r->get_remote_host' return a string that contains the dotted decimal representation of the remote client's IP address. However this string is not cached, and `$c->remote_host' is undefined. So, it's best to to call `$r->get_remote_host' instead of directly accessing this variable. $c->remote_ip The dotted decimal representation of the remote client's IP address. This is set by the server when the connection record is created so is always defined. You can also set this value by providing an argument to it. This is helpful if your server is behind a squid accelerator proxy which adds a X-Forwarded-For header. $c->local_addr A packed SOCKADDR_IN in the same format as returned by `pack_sockaddr_in', *Note Socket: Socket,, containing the port and address on the local host that the remote client is connected to. This is set by the server when the connection record is created so it is always defined. $c->remote_addr A packed SOCKADDR_IN in the same format as returned by `pack_sockaddr_in', *Note Socket: Socket,, containing the port and address on the remote host that the server is connected to. This is set by the server when the connection record is created so it is always defined. Among other things, this can be used, together with `$c->local_addr', to perform RFC1413 ident lookups on the remote client even when the configuration directive *IdentityCheck* is turned off. Can be used like: use Net::Ident qw (lookupFromInAddr); ... my $remoteuser = lookupFromInAddr ($c->local_addr, $c->remote_addr, 2); Note that the lookupFromInAddr interface does not currently exist in the *Net::Ident* module, but the author is planning on adding it soon. $c->remote_logname If the configuration directive *IdentityCheck* is set to on: then the first time `$r->get_remote_logname' is called the server does an RFC 1413 (ident) lookup to get the remote users system name. Generally for UNI* systems this is their login. The result is cached in `$c->remote_logname' then returned. Subsequent calls to `$r->get_remote_host' return the cached value. If the configuration directive *IdentityCheck* is set to off: then `$r->get_remote_logname' does nothing and `$c->remote_logname' is always undefined. $c->user( [$user] ) If an authentication check was successful, the authentication handler caches the user name here. Sets the user name to the optional first argument. $c->auth_type Returns the authentication scheme that successfully authenticate `$c->user', if any. $c->aborted Returns true if the client stopped talking to us. $c->fileno( [$direction] ) Returns the client file descriptor. If $direction is 0, the input fd is returned. If $direction is not null or ommitted, the output fd is returned. This can be used to detect client disconnect without doing any I/O, e.g. using IO::Select. SERVER CONFIGURATION INFORMATION ================================ The following methods are used to obtain information from server configuration and access control files. $r->dir_config( $key ) Returns the value of a per-directory variable specified by the PerlSetVar directive. # # PerlSetVar Key Value # my $val = $r->dir_config('Key'); Keys are case-insensitive. Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. See Apache::Table. $r->dir_config->get( $key ) Returns the value of a per-directory array variable specified by the `PerlAddVar' directive. # # PerlAddVar Key Value1 # PerlAddVar Key Value2 # my @val = $r->dir_config->get('Key'); Alternatively in your code you can extend the setting with: $r->dir_config->add(Key => 'Value3'); Keys are case-insensitive. Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. See Apache::Table. $r->requires Returns an array reference of hash references, containing information related to the require directive. This is normally used for access control, see `Apache::AuthzAge' in this node for an example. $r->auth_type Returns a reference to the current value of the per directory configuration directive *AuthType*. Normally this would be set to Basic to use the basic authentication scheme defined in RFC 1945, *Hypertext Transfer Protocol - HTTP/1.0*. However, you could set to something else and implement your own authentication scheme. $r->auth_name Returns a reference to the current value of the per directory configuration directive *AuthName*. The AuthName directive creates protection realm within the server document space. To quote RFC 1945 "These realms allow the protected resources on a server to be partitioned into a set of protection spaces, each with its own authentication scheme and/or authorization database." The client uses the root URL of the server to determine which authentication credentials to send with each HTTP request. These credentials are tagged with the name of the authentication realm that created them. Then during the authentication stage the server uses the current authentication realm, from `$r->auth_name', to determine which set of credentials to authenticate. $r->document_root Returns a reference to the current value of the per server configuration directive *DocumentRoot*. To quote the Apache server documentation, "Unless matched by a directive like Alias, the server appends the path from the requested URL to the document root to make the path to the document." This same value is passed to CGI scripts in the DOCUMENT_ROOT environment variable. $r->allow_options The `$r->allow_options' method can be used for checking if it is OK to run a perl script. The *Apache::Options* module provides the constants to check against. if(!($r->allow_options & OPT_EXECCGI)) { $r->log_reason("Options ExecCGI is off in this directory", $filename); } $r->get_server_port Returns the port number on which the server is listening. $s = $r->server Return a reference to the server info object (blessed into the *Apache::Server* package). This is really a `server_rec*' in disguise. The following methods can be used on the server object: $s = Apache->server Same as above, but only available during server startup for use in sections, *PerlScript* or *PerlModule*. $s->server_admin Returns the mail address of the person responsible for this server. $s->server_hostname Returns the hostname used by this server. $s->port Returns the port that this servers listens too. $s->is_virtual Returns true if this is a virtual server. $s->names Returns the wild-carded names for ServerAlias servers. $s->dir_config( $key ) Alias for Apache::dir_config. $s->warn Alias for Apache::warn. $s->log_error Alias for Apache::log_error. $s->uid Returns the numeric user id under which the server answers requests. This is the value of the User directive. $s->gid Returns the numeric group id under which the server answers requests. This is the value of the Group directive. $s->loglevel Get or set the value of the current LogLevel. This method is added by the Apache::Log module, which needs to be pulled in. use Apache::Log; print "LogLevel = ", $s->loglevel; $s->loglevel(Apache::Log::DEBUG); If using Perl 5.005+, the following constants are defined (but not exported): Apache::Log::EMERG Apache::Log::ALERT Apache::Log::CRIT Apache::Log::ERR Apache::Log::WARNING Apache::Log::NOTICE Apache::Log::INFO Apache::Log::DEBUG $r->get_handlers( $hook ) Returns a reference to a list of handlers enabled for $hook. $hook is a string representing the phase to handle. The returned list is a list of references to the handler subroutines. $list = $r->get_handlers( 'PerlHandler' ); $r->set_handlers( $hook, [\&handler, ... ] ) Sets the list if handlers to be called for $hook. $hook is a string representing the phase to handle. The list of handlers is an anonymous array of code references to the handlers to install for this request phase. The special list [ \&OK ] can be used to disable a particular phase. $r->set_handlers( PerlLogHandler => [ \&myhandler1, \&myhandler2 ] ); $r->set_handlers( PerlAuthenHandler => [ \&OK ] ); $r->push_handlers( $hook, \&handler ) Pushes a new handler to be called for $hook. $hook is a string representing the phase to handle. The handler is a reference to a subroutine to install for this request phase. This handler will be called before any configured handlers. $r->push_handlers( PerlHandler => \&footer); SETTING UP THE RESPONSE ======================= The following methods are used to set up and return the response back to the client. This typically involves setting up $r->status(), the various content attributes and optionally some additional $r->header_out() calls before calling $r->send_http_header() which will actually send the headers to the client. After this a typical application will call the $r->print() method to send the response content to the client. $r->send_http_header( [$content_type] ) Send the response line and all headers to the client. Takes an optional parameter indicating the content-type of the response, i.e. 'text/html'. This method will create headers from the $r->content_xxx() and $r->no_cache() attributes (described below) and then append the headers defined by $r->header_out (or $r->err_header_out if status indicates an error). $r->get_basic_auth_pw If the current request is protected by Basic authentication, this method will return 0, otherwise -1. The second return value will be the decoded password sent by the client. ($ret, $sent_pw) = $r->get_basic_auth_pw; $r->note_basic_auth_failure Prior to requiring Basic authentication from the client, this method will set the outgoing HTTP headers asking the client to authenticate for the realm defined by the configuration directive `AuthName'. $r->handler( [$meth] ) Set the handler for a request. Normally set by the configuration directive `AddHandler'. $r->handler( "perl-script" ); $r->notes( $key, [$value] ) Return the value of a named entry in the Apache notes table, or optionally set the value of a named entry. This table is used by Apache modules to pass messages amongst themselves. Generally if you are writing handlers in mod_perl you can use Perl variables for this. $r->notes("MY_HANDLER" => OK); $val = $r->notes("MY_HANDLER"); Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. This requires Apache::Table. $r->pnotes( $key, [$value] ) Like $r->notes, but takes any scalar as an value. $r->pnotes("MY_HANDLER" => [qw(one two)]); my $val = $r->pnotes("MY_HANDLER"); print $val->[0]; # prints "one" Advantage over just using a Perl variable is that $r->pnotes gets cleaned up after every request. $r->subprocess_env( $key, [$value] ) Return the value of a named entry in the Apache `subprocess_env' table, or optionally set the value of a named entry. This table is used by mod_include. By setting some custom variables inside a perl handler it is possible to combine perl with mod_include nicely. If you say, e.g. in a PerlHeaderParserHandler $r->subprocess_env(MyLanguage => "de"); you can then write in your .shtml document: English Deutsch Sorry Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. This requires Apache::Table. $r->content_type( [$newval] ) Get or set the content type being sent to the client. Content types are strings like "text/plain", "text/html" or "image/gif". This corresponds to the "Content-Type" header in the HTTP protocol. Example of usage is: $previous_type = $r->content_type; $r->content_type("text/plain"); $r->content_encoding( [$newval] ) Get or set the content encoding. Content encodings are string like "gzip" or "compress". This correspond to the "Content-Encoding" header in the HTTP protocol. $r->content_languages( [$array_ref] ) Get or set the content languages. The content language corresponds to the "Content-Language" HTTP header and is an array reference containing strings such as "en" or "no". $r->status( $integer ) Get or set the reply status for the client request. The *Apache::Constants* module provide mnemonic names for the status codes. $r->status_line( $string ) Get or set the response status line. The status line is a string like "200 Document follows" and it will take precedence over the value specified using the $r->status() described above. $r->headers_out The $r->headers_out method will return a %hash of server response headers. This can be used to initialize a perl hash, or one could use the $r->header_out() method (described below) to retrieve or set a specific header value directly. Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. This requires Apache::Table. $r->header_out( $header, $value ) Change the value of a response header, or create a new one. You should not define any "Content-XXX" headers by calling this method, because these headers use their own specific methods. Example of use: $r->header_out("WWW-Authenticate" => "Basic"); $val = $r->header_out($key); $r->err_headers_out The $r->err_headers_out method will return a %hash of server response headers. This can be used to initialize a perl hash, or one could use the $r->err_header_out() method (described below) to retrieve or set a specific header value directly. The difference between headers_out and err_headers_out is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them). Will return a HASH reference blessed into the Apache::Table class when called in a scalar context with no "key" argument. This requires Apache::Table. $r->err_header_out( $header, [$value] ) Change the value of an error response header, or create a new one. These headers are used if the status indicates an error. $r->err_header_out("Warning" => "Bad luck"); $val = $r->err_header_out($key); $r->no_cache( $boolean ) This is a flag that indicates that the data being returned is volatile and the client should be told not to cache it. $r->print( @list ) This method sends data to the client with `$r->write_client', but first sets a timeout before sending with `$r->soft_timeout'. This method is called instead of CORE::print when you use print() in your mod_perl programs. This method treats scalar references specially. If an item in @list is a scalar reference, it will be dereferenced before printing. This is a performance optimization which prevents unneeded copying of large strings, and it is subtly different from Perl's standard print() behavior. Example: $foo = \"bar"; print($foo); The result is "bar", not the "SCALAR(0xDEADBEEF)" you might have expected. If you really want the reference to be printed out, force it into a scalar context by using `print(scalar($foo))'. $r->send_fd( $filehandle ) Send the contents of a file to the client. Can for instance be used like this: open(FILE, $r->filename) || return 404; $r->send_fd(FILE); close(FILE); $r->internal_redirect( $newplace ) Redirect to a location in the server namespace without telling the client. For instance: $r->internal_redirect("/home/sweet/home.html"); $r->internal_redirect_handler( $newplace ) Same as *internal_redirect*, but the handler from $r is preserved. $r->custom_response($code, $uri) This method provides a hook into the *ErrorDocument* mechanism, allowing you to configure a custom response for a given response code at request-time. Example: use Apache::Constants ':common'; sub handler { my($r) = @_; if($things_are_ok) { return OK; } #uri> #ErrorDocument 401 /error.html # $r->custom_response(AUTH_REQUIRED, "/error.html"); #can send a string too #uri> #ErrorDocument 401 "sorry, go away" # #$r->custom_response(AUTH_REQUIRED, "sorry, go away"); return AUTH_REQUIRED; } SERVER CORE FUNCTIONS ===================== $r->soft_timeout($message) $r->hard_timeout($message) $r->kill_timeout $r->reset_timeout (Documentation borrowed from http_main.h) There are two functions which modules can call to trigger a timeout (with the per-virtual-server timeout duration); these are hard_timeout and soft_timeout. The difference between the two is what happens when the timeout expires (or earlier than that, if the client connection aborts) -- a soft_timeout just puts the connection to the client in an "aborted" state, which will cause http_protocol.c to stop trying to talk to the client, but otherwise allows the code to continue normally. hard_timeout(), by contrast, logs the request, and then aborts it completely -- longjmp()ing out to the accept() loop in http_main. Any resources tied into the request resource pool will be cleaned up; everything that is not will leak. soft_timeout() is recommended as a general rule, because it gives your code a chance to clean up. However, hard_timeout() may be the most convenient way of dealing with timeouts waiting for some external resource other than the client, if you can live with the restrictions. When a hard timeout is in scope, critical sections can be guarded with block_alarms() and unblock_alarms() -- these are declared in alloc.c because they are most often used in conjunction with routines to allocate something or other, to make sure that the cleanup does get registered before any alarm is allowed to happen which might require it to be cleaned up; they * are, however, implemented in http_main.c. kill_timeout() will disarm either variety of timeout. reset_timeout() resets the timeout in progress. $r->post_connection($code_ref) $r->register_cleanup($code_ref) Register a cleanup function which is called just before $r->pool is destroyed. $r->register_cleanup(sub { my $r = shift; warn "registered cleanup called for ", $r->uri, "\n"; }); Cleanup functions registered in the parent process (before forking) will run once when the server is shut down: #PerlRequire startup.pl warn "parent pid is $$\n"; Apache->server->register_cleanup(sub { warn "server cleanup in $$\n"}); The *post_connection* method is simply an alias for *register_cleanup*, as this method may be used to run code after the client connection is closed, which may not be a cleanup. CGI SUPPORT =========== We also provide some methods that make it easier to support the CGI type of interface. $r->send_cgi_header() Take action on certain headers including *Status:*, *Location:* and *Content-type:* just as mod_cgi does, then calls $r->send_http_header(). Example of use: $r->send_cgi_header(<log_reason($message, $file) The request failed, why?? Write a message to the server errorlog. $r->log_reason("Because I felt like it", $r->filename); $r->log_error($message) Uh, oh. Write a message to the server errorlog. $r->log_error("Some text that goes in the error_log"); $r->warn($message) For pre-1.3 versions of apache, this is just an alias for log_error. With 1.3+ versions of apache, this message will only be send to the error_log if *LogLevel* is set to warn or higher. UTILITY FUNCTIONS ================= Apache::unescape_url($string) Handy function for unescapes. Use this one for filenames/paths. Use unescape_url_info for the result of submitted form data. Apache::unescape_url_info($string) Handy function for unescapes submitted form data. In opposite to unescape_url it translates the plus sign to space. Apache::perl_hook($hook) Returns true if the specified callback hook is enabled: for (qw(Access Authen Authz ChildInit Cleanup Fixup HeaderParser Init Log Trans Type)) { print "$_ hook enabled\n" if Apache::perl_hook($_); } GLOBAL VARIABLES ================ $Apache::Server::Starting Set to true when the server is starting. $Apache::Server::ReStarting Set to true when the server is starting. SEE ALSO ======== perl(1), Apache::Constants(3), Apache::Registry(3), Apache::Debug(3), Apache::Options(3), CGI::Apache(3) Apache C API notes at `http://www.apache.org/docs/' AUTHORS ======= Perl interface to the Apache C API written by Doug MacEachern with contributions from Gisle Aas, Andreas Koenig, Eric Bartley, Rob Hartill, Gerald Richter, Salvador Ortiz and others.