diff options
Diffstat (limited to 'pod/modpods')
33 files changed, 2031 insertions, 0 deletions
diff --git a/pod/modpods/Abbrev.pod b/pod/modpods/Abbrev.pod new file mode 100644 index 0000000000..85ec88ef85 --- /dev/null +++ b/pod/modpods/Abbrev.pod @@ -0,0 +1,19 @@ +=head1 NAME + +abbrev - create an abbreviation table from a list + +=head1 SYNOPSIS + + use Abbrev; + abbrev *HASH, LIST + + +=head1 DESCRIPTION + +Stores all unambiguous truncations of each element of LIST +as keys key in the associative array indicated by C<*hash>. +The values are the original list elements. + +=head1 EXAMPLE + + abbrev(*hash,qw("list edit send abort gripe")); diff --git a/pod/modpods/AnyDBMFile.pod b/pod/modpods/AnyDBMFile.pod new file mode 100644 index 0000000000..7b579ca34c --- /dev/null +++ b/pod/modpods/AnyDBMFile.pod @@ -0,0 +1,73 @@ +=head1 NAME + +AnyDBM_File - provide framework for multiple DBMs + +NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations + +=head1 SYNOPSIS + + use AnyDBM_File; + +=head1 DESCRIPTION + +This module is a "pure virtual base class"--it has nothing of us 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 +L<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: + + @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); + +This 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; + +=head2 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 + + +=over 4 + +=item [0] + +on mixed universe machines, may be in the bsd compat library, +which is often shunned. + +=item [1] + +Can be trimmed if you compile for one access method. + +=item [2] + +See L<DB_File>. +Requires symbolic links. + +=item [3] + +By default, but can be redefined. + +=back + +=head1 SEE ALSO + +dbm(3), ndbm(3), DB_File(3) diff --git a/pod/modpods/AutoLoader.pod b/pod/modpods/AutoLoader.pod new file mode 100644 index 0000000000..203f951e39 --- /dev/null +++ b/pod/modpods/AutoLoader.pod @@ -0,0 +1,16 @@ +=head1 NAME + +AutoLoader - load functions only on demand + +=head1 SYNOPSIS + + package FOOBAR; + use Exporter; + use AutoLoader; + @ISA = (Exporter, AutoLoader); + +=head1 DESCRIPTION + +This module tells its users that functions in the FOOBAR package are to be +autoloaded from F<auto/$AUTOLOAD.al>. See L<perlsub/"Autoloading">. + diff --git a/pod/modpods/AutoSplit.pod b/pod/modpods/AutoSplit.pod new file mode 100644 index 0000000000..86df8c018b --- /dev/null +++ b/pod/modpods/AutoSplit.pod @@ -0,0 +1,11 @@ +=head1 NAME + +AutoSplit - split a package for autoloading + +=head1 DESCRIPTION + +This function will split up your program into files that the AutoLoader +module can handle. Normally only used to build autoloading Perl library +modules, especially extensions (like POSIX). You should look at how +they're built out for details. + diff --git a/pod/modpods/Basename.pod b/pod/modpods/Basename.pod new file mode 100644 index 0000000000..11cb15ee77 --- /dev/null +++ b/pod/modpods/Basename.pod @@ -0,0 +1,108 @@ +=head1 NAME + +Basename - parse file specifications + +fileparse - split a pathname into pieces + +basename - extract just the filename from a path + +dirname - extract just the directory from a path + +=head1 SYNOPSIS + + use File::Basename; + + ($name,$path,$suffix) = fileparse($fullname,@suffixlist) + fileparse_set_fstype($os_string); + $basename = basename($fullname,@suffixlist); + $dirname = dirname($fullname); + + ($name,$path,$suffix) = fileparse("lib/File/Basename.pm",".pm"); + fileparse_set_fstype("VMS"); + $basename = basename("lib/File/Basename.pm",".pm"); + $dirname = dirname("lib/File/Basename.pm"); + +=head1 DESCRIPTION + +These routines allow you to parse file specifications into useful +pieces according using the syntax of different operating systems. + +=over 4 + +=item fileparse_set_fstype + +You select the syntax via the routine fileparse_set_fstype(). +If the argument passed to it contains one of the substrings +"VMS", "MSDOS", or "MacOS", the file specification syntax of that +operating system is used in future calls to fileparse(), +basename(), and dirname(). If it contains none of these +substrings, UNIX syntax is used. This pattern matching is +case-insensitive. If you've selected VMS syntax, and the file +specification you pass to one of these routines contains a "/", +they assume you are using UNIX emulation and apply the UNIX syntax +rules instead, for that function call only. + +If you haven't called fileparse_set_fstype(), the syntax is chosen +by examining the "osname" entry from the C<Config> package +according to these rules. + +=item fileparse + +The fileparse() routine divides a file specification into three +parts: a leading B<path>, a file B<name>, and a B<suffix>. The +B<path> contains everything up to and including the last directory +separator in the input file specification. The remainder of the input +file specification is then divided into B<name> and B<suffix> based on +the optional patterns you specify in C<@suffixlist>. Each element of +this list is interpreted as a regular expression, and is matched +against the end of B<name>. If this succeeds, the matching portion of +B<name> is removed and prepended to B<suffix>. By proper use of +C<@suffixlist>, you can remove file types or versions for examination. + +You are guaranteed that if you concatenate B<path>, B<name>, and +B<suffix> together in that order, the result will be identical to the +input file specification. + +=back + +=head1 EXAMPLES + +Using UNIX file syntax: + + ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7', + '\.book\d+'); + +would yield + + $base eq 'draft' + $path eq '/virgil/aeneid', + $tail eq '.book7' + +Similarly, using VMS syntax: + + ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh', + '\..*'); + +would yield + + $name eq 'Rhetoric' + $dir eq 'Doc_Root:[Help]' + $type eq '.Rnh' + +=item C<basename> + +The basename() routine returns the first element of the list produced +by calling fileparse() with the same arguments. It is provided for +compatibility with the UNIX shell command basename(1). + +=item C<dirname> + +The dirname() routine returns the directory portion of the input file +specification. When using VMS or MacOS syntax, this is identical to the +second element of the list produced by calling fileparse() with the same +input file specification. When using UNIX or MSDOS syntax, the return +value conforms to the behavior of the UNIX shell command dirname(1). This +is usually the same as the behavior of fileparse(), but differs in some +cases. For example, for the input file specification F<lib/>, fileparse() +considers the directory name to be F<lib/>, while dirname() considers the +directory name to be F<.>). diff --git a/pod/modpods/Benchmark.pod b/pod/modpods/Benchmark.pod new file mode 100644 index 0000000000..bdb3f05700 --- /dev/null +++ b/pod/modpods/Benchmark.pod @@ -0,0 +1,159 @@ +=head1 NAME + +Benchmark - benchmark running times of code + +timethis - run a chunk of code several times + +timethese - run several chunks of code several times + +timeit - run a chunk of code and see how long it goes + +=head1 SYNOPSYS + + timethis ($count, "code"); + + timethese($count, { + 'Name1' => '...code1...', + 'Name2' => '...code2...', + }); + + $t = timeit($count, '...other code...') + print "$count loops of other code took:",timestr($t),"\n"; + +=head1 DESCRIPTION + +The Benchmark module encapsulates a number of routines to help you +figure out how long it takes to execute some code. + +=head2 Methods + +=over 10 + +=item new + +Returns the current time. Example: + + use Benchmark; + $t0 = new Benchmark; + # ... your code here ... + $t1 = new Benchmark; + $td = timediff($t1, $t0); + print "the code took:",timestr($dt),"\n"; + +=item debug + +Enables or disable debugging by setting the C<$Benchmark::Debug> flag: + + debug Benchmark 1; + $t = timeit(10, ' 5 ** $Global '); + debug Benchmark 0; + +=back + +=head2 Standard Exports + +The following routines will be exported into your namespace +if you use the Benchmark module: + +=over 10 + +=item timeit(COUNT, CODE) + +Arguments: COUNT is the number of time to run the loop, and +the second is the code to run. CODE may be a string containing the code, +a reference to the function to run, or a reference to a hash containing +keys which are names and values which are more CODE specs. + +Side-effects: prints out noise to standard out. + +Returns: a Benchmark object. + +=item timethis + +=item timethese + +=item timediff + +=item timestr + +=back + +=head2 Optional Exports + +The following routines will be exported into your namespace +if you specifically ask that they be imported: + +=over 10 + +clearcache + +clearallcache + +disablecache + +enablecache + +=back + +=head1 NOTES + +The data is stored as a list of values from the time and times +functions: + + ($real, $user, $system, $children_user, $children_system) + +in seconds for the whole loop (not divided by the number of rounds). + +The timing is done using time(3) and times(3). + +Code is executed in the caller's package. + +Enable debugging by: + + $Benchmark::debug = 1; + +The time of the null loop (a loop with the same +number of rounds but empty loop body) is subtracted +from the time of the real loop. + +The null loop times are cached, the key being the +number of rounds. The caching can be controlled using +calls like these: + + clearcache($key); + clearallcache(); + + disablecache(); + enablecache(); + +=head1 INHERITANCE + +Benchmark inherits from no other class, except of course +for Exporter. + +=head1 CAVEATS + +The real time timing is done using time(2) and +the granularity is therefore only one second. + +Short tests may produce negative figures because perl +can appear to take longer to execute the empty loop +than a short test; try: + + timethis(100,'1'); + +The system time of the null loop might be slightly +more than the system time of the loop with the actual +code and therefore the difference might end up being < 0. + +More documentation is needed :-( especially for styles and formats. + +=head1 AUTHORS + +Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>, +Tim Bunce <Tim.Bunce@ig.co.uk> + +=head1 MODIFICATION HISTORY + +September 8th, 1994; by Tim Bunce. + diff --git a/pod/modpods/Carp.pod b/pod/modpods/Carp.pod new file mode 100644 index 0000000000..b5439779ac --- /dev/null +++ b/pod/modpods/Carp.pod @@ -0,0 +1,22 @@ +=head1 NAME + +carp - warn of errors (from perspective of caller) + +croak - die of errors (from perspective of caller) + +confess - die of errors with stack backtrace + +=head1 SYNOPSIS + + use Carp; + croak "We're outta here!"; + +=head1 DESCRIPTION + +The Carp routines are useful in your own modules because +they act like die() or warn(), but report where the error +was in the code they were called from. Thus if you have a +routine Foo() that has a carp() in it, then the carp() +will report the error as occurring where Foo() was called, +not where carp() was called. + diff --git a/pod/modpods/CheckTree.pod b/pod/modpods/CheckTree.pod new file mode 100644 index 0000000000..cc06eeeda3 --- /dev/null +++ b/pod/modpods/CheckTree.pod @@ -0,0 +1,37 @@ +=head1 NAME + +validate - run many filetest checks on a tree + +=head1 SYNOPSIS + + use File::CheckTree; + + $warnings += validate( q{ + /vmunix -e || die + /boot -e || die + /bin cd + csh -ex + csh !-ug + sh -ex + sh !-ug + /usr -d || warn "What happened to $file?\n" + }); + +=head1 DESCRIPTION + +The validate() routine takes a single multiline string consisting of +lines containing a filename plus a file test to try on it. (The +file test may also be a "cd", causing subsequent relative filenames +to be interpreted relative to that directory.) After the file test +you may put C<|| die> to make it a fatal error if the file test fails. +The default is C<|| warn>. The file test may optionally have a "!' prepended +to test for the opposite condition. If you do a cd and then list some +relative filenames, you may want to indent them slightly for readability. +If you supply your own die() or warn() message, you can use $file to +interpolate the filename. + +Filetests may be bunched: "-rwx" tests for all of C<-r>, C<-w>, and C<-x>. +Only the first failed test of the bunch will produce a warning. + +The routine returns the number of warnings issued. + diff --git a/pod/modpods/Collate.pod b/pod/modpods/Collate.pod new file mode 100644 index 0000000000..852fd1f4bd --- /dev/null +++ b/pod/modpods/Collate.pod @@ -0,0 +1,31 @@ +=head1 NAME + +Collate - compare 8-bit scalar data according to the current locale + +=head1 SYNOPSIS + + use Collate; + setlocale(LC_COLLATE, 'locale-of-your-choice'); + $s1 = new Collate "scalar_data_1"; + $s2 = new Collate "scalar_data_2"; + +=head1 DESCRIPTION + +This module provides you with objects that will collate +according to your national character set, providing the +POSIX setlocale() function should be supported on your system. + +You can compare $s1 and $s2 above with + + $s1 le $s2 + +to extract the data itself, you'll need a dereference: $$s1 + +This uses POSIX::setlocale The basic collation conversion is done by +strxfrm() which terminates at NUL characters being a decent C routine. +collate_xfrm() handles embedded NUL characters gracefully. Due to C<cmp> +and overload magic, C<lt>, C<le>, C<eq>, C<ge>, and C<gt> work also. The +available locales depend on your operating system; try whether C<locale +-a> shows them or the more direct approach C<ls /usr/lib/nls/loc> or C<ls +/usr/lib/nls>. The locale names are probably something like +"xx_XX.(ISO)?8859-N". diff --git a/pod/modpods/Config.pod b/pod/modpods/Config.pod new file mode 100644 index 0000000000..141fb67393 --- /dev/null +++ b/pod/modpods/Config.pod @@ -0,0 +1,40 @@ +=head1 NAME + +Config - access Perl configuration option + +=head1 SYNOPSIS + + use Config; + if ($Config{'cc'} =~ /gcc/) { + print "built by gcc\n"; + } + +=head1 DESCRIPTION + +The Config module contains everything that was available to the +C<Configure> program at Perl build time. Shell variables from +F<config.sh> are stored in the readonly-variable C<%Config>, indexed by +their names. + +=head1 EXAMPLE + +Here's a more sophisticated example of using %Config: + + use Config; + + defined $Config{sig_name} || die "No sigs?"; + foreach $name (split(' ', $Config{sig_name})) { + $signo{$name} = $i; + $signame[$i] = $name; + $i++; + } + + print "signal #17 = $signame[17]\n"; + if ($signo{ALRM}) { + print "SIGALRM is $signo{ALRM}\n"; + } + +=head1 NOTE + +This module contains a good example of how to make a variable +readonly to those outside of it. diff --git a/pod/modpods/Cwd.pod b/pod/modpods/Cwd.pod new file mode 100644 index 0000000000..ac4e24f74d --- /dev/null +++ b/pod/modpods/Cwd.pod @@ -0,0 +1,26 @@ +=head1 NAME + +getcwd - get pathname of current working directory + +=head1 SYNOPSIS + + require Cwd; + $dir = Cwd::getcwd()' + + use Cwd; + $dir = getcwd()' + + use Cwd 'chdir'; + chdir "/tmp"; + print $ENV{'PWD'}; + +=head1 DESCRIPTION + +The getcwd() function re-implements the getcwd(3) (or getwd(3)) functions +in Perl. If you ask to override your chdir() built-in function, then your +PWD environment variable will be kept up to date. (See +L<perlsub/Overriding builtin functions>.) + +The fastgetcwd() function looks the same as getcwd(), but runs faster. +It's also more dangerous because you might conceivably chdir() out of a +directory that you can't chdir() back into. diff --git a/pod/modpods/DB_File.pod b/pod/modpods/DB_File.pod new file mode 100644 index 0000000000..919743b7ca --- /dev/null +++ b/pod/modpods/DB_File.pod @@ -0,0 +1,319 @@ +=head1 NAME + +DB_File - Perl5 access to Berkeley DB + +=head1 SYNOPSIS + + use DB_File ; + + [$X =] tie %hash, DB_File, $filename [, $flags, $mode, $DB_HASH] ; + [$X =] tie %hash, DB_File, $filename, $flags, $mode, $DB_BTREE ; + [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ; + + $status = $X->del($key [, $flags]) ; + $status = $X->put($key, $value [, $flags]) ; + $status = $X->get($key, $value [, $flags]) ; + $status = $X->seq($key, $value [, $flags]) ; + $status = $X->sync([$flags]) ; + $status = $X->fd ; + + untie %hash ; + untie @array ; + +=head1 DESCRIPTION + +B<DB_File> is a module which allows Perl programs to make use of +the facilities provided by Berkeley DB. If you intend to use this +module you should really have a copy of the Berkeley DB manual +page at hand. The interface defined here +mirrors the Berkeley DB interface closely. + +Berkeley DB is a C library which provides a consistent interface to a number of +database formats. +B<DB_File> provides an interface to all three of the database types currently +supported by Berkeley DB. + +The file types are: + +=over 5 + +=item DB_HASH + +This database type allows arbitrary key/data pairs to be stored in data files. +This is equivalent to the functionality provided by +other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. +Remember though, the files created using DB_HASH are +not compatible with any of the other packages mentioned. + +A default hashing algorithm, which will be adequate for most applications, +is built into Berkeley DB. +If you do need to use your own hashing algorithm it is possible to write your +own in Perl and have B<DB_File> use it instead. + +=item DB_BTREE + +The btree format allows arbitrary key/data pairs to be stored in a sorted, +balanced binary tree. + +As with the DB_HASH format, it is possible to provide a user defined Perl routine +to perform the comparison of keys. By default, though, the keys are stored +in lexical order. + +=item DB_RECNO + +DB_RECNO allows both fixed-length and variable-length flat text files to be +manipulated using +the same key/value pair interface as in DB_HASH and DB_BTREE. +In this case the key will consist of a record (line) number. + +=back + +=head2 How does DB_File interface to Berkeley DB? + +B<DB_File> allows access to Berkeley DB files using the tie() mechanism +in Perl 5 (for full details, see L<perlfunc/tie()>). +This facility allows B<DB_File> to access Berkeley DB files using +either an associative array (for DB_HASH & DB_BTREE file types) or an +ordinary array (for the DB_RECNO file type). + +In addition to the tie() interface, it is also possible to use most of the +functions provided in the Berkeley DB API. + +=head2 Differences with Berkeley DB + +Berkeley DB uses the function dbopen() to open or create a +database. Below is the C prototype for dbopen(). + + DB* + dbopen (const char * file, int flags, int mode, + DBTYPE type, const void * openinfo) + +The parameter C<type> is an enumeration which specifies which of the 3 +interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used. +Depending on which of these is actually chosen, the final parameter, +I<openinfo> points to a data structure which allows tailoring of the +specific interface method. + +This interface is handled +slightly differently in B<DB_File>. Here is an equivalent call using +B<DB_File>. + + tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ; + +The C<filename>, C<flags> and C<mode> parameters are the direct equivalent +of their dbopen() counterparts. The final parameter $DB_HASH +performs the function of both the C<type> and C<openinfo> +parameters in dbopen(). + +In the example above $DB_HASH is actually a reference to a hash object. +B<DB_File> has three of these pre-defined references. +Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO. + +The keys allowed in each of these pre-defined references is limited to the names +used in the equivalent C structure. +So, for example, the $DB_HASH reference will only allow keys called C<bsize>, +C<cachesize>, C<ffactor>, C<hash>, C<lorder> and C<nelem>. + +To change one of these elements, just assign to it like this + + $DB_HASH{cachesize} = 10000 ; + + +=head2 RECNO + + +In order to make RECNO more compatible with Perl the array offset for all +RECNO arrays begins at 0 rather than 1 as in Berkeley DB. + + +=head2 In Memory Databases + +Berkeley DB allows the creation of in-memory databases by using NULL (that is, a +C<(char *)0 in C) in +place of the filename. +B<DB_File> uses C<undef> instead of NULL to provide this functionality. + + +=head2 Using the Berkeley DB Interface Directly + +As well as accessing Berkeley DB using a tied hash or array, it is also +possible to make direct use of most of the functions defined in the Berkeley DB +documentation. + + +To do this you need to remember the return value from the tie. + + $db = tie %hash, DB_File, "filename" + +Once you have done that, you can access the Berkeley DB API functions directly. + + $db->put($key, $value, R_NOOVERWRITE) ; + +All the functions defined in L<dbx(3X)> are available except +for close() and dbopen() itself. +The B<DB_File> interface to these functions have been implemented to mirror +the the way Berkeley DB works. In particular note that all the functions return +only a status value. Whenever a Berkeley DB function returns data via one of +its parameters, the B<DB_File> equivalent does exactly the same. + +All the constants defined in L<dbopen> are also available. + +Below is a list of the functions available. + +=over 5 + +=item get + +Same as in C<recno> except that the flags parameter is optional. +Remember the value +associated with the key you request is returned in the $value parameter. + +=item put + +As usual the flags parameter is optional. + +If you use either the R_IAFTER or +R_IBEFORE flags, the key parameter will have the record number of the inserted +key/value pair set. + +=item del + +The flags parameter is optional. + +=item fd + +As in I<recno>. + +=item seq + +The flags parameter is optional. + +Both the key and value parameters will be set. + +=item sync + +The flags parameter is optional. + +=back + +=head1 EXAMPLES + +It is always a lot easier to understand something when you see a real example. +So here are a few. + +=head2 Using HASH + + use DB_File ; + use Fcntl ; + + tie %h, DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ; + + # Add a key/value pair to the file + $h{"apple"} = "orange" ; + + # Check for existence of a key + print "Exists\n" if $h{"banana"} ; + + # Delete + delete $h{"apple"} ; + + untie %h ; + +=head2 Using BTREE + +Here is sample of code which used BTREE. Just to make life more interesting +the default comparision function will not be used. Instead a Perl sub, C<Compare()>, +will be used to do a case insensitive comparison. + + use DB_File ; + use Fcntl ; + + sub Compare + { + my ($key1, $key2) = @_ ; + + "\L$key1" cmp "\L$key2" ; + } + + $DB_BTREE->{compare} = 'Compare' ; + + tie %h, DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ; + + # Add a key/value pair to the file + $h{'Wall'} = 'Larry' ; + $h{'Smith'} = 'John' ; + $h{'mouse'} = 'mickey' ; + $h{'duck'} = 'donald' ; + + # Delete + delete $h{"duck"} ; + + # Cycle through the keys printing them in order. + # Note it is not necessary to sort the keys as + # the btree will have kept them in order automatically. + foreach (keys %h) + { print "$_\n" } + + untie %h ; + +Here is the output from the code above. + + mouse + Smith + Wall + + +=head2 Using RECNO + + use DB_File ; + use Fcntl ; + + $DB_RECNO->{psize} = 3000 ; + + tie @h, DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ; + + # Add a key/value pair to the file + $h[0] = "orange" ; + + # Check for existence of a key + print "Exists\n" if $h[1] ; + + untie @h ; + + + +=head1 WARNINGS + +If you happen find any other functions defined in the source for this module +that have not been mentioned in this document -- beware. +I may drop them at a moments notice. + +If you cannot find any, then either you didn't look very hard or the moment has +passed and I have dropped them. + +=head1 BUGS + +Some older versions of Berkeley DB had problems with fixed length records +using the RECNO file format. The newest version at the time of writing +was 1.85 - this seems to have fixed the problems with RECNO. + +I am sure there are bugs in the code. If you do find any, or can suggest any +enhancements, I would welcome your comments. + +=head1 AVAILABILITY + +Berkeley DB is available via the hold C<ftp.cs.berkeley.edu> in the +directory C</ucb/4bsd/db.tar.gz>. It is I<not> under the GPL. + +=head1 SEE ALSO + +L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)> + +Berkeley DB is available from F<ftp.cs.berkeley.edu> in the directory F</ucb/4bsd>. + +=head1 AUTHOR + +The DB_File interface was written by +Paul Marquess <pmarquess@bfsec.bt.co.uk>. +Questions about the DB system itself may be addressed to +Keith Bostic <bostic@cs.berkeley.edu>. diff --git a/pod/modpods/Dynaloader.pod b/pod/modpods/Dynaloader.pod new file mode 100644 index 0000000000..9810dad205 --- /dev/null +++ b/pod/modpods/Dynaloader.pod @@ -0,0 +1,316 @@ +=head1 NAME + +DynaLoader - Dynamically load C libraries into Perl code + +dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules + +=head1 SYNOPSIS + + require DynaLoader; + push (@ISA, 'DynaLoader'); + + +=head1 DESCRIPTION + +This specification defines a standard generic interface to the dynamic +linking mechanisms available on many platforms. Its primary purpose is +to implement automatic dynamic loading of Perl modules. + +The DynaLoader is designed to be a very simple high-level +interface that is sufficiently general to cover the requirements +of SunOS, HP-UX, NeXT, Linux, VMS and other platforms. + +It is also hoped that the interface will cover the needs of OS/2, +NT etc and allow pseudo-dynamic linking (using C<ld -A> at runtime). + +This document serves as both a specification for anyone wishing to +implement the DynaLoader for a new platform and as a guide for +anyone wishing to use the DynaLoader directly in an application. + +It must be stressed that the DynaLoader, by itself, is practically +useless for accessing non-Perl libraries because it provides almost no +Perl-to-C 'glue'. There is, for example, no mechanism for calling a C +library function or supplying arguments. It is anticipated that any +glue that may be developed in the future will be implemented in a +separate dynamically loaded module. + +DynaLoader Interface Summary + + @dl_library_path + @dl_resolve_using + @dl_require_symbols + $dl_debug + Implemented in: + bootstrap($modulename) Perl + @filepaths = dl_findfile(@names) Perl + + $libref = dl_load_file($filename) C + $symref = dl_find_symbol($libref, $symbol) C + @symbols = dl_undef_symbols() C + dl_install_xsub($name, $symref [, $filename]) C + $message = dl_error C + +=over 4 + +=item @dl_library_path + +The standard/default list of directories in which dl_findfile() will +search for libraries etc. Directories are searched in order: +$dl_library_path[0], [1], ... etc + +@dl_library_path is initialised to hold the list of 'normal' directories +(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}.). This should +ensure portability across a wide range of platforms. + +@dl_library_path should also be initialised with any other directories +that can be determined from the environment at runtime (such as +LD_LIBRARY_PATH for SunOS). + +After initialisation @dl_library_path can be manipulated by an +application using push and unshift before calling dl_findfile(). +Unshift can be used to add directories to the front of the search order +either to save search time or to override libraries with the same name +in the 'normal' directories. + +The load function that dl_load_file() calls may require an absolute +pathname. The dl_findfile() function and @dl_library_path can be +used to search for and return the absolute pathname for the +library/object that you wish to load. + +=item @dl_resolve_using + +A list of additional libraries or other shared objects which can be +used to resolve any undefined symbols that might be generated by a +later call to load_file(). + +This is only required on some platforms which do not handle dependent +libraries automatically. For example the Socket Perl extension library +(F<auto/Socket/Socket.so>) contains references to many socket functions +which need to be resolved when it's loaded. Most platforms will +automatically know where to find the 'dependent' library (e.g., +F</usr/lib/libsocket.so>). A few platforms need to to be told the location +of the dependent library explicitly. Use @dl_resolve_using for this. + +Example usage: + + @dl_resolve_using = dl_findfile('-lsocket'); + +=item @dl_require_symbols + +A list of one or more symbol names that are in the library/object file +to be dynamically loaded. This is only required on some platforms. + +=item dl_error() + +Syntax: + + $message = dl_error(); + +Error message text from the last failed DynaLoader function. Note +that, similar to errno in unix, a successful function call does not +reset this message. + +Implementations should detect the error as soon as it occurs in any of +the other functions and save the corresponding message for later +retrieval. This will avoid problems on some platforms (such as SunOS) +where the error message is very temporary (e.g., dlerror()). + +=item $dl_debug + +Internal debugging messages are enabled when $dl_debug is set true. +Currently setting $dl_debug only affects the Perl side of the +DynaLoader. These messages should help an application developer to +resolve any DynaLoader usage problems. + +$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined. + +For the DynaLoader developer/porter there is a similar debugging +variable added to the C code (see dlutils.c) and enabled if Perl was +built with the B<-DDEBUGGING> flag. This can also be set via the +PERL_DL_DEBUG environment variable. Set to 1 for minimal information or +higher for more. + +=item dl_findfile() + +Syntax: + + @filepaths = dl_findfile(@names) + +Determine the full paths (including file suffix) of one or more +loadable files given their generic names and optionally one or more +directories. Searches directories in @dl_library_path by default and +returns an empty list if no files were found. + +Names can be specified in a variety of platform independent forms. Any +names in the form B<-lname> are converted into F<libname.*>, where F<.*> is +an appropriate suffix for the platform. + +If a name does not already have a suitable prefix and/or suffix then +the corresponding file will be searched for by trying combinations of +prefix and suffix appropriate to the platform: "$name.o", "lib$name.*" +and "$name". + +If any directories are included in @names they are searched before +@dl_library_path. Directories may be specified as B<-Ldir>. Any other names +are treated as filenames to be searched for. + +Using arguments of the form C<-Ldir> and C<-lname> is recommended. + +Example: + + @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix)); + + +=item dl_expandspec() + +Syntax: + + $filepath = dl_expandspec($spec) + +Some unusual systems, such as VMS, require special filename handling in +order to deal with symbolic names for files (i.e., VMS's Logical Names). + +To support these systems a dl_expandspec() function can be implemented +either in the F<dl_*.xs> file or code can be added to the autoloadable +dl_expandspec(0 function in F<DynaLoader.pm). See F<DynaLoader.pm> for more +information. + +=item dl_load_file() + +Syntax: + + $libref = dl_load_file($filename) + +Dynamically load $filename, which must be the path to a shared object +or library. An opaque 'library reference' is returned as a handle for +the loaded object. Returns undef on error. + +(On systems that provide a handle for the loaded object such as SunOS +and HPUX, $libref will be that handle. On other systems $libref will +typically be $filename or a pointer to a buffer containing $filename. +The application should not examine or alter $libref in any way.) + +This is function that does the real work. It should use the current +values of @dl_require_symbols and @dl_resolve_using if required. + + SunOS: dlopen($filename) + HP-UX: shl_load($filename) + Linux: dld_create_reference(@dl_require_symbols); dld_link($filename) + NeXT: rld_load($filename, @dl_resolve_using) + VMS: lib$find_image_symbol($filename,$dl_require_symbols[0]) + + +=item dl_find_symbol() + +Syntax: + + $symref = dl_find_symbol($libref, $symbol) + +Return the address of the symbol $symbol or C<undef> if not found. If the +target system has separate functions to search for symbols of different +types then dl_find_symbol() should search for function symbols first and +then other types. + +The exact manner in which the address is returned in $symref is not +currently defined. The only initial requirement is that $symref can +be passed to, and understood by, dl_install_xsub(). + + SunOS: dlsym($libref, $symbol) + HP-UX: shl_findsym($libref, $symbol) + Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol) + NeXT: rld_lookup("_$symbol") + VMS: lib$find_image_symbol($libref,$symbol) + + +=item dl_undef_symbols() + +Example + + @symbols = dl_undef_symbols() + +Return a list of symbol names which remain undefined after load_file(). +Returns C<()> if not known. Don't worry if your platform does not provide +a mechanism for this. Most do not need it and hence do not provide it. + + +=item dl_install_xsub() + +Syntax: + + dl_install_xsub($perl_name, $symref [, $filename]) + +Create a new Perl external subroutine named $perl_name using $symref as +a pointer to the function which implements the routine. This is simply +a direct call to newXSUB(). Returns a reference to the installed +function. + +The $filename parameter is used by Perl to identify the source file for +the function if required by die(), caller() or the debugger. If +$filename is not defined then "DynaLoader" will be used. + + +=item boostrap() + +Syntax: + +bootstrap($module) + +This is the normal entry point for automatic dynamic loading in Perl. + +It performs the following actions: + +=over 8 + +=item * + +locates an auto/$module directory by searching @INC + +=item * + +uses dl_findfile() to determine the filename to load + +=item * + +sets @dl_require_symbols to C<("boot_$module")> + +=item * + +executes an F<auto/$module/$module.bs> file if it exists +(typically used to add to @dl_resolve_using any files which +are required to load the module on the current platform) + +=item * + +calls dl_load_file() to load the file + +=item * + +calls dl_undef_symbols() and warns if any symbols are undefined + +=item * + +calls dl_find_symbol() for "boot_$module" + +=item * + +calls dl_install_xsub() to install it as "${module}::bootstrap" + +=item * + +calls &{"${module}::bootstrap"} to bootstrap the module + +=back + +=back + + +=head1 AUTHOR + +This interface is based on the work and comments of (in no particular +order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno +Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, and others. + +Larry Wall designed the elegant inherited bootstrap mechanism and +implemented the first Perl 5 dynamic loader using it. + +Tim Bunce, 11 August 1994. diff --git a/pod/modpods/English.pod b/pod/modpods/English.pod new file mode 100644 index 0000000000..d6b26beaf2 --- /dev/null +++ b/pod/modpods/English.pod @@ -0,0 +1,24 @@ +=head1 NAME + +English - use nice English (or awk) names for ugly punctuation variables + +=head1 SYNOPSIS + + use English; + ... + if ($ERRNO =~ /denied/) { ... } + +=head1 DESCRIPTION + +This module provides aliases for the built-in variables whose +names no one seems to like to read. Variables with side-effects +which get triggered just by accessing them (like $0) will still +be affected. + +For those variables that have an B<awk> version, both long +and short English alternatives are provided. For example, +the C<$/> variable can be referred to either $RS or +$INPUT_RECORD_SEPARATOR if you are using the English module. + +See L<perlvar> for a complete list of these. + diff --git a/pod/modpods/Env.pod b/pod/modpods/Env.pod new file mode 100644 index 0000000000..44344998bd --- /dev/null +++ b/pod/modpods/Env.pod @@ -0,0 +1,31 @@ +=head1 NAME + +Env - Perl module that imports environment variables + +=head1 DESCRIPTION + +Perl maintains environment variables in a pseudo-associative-array +named %ENV. For when this access method is inconvenient, the Perl +module C<Env> allows environment variables to be treated as simple +variables. + +The Env::import() function ties environment variables with suitable +names to global Perl variables with the same names. By default it +does so with all existing environment variables (C<keys %ENV>). If +the import function receives arguments, it takes them to be a list of +environment variables to tie; it's okay if they don't yet exist. + +After an environment variable is tied, merely use it like a normal variable. +You may access its value + + @path = split(/:/, $PATH); + +or modify it + + $PATH .= ":."; + +however you'd like. +To remove a tied environment variable from +the environment, assign it the undefined value + + undef $PATH; diff --git a/pod/modpods/Exporter.pod b/pod/modpods/Exporter.pod new file mode 100644 index 0000000000..03e6a1c92d --- /dev/null +++ b/pod/modpods/Exporter.pod @@ -0,0 +1,60 @@ +=head1 NAME + +Exporter - module to control namespace manipulations + +import - import functions into callers namespace + +=head1 SYNOPSYS + + package WhatEver; + require Exporter; + @ISA = (Exporter); + @EXPORT = qw(func1, $foo, %tabs); + @EXPORT_OK = qw(sin cos); + ... + use Whatever; + use WhatEver 'sin'; + +=head1 DESCRIPTION + +The Exporter module is used by well-behaved Perl modules to +control what they will export into their user's namespace. +The WhatEver module above has placed in its export list +the function C<func1()>, the scalar C<$foo>, and the +hash C<%tabs>. When someone decides to +C<use WhatEver>, they get those identifier grafted +onto their own namespace. That means the user of +package whatever can use the function func1() instead +of fully qualifying it as WhatEver::func1(). + +You should be careful of such namespace pollution. +Of course, the user of the WhatEver module is free to +use a C<require> instead of a C<use>, which will +preserve the sanctity of their namespace. + +In particular, you almost certainly shouldn't +automatically export functions whose names are +already used in the language. For this reason, +the @EXPORT_OK list contains those function which +may be selectively imported, as the sin() function +was above. +See L<perlsub/Overriding builtin functions>. + +You can't import names that aren't in either the @EXPORT +or the @EXPORT_OK list. + +Remember that these two constructs are identical: + + use WhatEver; + + BEGIN { + require WhatEver; + import Module; + } + +The import() function above is not predefined in the +language. Rather, it's a method in the Exporter module. +A sneaky library writer could conceivably have an import() +method that behaved differently from the standard one, but +that's not very friendly. + diff --git a/pod/modpods/Fcntl.pod b/pod/modpods/Fcntl.pod new file mode 100644 index 0000000000..165153e475 --- /dev/null +++ b/pod/modpods/Fcntl.pod @@ -0,0 +1,20 @@ +=head1 NAME + +Fcntl - load the C Fcntl.h defines + +=head1 SYNOPSIS + + use Fcntl; + +=head1 DESCRIPTION + +This module is just a translation of the C F<fnctl.h> file. +Unlike the old mechanism of requiring a translated F<fnctl.ph> +file, this uses the B<h2xs> program (see the Perl source distribution) +and your native C compiler. This means that it has a +far more likely chance of getting the numbers right. + +=head1 NOTE + +Only C<#define> symbols get translated; you must still correctly +pack up your own arguments to pass as args for locking functions, etc. diff --git a/pod/modpods/FileHandle.pod b/pod/modpods/FileHandle.pod new file mode 100644 index 0000000000..d595617973 --- /dev/null +++ b/pod/modpods/FileHandle.pod @@ -0,0 +1,46 @@ +=head1 NAME + +FileHandle - supply object methods for filehandles + +cacheout - keep more files open than the system permits + +=head1 SYNOPSIS + + use FileHandle; + autoflush STDOUT 1; + + cacheout($path); + print $path @data; + +=head1 DESCRIPTION + +See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> +methods: + + print + autoflush + output_field_separator + output_record_separator + input_record_separator + input_line_number + format_page_number + format_lines_per_page + format_lines_left + format_name + format_top_name + format_line_break_characters + format_formfeed + +The cacheout() function will make sure that there's a filehandle +open for writing available as the pathname you give it. It automatically +closes and re-opens files if you exceed your system file descriptor maximum. + +=head1 BUGS + +F<sys/param.h> lies with its C<NOFILE> define on some systems, +so you may have to set $cacheout::maxopen yourself. + +Due to backwards compatibility, all filehandles resemble objects +of class C<FileHandle>, or actually classes derived from that class. +They actually aren't. Which means you can't derive your own +class from C<FileHandle> and inherit those methods. diff --git a/pod/modpods/Find.pod b/pod/modpods/Find.pod new file mode 100644 index 0000000000..81b46a9879 --- /dev/null +++ b/pod/modpods/Find.pod @@ -0,0 +1,44 @@ +=head1 NAME + +find - traverse a file tree + +=head1 SYNOPSYS + + use File::Find; + find(\&wanted, '/foo','/bar'); + sub wanted { ... } + +=head1 DESCRIPTION + +The wanted() function does whatever verificationsyou want. $dir contains +the current directory name, and $_ the current filename within that +directory. $name contains C<"$dir/$_">. You are chdir()'d to $dir when +the function is called. The function may set $prune to prune the tree. + +This library is primarily for the C<find2perl> tool, which when fed, + + find2perl / -name .nfs\* -mtime +7 \ + -exec rm -f {} \; -o -fstype nfs -prune + +produces something like: + + sub wanted { + /^\.nfs.*$/ && + (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && + int(-M _) > 7 && + unlink($_) + || + ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) && + $dev < 0 && + ($prune = 1); + } + +Set the variable $dont_use_nlink if you're using AFS, since AFS cheats. + +Here's another interesting wanted function. It will find all symlinks +that don't resolve: + + sub wanted { + -l && !-e && print "bogus link: $name\n"; + } + diff --git a/pod/modpods/Finddepth.pod b/pod/modpods/Finddepth.pod new file mode 100644 index 0000000000..022ddaf9f4 --- /dev/null +++ b/pod/modpods/Finddepth.pod @@ -0,0 +1,16 @@ +=head1 NAME + +finddepth - traverse a directory structure depth-first + +=head1 SYNOPSYS + + use File::Finddepth; + finddepth(\&wanted, '/foo','/bar'); + sub wanted { ... } + +=head2 DESCRIPTION + +This is just like C<File::Find>, except that it does a depthfirst +search uses finddepth() rather than find(), and performs a +depth-first search. + diff --git a/pod/modpods/GetOptions.pod b/pod/modpods/GetOptions.pod new file mode 100644 index 0000000000..ca64639968 --- /dev/null +++ b/pod/modpods/GetOptions.pod @@ -0,0 +1,137 @@ +=head1 NAME + +Getopt::Long, GetOptions - extended getopt processing + +=head1 SYNOPSIS + + use Getopt::Long; + $result = GetOptions (...option-descriptions...); + +=head1 DESCRIPTION + +This package implements an extended getopt function. This function adheres +to the new syntax (long option names, no bundling). +It tries to implement the better functionality of traditional, GNU and +POSIX getopt() functions. + +Each description should designate a valid Perl identifier, optionally +followed by an argument specifier. + +Values for argument specifiers are: + + <none> option does not take an argument + ! option does not take an argument and may be negated + =s :s option takes a mandatory (=) or optional (:) string argument + =i :i option takes a mandatory (=) or optional (:) integer argument + =f :f option takes a mandatory (=) or optional (:) real number argument + +If option "name" is set, it will cause the Perl variable $opt_name to +be set to the specified value. The calling program can use this +variable to detect whether the option has been set. Options that do +not take an argument will be set to 1 (one). + +Options that take an optional argument will be defined, but set to '' +if no actual argument has been supplied. + +If an "@" sign is appended to the argument specifier, the option is +treated as an array. Value(s) are not set, but pushed into array +@opt_name. + +Options that do not take a value may have an "!" argument spacifier to +indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which +sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). + +The option name may actually be a list of option names, separated by +'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and +'blech' will set $opt_foo instead. + +Option names may be abbreviated to uniqueness, depending on +configuration variable $autoabbrev. + +Dashes in option names are allowed (e.g. pcc-struct-return) and will +be translated to underscores in the corresponding Perl variable (e.g. +$opt_pcc_struct_return). Note that a lone dash "-" is considered an +option, corresponding Perl identifier is $opt_ . + +A double dash "--" signals end of the options list. + +If the first option of the list consists of non-alphanumeric +characters only, it is interpreted as a generic option starter. +Everything starting with one of the characters from the starter will +be considered an option. + +The default values for the option starters are "-" (traditional), "--" +(POSIX) and "+" (GNU, being phased out). + +Options that start with "--" may have an argument appended, separated +with an "=", e.g. "--foo=bar". + +If configuration varaible $getopt_compat is set to a non-zero value, +options that start with "+" may also include their arguments, +e.g. "+foo=bar". + +A return status of 0 (false) indicates that the function detected +one or more errors. + +=head1 EXAMPLES + +If option "one:i" (i.e. takes an optional integer argument), then +the following situations are handled: + + -one -two -> $opt_one = '', -two is next option + -one -2 -> $opt_one = -2 + +Also, assume "foo=s" and "bar:s" : + + -bar -xxx -> $opt_bar = '', '-xxx' is next option + -foo -bar -> $opt_foo = '-bar' + -foo -- -> $opt_foo = '--' + +In GNU or POSIX format, option names and values can be combined: + + +foo=blech -> $opt_foo = 'blech' + --bar= -> $opt_bar = '' + --bar=-- -> $opt_bar = '--' + +=over 12 + +=item $autoabbrev + +Allow option names to be abbreviated to uniqueness. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $getopt_compat + +Allow '+' to start options. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $option_start + +Regexp with option starters. +Default is (--|-) if environment variable +POSIXLY_CORRECT has been set, (--|-|\+) otherwise. + +=item $order + +Whether non-options are allowed to be mixed with +options. +Default is $REQUIRE_ORDER if environment variable +POSIXLY_CORRECT has been set, $PERMUTE otherwise. + +=item $ignorecase + +Ignore case when matching options. Default is 1. + +=item $debug + +Enable debugging output. Default is 0. + +=back + +=head1 NOTE + +Does not yet use the Exporter--or even packages!! +Thus, it's not a real module. + diff --git a/pod/modpods/Getopt.pod b/pod/modpods/Getopt.pod new file mode 100644 index 0000000000..2f607257ba --- /dev/null +++ b/pod/modpods/Getopt.pod @@ -0,0 +1,152 @@ +=head1 NAME + +getopt - Process single-character switches with switch clustering + +getopts - Process single-character switches with switch clustering + +GetOptions - extended getopt processing + +=head1 SYNOPSIS + + use Getopt::Std; + getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. + getopts('oif:'); # likewise, but all of them + + use Getopt::Long; + $result = GetOptions (...option-descriptions...); + +=head1 DESCRIPTION + +The getopt() functions processes single-character switches with switch +clustering. Pass one argument which is a string containing all switches +that take an argument. For each switch found, sets $opt_x (where x is the +switch name) to the value of the argument, or 1 if no argument. Switches +which take an argument don't care whether there is a space between the +switch and the argument. + +The Getopt::Long module implements an extended getopt function called +GetOptions(). This function adheres to the new syntax (long option names, +no bundling). It tries to implement the better functionality of +traditional, GNU and POSIX getopt() functions. + +Each description should designate a valid Perl identifier, optionally +followed by an argument specifier. + +Values for argument specifiers are: + + <none> option does not take an argument + ! option does not take an argument and may be negated + =s :s option takes a mandatory (=) or optional (:) string argument + =i :i option takes a mandatory (=) or optional (:) integer argument + =f :f option takes a mandatory (=) or optional (:) real number argument + +If option "name" is set, it will cause the Perl variable $opt_name to +be set to the specified value. The calling program can use this +variable to detect whether the option has been set. Options that do +not take an argument will be set to 1 (one). + +Options that take an optional argument will be defined, but set to '' +if no actual argument has been supplied. + +If an "@" sign is appended to the argument specifier, the option is +treated as an array. Value(s) are not set, but pushed into array +@opt_name. + +Options that do not take a value may have an "!" argument specifier to +indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which +sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). + +The option name may actually be a list of option names, separated by +'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and +'blech' will set $opt_foo instead. + +Option names may be abbreviated to uniqueness, depending on +configuration variable $autoabbrev. + +Dashes in option names are allowed (e.g. pcc-struct-return) and will +be translated to underscores in the corresponding Perl variable (e.g. +$opt_pcc_struct_return). Note that a lone dash "-" is considered an +option, corresponding Perl identifier is $opt_ . + +A double dash "--" signals end of the options list. + +If the first option of the list consists of non-alphanumeric +characters only, it is interpreted as a generic option starter. +Everything starting with one of the characters from the starter will +be considered an option. + +The default values for the option starters are "-" (traditional), "--" +(POSIX) and "+" (GNU, being phased out). + +Options that start with "--" may have an argument appended, separated +with an "=", e.g. "--foo=bar". + +If configuration variable $getopt_compat is set to a non-zero value, +options that start with "+" may also include their arguments, +e.g. "+foo=bar". + +A return status of 0 (false) indicates that the function detected +one or more errors. + +=head1 EXAMPLES + +If option "one:i" (i.e. takes an optional integer argument), then +the following situations are handled: + + -one -two -> $opt_one = '', -two is next option + -one -2 -> $opt_one = -2 + +Also, assume "foo=s" and "bar:s" : + + -bar -xxx -> $opt_bar = '', '-xxx' is next option + -foo -bar -> $opt_foo = '-bar' + -foo -- -> $opt_foo = '--' + +In GNU or POSIX format, option names and values can be combined: + + +foo=blech -> $opt_foo = 'blech' + --bar= -> $opt_bar = '' + --bar=-- -> $opt_bar = '--' + +=over 12 + +=item $autoabbrev + +Allow option names to be abbreviated to uniqueness. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $getopt_compat + +Allow '+' to start options. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $option_start + +Regexp with option starters. +Default is (--|-) if environment variable +POSIXLY_CORRECT has been set, (--|-|\+) otherwise. + +=item $order + +Whether non-options are allowed to be mixed with +options. +Default is $REQUIRE_ORDER if environment variable +POSIXLY_CORRECT has been set, $PERMUTE otherwise. + +=item $ignorecase + +Ignore case when matching options. Default is 1. + +=item $debug + +Enable debugging output. Default is 0. + +=back + +=head1 NOTE + +Does not yet use the Exporter--or even packages!! +Thus, it's not a real module. + diff --git a/pod/modpods/MakeMaker.pod b/pod/modpods/MakeMaker.pod new file mode 100644 index 0000000000..4db758fb20 --- /dev/null +++ b/pod/modpods/MakeMaker.pod @@ -0,0 +1,24 @@ +=head1 NAME + +MakeMaker - generate a Makefile for Perl extension + +=head1 SYNOPSIS + + use ExtUtils::MakeMaker; + +=head1 DESCRIPTION + +This utility is designed to write a Makefile for an extension module from +a Makefile.PL. It splits the task of generating the Makefile into several +subroutines that can be individually overridden. Each subroutines returns +the text it wishes to have written to the Makefile. + +The best way to learn to use this is to look at how some of the +extensions are generated, such as Socket. + +=head1 AUTHOR + +Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, +Andreas Koenig <F<k@franz.ww.TU-Berlin.DE>>, +and +Tim Bunce <F<Tim.Bunce@ig.co.uk>>. diff --git a/pod/modpods/Open2.pod b/pod/modpods/Open2.pod new file mode 100644 index 0000000000..19f0369cfd --- /dev/null +++ b/pod/modpods/Open2.pod @@ -0,0 +1,33 @@ +=head1 NAME + +IPC::Open2, open2 - open a process for both reading and writing + +=head1 SYNOPSIS + + use IPC::Open2; + $pid = open2('rdr', 'wtr', 'some cmd and args'); + # or + $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args'); + +=head1 DESCRIPTION + +The open2() function spawns the given $cmd and connects $rdr for +reading and $wtr for writing. It's what you think should work +when you try + + open(HANDLE, "|cmd args"); + +open2() returns the process ID of the child process. It doesn't return on +failure: it just raises an exception matching C</^open2:/>. + +=head1 WARNING + +It will not create these file handles for you. You have to do this yourself. +So don't pass it empty variables expecting them to get filled in for you. + +Additionally, this is very dangerous as you may block forever. +It assumes it's going to talk to something like B<bc>, both writing to +it and reading from it. This is presumably safe because you "know" +that commands like B<bc> will read a line at a time and output a line at +a time. Programs like B<sort> that read their entire input stream first, +however, are quite apt to cause deadlock. See L<open3> for an alternative. diff --git a/pod/modpods/Open3.pod b/pod/modpods/Open3.pod new file mode 100644 index 0000000000..690d8ffdfb --- /dev/null +++ b/pod/modpods/Open3.pod @@ -0,0 +1,23 @@ +=head1 NAME + +IPC::Open3, open3 - open a process for reading, writing, and error handling + +=head1 SYNOPSIS + + $pid = open3('WTRFH', 'RDRFH', 'ERRFH' + 'some cmd and args', 'optarg', ...); + +=head1 DESCRIPTION + +Extremely similar to open2(), open3() spawns the given $cmd and +connects RDRFH for reading, WTRFH for writing, and ERRFH for errors. If +ERRFH is '', or the same as RDRFH, then STDOUT and STDERR of the child are +on the same file handle. + +If WTRFH begins with ">&", then WTRFH will be closed in the parent, and +the child will read from it directly. if RDRFH or ERRFH begins with +">&", then the child will send output directly to that file handle. In both +cases, there will be a dup(2) instead of a pipe(2) made. + +All caveats from open2() continue to apply. See L<open2> for details. + diff --git a/pod/modpods/POSIX.pod b/pod/modpods/POSIX.pod new file mode 100644 index 0000000000..30539ad36f --- /dev/null +++ b/pod/modpods/POSIX.pod @@ -0,0 +1,53 @@ +=head1 NAME + +POSIX - Perl interface to IEEE 1003.1 namespace + +=head1 SYNOPSIS + + use POSIX; + use POSIX 'strftime'; + +=head1 DESCRIPTION + +The POSIX module permits you to access all (or nearly all) the standard +POSIX 1003.1 identifiers. Things which are C<#defines> in C, like EINTR +or O_NDELAY, are automatically exported into your namespace. All +functions are only exported if you ask for them explicitly. Most likely +people will prefer to use the fully-qualified function names. + +To get a list of all the possible identifiers available to you--and +their semantics--you should pick up a 1003.1 spec, or look in the +F<POSIX.pm> module. + +=head1 EXAMPLES + + printf "EENTR is %d\n", EINTR; + + POSIX::setsid(0); + + $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644); + # note: that's a filedescriptor, *NOT* a filehandle + +=head1 NOTE + +The POSIX module is probably the most complex Perl module supplied with +the standard distribution. It incorporates autoloading, namespace games, +and dynamic loading of code that's in Perl, C, or both. It's a great +source of wisdom. + +=head1 CAVEATS + +A few functions are not implemented because they are C specific. If you +attempt to call these, they will print a message telling you that they +aren't implemented because they're, supplying the Perl equivalent if one +exists. For example, trying to access the setjmp() call will elicit the +message "setjmp() is C-specific: use eval {} instead". + +Furthermore, some evil vendors will claim 1003.1 compliance, but in fact +are not so: they will not pass the PCTS (POSIX Compliance Test Suites). +For example, one vendor may not define EDEADLK, or the semantics of the +errno values set by open(2) might not be quite right. Perl does not +attempt to verify POSIX compliance. That means you can currently +successfully say "use POSIX", and then later in your program you find +that your vendor has been lax and there's no usable ICANON macro after +all. This could be construed to be a bug. diff --git a/pod/modpods/Ping.pod b/pod/modpods/Ping.pod new file mode 100644 index 0000000000..01bc25c64f --- /dev/null +++ b/pod/modpods/Ping.pod @@ -0,0 +1,37 @@ +=head1 NAME + +Net::Ping, pingecho - check a host for upness + +=head1 SYNOPSIS + + use Net::Ping; + print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ; + +=head1 DESCRIPTION + +This module contains routines to test for the reachability of remote hosts. +Currently the only routine implemented is pingecho(). + +pingecho() uses a TCP echo (I<NOT> an ICMP one) to determine if the +remote host is reachable. This is usually adequate to tell that a remote +host is available to rsh(1), ftp(1), or telnet(1) onto. + +=head2 Parameters + +=over 5 + +=item hostname + +The remote host to check, specified either as a hostname or as an IP address. + +=item timeout + +The timeout in seconds. If not specified it will default to 5 seconds. + +=back + +=head1 WARNING + +pingecho() uses alarm to implement the timeout, so don't set another alarm +while you are using it. + diff --git a/pod/modpods/Socket.pod b/pod/modpods/Socket.pod new file mode 100644 index 0000000000..7dfab25b26 --- /dev/null +++ b/pod/modpods/Socket.pod @@ -0,0 +1,23 @@ +=head1 NAME + +Socket - load the C socket.h defines + +=head1 SYNOPSIS + + use Socket; + + $proto = (getprotobyname('udp'))[2]; + socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto); + +=head1 DESCRIPTION + +This module is just a translation of the C F<socket.h> file. +Unlike the old mechanism of requiring a translated F<socket.ph> +file, this uses the B<h2xs> program (see the Perl source distribution) +and your native C compiler. This means that it has a +far more likely chance of getting the numbers right. + +=head1 NOTE + +Only C<#define> symbols get translated; you must still correctly +pack up your own arguments to pass to bind(), etc. diff --git a/pod/modpods/integer.pod b/pod/modpods/integer.pod new file mode 100644 index 0000000000..d459bca385 --- /dev/null +++ b/pod/modpods/integer.pod @@ -0,0 +1,18 @@ +=head1 NAME + +integer - Perl pragma to compute arithmetic in integer instead of double + +=head1 SYNOPSIS + + use integer; + $x = 10/3; + # $x is now 3, not 3.33333333333333333 + +=head1 DESCRIPTION + +This tells the compiler that it's okay to use integer operations +from here to the end of the enclosing BLOCK. On many machines, +this doesn't matter a great deal for most computations, but on those +without floating point hardware, it can make a big difference. + +See L<perlmod/Pragmatic Modules>. diff --git a/pod/modpods/less.pod b/pod/modpods/less.pod new file mode 100644 index 0000000000..bccc5341d1 --- /dev/null +++ b/pod/modpods/less.pod @@ -0,0 +1,13 @@ +=head1 NAME + +less - Perl pragma to request less of something from the compiler + +=head1 DESCRIPTION + +Currently unimplemented, this may someday be a compiler directive +to make certain trade-off, such as perhaps + + use less 'memory'; + use less 'CPU'; + use less 'fat'; + diff --git a/pod/modpods/sigtrap.pod b/pod/modpods/sigtrap.pod new file mode 100644 index 0000000000..ecc35421cc --- /dev/null +++ b/pod/modpods/sigtrap.pod @@ -0,0 +1,19 @@ +=head1 NAME + +sigtrap - Perl pragma to enable stack backtrace on unexpected signals + +=head1 SYNOPSIS + + use sigtrap; + use sigtrap qw(BUS SEGV PIPE SYS ABRT TRAP); + +=head1 DESCRIPTION + +The C<sigtrap> pragma initializes some default signal handlers that print +a stack dump of your Perl program, then sends itself a SIGABRT. This +provides a nice starting point if something horrible goes wrong. + +By default, handlers are installed for the ABRT, BUS, EMT, FPE, ILL, PIPE, +QUIT, SEGV, SYS, TERM, and TRAP signals. + +See L<perlmod/Pragmatic Modules>. diff --git a/pod/modpods/strict.pod b/pod/modpods/strict.pod new file mode 100644 index 0000000000..e994ed2bc5 --- /dev/null +++ b/pod/modpods/strict.pod @@ -0,0 +1,65 @@ +=head1 NAME + +strict - Perl pragma to restrict unsafe constructs + +=head1 SYNOPSIS + + use strict; + + use strict "vars"; + use strict "refs"; + use strict "subs"; + + use strict; + no strict "vars"; + +=head1 DESCRIPTION + +If no import list is supplied, all possible restrictions are assumed. +(This the safest mode to operate in, but is sometimes too strict for +casual programming.) Currently, there are three possible things to be +strict about: "subs", "vars", or "refs". + +=over 6 + +=item C<strict refs> + +This generates a runtime error if you +use symbolic references (see L<perlref>). + + use strict 'refs'; + $ref = \$foo; + print $$ref; # ok + $ref = "foo"; + print $$ref; # runtime error; normally ok + +=item C<strict vars> + +This generates a compile-time error if you access a variable that wasn't +localized via C<my()> or wasn't fully qualified. Because this is to avoid +variable suicide problems and subtle dynamic scoping issues, a merely +local() variable isn't good enough. See L<perlfunc/my> and +L<perlfunc/local>. + + use strict 'vars'; + $X::foo = 1; # ok, fully qualified + my $foo = 10; # ok, my() var + local $foo = 9; # blows up + +The local() generated a compile-time error because you just touched a global +name without fully qualifying it. + +=item C<strict subs> + +This disables the poetry optimization, +generating a compile-time error if you +try to use a bareword identifiers that's not a subroutine. + + use strict 'subs'; + $SIG{PIPE} = Plumber; # blows up + $SIG{"PIPE"} = "Plumber"; # just fine + +=back + +See L<perlmod/Pragmatic Modules>. + diff --git a/pod/modpods/subs.pod b/pod/modpods/subs.pod new file mode 100644 index 0000000000..b54b6754ce --- /dev/null +++ b/pod/modpods/subs.pod @@ -0,0 +1,16 @@ +=head1 NAME + +subs - Perl pragma to predeclare sub names + +=head1 SYNOPSIS + + use subs qw(frob); + frob 3..10; + +=head1 DESCRIPTION + +This will predeclare all the subroutine whose names are +in the list, allowing you to use them without parentheses +even before they're declared. + +See L<perlmod/Pragmatic Modules> and L<strict/subs>. |