diff options
Diffstat (limited to 'contrib/perl5/pod')
52 files changed, 6139 insertions, 1381 deletions
diff --git a/contrib/perl5/pod/Makefile b/contrib/perl5/pod/Makefile index 9187c84..eb3fcfe 100644 --- a/contrib/perl5/pod/Makefile +++ b/contrib/perl5/pod/Makefile @@ -16,12 +16,14 @@ REALPERL = ../perl POD = \ perl.pod \ perldelta.pod \ + perl5004delta.pod \ perldata.pod \ perlsyn.pod \ perlop.pod \ perlre.pod \ perlrun.pod \ perlfunc.pod \ + perlopentut.pod \ perlvar.pod \ perlsub.pod \ perlmod.pod \ @@ -30,6 +32,7 @@ POD = \ perlform.pod \ perllocale.pod \ perlref.pod \ + perlreftut.pod \ perldsc.pod \ perllol.pod \ perltoot.pod \ @@ -37,6 +40,7 @@ POD = \ perltie.pod \ perlbot.pod \ perlipc.pod \ + perlthrtut.pod \ perldebug.pod \ perldiag.pod \ perlsec.pod \ @@ -51,6 +55,7 @@ POD = \ perlxstut.pod \ perlguts.pod \ perlcall.pod \ + perlhist.pod \ perlfaq.pod \ perlfaq1.pod \ perlfaq2.pod \ @@ -66,12 +71,14 @@ POD = \ MAN = \ perl.man \ perldelta.man \ + perl5004delta.man \ perldata.man \ perlsyn.man \ perlop.man \ perlre.man \ perlrun.man \ perlfunc.man \ + perlopentut.man \ perlvar.man \ perlsub.man \ perlmod.man \ @@ -80,6 +87,7 @@ MAN = \ perlform.man \ perllocale.man \ perlref.man \ + perlreftut.man \ perldsc.man \ perllol.man \ perltoot.man \ @@ -87,6 +95,7 @@ MAN = \ perltie.man \ perlbot.man \ perlipc.man \ + perlthrtut.man \ perldebug.man \ perldiag.man \ perlsec.man \ @@ -101,6 +110,7 @@ MAN = \ perlxstut.man \ perlguts.man \ perlcall.man \ + perlhist.man \ perlfaq.man \ perlfaq1.man \ perlfaq2.man \ @@ -116,12 +126,14 @@ MAN = \ HTML = \ perl.html \ perldelta.html \ + perl5004delta.html \ perldata.html \ perlsyn.html \ perlop.html \ perlre.html \ perlrun.html \ perlfunc.html \ + perlopentut.html \ perlvar.html \ perlsub.html \ perlmod.html \ @@ -130,6 +142,7 @@ HTML = \ perlform.html \ perllocale.html \ perlref.html \ + perlreftut.html \ perldsc.html \ perllol.html \ perltoot.html \ @@ -137,6 +150,7 @@ HTML = \ perltie.html \ perlbot.html \ perlipc.html \ + perlthrtut.html \ perldebug.html \ perldiag.html \ perlsec.html \ @@ -151,6 +165,7 @@ HTML = \ perlxstut.html \ perlguts.html \ perlcall.html \ + perlhist.html \ perlfaq.html \ perlfaq1.html \ perlfaq2.html \ @@ -166,12 +181,14 @@ HTML = \ TEX = \ perl.tex \ perldelta.tex \ + perl5004delta.tex \ perldata.tex \ perlsyn.tex \ perlop.tex \ perlre.tex \ perlrun.tex \ perlfunc.tex \ + perlopentut.tex \ perlvar.tex \ perlsub.tex \ perlmod.tex \ @@ -180,6 +197,8 @@ TEX = \ perlform.tex \ perllocale.tex \ perlref.tex \ + perlreftut.tex \ + perlopentut.tex \ perldsc.tex \ perllol.tex \ perltoot.tex \ @@ -187,6 +206,7 @@ TEX = \ perltie.tex \ perlbot.tex \ perlipc.tex \ + perlthrtut.tex \ perldebug.tex \ perldiag.tex \ perlsec.tex \ @@ -201,6 +221,7 @@ TEX = \ perlxstut.tex \ perlguts.tex \ perlcall.tex \ + perlhist.tex \ perlfaq.tex \ perlfaq1.tex \ perlfaq2.tex \ diff --git a/contrib/perl5/pod/buildtoc b/contrib/perl5/pod/buildtoc index 80ca2ec..a4b9d5a 100644 --- a/contrib/perl5/pod/buildtoc +++ b/contrib/perl5/pod/buildtoc @@ -6,10 +6,10 @@ sub output ($); @pods = qw( perl perlfaq perlfaq1 perlfaq2 perlfaq3 perlfaq4 perlfaq5 - perlfaq6 perlfaq7 perlfaq8 perlfaq9 perldelta perldata - perlsyn perlop perlre perlrun perlfunc perlvar perlsub + perlfaq6 perlfaq7 perlfaq8 perlfaq9 perldelta perldata perlopentut + perlsyn perlop perlre perlreftut perlrun perlfunc perlvar perlsub perlmod perlmodlib perlmodinstall perlform perllocale perlref perldsc - perllol perltoot perlobj perltie perlbot perlipc perldebug + perllol perltoot perlobj perltie perlthrtut perlbot perlipc perldebug perldiag perlsec perltrap perlport perlstyle perlpod perlbook perlembed perlapio perlxs perlxstut perlguts perlcall perlhist diff --git a/contrib/perl5/pod/perl.pod b/contrib/perl5/pod/perl.pod index 0b9e9fa..6e218cd 100644 --- a/contrib/perl5/pod/perl.pod +++ b/contrib/perl5/pod/perl.pod @@ -20,6 +20,7 @@ of sections: perl Perl overview (this section) perldelta Perl changes since previous version + perl5004delta Perl changes in version 5.004 perlfaq Perl frequently asked questions perltoc Perl documentation table of contents @@ -29,6 +30,7 @@ of sections: perlre Perl regular expressions perlrun Perl execution and options perlfunc Perl builtin functions + perlopentut Perl open() tutorial perlvar Perl predefined variables perlsub Perl subroutines perlmod Perl modules: how they work @@ -38,6 +40,7 @@ of sections: perllocale Perl locale support perlref Perl references + perlreftut Perl references short introduction perldsc Perl data structures intro perllol Perl data structures: lists of lists perltoot Perl OO tutorial @@ -45,6 +48,7 @@ of sections: perltie Perl objects hidden behind simple variables perlbot Perl OO tricks and examples perlipc Perl interprocess communication + perlthrtut Perl threads tutorial perldebug Perl debugging perldiag Perl diagnostic messages @@ -68,8 +72,8 @@ of sections: (If you're intending to read these straight through for the first time, the suggested order will tend to reduce the number of forward references.) -By default, all of the above manpages are installed in the -F</usr/local/man/> directory. +By default, all of the above manpages are installed in the +F</usr/local/man/> directory. Extensive additional documentation for Perl modules is available. The default configuration for perl will place this additional documentation @@ -116,9 +120,9 @@ BASIC-PLUS.) Expression syntax corresponds quite closely to C expression syntax. Unlike most Unix utilities, Perl does not arbitrarily limit the size of your data--if you've got the memory, Perl can slurp in your whole file as a single string. Recursion is of -unlimited depth. And the tables used by hashes (previously called +unlimited depth. And the tables used by hashes (sometimes called "associative arrays") grow as necessary to prevent degraded -performance. Perl uses sophisticated pattern matching techniques to +performance. Perl can use sophisticated pattern matching techniques to scan large amounts of data very quickly. Although optimized for scanning text, Perl can also deal with binary data, and can make dbm files look like hashes. Setuid Perl scripts are safer than C programs @@ -239,6 +243,79 @@ optimized C code. Okay, that's I<definitely> enough hype. +=head1 AVAILABILITY + +Perl is available for the vast majority of operating system platforms, +including most Unix-like platforms. The following situation is as of +February 1999 and Perl 5.005_03. + +The following platforms are able to build Perl from the standard +source code distribution available at +F<http://www.perl.com/CPAN/src/index.html> + + AIX Linux SCO ODT/OSR + A/UX MachTen Solaris + BeOS MPE/iX SunOS + BSD/OS NetBSD SVR4 + DG/UX NextSTEP Tru64 UNIX 3) + DomainOS OpenBSD Ultrix + DOS DJGPP 1) OpenSTEP UNICOS + DYNIX/ptx OS/2 VMS + FreeBSD OS390 2) VOS + HP-UX PowerMAX Windows 3.1 1) + Hurd QNX Windows 95 1) 4) + IRIX Windows 98 1) 4) + Windows NT 1) 4) + + 1) in DOS mode either the DOS or OS/2 ports can be used + 2) formerly known as MVS + 3) formerly known as Digital UNIX and before that DEC OSF/1 + 4) compilers: Borland, Cygwin32, Mingw32 EGCS/GCC, VC++ + +The following platforms have been known to build Perl from the source +but for the Perl release 5.005_03 we haven't been able to verify them, +either because the hardware/software platforms are rather rare or +because we don't have an active champion on these platforms, or both. + + 3b1 FPS Plan 9 + AmigaOS GENIX PowerUX + ConvexOS Greenhills RISC/os + CX/UX ISC Stellar + DC/OSx MachTen 68k SVR2 + DDE SMES MiNT TI1500 + DOS EMX MPC TitanOS + Dynix NEWS-OS UNICOS/mk + EP/IX Opus Unisys Dynix + ESIX Unixware + +The following platforms are planned to be supported in the standard +source code distribution of the Perl release 5.006 but are not +supported in the Perl release 5.005_03: + + BS2000 + Netware + Rhapsody + VM/ESA + +The following platforms have their own source code distributions and +binaries available via F<http://www.perl.com/CPAN/ports/index.html>. + + Perl release + + AS/400 5.003 + MacOS 5.004 + Netware 5.003_07 + Tandem Guardian 5.004 + +The following platforms have only binaries available via +F<http://www.perl.com/CPAN/ports/index.html>. + + Perl release + + Acorn RISCOS 5.005_02 + AOS 5.002 + LynxOS 5.004_02 + =head1 ENVIRONMENT See L<perlrun>. @@ -247,14 +324,13 @@ See L<perlrun>. Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks. -If your Perl success stories and testimonials may be of help to others -who wish to advocate the use of Perl in their applications, -or if you wish to simply express your gratitude to Larry and the +If your Perl success stories and testimonials may be of help to others +who wish to advocate the use of Perl in their applications, +or if you wish to simply express your gratitude to Larry and the Perl developers, please write to <F<perl-thanks@perl.org>>. =head1 FILES - "/tmp/perl-e$$" temporary file for -e commands "@INC" locations of perl libraries =head1 SEE ALSO @@ -296,9 +372,10 @@ and syswrite().) While none of the built-in data types have any arbitrary size limits (apart from memory size), there are still a few arbitrary limits: a -given variable name may not be longer than 255 characters, and no -component of your PATH may be longer than 255 if you use B<-S>. A regular -expression may not compile to more than 32767 bytes internally. +given variable name may not be longer than 251 characters. Line numbers +displayed by diagnostics are internally stored as short integers, +so they are limited to a maximum of 65535 (higher numbers usually being +affected by wraparound). You may mail your bug reports (be sure to include full configuration information as output by the myconfig program in the perl source tree, diff --git a/contrib/perl5/pod/perl5004delta.pod b/contrib/perl5/pod/perl5004delta.pod index f1b6c8f..323830b 100644 --- a/contrib/perl5/pod/perl5004delta.pod +++ b/contrib/perl5/pod/perl5004delta.pod @@ -1432,7 +1432,7 @@ subscript, which can do weird things if you're expecting only one subscript. =item Stub found while resolving method `%s' overloading `%s' in package `%s' (P) Overloading resolution over @ISA tree may be broken by importing stubs. -Stubs should never be implicitely created, but explicit calls to C<can> +Stubs should never be implicitly created, but explicit calls to C<can> may break this. =item Too late for "B<-T>" option diff --git a/contrib/perl5/pod/perlcall.pod b/contrib/perl5/pod/perlcall.pod index c239cfe..2b83780 100644 --- a/contrib/perl5/pod/perlcall.pod +++ b/contrib/perl5/pod/perlcall.pod @@ -72,7 +72,7 @@ Each of the functions will now be discussed in turn. =over 5 -=item B<perl_call_sv> +=item perl_call_sv I<perl_call_sv> takes two parameters, the first, C<sv>, is an SV*. This allows you to specify the Perl subroutine to be called either as a @@ -80,7 +80,7 @@ C string (which has first been converted to an SV) or a reference to a subroutine. The section, I<Using perl_call_sv>, shows how you can make use of I<perl_call_sv>. -=item B<perl_call_pv> +=item perl_call_pv The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it expects its first parameter to be a C char* which identifies the Perl @@ -88,7 +88,7 @@ subroutine you want to call, e.g., C<perl_call_pv("fred", 0)>. If the subroutine you want to call is in another package, just include the package name in the string, e.g., C<"pkg::fred">. -=item B<perl_call_method> +=item perl_call_method The function I<perl_call_method> is used to call a method from a Perl class. The parameter C<methname> corresponds to the name of the method @@ -99,7 +99,7 @@ object (for a virtual method). See L<perlobj> for more information on static and virtual methods and L<Using perl_call_method> for an example of using I<perl_call_method>. -=item B<perl_call_argv> +=item perl_call_argv I<perl_call_argv> calls the Perl subroutine specified by the C string stored in the C<subname> parameter. It also takes the usual C<flags> @@ -971,7 +971,8 @@ and some C to call it /* Check the eval first */ if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; + STRLEN n_a; + printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ; POPs ; } else @@ -1013,7 +1014,8 @@ The code if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; + STRLEN n_a; + printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ; POPs ; } @@ -1923,8 +1925,8 @@ refers to the last. =head2 Creating and calling an anonymous subroutine in C As we've already shown, C<perl_call_sv> can be used to invoke an -anonymous subroutine. However, our example showed how Perl script -invoking an XSUB to preform this operation. Let's see how it can be +anonymous subroutine. However, our example showed a Perl script +invoking an XSUB to perform this operation. Let's see how it can be done inside our C code: ... diff --git a/contrib/perl5/pod/perldata.pod b/contrib/perl5/pod/perldata.pod index 58c1123..9e41c2c 100644 --- a/contrib/perl5/pod/perldata.pod +++ b/contrib/perl5/pod/perldata.pod @@ -253,7 +253,7 @@ literals are subject to backslash and variable substitution; single-quoted strings are not (except for "C<\'>" and "C<\\>"). The usual Unix backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic forms. See -L<perlop/Quote and Quotelike Operators> for a list. +L<perlop/"Quote and Quotelike Operators"> for a list. Octal or hex representations in string literals (e.g. '0xffff') are not automatically converted to their integer representation. The hex() and @@ -471,7 +471,7 @@ is legal to assign to: ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00); -Array assignment in a scalar context returns the number of elements +List assignment in a scalar context returns the number of elements produced by the expression on the right side of the assignment: $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2 diff --git a/contrib/perl5/pod/perldebug.pod b/contrib/perl5/pod/perldebug.pod index 7a6e814..760d517 100644 --- a/contrib/perl5/pod/perldebug.pod +++ b/contrib/perl5/pod/perldebug.pod @@ -1109,7 +1109,7 @@ or B<pop>, the stack backtrace will not show the original values. Perl is I<very> frivolous with memory. There is a saying that to estimate memory usage of Perl, assume a reasonable algorithm of -allocation, and multiply your estimages by 10. This is not absolutely +allocation, and multiply your estimates by 10. This is not absolutely true, but may give you a good grasp of what happens. Say, an integer cannot take less than 20 bytes of memory, a float @@ -1161,7 +1161,7 @@ in the following example: Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. It is possible to ask for such a statistic at arbitrary moment by -usind Devel::Peek::mstats() (module Devel::Peek is available on CPAN). +using Devel::Peek::mstats() (module Devel::Peek is available on CPAN). Here is the explanation of different parts of the format: @@ -1195,7 +1195,7 @@ memory footprints of the buckets are between memory footprints of two buckets "above". Say, with the above example the memory footprints are (with current -algorith) +algorithm) free: 8 16 32 64 128 256 512 1024 2048 4096 8192 4 12 24 48 80 @@ -1328,7 +1328,7 @@ though the subroutine itself is not defined yet). It also creates C arrays to keep data for the stash (this is one HV, but it grows, thus there are 4 big allocations: the big chunks are not -freeed, but are kept as additional arenas for C<SV> allocations). +freed, but are kept as additional arenas for C<SV> allocations). =item C<054> diff --git a/contrib/perl5/pod/perldelta.pod b/contrib/perl5/pod/perldelta.pod index a3c6b6c..a0af1e1 100644 --- a/contrib/perl5/pod/perldelta.pod +++ b/contrib/perl5/pod/perldelta.pod @@ -85,7 +85,7 @@ begin with C<perl> be referenced with a C<Perl_> prefix. The bare function names without the C<Perl_> prefix are supported with macros, but this support may cease in a future release. -See L<perlguts/API LISTING>. +See L<perlguts/"API LISTING">. =item Enabling threads has source compatibility issues @@ -100,7 +100,7 @@ directly accessing perl globals as C<GvSV(errgv)>. The API call is backward compatible with existing perls and provides source compatibility with threading is enabled. -See L<API Changes for more information>. +See L<"C Source Compatibility"> for more information. =back @@ -153,6 +153,9 @@ and some bugs. These are expected to be fixed in future versions. See L<README.threads>. +Mach cthreads (NEXTSTEP, OPENSTEP, Rhapsody) are now supported by +the Thread extension. + =head2 Compiler WARNING: The Compiler and related tools are considered B<experimental>. @@ -310,7 +313,7 @@ and in XSUBs. Perl used to complain if it encountered literal carriage returns in scripts. Now they are mostly treated like whitespace within program text. Inside string literals and here documents, literal carriage returns are -ignored if they occur paired with newlines, or get interpreted as newlines +ignored if they occur paired with linefeeds, or get interpreted as whitespace if they stand alone. This behavior means that literal carriage returns in files should be avoided. You can get the older, more compatible (but less generous) behavior by defining the preprocessor symbol @@ -488,6 +491,30 @@ If C<$/> is a referenence to an integer, or a scalar that holds an integer, E<lt>E<gt> will read in records instead of lines. For more info, see L<perlvar/$/>. +=head2 pack() format 'Z' supported + +The new format type 'Z' is useful for packing and unpacking null-terminated +strings. See L<perlfunc/"pack">. + +=head1 Significant bug fixes + +=head2 E<lt>HANDLEE<gt> on empty files + +With C<$/> set to C<undef>, slurping an empty file returns a string of +zero length (instead of C<undef>, as it used to) for the first time the +HANDLE is read. Subsequent reads yield C<undef>. + +This means that the following will append "foo" to an empty file (it used +to not do anything before): + + perl -0777 -pi -e 's/^/foo/' empty_file + +Note that the behavior of: + + perl -pi -e 's/^/foo/' empty_file + +is unchanged (it continues to leave the file empty). + =head1 Supported Platforms Configure has many incremental improvements. Site-wide policy for building @@ -500,9 +527,15 @@ BeOS is now supported. See L<README.beos>. DOS is now supported under the DJGPP tools. See L<README.dos>. +GNU/Hurd is now supported. + +MiNT is now supported. See L<README.mint>. + MPE/iX is now supported. See L<README.mpeix>. -MVS (OS390) is now supported. See L<README.os390>. +MVS (aka OS390, aka Open Edition) is now supported. See L<README.os390>. + +Stratus VOS is now supported. See L<README.vos>. =head2 Changes in existing support @@ -528,6 +561,10 @@ Perl compiler and tools. See L<B>. A module to pretty print Perl data. See L<Data::Dumper>. +=item Dumpvalue + +A module to dump perl values to the screen. See L<Dumpvalue>. + =item Errno A module to look up errors more conveniently. See L<Errno>. @@ -587,10 +624,52 @@ Various pragmata to control behavior of regular expressions. =over +=item Benchmark + +You can now run tests for I<n> seconds instead of guessing the right +number of tests to run: e.g. timethese(-5, ...) will run each of the +codes for at least 5 CPU seconds. Zero as the "number of repetitions" +means "for at least 3 CPU seconds". The output format has also +changed. For example: + +use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}}) + +will now output something like this: + +Benchmark: running a, b, each for at least 5 CPU seconds... + a: 5 wallclock secs ( 5.77 usr + 0.00 sys = 5.77 CPU) @ 200551.91/s (n=1156516) + b: 4 wallclock secs ( 5.00 usr + 0.02 sys = 5.02 CPU) @ 159605.18/s (n=800686) + +New features: "each for at least N CPU seconds...", "wallclock secs", +and the "@ operations/CPU second (n=operations)". + +=item Carp + +Carp has a new function cluck(). cluck() warns, like carp(), but also adds +a stack backtrace to the error message, like confess(). + =item CGI CGI has been updated to version 2.42. +=item Fcntl + +More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for +large (more than 4G) file access (the 64-bit support is not yet +working, though, so no need to get overly excited), Free/Net/OpenBSD +locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and +O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR. + +=item Math::Complex + +The accessor methods Re, Im, arg, abs, rho, and theta, can now also +act as mutators (accessor $z->Re(), mutator $z->Re(3)). + +=item Math::Trig + +A little bit of radial trigonometry (cylindrical and spherical) added: +radial coordinate conversions and the great circle distance. + =item POSIX POSIX now has its own platform-specific hints files. @@ -655,6 +734,12 @@ sites. Some more Perl traps are documented now. See L<perltrap>. +L<perlopentut> gives a tutorial on using open(). + +L<perlreftut> gives a tutorial on references. + +L<perlthrtut> gives a tutorial on threads. + =head1 New Diagnostics =over @@ -697,6 +782,10 @@ Something like this will reproduce the error: process $BADREF 1,2,3; $BADREF->process(1,2,3); +=item Can't check filesystem of script "%s" for nosuid + +(P) For some reason you can't check the filesystem of the script for nosuid. + =item Can't coerce array into hash (F) You used an array where a hash was expected, but the array has no @@ -776,7 +865,7 @@ See L<perlre/(?{ code })>. (W) You are blessing a reference to a zero length string. This has the effect of blessing the reference into the package main. This is usually not what you want. Consider providing a default target -package, e.g. bless($ref, $p or 'MyPackage'); +package, e.g. bless($ref, $p || 'MyPackage'); =item Illegal hex digit ignored @@ -860,7 +949,7 @@ not use those settings. This was not dead serious, fortunately: there is a "default locale" called "C" that Perl can and will use, the script will be run. Before you really fix the problem, however, you will get the same error message each time you run Perl. How to really -fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. +fix the problem can be found in L<perllocale/"LOCALE PROBLEMS">. =back @@ -874,18 +963,39 @@ fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. (F) The mktemp() routine failed for some reason while trying to process a B<-e> switch. Maybe your /tmp partition is full, or clobbered. +Removed because B<-e> doesn't use temporary files any more. + =item Can't write to temp file for B<-e>: %s (F) The write routine failed for some reason while trying to process a B<-e> switch. Maybe your /tmp partition is full, or clobbered. +Removed because B<-e> doesn't use temporary files any more. + =item Cannot open temporary file (F) The create routine failed for some reason while trying to process a B<-e> switch. Maybe your /tmp partition is full, or clobbered. +Removed because B<-e> doesn't use temporary files any more. + +=item regexp too big + +(F) The current implementation of regular expressions uses shorts as +address offsets within a string. Unfortunately this means that if +the regular expression compiles to longer than 32767, it'll blow up. +Usually when you want a regular expression this big, there is a better +way to do it with multiple statements. See L<perlre>. + =back +=head1 Configuration Changes + +You can use "Configure -Uinstallusrbinperl" which causes installperl +to skip installing perl also as /usr/bin/perl. This is useful if you +prefer not to modify /usr/bin for some reason or another but harmful +because many scripts assume to find Perl in /usr/bin/perl. + =head1 BUGS If you find what you think is a bug, you might check the headers of diff --git a/contrib/perl5/pod/perldiag.pod b/contrib/perl5/pod/perldiag.pod index 8d21323..fe31991 100644 --- a/contrib/perl5/pod/perldiag.pod +++ b/contrib/perl5/pod/perldiag.pod @@ -33,11 +33,11 @@ The symbols C<"%(-?@> sort before the letters, while C<[> and C<\> sort after. to try to declare one with a package qualifier on the front. Use local() if you want to localize a package variable. -=item "my" variable %s masks earlier declaration in same scope +=item "my" variable %s masks earlier declaration in same %s -(W) A lexical variable has been redeclared in the same scope, effectively -eliminating all access to the previous instance. This is almost always -a typographical error. Note that the earlier variable will still exist +(W) A lexical variable has been redeclared in the current scope or statement, +effectively eliminating all access to the previous instance. This is almost +always a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed. @@ -143,6 +143,18 @@ Perl yourself. instead of Perl. Check the #! line, or manually feed your script into Perl yourself. +=item (in cleanup) %s + +(W) This prefix usually indicates that a DESTROY() method raised +the indicated exception. Since destructors are usually called by +the system at arbitrary points during execution, and often a vast +number of times, the warning is issued only once for any number +of failures that would otherwise result in the same message being +repeated. + +Failure of user callbacks dispatched using the C<G_KEEPERR> flag +could also result in this warning. See L<perlcall/G_KEEPERR>. + =item (Missing semicolon on previous line?) (S) This is an educated guess made in conjunction with the message "%s @@ -376,7 +388,7 @@ Perl yourself. =item Bareword "%s" not allowed while "strict subs" in use (F) With "strict subs" in use, a bareword is only allowed as a -subroutine identifier, in curly braces or to the left of the "=>" symbol. +subroutine identifier, in curly brackets or to the left of the "=>" symbol. Perhaps you need to predeclare a subroutine? =item Bareword "%s" refers to nonexistent package @@ -499,6 +511,10 @@ Something like this will reproduce the error: (F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory that you can chdir to, possibly because it doesn't exist. +=item Can't check filesystem of script "%s" for nosuid + +(P) For some reason you can't check the filesystem of the script for nosuid. + =item Can't coerce %s to integer in %s (F) Certain types of SVs, in particular real symbol table entries @@ -1002,6 +1018,14 @@ for information on I<Mastering Regular Expressions>.) (W) You tried to do a connect on a closed socket. Did you forget to check the return value of your socket() call? See L<perlfunc/connect>. +=item Constant is not %s reference + +(F) A constant value (perhaps declared using the C<use constant> pragma) +is being dereferenced, but it amounts to the wrong type of reference. The +message indicates the type of reference that was expected. This usually +indicates a syntax error in dereferencing the constant value. +See L<perlsub/"Constant Functions"> and L<constant>. + =item Constant subroutine %s redefined (S) You redefined a subroutine which had previously been eligible for @@ -1162,7 +1186,7 @@ a return, a goto, or a loop control statement. (W) You are blessing a reference to a zero length string. This has the effect of blessing the reference into the package main. This is usually not what you want. Consider providing a default target -package, e.g. bless($ref, $p or 'MyPackage'); +package, e.g. bless($ref, $p || 'MyPackage'); =item Fatal VMS error at %s, line %d @@ -1258,7 +1282,6 @@ Did you forget to check the return value of your socket() call? (S) A warning peculiar to VMS. The call to C<sys$getuai> underlying the C<getpwnam> operator returned an invalid UIC. - =item Glob not terminated (F) The lexer saw a left angle bracket in a place where it was expecting @@ -1404,7 +1427,7 @@ architecture. On a 32-bit architecture the largest octal literal is (S) A warning peculiar to VMS. Perl keeps track of the number of times you've called C<fork> and C<exec>, to determine whether the current call to C<exec> should affect the current -script or a subprocess (see L<perlvms/exec>). Somehow, this count +script or a subprocess (see L<perlvms/"exec LIST">). Somehow, this count has become scrambled, so Perl is making a guess and treating this C<exec> as a request to terminate the Perl script and execute the specified command. @@ -1413,16 +1436,19 @@ and execute the specified command. (P) Something went badly wrong in the regular expression parser. -=item internal error: glob failed +=item glob failed (%s) -(P) Something went wrong with the external program(s) used for C<glob> -and C<E<lt>*.cE<gt>>. This may mean that your csh (C shell) is -broken. If so, you should change all of the csh-related variables in -config.sh: If you have tcsh, make the variables refer to it as if it -were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all -empty (except that C<d_csh> should be C<'undef'>) so that Perl will -think csh is missing. In either case, after editing config.sh, run -C<./Configure -S> and rebuild Perl. +(W) Something went wrong with the external program(s) used for C<glob> +and C<E<lt>*.cE<gt>>. Usually, this means that you supplied a C<glob> +pattern that caused the external program to fail and exit with a nonzero +status. If the message indicates that the abnormal exit resulted in a +coredump, this may also mean that your csh (C shell) is broken. If so, +you should change all of the csh-related variables in config.sh: If you +have tcsh, make the variables refer to it as if it were csh (e.g. +C<full_csh='/usr/bin/tcsh'>); otherwise, make them all empty (except that +C<d_csh> should be C<'undef'>) so that Perl will think csh is missing. +In either case, after editing config.sh, run C<./Configure -S> and +rebuild Perl. =item internal urp in regexp at /%s/ @@ -2322,12 +2348,14 @@ from the user it isn't running under, and isn't in a location where the CGI server can't find it, basically, more or less. Please see the following for more information: - http://www.perl.com/perl/faq/idiots-guide.html - http://www.perl.com/perl/faq/perl-cgi-faq.html + http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html + http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html ftp://rtfm.mit.edu/pub/usenet/news.answers/www/cgi-faq http://hoohoo.ncsa.uiuc.edu/cgi/interface.html http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html +You should also look at L<perlfaq9>. + =item setegid() not implemented (F) You tried to assign to C<$)>, and your operating system doesn't support @@ -2405,6 +2433,14 @@ there was a failure. You probably wanted to use system() instead, which does return. To suppress this warning, put the exec() in a block by itself. +=item Strange *+?{} on zero-length expression + +(W) You applied a regular expression quantifier in a place where it +makes no sense, such as on a zero-width assertion. +Try putting the quantifier inside the assertion instead. For example, +the way to match "abc" provided that it is followed by three +repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. + =item Stub found while resolving method `%s' overloading `%s' in package `%s' (P) Overloading resolution over @ISA tree may be broken by importation stubs. diff --git a/contrib/perl5/pod/perldsc.pod b/contrib/perl5/pod/perldsc.pod index d0cc335..ef3ae75 100644 --- a/contrib/perl5/pod/perldsc.pod +++ b/contrib/perl5/pod/perldsc.pod @@ -690,7 +690,7 @@ many different sorts: print $rec->{TEXT}; - print $rec->{LIST}[0]; + print $rec->{SEQUENCE}[0]; $last = pop @ { $rec->{SEQUENCE} }; print $rec->{LOOKUP}{"key"}; diff --git a/contrib/perl5/pod/perlembed.pod b/contrib/perl5/pod/perlembed.pod index c09d6e3..03c5507 100644 --- a/contrib/perl5/pod/perlembed.pod +++ b/contrib/perl5/pod/perlembed.pod @@ -141,7 +141,7 @@ you: If the B<ExtUtils::Embed> module isn't part of your Perl distribution, you can retrieve it from -http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils::Embed. (If +http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/. (If this documentation came from your Perl distribution, then you're running 5.004 or better and you already have it.) @@ -285,6 +285,7 @@ the first, a C<float> from the second, and a C<char *> from the third. main (int argc, char **argv, char **env) { + STRLEN n_a; char *embedding[] = { "", "-e", "0" }; my_perl = perl_alloc(); @@ -303,7 +304,7 @@ the first, a C<float> from the second, and a C<char *> from the third. /** Treat $a as a string **/ perl_eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE); - printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), PL_na)); + printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), n_a)); perl_destruct(my_perl); perl_free(my_perl); @@ -325,8 +326,9 @@ possible and in most cases a better strategy to fetch the return value from I<perl_eval_pv()> instead. Example: ... + STRLEN n_a; SV *val = perl_eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE); - printf("%s\n", SvPV(val,PL_na)); + printf("%s\n", SvPV(val,n_a)); ... This way, we avoid namespace pollution by not creating global @@ -371,6 +373,7 @@ been wrapped here): { dSP; SV* retval; + STRLEN n_a; PUSHMARK(SP); perl_eval_sv(sv, G_SCALAR); @@ -380,7 +383,7 @@ been wrapped here): PUTBACK; if (croak_on_error && SvTRUE(ERRSV)) - croak(SvPVx(ERRSV, PL_na)); + croak(SvPVx(ERRSV, n_a)); return retval; } @@ -395,9 +398,10 @@ been wrapped here): I32 match(SV *string, char *pattern) { SV *command = NEWSV(1099, 0), *retval; + STRLEN n_a; sv_setpvf(command, "my $string = '%s'; $string =~ %s", - SvPV(string,PL_na), pattern); + SvPV(string,n_a), pattern); retval = my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -416,9 +420,10 @@ been wrapped here): I32 substitute(SV **string, char *pattern) { SV *command = NEWSV(1099, 0), *retval; + STRLEN n_a; sv_setpvf(command, "$string = '%s'; ($string =~ %s)", - SvPV(*string,PL_na), pattern); + SvPV(*string,n_a), pattern); retval = my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -439,9 +444,10 @@ been wrapped here): { SV *command = NEWSV(1099, 0); I32 num_matches; + STRLEN n_a; sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", - SvPV(string,PL_na), pattern); + SvPV(string,n_a), pattern); my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -459,6 +465,7 @@ been wrapped here): AV *match_list; I32 num_matches, i; SV *text = NEWSV(1099,0); + STRLEN n_a; perl_construct(my_perl); perl_parse(my_perl, NULL, 3, embedding, NULL); @@ -480,7 +487,7 @@ been wrapped here): printf("matches: m/(wi..)/g found %d matches...\n", num_matches); for (i = 0; i < num_matches; i++) - printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),PL_na)); + printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a)); printf("\n"); /** Remove all vowels from text **/ @@ -488,7 +495,7 @@ been wrapped here): if (num_matches) { printf("substitute: s/[aeiou]//gi...%d substitutions made.\n", num_matches); - printf("Now text is: %s\n\n", SvPV(text,PL_na)); + printf("Now text is: %s\n\n", SvPV(text,n_a)); } /** Attempt a substitution **/ @@ -726,6 +733,7 @@ with L<perlfunc/my> whenever possible. char *args[] = { "", DO_CLEAN, NULL }; char filename [1024]; int exitstatus = 0; + STRLEN n_a; if((perl = perl_alloc()) == NULL) { fprintf(stderr, "no memory!"); @@ -747,7 +755,7 @@ with L<perlfunc/my> whenever possible. /* check $@ */ if(SvTRUE(ERRSV)) - fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,PL_na)); + fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a)); } } @@ -955,7 +963,7 @@ Interfacing to ActiveState's Perl library is quite different from the examples in this documentation, as significant changes were made to the internal Perl API. However, it is possible to embed ActiveState's Perl runtime. For details, see the Perl for Win32 FAQ at -http://www.perl.com/perl/faq/win32/Perl_for_Win32_FAQ.html. +http://www.perl.com/CPAN/doc/FAQs/win32/perlwin32faq.html. With the "official" Perl version 5.004 or higher, all the examples within this documentation will compile and run untouched, although diff --git a/contrib/perl5/pod/perlfaq.pod b/contrib/perl5/pod/perlfaq.pod index e6be112..cb35493 100644 --- a/contrib/perl5/pod/perlfaq.pod +++ b/contrib/perl5/pod/perlfaq.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq - frequently asked questions about Perl ($Date: 1998/08/05 12:09:32 $) +perlfaq - frequently asked questions about Perl ($Date: 1999/01/08 05:54:52 $) =head1 DESCRIPTION @@ -16,42 +16,682 @@ This document. Very general, high-level information about Perl. +=over 4 + +=item * What is Perl? + +=item * Who supports Perl? Who develops it? Why is it free? + +=item * Which version of Perl should I use? + +=item * What are perl4 and perl5? + +=item * What is perl6? + +=item * How stable is Perl? + +=item * Is Perl difficult to learn? + +=item * How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl? + +=item * Can I do [task] in Perl? + +=item * When shouldn't I program in Perl? + +=item * What's the difference between "perl" and "Perl"? + +=item * Is it a Perl program or a Perl script? + +=item * What is a JAPH? + +=item * Where can I get a list of Larry Wall witticisms? + +=item * How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)? + +=back + + =item L<perlfaq2>: Obtaining and Learning about Perl Where to find source and documentation to Perl, support, and related matters. +=over 4 + +=item * What machines support Perl? Where do I get it? + +=item * How can I get a binary version of Perl? + +=item * I don't have a C compiler on my system. How can I compile perl? + +=item * I copied the Perl binary from one machine to another, but scripts don't work. + +=item * I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? + +=item * What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? + +=item * Is there an ISO or ANSI certified version of Perl? + +=item * Where can I get information on Perl? + +=item * What are the Perl newsgroups on USENET? Where do I post questions? + +=item * Where should I post source code? + +=item * Perl Books + +=item * Perl in Magazines + +=item * Perl on the Net: FTP and WWW Access + +=item * What mailing lists are there for perl? + +=item * Archives of comp.lang.perl.misc + +=item * Where can I buy a commercial version of Perl? + +=item * Where do I send bug reports? + +=item * What is perl.com? + +=back + + =item L<perlfaq3>: Programming Tools Programmer tools and programming support. +=over 4 + +=item * How do I do (anything)? + +=item * How can I use Perl interactively? + +=item * Is there a Perl shell? + +=item * How do I debug my Perl programs? + +=item * How do I profile my Perl programs? + +=item * How do I cross-reference my Perl programs? + +=item * Is there a pretty-printer (formatter) for Perl? + +=item * Is there a ctags for Perl? + +=item * Is there an IDE or Windows Perl Editor? + +=item * Where can I get Perl macros for vi? + +=item * Where can I get perl-mode for emacs? + +=item * How can I use curses with Perl? + +=item * How can I use X or Tk with Perl? + +=item * How can I generate simple menus without using CGI or Tk? + +=item * What is undump? + +=item * How can I make my Perl program run faster? + +=item * How can I make my Perl program take less memory? + +=item * Is it unsafe to return a pointer to local data? + +=item * How can I free an array or hash so my program shrinks? + +=item * How can I make my CGI script more efficient? + +=item * How can I hide the source for my Perl program? + +=item * How can I compile my Perl program into byte code or C? + +=item * How can I compile Perl into Java? + +=item * How can I get C<#!perl> to work on [MS-DOS,NT,...]? + +=item * Can I write useful perl programs on the command line? + +=item * Why don't perl one-liners work on my DOS/Mac/VMS system? + +=item * Where can I learn about CGI or Web programming in Perl? + +=item * Where can I learn about object-oriented Perl programming? + +=item * Where can I learn about linking C with Perl? [h2xs, xsubpp] + +=item * I've read perlembed, perlguts, etc., but I can't embed perl in +my C program, what am I doing wrong? + +=item * When I tried to run my script, I got this message. What does it +mean? + +=item * What's MakeMaker? + +=back + + =item L<perlfaq4>: Data Manipulation Manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues. +=over 4 + +=item * Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? + +=item * Why isn't my octal data interpreted correctly? + +=item * Does Perl have a round() function? What about ceil() and floor()? Trig functions? + +=item * How do I convert bits into ints? + +=item * Why doesn't & work the way I want it to? + +=item * How do I multiply matrices? + +=item * How do I perform an operation on a series of integers? + +=item * How can I output Roman numerals? + +=item * Why aren't my random numbers random? + +=item * How do I find the week-of-the-year/day-of-the-year? + +=item * How can I compare two dates and find the difference? + +=item * How can I take a string and turn it into epoch seconds? + +=item * How can I find the Julian Day? + +=item * How do I find yesterday's date? + +=item * Does Perl have a year 2000 problem? Is Perl Y2K compliant? + +=item * How do I validate input? + +=item * How do I unescape a string? + +=item * How do I remove consecutive pairs of characters? + +=item * How do I expand function calls in a string? + +=item * How do I find matching/nesting anything? + +=item * How do I reverse a string? + +=item * How do I expand tabs in a string? + +=item * How do I reformat a paragraph? + +=item * How can I access/change the first N letters of a string? + +=item * How do I change the Nth occurrence of something? + +=item * How can I count the number of occurrences of a substring within a string? + +=item * How do I capitalize all the words on one line? + +=item * How can I split a [character] delimited string except when inside +[character]? (Comma-separated files) + +=item * How do I strip blank space from the beginning/end of a string? + +=item * How do I pad a string with blanks or pad a number with zeroes? + +=item * How do I extract selected columns from a string? + +=item * How do I find the soundex value of a string? + +=item * How can I expand variables in text strings? + +=item * What's wrong with always quoting "$vars"? + +=item * Why don't my E<lt>E<lt>HERE documents work? + +=item * What is the difference between a list and an array? + +=item * What is the difference between $array[1] and @array[1]? + +=item * How can I extract just the unique elements of an array? + +=item * How can I tell whether a list or array contains a certain element? + +=item * How do I compute the difference of two arrays? How do I compute the intersection of two arrays? + +=item * How do I test whether two arrays or hashes are equal? + +=item * How do I find the first array element for which a condition is true? + +=item * How do I handle linked lists? + +=item * How do I handle circular lists? + +=item * How do I shuffle an array randomly? + +=item * How do I process/modify each element of an array? + +=item * How do I select a random element from an array? + +=item * How do I permute N elements of a list? + +=item * How do I sort an array by (anything)? + +=item * How do I manipulate arrays of bits? + +=item * Why does defined() return true on empty arrays and hashes? + +=item * How do I process an entire hash? + +=item * What happens if I add or remove keys from a hash while iterating over it? + +=item * How do I look up a hash element by value? + +=item * How can I know how many entries are in a hash? + +=item * How do I sort a hash (optionally by value instead of key)? + +=item * How can I always keep my hash sorted? + +=item * What's the difference between "delete" and "undef" with hashes? + +=item * Why don't my tied hashes make the defined/exists distinction? + +=item * How do I reset an each() operation part-way through? + +=item * How can I get the unique keys from two hashes? + +=item * How can I store a multidimensional array in a DBM file? + +=item * How can I make my hash remember the order I put elements into it? + +=item * Why does passing a subroutine an undefined element in a hash create it? + +=item * How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? + +=item * How can I use a reference as a hash key? + +=item * How do I handle binary data correctly? + +=item * How do I determine whether a scalar is a number/whole/integer/float? + +=item * How do I keep persistent data across program calls? + +=item * How do I print out or copy a recursive data structure? + +=item * How do I define methods for every class/object? + +=item * How do I verify a credit card checksum? + +=item * How do I pack arrays of doubles or floats for XS code? + +=back + + =item L<perlfaq5>: Files and Formats I/O and the "f" issues: filehandles, flushing, formats and footers. +=over 4 + +=item * How do I flush/unbuffer an output filehandle? Why must I do this? + +=item * How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file? + +=item * How do I count the number of lines in a file? + +=item * How do I make a temporary file name? + +=item * How can I manipulate fixed-record-length files? + +=item * How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles? + +=item * How can I use a filehandle indirectly? + +=item * How can I set up a footer format to be used with write()? + +=item * How can I write() into a string? + +=item * How can I output my numbers with commas added? + +=item * How can I translate tildes (~) in a filename? + +=item * How come when I open a file read-write it wipes it out? + +=item * Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>? + +=item * Is there a leak/bug in glob()? + +=item * How can I open a file with a leading "E<gt>" or trailing blanks? + +=item * How can I reliably rename a file? + +=item * How can I lock a file? + +=item * Why can't I just open(FH, ">file.lock")? + +=item * I still don't get locking. I just want to increment the number in the file. How can I do this? + +=item * How do I randomly update a binary file? + +=item * How do I get a file's timestamp in perl? + +=item * How do I set a file's timestamp in perl? + +=item * How do I print to more than one file at once? + +=item * How can I read in a file by paragraphs? + +=item * How can I read a single character from a file? From the keyboard? + +=item * How can I tell whether there's a character waiting on a filehandle? + +=item * How do I do a C<tail -f> in perl? + +=item * How do I dup() a filehandle in Perl? + +=item * How do I close a file descriptor by number? + +=item * Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work? + +=item * Why doesn't glob("*.*") get all the files? + +=item * Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? + +=item * How do I select a random line from a file? + +=item * Why do I get weird spaces when I print an array of lines? + +=back + + =item L<perlfaq6>: Regexps Pattern matching and regular expressions. +=over 4 + +=item * How can I hope to use regular expressions without creating illegible and unmaintainable code? + +=item * I'm having trouble matching over more than one line. What's wrong? + +=item * How can I pull out lines between two patterns that are themselves on different lines? + +=item * I put a regular expression into $/ but it didn't work. What's wrong? + +=item * How do I substitute case insensitively on the LHS, but preserving case on the RHS? + +=item * How can I make C<\w> match national character sets? + +=item * How can I match a locale-smart version of C</[a-zA-Z]/>? + +=item * How can I quote a variable to use in a regexp? + +=item * What is C</o> really for? + +=item * How do I use a regular expression to strip C style comments from a file? + +=item * Can I use Perl regular expressions to match balanced text? + +=item * What does it mean that regexps are greedy? How can I get around it? + +=item * How do I process each word on each line? + +=item * How can I print out a word-frequency or line-frequency summary? + +=item * How can I do approximate matching? + +=item * How do I efficiently match many regular expressions at once? + +=item * Why don't word-boundary searches with C<\b> work for me? + +=item * Why does using $&, $`, or $' slow my program down? + +=item * What good is C<\G> in a regular expression? + +=item * Are Perl regexps DFAs or NFAs? Are they POSIX compliant? + +=item * What's wrong with using grep or map in a void context? + +=item * How can I match strings with multibyte characters? + +=item * How do I match a pattern that is supplied by the user? + +=back + + =item L<perlfaq7>: General Perl Language Issues General Perl language issues that don't clearly fit into any of the other sections. +=over 4 + +=item * Can I get a BNF/yacc/RE for the Perl language? + +=item * What are all these $@%* punctuation signs, and how do I know when to use them? + +=item * Do I always/never have to quote my strings or use semicolons and commas? + +=item * How do I skip some return values? + +=item * How do I temporarily block warnings? + +=item * What's an extension? + +=item * Why do Perl operators have different precedence than C operators? + +=item * How do I declare/create a structure? + +=item * How do I create a module? + +=item * How do I create a class? + +=item * How can I tell if a variable is tainted? + +=item * What's a closure? + +=item * What is variable suicide and how can I prevent it? + +=item * How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regexp}? + +=item * How do I create a static variable? + +=item * What's the difference between dynamic and lexical (static) scoping? Between local() and my()? + +=item * How can I access a dynamic variable while a similarly named lexical is in scope? + +=item * What's the difference between deep and shallow binding? + +=item * Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right? + +=item * How do I redefine a builtin function, operator, or method? + +=item * What's the difference between calling a function as &foo and foo()? + +=item * How do I create a switch or case statement? + +=item * How can I catch accesses to undefined variables/functions/methods? + +=item * Why can't a method included in this same file be found? + +=item * How can I find out my current package? + +=item * How can I comment out a large block of perl code? + +=item * How do I clear a package? + +=back + + =item L<perlfaq8>: System Interaction Interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices). +=over 4 + +=item * How do I find out which operating system I'm running under? + +=item * How come exec() doesn't return? + +=item * How do I do fancy stuff with the keyboard/screen/mouse? + +=item * How do I print something out in color? + +=item * How do I read just one key without waiting for a return key? + +=item * How do I check whether input is ready on the keyboard? + +=item * How do I clear the screen? + +=item * How do I get the screen size? + +=item * How do I ask the user for a password? + +=item * How do I read and write the serial port? + +=item * How do I decode encrypted password files? + +=item * How do I start a process in the background? + +=item * How do I trap control characters/signals? + +=item * How do I modify the shadow password file on a Unix system? + +=item * How do I set the time and date? + +=item * How can I sleep() or alarm() for under a second? + +=item * How can I measure time under a second? + +=item * How can I do an atexit() or setjmp()/longjmp()? (Exception handling) + +=item * Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? + +=item * How can I call my system's unique C functions from Perl? + +=item * Where do I get the include files to do ioctl() or syscall()? + +=item * Why do setuid perl scripts complain about kernel problems? + +=item * How can I open a pipe both to and from a command? + +=item * Why can't I get the output of a command with system()? + +=item * How can I capture STDERR from an external command? + +=item * Why doesn't open() return an error when a pipe open fails? + +=item * What's wrong with using backticks in a void context? + +=item * How can I call backticks without shell processing? + +=item * Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? + +=item * How can I convert my shell script to perl? + +=item * Can I use perl to run a telnet or ftp session? + +=item * How can I write expect in Perl? + +=item * Is there a way to hide perl's command line from programs such as "ps"? + +=item * I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? + +=item * How do I close a process's filehandle without waiting for it to complete? + +=item * How do I fork a daemon process? + +=item * How do I make my program run with sh and csh? + +=item * How do I find out if I'm running interactively or not? + +=item * How do I timeout a slow event? + +=item * How do I set CPU limits? + +=item * How do I avoid zombies on a Unix system? + +=item * How do I use an SQL database? + +=item * How do I make a system() exit on control-C? + +=item * How do I open a file without blocking? + +=item * How do I install a CPAN module? + +=item * What's the difference between require and use? + +=item * How do I keep my own module/library directory? + +=item * How do I add the directory my program lives in to the module/library search path? + +=item * How do I add a directory to my include path at runtime? + +=item * What is socket.ph and where do I get it? + +=back + + =item L<perlfaq9>: Networking Networking, the Internet, and a few on the web. +=over 4 + +=item * My CGI script runs from the command line but not the browser. (500 Server Error) + +=item * How can I get better error messages from a CGI program? + +=item * How do I remove HTML from a string? + +=item * How do I extract URLs? + +=item * How do I download a file from the user's machine? How do I open a file on another machine? + +=item * How do I make a pop-up menu in HTML? + +=item * How do I fetch an HTML file? + +=item * How do I automate an HTML form submission? + +=item * How do I decode or create those %-encodings on the web? + +=item * How do I redirect to another page? + +=item * How do I put a password on my web pages? + +=item * How do I edit my .htpasswd and .htgroup files with Perl? + +=item * How do I make sure users can't enter values into a form that cause my CGI script to do bad things? + +=item * How do I parse a mail header? + +=item * How do I decode a CGI form? + +=item * How do I check a valid mail address? + +=item * How do I decode a MIME/BASE64 string? + +=item * How do I return the user's mail address? + +=item * How do I send mail? + +=item * How do I read mail? + +=item * How do I find out my hostname/domainname/IP address? + +=item * How do I fetch a news article or the active newsgroups? + +=item * How do I fetch/put an FTP file? + +=item * How can I do RPC in Perl? + +=back + + =back =head2 Where to get this document @@ -66,6 +706,7 @@ at http://www.perl.com/perl/faq/ . You may mail corrections, additions, and suggestions to perlfaq-suggestions@perl.com . This alias should not be used to I<ask> FAQs. It's for fixing the current FAQ. +Send questions to the comp.lang.perl.misc newsgroup. =head2 What will happen if you mail your Perl programming problems to the authors @@ -88,7 +729,7 @@ Perl Porters. =head1 Author and Copyright Information -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. =head2 Bundled Distributions @@ -117,6 +758,11 @@ in respect of this information or its use. =over 4 +=item 7/January/99 + +Small touchups here and there. Added all questions in this +document as a sort of table of contents. + =item 22/June/98 Significant changes throughout in preparation for the 5.005 @@ -170,3 +816,4 @@ This is the initial release of version 3 of the FAQ; consequently there have been no changes since its initial release. =back + diff --git a/contrib/perl5/pod/perlfaq1.pod b/contrib/perl5/pod/perlfaq1.pod index 5a95f19..d4cac42 100644 --- a/contrib/perl5/pod/perlfaq1.pod +++ b/contrib/perl5/pod/perlfaq1.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq1 - General Questions About Perl ($Revision: 1.15 $, $Date: 1998/08/05 11:52:24 $) +perlfaq1 - General Questions About Perl ($Revision: 1.20 $, $Date: 1999/01/08 04:22:09 $) =head1 DESCRIPTION @@ -32,12 +32,14 @@ the personal note at the end of the README file in the perl source distribution for more details. See L<perlhist> (new as of 5.005) for Perl's milestone releases. -In particular, the core development team (known as the Perl -Porters) are a rag-tag band of highly altruistic individuals -committed to producing better software for free than you -could hope to purchase for money. You may snoop on pending -developments via news://genetics.upenn.edu/perl.porters-gw/ and -http://www.frii.com/~gnat/perl/porters/summary.html. +In particular, the core development team (known as the Perl Porters) +are a rag-tag band of highly altruistic individuals committed +to producing better software for free than you could hope to +purchase for money. You may snoop on pending developments via +nntp://news.perl.com/perl.porters-gw/ and the Deja News archive at +http://www.dejanews.com/ using the perl.porters-gw newsgroup, or you can +subscribe to the mailing list by sending perl5-porters-request@perl.org +a subscription request. While the GNU project includes Perl in its distributions, there's no such thing as "GNU Perl". Perl is not produced nor maintained by the @@ -51,12 +53,16 @@ users the informal support will more than suffice. See the answer to =head2 Which version of Perl should I use? You should definitely use version 5. Version 4 is old, limited, and -no longer maintained; its last patch (4.036) was in 1992. The most -recent production release is 5.005_01. Further references to the Perl -language in this document refer to this production release unless -otherwise specified. There may be one or more official bug fixes for -5.005_01 by the time you read this, and also perhaps some experimental -versions on the way to the next release. +no longer maintained; its last patch (4.036) was in 1992, long ago and +far away. Sure, it's stable, but so is anything that's dead; in fact, +perl4 had been called a dead, flea-bitten camel carcass. The most recent +production release is 5.005_02 (although 5.004_04 is still supported). +The most cutting-edge development release is 5.005_54. Further references +to the Perl language in this document refer to the production release +unless otherwise specified. There may be one or more official bug +fixes for 5.005_02 by the time you read this, and also perhaps some +experimental versions on the way to the next release. All releases +prior to 5.004 were subject to buffer overruns, a grave security issue. =head2 What are perl4 and perl5? @@ -68,11 +74,12 @@ Perl5 is merely the popular name for the fifth major release (October 1994), while perl4 was the fourth major release (March 1991). There was also a perl1 (in January 1988), a perl2 (June 1988), and a perl3 (October 1989). -The 5.0 release is, essentially, a complete rewrite of the perl source -code from the ground up. It has been modularized, object-oriented, -tweaked, trimmed, and optimized until it almost doesn't look like the -old code. However, the interface is mostly the same, and compatibility -with previous releases is very high. +The 5.0 release is, essentially, a ground-up rewrite of the original +perl source code from releases 1 through 4. It has been modularized, +object-oriented, tweaked, trimmed, and optimized until it almost doesn't +look like the old code. However, the interface is mostly the same, and +compatibility with previous releases is very high. See L<perltrap/"Perl4 +to Perl5 Traps">. To avoid the "what language is perl5?" confusion, some people prefer to simply use "perl" to refer to the latest version of perl and avoid using @@ -80,6 +87,27 @@ simply use "perl" to refer to the latest version of perl and avoid using See L<perlhist> for a history of Perl revisions. +=head2 What is perl6? + +Perl6 is a semi-jocular reference to the Topaz project. Headed by Chip +Salzenberg, Topaz is yet-another ground-up rewrite of the current release +of Perl, one whose major goal is to create a more maintainable core than +found in release 5. Written in nominally portable C++, Topaz hopes to +maintain 100% source-compatibility with previous releases of Perl but to +run significantly faster and smaller. The Topaz team hopes to provide +an XS compatibility interface to allow most XS modules to work unchanged, +albeit perhaps without the efficiency that the new interface uowld allow. +New features in Topaz are as yet undetermined, and will be addressed +once compatibility and performance goals are met. + +If you are a hard-working C++ wizard with a firm command of Perl's +internals, and you would like to work on the project, send a request to +perl6-porters-request@perl.org to subscribe to the Topaz mailing list. + +There is no ETA for Topaz. It is expected to be several years before it +achieves enough robustness, compatibility, portability, and performance +to replace perl5 for ordinary use by mere mortals. + =head2 How stable is Perl? Production releases, which incorporate bug fixes and new functionality, @@ -106,18 +134,18 @@ to do it" (TMTOWTDI, sometimes pronounced "tim toady"). Perl's learning curve is therefore shallow (easy to learn) and long (there's a whole lot you can do if you really want). -Finally, Perl is (frequently) an interpreted language. This means -that you can write your programs and test them without an intermediate -compilation step, allowing you to experiment and test/debug quickly -and easily. This ease of experimentation flattens the learning curve -even more. +Finally, because Perl is frequently (but not always, and certainly not by +definition) an interpreted language, you can write your programs and test +them without an intermediate compilation step, allowing you to experiment +and test/debug quickly and easily. This ease of experimentation flattens +the learning curve even more. Things that make Perl easier to learn: Unix experience, almost any kind of programming experience, an understanding of regular expressions, and the ability to understand other people's code. If there's something you need to do, then it's probably already been done, and a working example is usually available for free. Don't forget the new perl modules, either. -They're discussed in Part 3 of this FAQ, along with the CPAN, which is +They're discussed in Part 3 of this FAQ, along with CPAN, which is discussed in Part 2. =head2 How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl? @@ -130,22 +158,25 @@ Probably the best thing to do is try to write equivalent code to do a set of tasks. These languages have their own newsgroups in which you can learn about (but hopefully not argue about) them. +Some comparison documents can be found at http://language.perl.com/versus/ +if you really can't stop yourself. + =head2 Can I do [task] in Perl? -Perl is flexible and extensible enough for you to use on almost any -task, from one-line file-processing tasks to complex systems. For -many people, Perl serves as a great replacement for shell scripting. -For others, it serves as a convenient, high-level replacement for most -of what they'd program in low-level languages like C or C++. It's -ultimately up to you (and possibly your management ...) which tasks -you'll use Perl for and which you won't. +Perl is flexible and extensible enough for you to use on virtually any +task, from one-line file-processing tasks to large, elaborate systems. +For many people, Perl serves as a great replacement for shell scripting. +For others, it serves as a convenient, high-level replacement for most of +what they'd program in low-level languages like C or C++. It's ultimately +up to you (and possibly your management) which tasks you'll use Perl +for and which you won't. If you have a library that provides an API, you can make any component of it available as just another Perl function or variable using a Perl extension written in C or C++ and dynamically linked into your main perl interpreter. You can also go the other direction, and write your main program in C or C++, and then link in some Perl code on the fly, -to create a powerful application. +to create a powerful application. See L<perlembed>. That said, there will always be small, focused, special-purpose languages dedicated to a specific problem domain that are simply more @@ -164,17 +195,16 @@ certain task (e.g. prolog, make). For various reasons, Perl is probably not well-suited for real-time embedded systems, low-level operating systems development work like -device drivers or context-switching code, complex multithreaded +device drivers or context-switching code, complex multi-threaded shared-memory applications, or extremely large applications. You'll notice that perl is not itself written in Perl. -The new native-code compiler for Perl may reduce the limitations given -in the previous statement to some degree, but understand that Perl -remains fundamentally a dynamically typed language, and not a -statically typed one. You certainly won't be chastized if you don't -trust nuclear-plant or brain-surgery monitoring code to it. And -Larry will sleep easier, too -- Wall Street programs not -withstanding. :-) +The new, native-code compiler for Perl may eventually reduce the +limitations given in the previous statement to some degree, but understand +that Perl remains fundamentally a dynamically typed language, not +a statically typed one. You certainly won't be chastised if you don't +trust nuclear-plant or brain-surgery monitoring code to it. And Larry +will sleep easier, too -- Wall Street programs not withstanding. :-) =head2 What's the difference between "perl" and "Perl"? @@ -183,33 +213,58 @@ signify the language proper and "perl" the implementation of it, i.e. the current interpreter. Hence Tom's quip that "Nothing but perl can parse Perl." You may or may not choose to follow this usage. For example, parallelism means "awk and perl" and "Python and Perl" look -ok, while "awk and Perl" and "Python and perl" do not. +ok, while "awk and Perl" and "Python and perl" do not. But never +write "PERL", because perl isn't really an acronym, aprocryphal +folklore and post-facto expansions notwithstanding. =head2 Is it a Perl program or a Perl script? -It doesn't matter. - -In "standard terminology" a I<program> has been compiled to physical -machine code once, and can then be be run multiple times, whereas a -I<script> must be translated by a program each time it's used. Perl -programs, however, are usually neither strictly compiled nor strictly -interpreted. They can be compiled to a byte code form (something of a +Larry doesn't really care. He says (half in jest) that "a script is +what you give the actors. A program is what you give the audience." + +Originally, a script was a canned sequence of normally interactive +commands, that is, a chat script. Something like a uucp or ppp chat +script or an expect script fits the bill nicely, as do configuration +scripts run by a program at its start up, such F<.cshrc> or F<.ircrc>, +for example. Chat scripts were just drivers for existing programs, +not stand-alone programs in their own right. + +A computer scientist will correctly explain that all programs are +interpreted, and that the only question is at what level. But if you +ask this question of someone who isn't a computer scientist, they might +tell you that a I<program> has been compiled to physical machine code +once, and can then be run multiple times, whereas a I<script> must be +translated by a program each time it's used. + +Perl programs are (usually) neither strictly compiled nor strictly +interpreted. They can be compiled to a byte-code form (something of a Perl virtual machine) or to completely different languages, like C or -assembly language. You can't tell just by looking whether the source -is destined for a pure interpreter, a parse-tree interpreter, a byte -code interpreter, or a native-code compiler, so it's hard to give a -definitive answer here. +assembly language. You can't tell just by looking at it whether the +source is destined for a pure interpreter, a parse-tree interpreter, +a byte-code interpreter, or a native-code compiler, so it's hard to give +a definitive answer here. + +Now that "script" and "scripting" are terms that have been seized by +unscrupulous or unknowing marketeers for their own nefarious purposes, +they have begun to take on strange and often pejorative meanings, +like "non serious" or "not real programming". Consequently, some perl +programmers prefer to avoid them altogether. =head2 What is a JAPH? These are the "just another perl hacker" signatures that some people -sign their postings with. About 100 of the of the earlier ones are -available from http://www.perl.com/CPAN/misc/japh . +sign their postings with. Randal Schwartz made these famous. About +100 of the earlier ones are available from +http://www.perl.com/CPAN/misc/japh . =head2 Where can I get a list of Larry Wall witticisms? Over a hundred quips by Larry, from postings of his or source code, -can be found at http://www.perl.com/CPAN/misc/lwall-quotes . +can be found at http://www.perl.com/CPAN/misc/lwall-quotes.txt.gz . + +Newer examples can be found by perusing Larry's postings: + + http://x1.dejanews.com/dnquery.xp?QRY=*&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=100&subjects=&groups=&authors=larry@*wall.org&fromdate=&todate= =head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)? @@ -232,32 +287,33 @@ many Unix vendors now ship Perl by default, and support is usually just a news-posting away, if you can't find the answer in the I<comprehensive> documentation, including this FAQ. +See http://www.perl.org/advocacy/ for more information. + If you face reluctance to upgrading from an older version of perl, then point out that version 4 is utterly unmaintained and unsupported by the Perl Development Team. Another big sell for Perl5 is the large number of modules and extensions which greatly reduce development time for any given task. Also mention that the difference between version 4 and version 5 of Perl is like the difference between awk and C++. -(Well, ok, maybe not quite that distinct, but you get the idea.) If -you want support and a reasonable guarantee that what you're -developing will continue to work in the future, then you have to run -the supported version. That probably means running the 5.005 release, -although 5.004 isn't that bad (it's just one year and one release -behind). Several important bugs were fixed from the 5.000 through +(Well, ok, maybe not quite that distinct, but you get the idea.) If you +want support and a reasonable guarantee that what you're developing +will continue to work in the future, then you have to run the supported +version. That probably means running the 5.005 release, although 5.004 +isn't that bad. Several important bugs were fixed from the 5.000 through 5.003 versions, though, so try upgrading past them if possible. Of particular note is the massive bughunt for buffer overflow problems that went into the 5.004 release. All releases prior to that, including perl4, are considered insecure and should be upgraded -as soon as possible. +as soon as possible. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution -of Perl or of its documentation (printed or otherwise), this works is +of Perl or of its documentation (printed or otherwise), this work is covered under Perl's Artistic Licence. For separate distributions of all or part of this FAQ outside of that, see L<perlfaq>. @@ -266,3 +322,4 @@ domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq2.pod b/contrib/perl5/pod/perlfaq2.pod index 918e936..32970af 100644 --- a/contrib/perl5/pod/perlfaq2.pod +++ b/contrib/perl5/pod/perlfaq2.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.25 $, $Date: 1998/08/05 11:47:25 $) +perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.30 $, $Date: 1998/12/29 19:43:32 $) =head1 DESCRIPTION @@ -12,7 +12,7 @@ related matters. The standard release of Perl (the one maintained by the perl development team) is distributed only in source code form. You -can find this at http://www.perl.com/CPAN/src/latest.tar.gz, which +can find this at http://www.perl.com/CPAN/src/latest.tar.gz , which in standard Internet format (a gzipped archive in POSIX tar format). Perl builds and runs on a bewildering number of platforms. Virtually @@ -22,7 +22,7 @@ QNX, BeOS, and the Amiga. There are also the beginnings of support for MPE/iX. Binary distributions for some proprietary platforms, including -Apple systems can be found http://www.perl.com/CPAN/ports/ directory. +Apple systems, can be found http://www.perl.com/CPAN/ports/ directory. Because these are not part of the standard distribution, they may and in fact do differ from the base Perl port in a variety of ways. You'll have to check their respective release notes to see just @@ -31,22 +31,23 @@ what the differences are. These differences can be either positive are not supported in the source release of perl) or negative (e.g. might be based upon a less current source release of perl). -A useful FAQ for Win32 Perl users is -http://www.endcontsw.com/people/evangelo/Perl_for_Win32_FAQ.html - =head2 How can I get a binary version of Perl? -If you don't have a C compiler because for whatever reasons your -vendor did not include one with your system, the best thing to do is +If you don't have a C compiler because your vendor for whatever +reasons did not include one with your system, the best thing to do is grab a binary version of gcc from the net and use that to compile perl with. CPAN only has binaries for systems that are terribly hard to get free compilers for, not for Unix systems. -Your first stop should be http://www.perl.com/CPAN/ports to see what -information is already available. A simple installation guide for -MS-DOS is available at http://www.cs.ruu.nl/~piet/perl5dos.html , and -similarly for Windows 3.1 at http://www.cs.ruu.nl/~piet/perlwin3.html -. +Some URLs that might help you are: + + http://language.perl.com/info/software.html + http://www.perl.com/latest/ + http://www.perl.com/CPAN/ports/ + +If you want information on proprietary systems. A simple installation +guide for MS-DOS is available at http://www.cs.ruu.nl/~piet/perl5dos.html +and similarly for Windows 3.1 at http://www.cs.ruu.nl/~piet/perlwin3.html . =head2 I don't have a C compiler on my system. How can I compile perl? @@ -67,11 +68,14 @@ approaches are doomed to failure. One simple way to check that things are in the right place is to print out the hard-coded @INC which perl is looking for. - perl -e 'print join("\n",@INC)' + % perl -e 'print join("\n",@INC)' If this command lists any paths which don't exist on your system, then you may need to move the appropriate libraries to these locations, or create -symlinks, aliases, or shortcuts appropriately. +symlinks, aliases, or shortcuts appropriately. @INC is also printed as +part of the output of + + % perl -V You might also want to check out L<perlfaq8/"How do I keep my own module/library directory?">. @@ -79,7 +83,7 @@ module/library directory?">. =head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? Read the F<INSTALL> file, which is part of the source distribution. -It describes in detail how to cope with most idiosyncracies that the +It describes in detail how to cope with most idiosyncrasies that the Configure script can't work around for any given system or architecture. @@ -141,6 +145,16 @@ http://www.perl.com/perl/info/documentation.html that might help. Many good books have been written about Perl -- see the section below for more details. +Tutorial documents are included in current or upcoming Perl releases +include L<perltoot> for objects, L<perlopentut> for file opening +semantics, L<perlreftut> for managing references, and L<perlxstut> +for linking C and Perl together. There may be more by the +time you read this. The following URLs might also be of +assistance: + + http://language.perl.com/info/documentation.html + http://reference.perl.com/query.cgi?tutorials + =head2 What are the Perl newsgroups on USENET? Where do I post questions? The now defunct comp.lang.perl newsgroup has been superseded by the @@ -154,20 +168,17 @@ following groups: comp.infosystems.www.authoring.cgi Writing CGI scripts for the Web. -Actually, the moderated group hasn't passed yet, but we're -keeping our fingers crossed. - There is also USENET gateway to the mailing list used by the crack Perl development team (perl5-porters) at news://news.perl.com/perl.porters-gw/ . =head2 Where should I post source code? -You should post source code to whichever group is most appropriate, -but feel free to cross-post to comp.lang.perl.misc. If you want to -cross-post to alt.sources, please make sure it follows their posting -standards, including setting the Followup-To header line to NOT -include alt.sources; see their FAQ for details. +You should post source code to whichever group is most appropriate, but +feel free to cross-post to comp.lang.perl.misc. If you want to cross-post +to alt.sources, please make sure it follows their posting standards, +including setting the Followup-To header line to NOT include alt.sources; +see their FAQ (http://www.faqs.org/faqs/alt-sources-intro/) for details. If you're just looking for software, first use Alta Vista, Deja News, and search CPAN. This is faster and more productive than just posting @@ -184,7 +195,7 @@ The incontestably definitive reference book on Perl, written by the creator of Perl, is now in its second edition: Programming Perl (the "Camel Book"): - Authors: Larry Wall, Tom Christiansen, and Randal Schwartz + by Larry Wall, Tom Christiansen, and Randal Schwartz ISBN 1-56592-149-6 (English) ISBN 4-89052-384-7 (Japanese) URL: http://www.oreilly.com/catalog/pperl2/ @@ -196,7 +207,7 @@ of real-world examples, mini-tutorials, and complete programs (first premiering at the 1998 Perl Conference), is: The Perl Cookbook (the "Ram Book"): - Authors: Tom Christiansen and Nathan Torkington, + by Tom Christiansen and Nathan Torkington, with Foreword by Larry Wall ISBN: 1-56592-243-3 URL: http://perl.oreilly.com/cookbook/ @@ -206,7 +217,7 @@ might suffice for you to learn Perl from. But if you're not, check out: Learning Perl (the "Llama Book"): - Authors: Randal Schwartz and Tom Christiansen + by Randal Schwartz and Tom Christiansen with Foreword by Larry Wall ISBN: 1-56592-284-0 URL: http://www.oreilly.com/catalog/lperl2/ @@ -230,7 +241,7 @@ See http://www.ora.com/ on the Web. What follows is a list of the books that the FAQ authors found personally useful. Your mileage may (but, we hope, probably won't) vary. -Recommended books on (or muchly on) Perl follow; those marked with +Recommended books on (or mostly on) Perl follow; those marked with a star may be ordered from O'Reilly. =over @@ -262,7 +273,7 @@ a star may be ordered from O'Reilly. MacPerl: Power and Ease by Vicki Brown and Chris Nandor, foreword by Matthias Neeracher -=item Task-Oriented +=item Task-Oriented *The Perl Cookbook by Tom Christiansen and Nathan Torkington @@ -296,7 +307,7 @@ development, databases, Win32 Perl, graphical programming, regular expressions, and networking, and sponsors the Obfuscated Perl Contest. It is published quarterly under the gentle hand of its editor, Jon Orwant. See http://www.tpj.com/ or send mail to -subscriptions@tpj.com. +subscriptions@tpj.com . Beyond this, magazines that frequently carry high-quality articles on Perl are I<Web Techniques> (see http://www.webtechniques.com/), @@ -309,10 +320,11 @@ http://www.stonehenge.com/merlyn/WebTechniques/. To get the best (and possibly cheapest) performance, pick a site from the list below and use it to grab the complete list of mirror sites. -From there you can find the quickest site for you. Remember, the +>From there you can find the quickest site for you. Remember, the following list is I<not> the complete list of CPAN mirrors. - http://www.perl.com/CPAN (redirects to another mirror) + http://www.perl.com/CPAN-local + http://www.perl.com/CPAN (redirects to an ftp mirror) http://www.perl.org/CPAN ftp://ftp.funet.fi/pub/languages/perl/CPAN/ http://www.cs.ruu.nl/pub/PERL/CPAN/ @@ -322,69 +334,19 @@ following list is I<not> the complete list of CPAN mirrors. Most of the major modules (tk, CGI, libwww-perl) have their own mailing lists. Consult the documentation that came with the module for -subscription information. The following are a list of mailing lists -related to perl itself. - -If you subscribe to a mailing list, it behooves you to know how to -unsubscribe from it. Strident pleas to the list itself to get you off -will not be favorably received. - -=over 4 - -=item MacPerl - -There is a mailing list for discussing Macintosh Perl. Contact -"mac-perl-request@iis.ee.ethz.ch". - -Also see Matthias Neeracher's (the creator and maintainer of MacPerl) -webpage at http://www.iis.ee.ethz.ch/~neeri/macintosh/perl.html for -many links to interesting MacPerl sites, and the applications/MPW -tools, precompiled. - -=item Perl5-Porters - -The core development team have a mailing list for discussing fixes and -changes to the language. Send mail to -"perl5-porters-request@perl.org" with help in the body of the message -for information on subscribing. - -=item NTPerl +subscription information. The Perl Institute attempts to maintain a +list of mailing lists at: -This list is used to discuss issues involving Win32 Perl 5 (Windows NT -and Win95). Subscribe by mailing ListManager@ActiveWare.com with the -message body: + http://www.perl.org/maillist.html - subscribe Perl-Win32-Users - -The list software, also written in perl, will automatically determine -your address, and subscribe you automatically. To unsubscribe, mail -the following in the message body to the same address like so: - - unsubscribe Perl-Win32-Users - -You can also check http://www.activeware.com/ and select "Mailing Lists" -to join or leave this list. - -=item Perl-Packrats - -Discussion related to archiving of perl materials, particularly the -Comprehensive Perl Archive Network (CPAN). Subscribe by emailing -majordomo@cis.ufl.edu: - - subscribe perl-packrats - -The list software, also written in perl, will automatically determine -your address, and subscribe you automatically. To unsubscribe, simple -prepend the same command with an "un", and mail to the same address -like so: - - unsubscribe perl-packrats +=head2 Archives of comp.lang.perl.misc -=back +Have you tried Deja News or Alta Vista? Those are the +best archives. Just look up "*perl*" as a newsgroup. -=head2 Archives of comp.lang.perl.misc + http://www.dejanews.com/dnquery.xp?QRY=&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=25&subjects=&groups=*perl*&authors=&fromdate=&todate= -Have you tried Deja News or Alta Vista? +You'll probably want to trim that down a bit, though. ftp.cis.ufl.edu:/pub/perl/comp.lang.perl.*/monthly has an almost complete collection dating back to 12/89 (missing 08/91 through @@ -402,21 +364,24 @@ let perlfaq-suggestions@perl.com know. =head2 Where can I buy a commercial version of Perl? -In a sense, Perl already I<is> commercial software: It has a licence -that you can grab and carefully read to your manager. It is -distributed in releases and comes in well-defined packages. There is a -very large user community and an extensive literature. The -comp.lang.perl.* newsgroups and several of the mailing lists provide -free answers to your questions in near real-time. Perl has -traditionally been supported by Larry, dozens of software designers -and developers, and thousands of programmers, all working for free -to create a useful thing to make life better for everyone. +In a real sense, Perl already I<is> commercial software: It has a licence +that you can grab and carefully read to your manager. It is distributed +in releases and comes in well-defined packages. There is a very large +user community and an extensive literature. The comp.lang.perl.* +newsgroups and several of the mailing lists provide free answers to your +questions in near real-time. Perl has traditionally been supported by +Larry, scores of software designers and developers, and myriads of +programmers, all working for free to create a useful thing to make life +better for everyone. However, these answers may not suffice for managers who require a -purchase order from a company whom they can sue should anything go -wrong. Or maybe they need very serious hand-holding and contractual -obligations. Shrink-wrapped CDs with perl on them are available from -several sources if that will help. +purchase order from a company whom they can sue should anything go awry. +Or maybe they need very serious hand-holding and contractual obligations. +Shrink-wrapped CDs with perl on them are available from several sources if +that will help. For example, many perl books carry a perl distribution +on them, as do the O'Reily Perl Resource Kits (in both the Unix flavor +and in the proprietary Microsoft flavor); the free Unix distributions +also all come with Perl. Or you can purchase a real support contract. Although Cygnus historically provided this service, they no longer sell support contracts for Perl. @@ -438,20 +403,20 @@ Oraperl and related modules (which Oracle is planning to ship as part of Oracle Web Server 3). 20% of the profit from our Perl support work will be donated to The Perl Institute." -For more information, contact the The Perl Clinic: +For more information, contact The Perl Clinic: Tel: +44 1483 424424 Fax: +44 1483 419419 Web: http://www.perl.co.uk/ Email: perl-support-info@perl.co.uk or Tim.Bunce@ig.co.uk -See also www.perl.com for updates on training and support. +See also www.perl.com for updates on tutorials, training, and support. =head2 Where do I send bug reports? If you are reporting a bug in the perl interpreter or the modules shipped with perl, use the I<perlbug> program in the perl distribution or -mail your report to perlbug@perl.com. +mail your report to perlbug@perl.com . If you are posting a bug with a non-standard port (see the answer to "What platforms is Perl available for?"), a binary distribution, or a @@ -461,34 +426,28 @@ bugs. Read the perlbug(1) man page (perl5.004 or later) for more information. -=head2 What is perl.com? perl.org? The Perl Institute? +=head2 What is perl.com? -The perl.com domain is managed by Tom Christiansen, who created it as a +The perl.com domain is owned by Tom Christiansen, who created it as a public service long before perl.org came about. Despite the name, it's a pretty non-commercial site meant to be a clearinghouse for information about all things Perlian, accepting no paid advertisements, bouncy happy gifs, or silly java applets on its pages. The Perl Home Page at http://www.perl.com/ is currently hosted on a T3 line courtesy of Songline Systems, a software-oriented subsidiary of O'Reilly and Associates. +Other starting points include -perl.org is the official vehicle for The Perl Institute. The motto of -TPI is "helping people help Perl help people" (or something like -that). It's a non-profit organization supporting development, -documentation, and dissemination of perl. - -=head2 How do I learn about object-oriented Perl programming? - -L<perltoot> (distributed with 5.004 or later) is a good place to start. -Also, L<perlobj>, L<perlref>, and L<perlmod> are useful references, -while L<perlbot> has some excellent tips and tricks. + http://language.perl.com/ + http://conference.perl.com/ + http://reference.perl.com/ =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution -of Perl or of its documentation (printed or otherwise), this works is +of Perl or of its documentation (printed or otherwise), this work is covered under Perl's Artistic Licence. For separate distributions of all or part of this FAQ outside of that, see L<perlfaq>. @@ -497,3 +456,4 @@ domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq3.pod b/contrib/perl5/pod/perlfaq3.pod index d06f2be..a811c3c 100644 --- a/contrib/perl5/pod/perlfaq3.pod +++ b/contrib/perl5/pod/perlfaq3.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq3 - Programming Tools ($Revision: 1.29 $, $Date: 1998/08/05 11:57:04 $) +perlfaq3 - Programming Tools ($Revision: 1.33 $, $Date: 1998/12/29 20:12:12 $) =head1 DESCRIPTION @@ -102,6 +102,10 @@ on your hardware, operating system, and the load on your machine): for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu) map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) +Be aware that a good benchmark is very hard to write. It only tests the +data you give it, and really proves little about differing complexities +of contrasting algorithms. + =head2 How do I cross-reference my Perl programs? The B::Xref module, shipped with the new, alpha-release Perl compiler @@ -122,23 +126,57 @@ shouldn't need to reformat. The habit of formatting your code as you write it will help prevent bugs. Your editor can and should help you with this. The perl-mode for emacs can provide a remarkable amount of help with most (but not all) code, and even less programmable editors -can provide significant assistance. +can provide significant assistance. Tom swears by the following +settings in vi and its clones: + + set ai sw=4 + map ^O {^M}^[O^T -If you are used to using I<vgrind> program for printing out nice code +Now put that in your F<.exrc> file (replacing the caret characters +with control characters) and away you go. In insert mode, ^T is +for indenting, ^D is for undenting, and ^O is for blockdenting -- +as it were. If you haven't used the last one, you're missing +a lot. A more complete example, with comments, can be found at +http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz + +If you are used to using the I<vgrind> program for printing out nice code to a laser printer, you can take a stab at this using http://www.perl.com/CPAN/doc/misc/tips/working.vgrind.entry, but the results are not particularly satisfying for sophisticated code. -=head2 Is there a ctags for Perl? +The a2ps at http://www.infres.enst.fr/~demaille/a2ps/ does lots of things +related to generating nicely printed output of documents. + +=head2 Is there a etags/ctags for perl? -There's a simple one at +With respect to the source code for the Perl interpreter, yes. +There has been support for etags in the source for a long time. +Ctags was introduced in v5.005_54 (and probably 5.005_03). +After building perl, type 'make etags' or 'make ctags' and both +sets of tag files will be built. + +Now, if you're looking to build a tag file for perl code, then there's +a simple one at http://www.perl.com/CPAN/authors/id/TOMC/scripts/ptags.gz which may do -the trick. +the trick. And if not, it's easy to hack into what you want. + +=head2 Is there an IDE or Windows Perl Editor? + +If you're on Unix, you already have an IDE -- Unix itself. +You just have to learn the toolbox. If you're not, then you +probably don't have a toolbox, so may need something else. + +PerlBuilder (XXX URL to follow) is an integrated development +environment for Windows that supports Perl development. Perl programs +are just plain text, though, so you could download emacs for Windows +(XXX) or vim for win32 (http://www.cs.vu.nl/~tmgil/vi.html). If +you're transferring Windows files to Unix, be sure to transfer in +ASCII mode so the ends of lines are appropriately converted. =head2 Where can I get Perl macros for vi? For a complete version of Tom Christiansen's vi configuration file, -see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc, +see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz, the standard benchmark file for vi emulators. This runs best with nvi, the current version of vi out of Berkeley, which incidentally can be built with an embedded Perl interpreter -- see http://www.perl.com/CPAN/src/misc. @@ -155,7 +193,7 @@ context-sensitive help, and other nifty things. Note that the perl-mode of emacs will have fits with C<"main'foo"> (single quote), and mess up the indentation and hilighting. You -should be using C<"main::foo"> in new Perl code anyway, so this +are probably using C<"main::foo"> in new Perl code anyway, so this shouldn't be an issue. =head2 How can I use curses with Perl? @@ -236,7 +274,7 @@ wasn't a good solution anyway. When it comes to time-space tradeoffs, Perl nearly always prefers to throw memory at a problem. Scalars in Perl use more memory than -strings in C, arrays take more that, and hashes use even more. While +strings in C, arrays take more than that, and hashes use even more. While there's still a lot to be done, recent releases have been addressing these issues. For example, as of 5.004, duplicate hash keys are shared amongst all hashes using them, so require no reallocation. @@ -278,10 +316,15 @@ No, Perl's garbage collection system takes care of this. You can't. On most operating systems, memory allocated to a program can never be returned to the system. That's why long-running programs -sometimes re-exec themselves. Some operating systems (notably, FreeBSD) -allegedly reclaim large chunks of memory that is no longer used, but -it doesn't appear to happen with Perl (yet). The Mac appears to be the -only platform that will reliably (albeit, slowly) return memory to the OS. +sometimes re-exec themselves. Some operating systems (notably, +FreeBSD and Linux) allegedly reclaim large chunks of memory that is no +longer used, but it doesn't appear to happen with Perl (yet). The Mac +appears to be the only platform that will reliably (albeit, slowly) +return memory to the OS. + +We've had reports that on Linux (Redhat 5.1) on Intel, C<undef +$scalar> will return memory to the system, while on Solaris 2.6 it +won't. In general, try it yourself and see. However, judicious use of my() on your variables will help make sure that they go out of scope so that Perl can free up their storage for @@ -314,8 +357,7 @@ the internal server API, so modules written in Perl can do just about anything a module written in C can. For more on mod_perl, see http://perl.apache.org/ -With the FCGI module (from CPAN), a Perl executable compiled with sfio -(see the F<INSTALL> file in the distribution) and the mod_fastcgi +With the FCGI module (from CPAN) and the mod_fastcgi module (available from http://www.fastcgi.com/) each of your perl scripts becomes a permanent CGI daemon process. @@ -325,8 +367,8 @@ care. See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . -A non-free, commerical product, ``The Velocity Engine for Perl'', -(http://www.binevolve.com/ or http://www.binevolve.com/bine/vep) might +A non-free, commercial product, ``The Velocity Engine for Perl'', +(http://www.binevolve.com/ or also be worth looking at. It will allow you to increase the performance of your perl scripts, upto 25 times faster than normal CGI perl by running in persistent perl mode, or 4 to 5 times faster without any @@ -353,12 +395,12 @@ source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed. You can try using encryption via source filters (Filter::* from CPAN), -but crackers might be able to decrypt it. You can try using the byte -code compiler and interpreter described below, but crackers might be -able to de-compile it. You can try using the native-code compiler -described below, but crackers might be able to disassemble it. These -pose varying degrees of difficulty to people wanting to get at your -code, but none can definitively conceal it (this is true of every +but any decent programmer will be able to decrypt it. You can try using +the byte code compiler and interpreter described below, but the curious +might still be able to de-compile it. You can try using the native-code +compiler described below, but crackers might be able to disassemble it. +These pose varying degrees of difficulty to people wanting to get at +your code, but none can definitively conceal it (this is true of every language, not just Perl). If you're concerned about people profiting from your code, then the @@ -407,6 +449,14 @@ packaging, and once you see the size of what it makes (well, unless you use a shared I<libperl.so>), you'll probably want a complete Perl install anyway. +=head2 How can I compile Perl into Java? + +You can't. Not yet, anyway. You can integrate Java and Perl with the +Perl Resource Kit from O'Reilly and Associates. See +http://www.oreilly.com/catalog/prkunix/ for more information. +The Java interface will be supported in the core 5.006 release +of Perl. + =head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]? For OS/2 just use @@ -420,12 +470,15 @@ F<INSTALL> file in the source distribution for more information). The Win95/NT installation, when using the ActiveState port of Perl, will modify the Registry to associate the C<.pl> extension with the -perl interpreter. If you install another port (Gurusaramy Sarathy's -is the recommended Win95/NT port), or (eventually) build your own -Win95/NT Perl using WinGCC, then you'll have to modify the Registry -yourself. - -Macintosh perl scripts will have the the appropriate Creator and +perl interpreter. If you install another port (Gurusamy Sarathy's is +the recommended Win95/NT port), or (eventually) build your own +Win95/NT Perl using a Windows port of gcc (e.g., with cygwin32 or +mingw32), then you'll have to modify the Registry yourself. In +addition to associating C<.pl> with the interpreter, NT people can +use: C<SET PATHEXT=%PATHEXT%;.PL> to let them run the program +C<install-linux.pl> merely by typing C<install-linux>. + +Macintosh perl scripts will have the appropriate Creator and Type, so that double-clicking them will invoke the perl application. I<IMPORTANT!>: Whatever you do, PLEASE don't get frustrated, and just @@ -494,6 +547,9 @@ shell, or MPW, is much like Unix shells in its support for several quoting variants, except that it makes free use of the Mac's non-ASCII characters as control characters. +Using qq(), q(), and qx(), instead of "double quotes", 'single +quotes', and `backticks`, may make one-liners easier to write. + There is no general solution to all of this. It is a mess, pure and simple. Sucks to be away from Unix, huh? :-) @@ -514,7 +570,7 @@ when it runs fine on the command line'', see these sources: http://www.boutell.com/faq/ CGI FAQ - http://www.webthing.com/page.cgi/cgifaq + http://www.webthing.com/tutorials/cgifaq.html HTTP Spec http://www.w3.org/pub/WWW/Protocols/HTTP/ @@ -529,6 +585,7 @@ when it runs fine on the command line'', see these sources: CGI Security FAQ http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt +Also take a look at L<perlfaq9> =head2 Where can I learn about object-oriented Perl programming? @@ -580,11 +637,11 @@ information, see L<ExtUtils::MakeMaker>. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution -of Perl or of its documentation (printed or otherwise), this works is +of Perl or of its documentation (printed or otherwise), this work is covered under Perl's Artistic Licence. For separate distributions of all or part of this FAQ outside of that, see L<perlfaq>. @@ -593,3 +650,4 @@ domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq4.pod b/contrib/perl5/pod/perlfaq4.pod index 633f5f1..92aee2c 100644 --- a/contrib/perl5/pod/perlfaq4.pod +++ b/contrib/perl5/pod/perlfaq4.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq4 - Data Manipulation ($Revision: 1.26 $, $Date: 1998/08/05 12:04:00 $) +perlfaq4 - Data Manipulation ($Revision: 1.40 $, $Date: 1999/01/08 04:26:39 $) =head1 DESCRIPTION @@ -41,7 +41,7 @@ are consequently slower. To get rid of the superfluous digits, just use a format (eg, C<printf("%.2f", 19.95)>) to get the required precision. -See L<perlop/"Floating-point Arithmetic">. +See L<perlop/"Floating-point Arithmetic">. =head2 Why isn't my octal data interpreted correctly? @@ -59,7 +59,7 @@ umask(), or sysopen(), which all want permissions in octal. chmod(644, $file); # WRONG -- perl -w catches this chmod(0644, $file); # right -=head2 Does perl have a round function? What about ceil() and floor()? Trig functions? +=head2 Does Perl have a round() function? What about ceil() and floor()? Trig functions? Remember that int() merely truncates toward 0. For rounding to a certain number of digits, sprintf() or printf() is usually the easiest @@ -88,6 +88,19 @@ cases, it probably pays not to trust whichever system rounding is being used by Perl, but to instead implement the rounding function you need yourself. +To see why, notice how you'll still have an issue on half-way-point +alternation: + + for ($i = 0; $i < 1.01; $i += 0.05) { printf "%.1f ",$i} + + 0.0 0.1 0.1 0.2 0.2 0.2 0.3 0.3 0.4 0.4 0.5 0.5 0.6 0.7 0.7 + 0.8 0.8 0.9 0.9 1.0 1.0 + +Don't blame Perl. It's the same as in C. IEEE says we have to do this. +Perl numbers whose absolute values are integers under 2**31 (on 32 bit +machines) will work pretty much like mathematical integers. Other numbers +are not guaranteed. + =head2 How do I convert bits into ints? To turn a string of 1s and 0s like C<10110110> into a scalar containing @@ -100,6 +113,33 @@ Here's an example of going the other way: $binary_string = join('', unpack('B*', "\x29")); +=head2 Why doesn't & work the way I want it to? + +The behavior of binary arithmetic operators depends on whether they're +used on numbers or strings. The operators treat a string as a series +of bits and work with that (the string C<"3"> is the bit pattern +C<00110011>). The operators work with the binary form of a number +(the number C<3> is treated as the bit pattern C<00000011>). + +So, saying C<11 & 3> performs the "and" operation on numbers (yielding +C<1>). Saying C<"11" & "3"> performs the "and" operation on strings +(yielding C<"1">). + +Most problems with C<&> and C<|> arise because the programmer thinks +they have a number but really it's a string. The rest arise because +the programmer says: + + if ("\020\020" & "\101\101") { + # ... + } + +but a string consisting of two null bytes (the result of C<"\020\020" +& "\101\101">) is not a false value in Perl. You need: + + if ( ("\020\020" & "\101\101") !~ /[^\000]/) { + # ... + } + =head2 How do I multiply matrices? Use the Math::Matrix or Math::MatrixReal modules (available from CPAN) @@ -120,12 +160,12 @@ To call a function on each element of an array, but ignore the results: foreach $iterator (@array) { - &my_func($iterator); + some_func($iterator); } To call a function on each integer in a (small) range, you B<can> use: - @results = map { &my_func($_) } (5 .. 25); + @results = map { some_func($_) } (5 .. 25); but you should be aware that the C<..> operator creates an array of all integers in the range. This can take a lot of memory for large @@ -133,7 +173,7 @@ ranges. Instead use: @results = (); for ($i=5; $i < 500_005; $i++) { - push(@results, &my_func($i)); + push(@results, some_func($i)); } =head2 How can I output Roman numerals? @@ -142,20 +182,25 @@ Get the http://www.perl.com/CPAN/modules/by-module/Roman module. =head2 Why aren't my random numbers random? -The short explanation is that you're getting pseudorandom numbers, not -random ones, because computers are good at being predictable and bad -at being random (despite appearances caused by bugs in your programs -:-). A longer explanation is available on -http://www.perl.com/CPAN/doc/FMTEYEWTK/random, courtesy of Tom -Phoenix. John von Neumann said, ``Anyone who attempts to generate -random numbers by deterministic means is, of course, living in a state -of sin.'' +If you're using a version of Perl before 5.004, you must call C<srand> +once at the start of your program to seed the random number generator. +5.004 and later automatically call C<srand> at the beginning. Don't +call C<srand> more than once--you make your numbers less random, rather +than more. -You should also check out the Math::TrulyRandom module from CPAN. It -uses the imperfections in your system's timer to generate random -numbers, but this takes quite a while. If you want a better +Computers are good at being predictable and bad at being random +(despite appearances caused by bugs in your programs :-). +http://www.perl.com/CPAN/doc/FMTEYEWTK/random, courtesy of Tom +Phoenix, talks more about this.. John von Neumann said, ``Anyone who +attempts to generate random numbers by deterministic means is, of +course, living in a state of sin.'' + +If you want numbers that are more random than C<rand> with C<srand> +provides, you should also check out the Math::TrulyRandom module from +CPAN. It uses the imperfections in your system's timer to generate +random numbers, but this takes quite a while. If you want a better pseudorandom generator than comes with your operating system, look at -``Numerical Recipes in C'' at http://nr.harvard.edu/nr/bookc.html . +``Numerical Recipes in C'' at http://www.nr.com/ . =head1 Data: Dates @@ -178,10 +223,10 @@ You can find the week of the year by dividing this by 7: Of course, this believes that weeks start at zero. The Date::Calc module from CPAN has a lot of date calculation functions, including day of the year, week of the year, and so on. Note that not -all business consider ``week 1'' to be the same; for example, -American business often consider the first week with a Monday -in it to be Work Week #1, despite ISO 8601, which consider -WW1 to be the frist week with a Thursday in it. +all businesses consider ``week 1'' to be the same; for example, +American businesses often consider the first week with a Monday +in it to be Work Week #1, despite ISO 8601, which considers +WW1 to be the first week with a Thursday in it. =head2 How can I compare two dates and find the difference? @@ -201,23 +246,38 @@ and Date::Manip modules from CPAN. Neither Date::Manip nor Date::Calc deal with Julian days. Instead, there is an example of Julian date calculation that should help you in -http://www.perl.com/CPAN/authors/David_Muir_Sharnoff/modules/Time/JulianDay.pm.gz -. +Time::JulianDay (part of the Time-modules bundle) which can be found at +http://www.perl.com/CPAN/modules/by-module/Time/. + + +=head2 How do I find yesterday's date? + +The C<time()> function returns the current time in seconds since the +epoch. Take one day off that: + + $yesterday = time() - ( 24 * 60 * 60 ); + +Then you can pass this to C<localtime()> and get the individual year, +month, day, hour, minute, seconds values. =head2 Does Perl have a year 2000 problem? Is Perl Y2K compliant? -Short answer: No, Perl does not have a Year 2000 problem. Yes, -Perl is Y2K compliant. The programmers you're hired to use it, -however, probably are not. +Short answer: No, Perl does not have a Year 2000 problem. Yes, Perl is +Y2K compliant (whatever that means). The programmers you've hired to +use it, however, probably are not. + +Long answer: The question belies a true understanding of the issue. +Perl is just as Y2K compliant as your pencil--no more, and no less. +Can you use your pencil to write a non-Y2K-compliant memo? Of course +you can. Is that the pencil's fault? Of course it isn't. -Long answer: Perl is just as Y2K compliant as your pencil--no more, -and no less. The date and time functions supplied with perl (gmtime -and localtime) supply adequate information to determine the year well -beyond 2000 (2038 is when trouble strikes for 32-bit machines). The -year returned by these functions when used in an array context is the -year minus 1900. For years between 1910 and 1999 this I<happens> to -be a 2-digit decimal number. To avoid the year 2000 problem simply do -not treat the year as a 2-digit number. It isn't. +The date and time functions supplied with perl (gmtime and localtime) +supply adequate information to determine the year well beyond 2000 +(2038 is when trouble strikes for 32-bit machines). The year returned +by these functions when used in an array context is the year minus 1900. +For years between 1910 and 1999 this I<happens> to be a 2-digit decimal +number. To avoid the year 2000 problem simply do not treat the year as +a 2-digit number. It isn't. When gmtime() and localtime() are used in scalar context they return a timestamp string that contains a fully-expanded year. For example, @@ -286,8 +346,9 @@ parser. If you are serious about writing a parser, there are a number of modules or oddities that will make your life a lot easier. There is the CPAN module Parse::RecDescent, the standard module Text::Balanced, -the byacc program, and Mark-Jason Dominus's excellent I<py> tool at -http://www.plover.com/~mjd/perl/py/ . +the byacc program, the CPAN module Parse::Yapp, and Mark-Jason +Dominus's excellent I<py> tool at http://www.plover.com/~mjd/perl/py/ +. One simple destructive, inside-out approach that you might try is to pull out the smallest nesting parts one at a time: @@ -296,6 +357,21 @@ pull out the smallest nesting parts one at a time: # do something with $1 } +A more complicated and sneaky approach is to make Perl's regular +expression engine do it for you. This is courtesy Dean Inada, and +rather has the nature of an Obfuscated Perl Contest entry, but it +really does work: + + # $_ contains the string to parse + # BEGIN and END are the opening and closing markers for the + # nested text. + + @( = ('(',''); + @) = (')',''); + ($re=$_)=~s/((BEGIN)|(END)|.)/$)[!$3]\Q$1\E$([!$2]/gs; + @$ = (eval{/$re/},$@!~/unmatched/); + print join("\n",@$[0..$#$]) if( $$[-1] ); + =head2 How do I reverse a string? Use reverse() in scalar context, as documented in @@ -378,7 +454,7 @@ There are a number of ways, with varying efficiency: If you want a count of a certain single character (X) within a string, you can use the C<tr///> function like so: - $string = "ThisXlineXhasXsomeXx'sXinXit": + $string = "ThisXlineXhasXsomeXx'sXinXit"; $count = ($string =~ tr/X//); print "There are $count X charcters in the string"; @@ -422,6 +498,11 @@ You can (and probably should) enable locale awareness of those characters by placing a C<use locale> pragma in your program. See L<perllocale> for endless details on locales. +This is sometimes referred to as putting something into "title +case", but that's not quite accurate. Consdier the proper +capitalization of the movie I<Dr. Strangelove or: How I Learned to +Stop Worrying and Love the Bomb>, for example. + =head2 How can I split a [character] delimited string except when inside [character]? (Comma-separated files) @@ -457,13 +538,15 @@ distribution) lets you say: use Text::ParseWords; @new = quotewords(",", 0, $text); +There's also a Text::CSV module on CPAN. + =head2 How do I strip blank space from the beginning/end of a string? Although the simplest approach would seem to be: $string =~ s/^\s*(.*?)\s*$/$1/; -This is unneccesarily slow, destructive, and fails with embedded newlines. +This is unnecessarily slow, destructive, and fails with embedded newlines. It is much better faster to do this in two steps: $string =~ s/^\s+//; @@ -488,6 +571,44 @@ values of a hash if you use a slide: s/\s+$//; } +=head2 How do I pad a string with blanks or pad a number with zeroes? + +(This answer contributed by Uri Guttman) + +In the following examples, C<$pad_len> is the length to which you wish +to pad the string, C<$text> or C<$num> contains the string to be +padded, and C<$pad_char> contains the padding character. You can use a +single character string constant instead of the C<$pad_char> variable +if you know what it is in advance. + +The simplest method use the C<sprintf> function. It can pad on the +left or right with blanks and on the left with zeroes. + + # Left padding with blank: + $padded = sprintf( "%${pad_len}s", $text ) ; + + # Right padding with blank: + $padded = sprintf( "%${pad_len}s", $text ) ; + + # Left padding with 0: + $padded = sprintf( "%0${pad_len}d", $num ) ; + +If you need to pad with a character other than blank or zero you can use +one of the following methods. + +These methods generate a pad string with the C<x> operator and +concatenate that with the original text. + +Left and right padding with any character: + + $padded = $pad_char x ( $pad_len - length( $text ) ) . $text ; + $padded = $text . $pad_char x ( $pad_len - length( $text ) ) ; + +Or you can left or right pad $text directly: + + $text .= $pad_char x ( $pad_len - length( $text ) ) ; + substr( $text, 0, 0 ) = $pad_char x ( $pad_len - length( $text ) ) ; + =head2 How do I extract selected columns from a string? Use substr() or unpack(), both documented in L<perlfunc>. @@ -523,13 +644,13 @@ Let's assume that you have a string like: If those were both global variables, then this would suffice: - $text =~ s/\$(\w+)/${$1}/g; + $text =~ s/\$(\w+)/${$1}/g; # no /e needed But since they are probably lexicals, or at least, they could be, you'd have to do this: $text =~ s/(\$\w+)/$1/eeg; - die if $@; # needed on /ee, not /e + die if $@; # needed /ee, not /e It's probably better in the general case to treat those variables as entries in some special hash. For example: @@ -547,7 +668,9 @@ of the FAQ. The problem is that those double-quotes force stringification, coercing numbers and references into strings, even when you -don't want them to be. +don't want them to be. Think of it this way: double-quote +expansion is used to produce new strings. If you already +have a string, why do you need more? If you get used to writing odd things like these: @@ -583,7 +706,7 @@ Stringification also destroys arrays. print "@lines"; # WRONG - extra blanks print @lines; # right -=head2 Why don't my <<HERE documents work? +=head2 Why don't my E<lt>E<lt>HERE documents work? Check for these three things: @@ -665,6 +788,27 @@ indentation correctly preserved: =head1 Data: Arrays +=head2 What is the difference between a list and an array? + +An array has a changeable length. A list does not. An array is something +you can push or pop, while a list is a set of values. Some people make +the distinction that a list is a value while an array is a variable. +Subroutines are passed and return lists, you put things into list +context, you initialize arrays with lists, and you foreach() across +a list. C<@> variables are arrays, anonymous arrays are arrays, arrays +in scalar context behave like the number of elements in them, subroutines +access their arguments through the array C<@_>, push/pop/shift only work +on arrays. + +As a side note, there's no such thing as a list in scalar context. +When you say + + $scalar = (2, 5, 7, 9); + +you're using the comma operator in scalar context, so it evaluates the +left hand side, then evaluates and returns the left hand side. This +causes the last value to be returned: 9. + =head2 What is the difference between $array[1] and @array[1]? The former is a scalar value, the latter an array slice, which makes @@ -724,6 +868,8 @@ nice in that it won't work with false values like undef, 0, or ""; =back +But perhaps you should have been using a hash all along, eh? + =head2 How can I tell whether a list or array contains a certain element? Hearing the word "in" is an I<in>dication that you probably should have @@ -770,7 +916,17 @@ or worse yet These are slow (checks every element even if the first matches), inefficient (same reason), and potentially buggy (what if there are -regexp characters in $whatever?). +regexp characters in $whatever?). If you're only testing once, then +use: + + $is_there = 0; + foreach $elt (@array) { + if ($elt eq $elt_to_find) { + $is_there = 1; + last; + } + } + if ($is_there) { ... } =head2 How do I compute the difference of two arrays? How do I compute the intersection of two arrays? @@ -785,11 +941,60 @@ each element is unique in a given array: push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element; } +=head2 How do I test whether two arrays or hashes are equal? + +The following code works for single-level arrays. It uses a stringwise +comparison, and does not distinguish defined versus undefined empty +strings. Modify if you have other needs. + + $are_equal = compare_arrays(\@frogs, \@toads); + + sub compare_arrays { + my ($first, $second) = @_; + local $^W = 0; # silence spurious -w undef complaints + return 0 unless @$first == @$second; + for (my $i = 0; $i < @$first; $i++) { + return 0 if $first->[$i] ne $second->[$i]; + } + return 1; + } + +For multilevel structures, you may wish to use an approach more +like this one. It uses the CPAN module FreezeThaw: + + use FreezeThaw qw(cmpStr); + @a = @b = ( "this", "that", [ "more", "stuff" ] ); + + printf "a and b contain %s arrays\n", + cmpStr(\@a, \@b) == 0 + ? "the same" + : "different"; + +This approach also works for comparing hashes. Here +we'll demonstrate two different answers: + + use FreezeThaw qw(cmpStr cmpStrHard); + + %a = %b = ( "this" => "that", "extra" => [ "more", "stuff" ] ); + $a{EXTRA} = \%b; + $b{EXTRA} = \%a; + + printf "a and b contain %s hashes\n", + cmpStr(\%a, \%b) == 0 ? "the same" : "different"; + + printf "a and b contain %s hashes\n", + cmpStrHard(\%a, \%b) == 0 ? "the same" : "different"; + + +The first reports that both those the hashes contain the same data, +while the second reports that they do not. Which you prefer is left as +an exercise to the reader. + =head2 How do I find the first array element for which a condition is true? You can use this if you care about the index: - for ($i=0; $i < @array; $i++) { + for ($i= 0; $i < @array; $i++) { if ($array[$i] eq "Waldo") { $found_index = $i; last; @@ -810,7 +1015,42 @@ need to copy pointers each time. If you really, really wanted, you could use structures as described in L<perldsc> or L<perltoot> and do just what the algorithm book tells you -to do. +to do. For example, imagine a list node like this: + + $node = { + VALUE => 42, + LINK => undef, + }; + +You could walk the list this way: + + print "List: "; + for ($node = $head; $node; $node = $node->{LINK}) { + print $node->{VALUE}, " "; + } + print "\n"; + +You could grow the list this way: + + my ($head, $tail); + $tail = append($head, 1); # grow a new head + for $value ( 2 .. 10 ) { + $tail = append($tail, $value); + } + + sub append { + my($list, $value) = @_; + my $node = { VALUE => $value }; + if ($list) { + $node->{LINK} = $list->{LINK}; + $list->{LINK} = $node; + } else { + $_[0] = $node; # replace caller's version + } + return $node; + } + +But again, Perl's built-in are virtually always good enough. =head2 How do I handle circular lists? @@ -1006,9 +1246,54 @@ get those bits into your @ints array: This method gets faster the more sparse the bit vector is. (Courtesy of Tim Bunce and Winfried Koenig.) +Here's a demo on how to use vec(): + + # vec demo + $vector = "\xff\x0f\xef\xfe"; + print "Ilya's string \\xff\\x0f\\xef\\xfe represents the number ", + unpack("N", $vector), "\n"; + $is_set = vec($vector, 23, 1); + print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\n"; + pvec($vector); + + set_vec(1,1,1); + set_vec(3,1,1); + set_vec(23,1,1); + + set_vec(3,1,3); + set_vec(3,2,3); + set_vec(3,4,3); + set_vec(3,4,7); + set_vec(3,8,3); + set_vec(3,8,7); + + set_vec(0,32,17); + set_vec(1,32,17); + + sub set_vec { + my ($offset, $width, $value) = @_; + my $vector = ''; + vec($vector, $offset, $width) = $value; + print "offset=$offset width=$width value=$value\n"; + pvec($vector); + } + + sub pvec { + my $vector = shift; + my $bits = unpack("b*", $vector); + my $i = 0; + my $BASE = 8; + + print "vector length in bytes: ", length($vector), "\n"; + @bytes = unpack("A8" x length($vector), $bits); + print "bits are: @bytes\n\n"; + } + =head2 Why does defined() return true on empty arrays and hashes? -See L<perlfunc/defined> in the 5.004 release or later of Perl. +The short story is that you should probably only use defined on scalars or +functions, not on aggregates (arrays and hashes). See L<perlfunc/defined> +in the 5.004 release or later of Perl for more detail. =head1 Data: Hashes (Associative Arrays) @@ -1243,9 +1528,21 @@ awk's behavior. =head2 How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? -Use references (documented in L<perlref>). Examples of complex data -structures are given in L<perldsc> and L<perllol>. Examples of -structures and object-oriented classes are in L<perltoot>. +Usually a hash ref, perhaps like this: + + $record = { + NAME => "Jason", + EMPNO => 132, + TITLE => "deputy peon", + AGE => 23, + SALARY => 37_000, + PALS => [ "Norbert", "Rhys", "Phineas"], + }; + +References are documented in L<perlref> and the upcoming L<perlreftut>. +Examples of complex data structures are given in L<perldsc> and +L<perllol>. Examples of structures and object-oriented classes are +in L<perltoot>. =head2 How can I use a reference as a hash key? @@ -1263,8 +1560,9 @@ this works fine (assuming the files are found): print "Your kernel is GNU-zip enabled!\n"; } -On some systems, however, you have to play tedious games with "text" -versus "binary" files. See L<perlfunc/"binmode">. +On some legacy systems, however, you have to play tedious games with +"text" versus "binary" files. See L<perlfunc/"binmode">, or the upcoming +L<perlopentut> manpage. If you're concerned about 8-bit ASCII data, then see L<perllocale>. @@ -1276,14 +1574,14 @@ some gotchas. See the section on Regular Expressions. Assuming that you don't care about IEEE notations like "NaN" or "Infinity", you probably just want to use a regular expression. - warn "has nondigits" if /\D/; - warn "not a natural number" unless /^\d+$/; # rejects -3 - warn "not an integer" unless /^-?\d+$/; # rejects +3 - warn "not an integer" unless /^[+-]?\d+$/; - warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2 - warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/; - warn "not a C float" - unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/; + if (/\D/) { print "has nondigits\n" } + if (/^\d+$/) { print "is a whole number\n" } + if (/^-?\d+$/) { print "is an integer\n" } + if (/^[+-]?\d+$/) { print "is a +/- integer\n" } + if (/^-?\d+\.?\d*$/) { print "is a real number\n" } + if (/^-?(?:\d+(?:\.\d*)?|\.\d+)$/) { print "is a decimal number" } + if (/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/) + { print "a C float" } If you're on a POSIX system, Perl's supports the C<POSIX::strtod> function. Its semantics are somewhat cumbersome, so here's a C<getnum> @@ -1308,28 +1606,41 @@ if you just want to say, ``Is this a float?'' sub is_numeric { defined &getnum } -Or you could check out -http://www.perl.com/CPAN/modules/by-module/String/String-Scanf-1.1.tar.gz -instead. The POSIX module (part of the standard Perl distribution) -provides the C<strtol> and C<strtod> for converting strings to double +Or you could check out String::Scanf which can be found at +http://www.perl.com/CPAN/modules/by-module/String/. +The POSIX module (part of the standard Perl distribution) provides +the C<strtol> and C<strtod> for converting strings to double and longs, respectively. =head2 How do I keep persistent data across program calls? For some specific applications, you can use one of the DBM modules. -See L<AnyDBM_File>. More generically, you should consult the -FreezeThaw, Storable, or Class::Eroot modules from CPAN. +See L<AnyDBM_File>. More generically, you should consult the FreezeThaw, +Storable, or Class::Eroot modules from CPAN. Here's one example using +Storable's C<store> and C<retrieve> functions: + + use Storable; + store(\%hash, "filename"); + + # later on... + $href = retrieve("filename"); # by ref + %hash = %{ retrieve("filename") }; # direct to hash =head2 How do I print out or copy a recursive data structure? -The Data::Dumper module on CPAN is nice for printing out -data structures, and FreezeThaw for copying them. For example: +The Data::Dumper module on CPAN (or the 5.005 release of Perl) is great +for printing out data structures. The Storable module, found on CPAN, +provides a function called C<dclone> that recursively copies its argument. + + use Storable qw(dclone); + $r2 = dclone($r1); - use FreezeThaw qw(freeze thaw); - $new = thaw freeze $old; +Where $r1 can be a reference to any kind of data structure you'd like. +It will be deeply copied. Because C<dclone> takes and returns references, +you'd have to add extra punctuation if you had a hash of arrays that +you wanted to copy. -Where $old can be (a reference to) any kind of data structure you'd like. -It will be deeply copied. + %newhash = %{ dclone(\%oldhash) }; =head2 How do I define methods for every class/object? @@ -1339,14 +1650,20 @@ Use the UNIVERSAL class (see L<UNIVERSAL>). Get the Business::CreditCard module from CPAN. +=head2 How do I pack arrays of doubles or floats for XS code? + +The kgbpack.c code in the PGPLOT module on CPAN does just this. +If you're doing a lot of float or double processing, consider using +the PDL module from CPAN instead--it makes number-crunching easy. + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. +may be distributed only under the terms of Perl's Artistic Licence. Any distribution of this file or derivatives thereof I<outside> of that package require that special arrangements be made with copyright holder. @@ -1356,3 +1673,4 @@ are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq5.pod b/contrib/perl5/pod/perlfaq5.pod index 98e706a..99c25b7 100644 --- a/contrib/perl5/pod/perlfaq5.pod +++ b/contrib/perl5/pod/perlfaq5.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq5 - Files and Formats ($Revision: 1.24 $, $Date: 1998/07/05 15:07:20 $) +perlfaq5 - Files and Formats ($Revision: 1.34 $, $Date: 1999/01/08 05:46:13 $) =head1 DESCRIPTION @@ -78,12 +78,15 @@ See L<perlfaq9> for other examples of fetching URLs over the web. =head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file? +Those are operations of a text editor. Perl is not a text editor. +Perl is a programming language. You have to decompose the problem into +low-level calls to read, write, open, close, and seek. + Although humans have an easy time thinking of a text file as being a -sequence of lines that operates much like a stack of playing cards -- -or punch cards -- computers usually see the text file as a sequence of -bytes. In general, there's no direct way for Perl to seek to a -particular line of a file, insert text into a file, or remove text -from a file. +sequence of lines that operates much like a stack of playing cards -- or +punch cards -- computers usually see the text file as a sequence of bytes. +In general, there's no direct way for Perl to seek to a particular line +of a file, insert text into a file, or remove text from a file. (There are exceptions in special circumstances. You can add or remove at the very end of the file. Another is replacing a sequence of bytes with @@ -97,7 +100,7 @@ no locking. $old = $file; $new = "$file.tmp.$$"; - $bak = "$file.bak"; + $bak = "$file.orig"; open(OLD, "< $old") or die "can't open $old: $!"; open(NEW, "> $new") or die "can't open $new: $!"; @@ -124,7 +127,7 @@ platform-specific documentation that came with your port. perl -pi -e 's/(^\s+test\s+)\d+/ $1 . ++$count /e' t/op/taint.t # form a script - local($^I, @ARGV) = ('.bak', glob("*.c")); + local($^I, @ARGV) = ('.orig', glob("*.c")); while (<>) { if ($. == 1) { print "This line should appear at the top of each file\n"; @@ -174,9 +177,9 @@ Use the C<new_tmpfile> class method from the IO::File module to get a filehandle opened for reading and writing. Use this if you don't need to know the file's name. - use IO::File; + use IO::File; $fh = IO::File->new_tmpfile() - or die "Unable to make new temporary file: $!"; + or die "Unable to make new temporary file: $!"; Or you can use the C<tmpnam> function from the POSIX module to get a filename that you then open yourself. Use this if you do need to know @@ -222,7 +225,7 @@ one process, use a counter: =head2 How can I manipulate fixed-record-length files? The most efficient way is using pack() and unpack(). This is faster than -using substr() when take many, many strings. It is slower for just a few. +using substr() when taking many, many strings. It is slower for just a few. Here is a sample chunk of code to break up and put back together again some fixed-format input lines, in this case from the output of a normal, @@ -289,10 +292,10 @@ pair to make it easy to sort the hash in insertion order. } For passing filehandles to functions, the easiest way is to -prefer them with a star, as in func(*STDIN). See L<perlfaq7/"Passing +preface them with a star, as in func(*STDIN). See L<perlfaq7/"Passing Filehandles"> for details. -If you want to create many, anonymous handles, you should check out the +If you want to create many anonymous handles, you should check out the Symbol, FileHandle, or IO::Handle (etc.) modules. Here's the equivalent code with Symbol::gensym, which is reasonably light-weight: @@ -303,8 +306,8 @@ code with Symbol::gensym, which is reasonably light-weight: $file{$filename} = [ $i++, $fh ]; } -Or here using the semi-object-oriented FileHandle, which certainly isn't -light-weight: +Or here using the semi-object-oriented FileHandle module, which certainly +isn't light-weight: use FileHandle; @@ -343,7 +346,7 @@ and use it as though it were a normal filehandle. Then use any of those as you would a normal filehandle. Anywhere that Perl is expecting a filehandle, an indirect filehandle may be used instead. An indirect filehandle is just a scalar variable that contains -a filehandle. Functions like C<print>, C<open>, C<seek>, or the functions or +a filehandle. Functions like C<print>, C<open>, C<seek>, or the C<E<lt>FHE<gt>> diamond operator will accept either a read filehandle or a scalar variable containing one: @@ -352,7 +355,7 @@ or a scalar variable containing one: $got = <$ifh> print $efh "What was that: $got"; -Of you're passing a filehandle to a function, you can write +If you're passing a filehandle to a function, you can write the function in two ways: sub accept_fh { @@ -422,7 +425,7 @@ techniques to make it possible for the intrepid hacker. =head2 How can I write() into a string? -See L<perlform> for an swrite() function. +See L<perlform/"Accessing Formatting Internals"> for an swrite() function. =head2 How can I output my numbers with commas added? @@ -430,7 +433,7 @@ This one will do it for you: sub commify { local $_ = shift; - 1 while s/^(-?\d+)(\d{3})/$1,$2/; + 1 while s/^([-+]?\d+)(\d{3})/$1,$2/; return $_; } @@ -441,7 +444,7 @@ This one will do it for you: You can't just: - s/^(-?\d+)(\d{3})/$1,$2/g; + s/^([-+]?\d+)(\d{3})/$1,$2/g; because you have to put the comma in and then recalculate your position. @@ -455,7 +458,7 @@ whatever: my $input = shift; $input = reverse $input; $input =~ s<(\d\d\d)(?=\d)(?!\d*\.)><$1,>g; - return reverse $input; + return scalar reverse $input; } =head2 How can I translate tildes (~) in a filename? @@ -547,7 +550,9 @@ be an atomic operation over NFS. That is, two processes might both successful create or unlink the same file! Therefore O_EXCL isn't so exclusive as you might wish. -=head2 Why do I sometimes get an "Argument list too long" when I use <*>? +See also the new L<perlopentut> if you have it (new for 5.006). + +=head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>? The C<E<lt>E<gt>> operator performs a globbing operation (see above). By default glob() forks csh(1) to do the actual glob expansion, but @@ -555,9 +560,9 @@ csh can't handle more than 127 items and so gives the error message C<Argument list too long>. People who installed tcsh as csh won't have this problem, but their users may be surprised by it. -To get around this, either do the glob yourself with C<Dirhandle>s and +To get around this, either do the glob yourself with readdir() and patterns, or use a module like Glob::KGlob, one that doesn't use the -shell to do globbing. +shell to do globbing. This is expected to be fixed soon. =head2 Is there a leak/bug in glob()? @@ -576,15 +581,28 @@ trailing null byte on the name to make perl leave it alone: sub safe_filename { local $_ = shift; - return m#^/# - ? "$_\0" - : "./$_\0"; + s#^([^./])#./$1#; + $_ .= "\0"; + return $_; } - $fn = safe_filename("<<<something really wicked "); - open(FH, "> $fn") or "couldn't open $fn: $!"; + $badpath = "<<<something really wicked "; + $fn = safe_filename($badpath"); + open(FH, "> $fn") or "couldn't open $badpath: $!"; + +This assumes that you are using POSIX (portable operating systems +interface) paths. If you are on a closed, non-portable, proprietary +system, you may have to adjust the C<"./"> above. + +It would be a lot clearer to use sysopen(), though: + + use Fcntl; + $badpath = "<<<something really wicked "; + open (FH, $badpath, O_WRONLY | O_CREAT | O_TRUNC) + or die "can't open $badpath: $!"; -You could also use the sysopen() function (see L<perlfunc/sysopen>). +For more information, see also the new L<perlopentut> if you have it +(new for 5.006). =head2 How can I reliably rename a file? @@ -601,7 +619,7 @@ then delete the old one. This isn't really the same semantics as a real rename(), though, which preserves metainformation like permissions, timestamps, inode info, etc. -The newer version of File::Copy export a move() function. +The newer version of File::Copy exports a move() function. =head2 How can I lock a file? @@ -631,9 +649,12 @@ build Perl. See the flock entry of L<perlfunc>, and the F<INSTALL> file in the source distribution for information on building Perl to do this. +For more information on file locking, see also L<perlopentut/"File +Locking"> if you have it (new for 5.006). + =back -=head2 What can't I just open(FH, ">file.lock")? +=head2 Why can't I just open(FH, ">file.lock")? A common bit of code B<NOT TO USE> is this: @@ -649,7 +670,7 @@ atomic test-and-set instruction. In theory, this "ought" to work: except that lamentably, file creation (and deletion) is not atomic over NFS, so this won't work (at least, not every time) over the net. -Various schemes involving involving link() have been suggested, but +Various schemes involving link() have been suggested, but these tend to involve busy-wait, which is also subdesirable. =head2 I still don't get locking. I just want to increment the number in the file. How can I do this? @@ -661,14 +682,15 @@ It's more realistic. Anyway, this is what you can do if you can't help yourself. - use Fcntl; + use Fcntl ':flock'; sysopen(FH, "numfile", O_RDWR|O_CREAT) or die "can't open numfile: $!"; - flock(FH, 2) or die "can't flock numfile: $!"; + flock(FH, LOCK_EX) or die "can't flock numfile: $!"; $num = <FH> || 0; seek(FH, 0, 0) or die "can't rewind numfile: $!"; truncate(FH, 0) or die "can't truncate numfile: $!"; (print FH $num+1, "\n") or die "can't write numfile: $!"; - # DO NOT UNLOCK THIS UNTIL YOU CLOSE + # Perl as of 5.004 automatically flushes before unlocking + flock(FH, LOCK_UN) or die "can't flock numfile: $!"; close FH or die "can't close numfile: $!"; Here's a much better web-page hit counter: @@ -693,7 +715,7 @@ like this: seek(FH, $recno * $RECSIZE, 0); read(FH, $record, $RECSIZE) == $RECSIZE || die "can't read record $recno: $!"; # munge the record - seek(FH, $recno * $RECSIZE, 0); + seek(FH, -$RECSIZE, 1); print FH $record; close FH; @@ -720,12 +742,15 @@ Here's an example: If you prefer something more legible, use the File::stat module (part of the standard distribution in version 5.004 and later): + # error checking left as an exercise for reader. use File::stat; use Time::localtime; $date_string = ctime(stat($file)->mtime); print "file $file updated at $date_string\n"; -Error checking is left as an exercise for the reader. +The POSIX::strftime() approach has the benefit of being, +in theory, independent of the current locale. See L<perllocale> +for details. =head2 How do I set a file's timestamp in perl? @@ -741,7 +766,7 @@ of them. ($atime, $mtime) = (stat($timestamp))[8,9]; utime $atime, $mtime, @ARGV; -Error checking is left as an exercise for the reader. +Error checking is, as usual, left as an exercise for the reader. Note that utime() currently doesn't work correctly with Win95/NT ports. A bug has been reported. Check it carefully before using @@ -774,11 +799,14 @@ than the stock version. =head2 How can I read in a file by paragraphs? -Use the C<$\> variable (see L<perlvar> for details). You can either +Use the C<$/> variable (see L<perlvar> for details). You can either set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">, for instance, gets treated as two paragraphs and not three), or C<"\n\n"> to accept empty paragraphs. +Note that a blank line must have no blanks in it. Thus C<"fred\n +\nstuff\n\n"> is one paragraph, but C<"fred\n\nstuff\n\n"> is two. + =head2 How can I read a single character from a file? From the keyboard? You can use the builtin C<getc()> function for most filehandles, but @@ -786,8 +814,9 @@ it won't (easily) work on a terminal device. For STDIN, either use the Term::ReadKey module from CPAN, or use the sample code in L<perlfunc/getc>. -If your system supports POSIX, you can use the following code, which -you'll note turns off echo processing as well. +If your system supports the portable operating system programming +interface (POSIX), you can use the following code, which you'll note +turns off echo processing as well. #!/usr/bin/perl -w use strict; @@ -838,7 +867,8 @@ you'll note turns off echo processing as well. END { cooked() } -The Term::ReadKey module from CPAN may be easier to use: +The Term::ReadKey module from CPAN may be easier to use. Recent version +include also support for non-portable systems as well. use Term::ReadKey; open(TTY, "</dev/tty"); @@ -849,7 +879,7 @@ The Term::ReadKey module from CPAN may be easier to use: printf "\nYou said %s, char number %03d\n", $key, ord $key; -For DOS systems, Dan Carson <dbc@tc.fluke.COM> reports the following: +For legacy DOS systems, Dan Carson <dbc@tc.fluke.COM> reports the following: To put the PC in "raw" mode, use ioctl with some magic numbers gleaned from msdos.c (Perl source file) and Ralf Brown's interrupt list (comes @@ -895,11 +925,12 @@ table: This is all trial and error I did a long time ago, I hope I'm reading the file that worked. -=head2 How can I tell if there's a character waiting on a filehandle? +=head2 How can I tell whether there's a character waiting on a filehandle? The very first thing you should do is look into getting the Term::ReadKey -extension from CPAN. It now even has limited support for closed, proprietary -(read: not open systems, not POSIX, not Unix, etc) systems. +extension from CPAN. As we mentioned earlier, it now even has limited +support for non-portable (read: not open systems, closed, proprietary, +not POSIX, not Unix, etc) systems. You should also check out the Frequently Asked Questions list in comp.unix.* for things like this: the answer is essentially the same. @@ -912,12 +943,11 @@ systems: return $nfd = select($rin,undef,undef,0); } -If you want to find out how many characters are waiting, -there's also the FIONREAD ioctl call to be looked at. - -The I<h2ph> tool that comes with Perl tries to convert C include -files to Perl code, which can be C<require>d. FIONREAD ends -up defined as a function in the I<sys/ioctl.ph> file: +If you want to find out how many characters are waiting, there's +also the FIONREAD ioctl call to be looked at. The I<h2ph> tool that +comes with Perl tries to convert C include files to Perl code, which +can be C<require>d. FIONREAD ends up defined as a function in the +I<sys/ioctl.ph> file: require 'sys/ioctl.ph'; @@ -939,7 +969,7 @@ Or write a small C program using the editor of champions: printf("%#08x\n", FIONREAD); } ^D - % cc -o fionread fionread + % cc -o fionread fionread.c % ./fionread 0x4004667f @@ -980,6 +1010,8 @@ the clearerr() method, which can remove the end of file condition on a filehandle. The method: read until end of file, clearerr(), read some more. Lather, rinse, repeat. +There's also a File::Tail module from CPAN. + =head2 How do I dup() a filehandle in Perl? If you check L<perlfunc/open>, you'll see that several of the ways @@ -1018,19 +1050,22 @@ Remember that within double quoted strings ("like\this"), the backslash is an escape character. The full list of these is in L<perlop/Quote and Quote-like Operators>. Unsurprisingly, you don't have a file called "c:(tab)emp(formfeed)oo" or -"c:(tab)emp(formfeed)oo.exe" on your DOS filesystem. +"c:(tab)emp(formfeed)oo.exe" on your legacy DOS filesystem. Either single-quote your strings, or (preferably) use forward slashes. Since all DOS and Windows versions since something like MS-DOS 2.0 or so have treated C</> and C<\> the same in a path, you might as well use the one that doesn't clash with Perl -- or the POSIX shell, ANSI C and C++, -awk, Tcl, Java, or Python, just to mention a few. +awk, Tcl, Java, or Python, just to mention a few. POSIX paths +are more portable, too. =head2 Why doesn't glob("*.*") get all the files? Because even on non-Unix ports, Perl's glob function follows standard Unix globbing semantics. You'll need C<glob("*")> to get all (non-hidden) -files. This makes glob() portable. +files. This makes glob() portable even to legacy systems. Your +port may include proprietary globbing functions as well. Check its +documentation for details. =head2 Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? @@ -1057,13 +1092,36 @@ This has a significant advantage in space over reading the whole file in. A simple proof by induction is available upon request if you doubt its correctness. +=head2 Why do I get weird spaces when I print an array of lines? + +Saying + + print "@lines\n"; + +joins together the elements of C<@lines> with a space between them. +If C<@lines> were C<("little", "fluffy", "clouds")> then the above +statement would print: + + little fluffy clouds + +but if each element of C<@lines> was a line of text, ending a newline +character C<("little\n", "fluffy\n", "clouds\n")> then it would print: + + little + fluffy + clouds + +If your array contains lines, just print them: + + print @lines; + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution -of Perl or of its documentation (printed or otherwise), this works is +of Perl or of its documentation (printed or otherwise), this work is covered under Perl's Artistic Licence. For separate distributions of all or part of this FAQ outside of that, see L<perlfaq>. @@ -1072,3 +1130,4 @@ domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq6.pod b/contrib/perl5/pod/perlfaq6.pod index 488a27c..234570d 100644 --- a/contrib/perl5/pod/perlfaq6.pod +++ b/contrib/perl5/pod/perlfaq6.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq6 - Regexps ($Revision: 1.22 $, $Date: 1998/07/16 14:01:07 $) +perlfaq6 - Regexps ($Revision: 1.25 $, $Date: 1999/01/08 04:50:47 $) =head1 DESCRIPTION @@ -128,7 +128,7 @@ L<perlop>): If you wanted text and not lines, you would use - perl -0777 -pe 'print "$1\n" while /START(.*?)END/gs' file1 file2 ... + perl -0777 -ne 'print "$1\n" while /START(.*?)END/gs' file1 file2 ... But if you want nested occurrences of C<START> through C<END>, you'll run up against the problem described in the question in this section @@ -387,48 +387,31 @@ See the module String::Approx available from CPAN. =head2 How do I efficiently match many regular expressions at once? -The following is super-inefficient: +The following is extremely inefficient: - while (<FH>) { - foreach $pat (@patterns) { - if ( /$pat/ ) { - # do something - } - } - } - -Instead, you either need to use one of the experimental Regexp extension -modules from CPAN (which might well be overkill for your purposes), -or else put together something like this, inspired from a routine -in Jeffrey Friedl's book: - - sub _bm_build { - my $condition = shift; - my @regexp = @_; # this MUST not be local(); need my() - my $expr = join $condition => map { "m/\$regexp[$_]/o" } (0..$#regexp); - my $match_func = eval "sub { $expr }"; - die if $@; # propagate $@; this shouldn't happen! - return $match_func; - } - - sub bm_and { _bm_build('&&', @_) } - sub bm_or { _bm_build('||', @_) } - - $f1 = bm_and qw{ - xterm - (?i)window - }; - - $f2 = bm_or qw{ - \b[Ff]ree\b - \bBSD\B - (?i)sys(tem)?\s*[V5]\b - }; - - # feed me /etc/termcap, prolly - while ( <> ) { - print "1: $_" if &$f1; - print "2: $_" if &$f2; + # slow but obvious way + @popstates = qw(CO ON MI WI MN); + while (defined($line = <>)) { + for $state (@popstates) { + if ($line =~ /\b$state\b/i) { + print $line; + last; + } + } + } + +That's because Perl has to recompile all those patterns for each of +the lines of the file. As of the 5.005 release, there's a much better +approach, one which makes use of the new C<qr//> operator: + + # use spiffy new qr// operator, with /i flag even + use 5.005; + @popstates = qw(CO ON MI WI MN); + @poppats = map { qr/\b$_\b/i } @popstates; + while (defined($line = <>)) { + for $patobj (@poppats) { + print $line if $line =~ /$patobj/; + } } =head2 Why don't word-boundary searches with C<\b> work for me? @@ -460,22 +443,24 @@ not "this" or "island". =head2 Why does using $&, $`, or $' slow my program down? -Because once Perl sees that you need one of these variables anywhere -in the program, it has to provide them on each and every pattern -match. The same mechanism that handles these provides for the use of -$1, $2, etc., so you pay the same price for each regexp that contains -capturing parentheses. But if you never use $&, etc., in your script, -then regexps I<without> capturing parentheses won't be penalized. So -avoid $&, $', and $` if you can, but if you can't (and some algorithms -really appreciate them), once you've used them once, use them at will, -because you've already paid the price. +Because once Perl sees that you need one of these variables anywhere in +the program, it has to provide them on each and every pattern match. +The same mechanism that handles these provides for the use of $1, $2, +etc., so you pay the same price for each regexp that contains capturing +parentheses. But if you never use $&, etc., in your script, then regexps +I<without> capturing parentheses won't be penalized. So avoid $&, $', +and $` if you can, but if you can't, once you've used them at all, use +them at will because you've already paid the price. Remember that some +algorithms really appreciate them. As of the 5.005 release. the $& +variable is no longer "expensive" the way the other two are. =head2 What good is C<\G> in a regular expression? The notation C<\G> is used in a match or substitution in conjunction the C</g> modifier (and ignored if there's no C</g>) to anchor the regular expression to the point just past where the last match occurred, i.e. the -pos() point. +pos() point. A failed match resets the position of C<\G> unless the +C</c> modifier is in effect. For example, suppose you had a line of text quoted in standard mail and Usenet notation, (that is, with leading C<E<gt>> characters), and @@ -596,25 +581,46 @@ Or like this: Or like this: - die "sorry, Perl doesn't (yet) have Martian support )-:\n"; - -In addition, a sample program which converts half-width to full-width -katakana (in Shift-JIS or EUC encoding) is available from CPAN as - -=for Tom make it so + die "sorry, Perl doesn't (yet) have Martian support )-:\n"; There are many double- (and multi-) byte encodings commonly used these days. Some versions of these have 1-, 2-, 3-, and 4-byte characters, all mixed. +=head2 How do I match a pattern that is supplied by the user? + +Well, if it's really a pattern, then just use + + chomp($pattern = <STDIN>); + if ($line =~ /$pattern/) { } + +Or, since you have no guarantee that your user entered +a valid regular expression, trap the exception this way: + + if (eval { $line =~ /$pattern/ }) { } + +But if all you really want to search for a string, not a pattern, +then you should either use the index() function, which is made for +string searching, or if you can't be disabused of using a pattern +match on a non-pattern, then be sure to use C<\Q>...C<\E>, documented +in L<perlre>. + + $pattern = <STDIN>; + + open (FILE, $input) or die "Couldn't open input $input: $!; aborting"; + while (<FILE>) { + print if /\Q$pattern\E/; + } + close FILE; + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. +may be distributed only under the terms of Perl's Artistic Licence. Any distribution of this file or derivatives thereof I<outside> of that package require that special arrangements be made with copyright holder. @@ -624,3 +630,4 @@ are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq7.pod b/contrib/perl5/pod/perlfaq7.pod index e1bccc8..a4ea872 100644 --- a/contrib/perl5/pod/perlfaq7.pod +++ b/contrib/perl5/pod/perlfaq7.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq7 - Perl Language Issues ($Revision: 1.21 $, $Date: 1998/06/22 15:20:07 $) +perlfaq7 - Perl Language Issues ($Revision: 1.24 $, $Date: 1999/01/08 05:32:11 $) =head1 DESCRIPTION @@ -180,7 +180,7 @@ own module. Make sure to change the names appropriately. # if using RCS/CVS, this next line may be preferred, # but beware two-digit versions. - $VERSION = do{my@r=q$Revision: 1.21 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r}; + $VERSION = do{my@r=q$Revision: 1.24 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r}; @ISA = qw(Exporter); @EXPORT = qw(&func1 &func2 &func3); @@ -229,6 +229,10 @@ own module. Make sure to change the names appropriately. 1; # modules must return true +The h2xs program will create stubs for all the important stuff for you: + + % h2xs -XA -n My::Module + =head2 How do I create a class? See L<perltoot> for an introduction to classes and objects, as well as @@ -313,7 +317,7 @@ caller's scope. Variable suicide is when you (temporarily or permanently) lose the value of a variable. It is caused by scoping through my() and local() -interacting with either closures or aliased foreach() interator +interacting with either closures or aliased foreach() iterator variables and subroutine arguments. It used to be easy to inadvertently lose a variable's value this way, but now it's much harder. Take this code: @@ -344,7 +348,7 @@ reference to an existing or anonymous variable or function: func( \$some_scalar ); - func( \$some_array ); + func( \@some_array ); func( [ 1 .. 10 ] ); func( \%some_hash ); @@ -392,7 +396,7 @@ If you're planning on generating new filehandles, you could do this: To pass regexps around, you'll need to either use one of the highly experimental regular expression modules from CPAN (Nick Ing-Simmons's Regexp or Ilya Zakharevich's Devel::Regexp), pass around strings -and use an exception-trapping eval, or else be be very, very clever. +and use an exception-trapping eval, or else be very, very clever. Here's an example of how to pass in a string to be regexp compared: sub compare($$) { @@ -484,7 +488,7 @@ could conceivably have several packages in that same file all accessing the same private variable, but another file with the same package couldn't get to it. -See L<perlsub/"Peristent Private Variables"> for details. +See L<perlsub/"Persistent Private Variables"> for details. =head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()? @@ -563,7 +567,7 @@ However, dynamic variables (aka global, local, or package variables) are effectively shallowly bound. Consider this just one more reason not to use them. See the answer to L<"What's a closure?">. -=head2 Why doesn't "my($foo) = <FILE>;" work right? +=head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right? C<my()> and C<local()> give list context to the right hand side of C<=>. The E<lt>FHE<gt> read operation, like so many of Perl's @@ -797,14 +801,39 @@ This can't go just anywhere. You have to put a pod directive where the parser is expecting a new statement, not just in the middle of an expression or some other arbitrary yacc grammar production. +=head2 How do I clear a package? + +Use this code, provided by Mark-Jason Dominus: + + sub scrub_package { + no strict 'refs'; + my $pack = shift; + die "Shouldn't delete main package" + if $pack eq "" || $pack eq "main"; + my $stash = *{$pack . '::'}{HASH}; + my $name; + foreach $name (keys %$stash) { + my $fullname = $pack . '::' . $name; + # Get rid of everything with that name. + undef $$fullname; + undef @$fullname; + undef %$fullname; + undef &$fullname; + undef *$fullname; + } + } + +Or, if you're using a recent release of Perl, you can +just use the Symbol::delete_package() function instead. + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. +may be distributed only under the terms of Perl's Artistic Licence. Any distribution of this file or derivatives thereof I<outside> of that package require that special arrangements be made with copyright holder. @@ -814,3 +843,4 @@ are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq8.pod b/contrib/perl5/pod/perlfaq8.pod index c4036ff..9ef41af 100644 --- a/contrib/perl5/pod/perlfaq8.pod +++ b/contrib/perl5/pod/perlfaq8.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq8 - System Interaction ($Revision: 1.26 $, $Date: 1998/08/05 12:20:28 $) +perlfaq8 - System Interaction ($Revision: 1.36 $, $Date: 1999/01/08 05:36:34 $) =head1 DESCRIPTION @@ -325,7 +325,6 @@ go bump in the night, finally came up with this: } } - =head2 How do I decode encrypted password files? You spend lots and lots of money on dedicated hardware, but this is @@ -452,9 +451,9 @@ http://www.perl.com/CPAN/doc/misc/ancient/tutorial/eg/itimers.pl . In general, you may not be able to. The Time::HiRes module (available from CPAN) provides this functionality for some systems. -In general, you may not be able to. But if your system supports both the -syscall() function in Perl as well as a system call like gettimeofday(2), -then you may be able to do something like this: +If your system supports both the syscall() function in Perl as well as +a system call like gettimeofday(2), then you may be able to do +something like this: require 'sys/syscall.ph'; @@ -462,7 +461,7 @@ then you may be able to do something like this: $done = $start = pack($TIMEVAL_T, ()); - syscall( &SYS_gettimeofday, $start, 0)) != -1 + syscall( &SYS_gettimeofday, $start, 0) != -1 or die "gettimeofday: $!"; ########################## @@ -674,19 +673,26 @@ there, and the old standard error shows up on the old standard out. =head2 Why doesn't open() return an error when a pipe open fails? -It does, but probably not how you expect it to. On systems that -follow the standard fork()/exec() paradigm (such as Unix), it works like -this: open() causes a fork(). In the parent, open() returns with the -process ID of the child. The child exec()s the command to be piped -to/from. The parent can't know whether the exec() was successful or -not - all it can return is whether the fork() succeeded or not. To -find out if the command succeeded, you have to catch SIGCHLD and -wait() to get the exit status. You should also catch SIGPIPE if -you're writing to the child -- you may not have found out the exec() +Because the pipe open takes place in two steps: first Perl calls +fork() to start a new process, then this new process calls exec() to +run the program you really wanted to open. The first step reports +success or failure to your process, so open() can only tell you +whether the fork() succeeded or not. + +To find out if the exec() step succeeded, you have to catch SIGCHLD +and wait() to get the exit status. You should also catch SIGPIPE if +you're writing to the child--you may not have found out the exec() failed by the time you write. This is documented in L<perlipc>. +In some cases, even this won't work. If the second argument to a +piped open() contains shell metacharacters, perl fork()s, then exec()s +a shell to decode the metacharacters and eventually run the desired +program. Now when you call wait(), you only learn whether or not the +I<shell> could be successfully started. Best to avoid shell +metacharacters. + On systems that follow the spawn() paradigm, open() I<might> do what -you expect - unless perl uses a shell to start your command. In this +you expect--unless perl uses a shell to start your command. In this case the fork()/exec() description still applies. =head2 What's wrong with using backticks in a void context? @@ -869,7 +875,7 @@ module for other solutions. =item * -Open /dev/tty and use the the TIOCNOTTY ioctl on it. See L<tty(4)> +Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty(4)> for details. Or better yet, you can just use the POSIX::setsid() function, so you don't have to worry about process groups. @@ -890,6 +896,9 @@ Background yourself like this: =back +The Proc::Daemon module, available from CPAN, provides a function to +perform these actions for you. + =head2 How do I make my program run with sh and csh? See the F<eg/nih> script (part of the perl source distribution). @@ -908,7 +917,7 @@ the current process group of your controlling terminal as follows: use POSIX qw/getpgrp tcgetpgrp/; open(TTY, "/dev/tty") or die $!; - $tpgrp = tcgetpgrp(TTY); + $tpgrp = tcgetpgrp(fileno(*TTY)); $pgrp = getpgrp(); if ($tpgrp == $pgrp) { print "foreground\n"; @@ -1034,6 +1043,13 @@ scripts that use the modules/libraries (see L<perlrun>) or say use lib '/u/mydir/perl'; +This is almost the same as: + + BEGIN { + unshift(@INC, '/u/mydir/perl'); + } + +except that the lib module checks for machine-dependent subdirectories. See Perl's L<lib> for more information. =head2 How do I add the directory my program lives in to the module/library search path? @@ -1048,7 +1064,7 @@ Here are the suggested ways of modifying your include path: the PERLLIB environment variable the PERL5LIB environment variable - the perl -Idir commpand line flag + the perl -Idir command line flag the use lib pragma, as in use lib "$ENV{HOME}/myown_perllib"; @@ -1056,14 +1072,20 @@ The latter is particularly useful because it knows about machine dependent architectures. The lib.pm pragmatic module was first included with the 5.002 release of Perl. +=head2 What is socket.ph and where do I get it? + +It's a perl4-style file defining values for system networking +constants. Sometimes it is built using h2ph when Perl is installed, +but other times it is not. Modern programs C<use Socket;> instead. + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. +may be distributed only under the terms of Perl's Artistic Licence. Any distribution of this file or derivatives thereof I<outside> of that package require that special arrangements be made with copyright holder. @@ -1073,3 +1095,4 @@ are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlfaq9.pod b/contrib/perl5/pod/perlfaq9.pod index 330158b..6536064 100644 --- a/contrib/perl5/pod/perlfaq9.pod +++ b/contrib/perl5/pod/perlfaq9.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq9 - Networking ($Revision: 1.20 $, $Date: 1998/06/22 18:31:09 $) +perlfaq9 - Networking ($Revision: 1.24 $, $Date: 1999/01/08 05:39:48 $) =head1 DESCRIPTION @@ -20,7 +20,7 @@ may not be so well received. The useful FAQs and related documents are: CGI FAQ - http://www.webthing.com/page.cgi/cgifaq + http://www.webthing.com/tutorials/cgifaq.html Web FAQ http://www.boutell.com/faq/ @@ -77,8 +77,7 @@ stamp prepended. =head2 How do I remove HTML from a string? The most correct way (albeit not the fastest) is to use HTML::Parse -from CPAN (part of the libwww-perl distribution, which is a must-have -module for all web hackers). +from CPAN (part of the HTML-Tree package on CPAN). Many folks attempt a simple-minded regular expression approach, like C<s/E<lt>.*?E<gt>//g>, but that fails in many cases because the tags @@ -172,6 +171,7 @@ do this. They work through proxies, and don't require lynx: getprint "http://www.sn.no/libwww-perl/"; # or print ASCII from HTML from a URL + # also need HTML-Tree package from CPAN use LWP::Simple; use HTML::Parse; use HTML::FormatText; @@ -213,7 +213,7 @@ Here's an example of decoding: $string =~ s/%([a-fA-F0-9]{2})/chr(hex($1))/ge; Encoding is a bit harder, because you can't just blindly change -all the non-alphanumunder character (C<\W>) into their hex escapes. +all the non-alphanumeric characters (C<\W>) into their hex escapes. It's important that characters with special meaning like C</> and C<?> I<not> be translated. Probably the easiest way to get this right is to avoid reinventing the wheel and just use the URI::Escape module, @@ -303,7 +303,7 @@ In short, they're bad hacks. Resist them at all costs. Please do not be tempted to reinvent the wheel. Instead, use the CGI.pm or CGI_Lite.pm (available from CPAN), or if you're trapped in the module-free land of perl1 .. perl4, you might look into cgi-lib.pl (available from -http://www.bio.cam.ac.uk/web/form.html). +http://cgi-lib.stanford.edu/cgi-lib/ ). Make sure you know whether to use a GET or a POST in your form. GETs should only be used for something that doesn't update the server. @@ -411,7 +411,8 @@ Use the C<sendmail> program directly: To: Final Destination <you\@otherhost> Subject: A relevant subject line - Body of the message goes here, in as many lines as you like. + Body of the message goes here after the blank line + in as many lines as you like. EOF close(SENDMAIL) or warn "sendmail didn't close nicely"; @@ -442,9 +443,8 @@ include queueing, MX records, and security. =head2 How do I read mail? -Use the Mail::Folder module from CPAN -(part of the MailFolder package) or the Mail::Internet module from -CPAN (also part of the MailTools package). +Use the Mail::Folder module from CPAN (part of the MailFolder package) or +the Mail::Internet module from CPAN (also part of the MailTools package). # sending mail use Mail::Internet; @@ -504,7 +504,7 @@ give you the hostname after which you can find out the IP address use Socket; use Sys::Hostname; my $host = hostname(); - my $addr = inet_ntoa(scalar(gethostbyname($name)) || 'localhost'); + my $addr = inet_ntoa(scalar gethostbyname($host || 'localhost')); Probably the simplest way to learn your DNS domain name is to grok it out of /etc/resolv.conf, at least under Unix. Of course, this @@ -531,16 +531,17 @@ available from CPAN) is more complex but can put as well as fetch. A DCE::RPC module is being developed (but is not yet available), and will be released as part of the DCE-Perl package (available from -CPAN). No ONC::RPC module is known. +CPAN). The rpcgen suite, available from CPAN/authors/id/JAKE/, is +an RPC stub generator and includes an RPC::ONC module. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. All rights reserved. When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work -may be distributed only under the terms of Perl's Artistic License. +may be distributed only under the terms of Perl's Artistic Licence. Any distribution of this file or derivatives thereof I<outside> of that package require that special arrangements be made with copyright holder. @@ -550,3 +551,4 @@ are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required. + diff --git a/contrib/perl5/pod/perlform.pod b/contrib/perl5/pod/perlform.pod index 6b65e04..b2c87fa 100644 --- a/contrib/perl5/pod/perlform.pod +++ b/contrib/perl5/pod/perlform.pod @@ -335,3 +335,12 @@ cannot be controlled by C<use locale> because the pragma is tied to the block structure of the program, and, for historical reasons, formats exist outside that block structure. See L<perllocale> for further discussion of locale handling. + +Inside of an expression, the whitespace characters \n, \t and \f are +considered to be equivalent to a single space. Thus, you could think +of this filter being applied to each value in the format: + + $value =~ tr/\n\t\f/ /; + +The remaining whitespace character, \r, forces the printing of a new +line if allowed by the picture line. diff --git a/contrib/perl5/pod/perlfunc.pod b/contrib/perl5/pod/perlfunc.pod index 4eac093..5fb7863 100644 --- a/contrib/perl5/pod/perlfunc.pod +++ b/contrib/perl5/pod/perlfunc.pod @@ -12,11 +12,12 @@ operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of a unary operator, but merely separates the arguments of a list operator. A unary operator generally provides a scalar context to its -argument, while a list operator may provide either scalar and list +argument, while a list operator may provide either scalar or list contexts for its arguments. If it does both, the scalar arguments will be first, and the list argument will follow. (Note that there can ever -be only one list argument.) For instance, splice() has three scalar -arguments followed by a list. +be only one such list argument.) For instance, splice() has three scalar +arguments followed by a list, whereas gethostbyname() has four scalar +arguments. In the syntax descriptions that follow, list operators that expect a list (and provide list context for the elements of the list) are shown @@ -47,6 +48,11 @@ example, the third line above produces: print (...) interpreted as function at - line 1. Useless use of integer addition in void context at - line 1. +A few functions take no arguments at all, and therefore work as neither +unary nor list operators. These include such functions as C<time> +and C<endpwent>. For example, C<time+86_400> always means +C<time() + 86_400>. + For functions that can be used in either a scalar or list context, nonabortive failure is generally indicated in a scalar context by returning the undefined value, and in a list context by returning the @@ -56,7 +62,7 @@ Remember the following important rule: There is B<no rule> that relates the behavior of an expression in list context to its behavior in scalar context, or vice versa. It might do two totally different things. Each operator and function decides which sort of value it would be most -appropriate to return in a scalar context. Some operators return the +appropriate to return in scalar context. Some operators return the length of the list that would have been returned in list context. Some operators return the first value in the list. Some operators return the last value in the list. Some operators return a count of successful @@ -129,8 +135,9 @@ C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec> =item Functions for filehandles, files, or directories C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>, -C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, C<readlink>, -C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>, C<unlink>, C<utime> +C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, +C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<umask>, +C<unlink>, C<utime> =item Keywords related to the control flow of your perl program @@ -206,6 +213,34 @@ C<dbmclose>, C<dbmopen> =back +=head2 Portability + +Perl was born in Unix and can therefore access all common Unix +system calls. In non-Unix environments, the functionality of some +Unix system calls may not be available, or details of the available +functionality may differ slightly. The Perl functions affected +by this are: + +C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>, +C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>, +C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>, +C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>, +C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, +C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>, +C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>, +C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>, +C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>, +C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>, +C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>, +C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>, +C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>, +C<shmwrite>, C<socket>, C<socketpair>, C<stat>, C<symlink>, C<syscall>, +C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<unlink>, +C<utime>, C<wait>, C<waitpid> + +For more information about the portability of these functions, see +L<perlport> and other available platform-specific documentation. + =head2 Alphabetical Listing of Perl Functions =over 8 @@ -262,15 +297,6 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> -A Same for access time. -C Same for inode change time. -The interpretation of the file permission operators C<-r>, C<-R>, C<-w>, -C<-W>, C<-x>, and C<-X> is based solely on the mode of the file and the -uids and gids of the user. There may be other reasons you can't actually -read, write, or execute the file, such as AFS access control lists. Also note that, for the superuser, -C<-r>, C<-R>, C<-w>, and C<-W> always return C<1>, and C<-x> and C<-X> return -C<1> if any execute bit is set in the mode. Scripts run by the superuser may -thus need to do a C<stat()> to determine the actual mode of the -file, or temporarily set the uid to something else. - Example: while (<>) { @@ -279,6 +305,20 @@ Example: #... } +The interpretation of the file permission operators C<-r>, C<-R>, +C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode +of the file and the uids and gids of the user. There may be other +reasons you can't actually read, write, or execute the file. Such +reasons may be for example network filesystem access controls, ACLs +(access control lists), read-only filesystems, and unrecognized +executable formats. + +Also note that, for the superuser on the local filesystems, the C<-r>, +C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1 +if any execute bit is set in the mode. Scripts run by the superuser +may thus need to do a stat() to determine the actual mode of the file, +or temporarily set their effective uid to something else. + Note that C<-s/a/b/> does not do a negated substitution. Saying C<-exp($foo)> still works as expected, however--only single letters following a minus are interpreted as file tests. @@ -324,7 +364,7 @@ If VALUE is omitted, uses C<$_>. Accepts an incoming socket connect, just as the accept(2) system call does. Returns the packed address if it succeeded, FALSE otherwise. -See example in L<perlipc/"Sockets: Client/Server Communication">. +See the example in L<perlipc/"Sockets: Client/Server Communication">. =item alarm SECONDS @@ -341,8 +381,12 @@ starting a new one. The returned value is the amount of time remaining on the previous timer. For delays of finer granularity than one second, you may use Perl's -C<syscall()> interface to access setitimer(2) if your system supports it, -or else see L</select()>. It is usually a mistake to intermix C<alarm()> +four-arugment version of select() leaving the first three arguments +undefined, or you might be able to use the C<syscall()> interface to +access setitimer(2) if your system supports it. The Time::HiRes module +from CPAN may also prove useful. + +It is usually a mistake to intermix C<alarm()> and C<sleep()> calls. If you want to use C<alarm()> to time out a system call you need to use an @@ -384,28 +428,42 @@ L<perlipc/"Sockets: Client/Server Communication">. =item binmode FILEHANDLE Arranges for the file to be read or written in "binary" mode in operating -systems that distinguish between binary and text files. Files that are -not in binary mode have CR LF sequences translated to LF on input and LF -translated to CR LF on output. Binmode has no effect under Unix; in MS-DOS -and similarly archaic systems, it may be imperative--otherwise your -MS-DOS-damaged C library may mangle your file. The key distinction between -systems that need C<binmode()> and those that don't is their text file -formats. Systems like Unix, MacOS, and Plan9 that delimit lines with a single -character, and that encode that character in C as C<"\n">, do not need -C<binmode()>. The rest need it. If FILEHANDLE is an expression, the value -is taken as the name of the filehandle. +systems that distinguish between binary and text files. Files that +are not in binary mode have CR LF sequences translated to LF on input +and LF translated to CR LF on output. Binmode has no effect under +many sytems, but in MS-DOS and similarly archaic systems, it may be +imperative--otherwise your MS-DOS-damaged C library may mangle your file. +The key distinction between systems that need C<binmode()> and those +that don't is their text file formats. Systems like Unix, MacOS, and +Plan9 that delimit lines with a single character, and that encode that +character in C as C<"\n">, do not need C<binmode()>. The rest may need it. +If FILEHANDLE is an expression, the value is taken as the name of the +filehandle. + +If the system does care about it, using it when you shouldn't is just as +perilous as failing to use it when you should. Fortunately for most of +us, you can't go wrong using binmode() on systems that don't care about +it, though. =item bless REF,CLASSNAME =item bless REF -This function tells the thingy referenced by REF that it is now -an object in the CLASSNAME package--or the current package if no CLASSNAME -is specified, which is often the case. It returns the reference for -convenience, because a C<bless()> is often the last thing in a constructor. -Always use the two-argument version if the function doing the blessing -might be inherited by a derived class. See L<perltoot> and L<perlobj> -for more about the blessing (and blessings) of objects. +This function tells the thingy referenced by REF that it is now an object +in the CLASSNAME package. If CLASSNAME is omitted, the current package +is used. Because a C<bless()> is often the last thing in a constructor. +it returns the reference for convenience. Always use the two-argument +version if the function doing the blessing might be inherited by a +derived class. See L<perltoot> and L<perlobj> for more about the blessing +(and blessings) of objects. + +Consider always blessing objects in CLASSNAMEs that are mixed case. +Namespaces with all lowercase names are considered reserved for +Perl pragmata. Builtin types have all uppercase names, so to prevent +confusion, you may wish to avoid such package names as well. Make sure +that CLASSNAME is a true value. + +See L<perlmod/"Perl Modules">. =item caller EXPR @@ -446,9 +504,9 @@ previous time C<caller()> was called. =item chdir EXPR -Changes the working directory to EXPR, if possible. If EXPR is -omitted, changes to home directory. Returns TRUE upon success, FALSE -otherwise. See example under C<die()>. +Changes the working directory to EXPR, if possible. If EXPR is omitted, +changes to the user's home directory. Returns TRUE upon success, +FALSE otherwise. See the example under C<die()>. =item chmod LIST @@ -471,14 +529,14 @@ successfully changed. See also L</oct>, if all you have is a string. =item chomp -This is a slightly safer version of L</chop>. It removes any -line ending that corresponds to the current value of C<$/> (also known as +This safer version of L</chop> removes any trailing string +that corresponds to the current value of C<$/> (also known as $INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total number of characters removed from all its arguments. It's often used to remove the newline from the end of an input record when you're worried -that the final record may be missing its newline. When in paragraph mode -(C<$/ = "">), it removes all trailing newlines from the string. If -VARIABLE is omitted, it chomps C<$_>. Example: +that the final record may be missing its newline. When in paragraph +mode (C<$/ = "">), it removes all trailing newlines from the string. +If VARIABLE is omitted, it chomps C<$_>. Example: while (<>) { chomp; # avoid \n on last field @@ -587,10 +645,10 @@ counter (C<$.>), while the implicit close done by C<open()> does not. If the file handle came from a piped open C<close()> will additionally return FALSE if one of the other system calls involved fails or if the program exits with non-zero status. (If the only problem was that the -program exited non-zero C<$!> will be set to C<0>.) Also, closing a pipe -waits for the process executing on the pipe to complete, in case you -want to look at the output of the pipe afterwards. Closing a pipe -explicitly also puts the exit status value of the command into C<$?>. +program exited non-zero C<$!> will be set to C<0>.) Closing a pipe +also waits for the process executing on the pipe to complete, in case you +want to look at the output of the pipe afterwards, and +implicitly puts the exit status value of that command into C<$?>. Example: @@ -673,19 +731,25 @@ eggs to make an omelette. There is no (known) corresponding decrypt function. As a result, this function isn't all that useful for cryptography. (For that, see your nearby CPAN mirror.) +When verifying an existing encrypted string you should use the encrypted +text as the salt (like C<crypt($plain, $crypted) eq $crypted>). This +allows your code to work with the standard C<crypt()> and with more +exotic implementations. When choosing a new salt create a random two +character string whose characters come from the set C<[./0-9A-Za-z]> +(like C<join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). + Here's an example that makes sure that whoever runs this program knows their own password: $pwd = (getpwuid($<))[1]; - $salt = substr($pwd, 0, 2); system "stty -echo"; print "Password: "; - chop($word = <STDIN>); + chomp($word = <STDIN>); print "\n"; system "stty echo"; - if (crypt($word, $salt) ne $pwd) { + if (crypt($word, $pwd) ne $pwd) { die "Sorry...\n"; } else { print "ok\n"; @@ -696,13 +760,13 @@ for it is unwise. =item dbmclose HASH -[This function has been superseded by the C<untie()> function.] +[This function has been largely superseded by the C<untie()> function.] Breaks the binding between a DBM file and a hash. =item dbmopen HASH,DBNAME,MODE -[This function has been superseded by the C<tie()> function.] +[This function has been largely superseded by the C<tie()> function.] This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a hash. HASH is the name of the hash. (Unlike normal C<open()>, the first @@ -735,6 +799,13 @@ See also L<AnyDBM_File> for a more general description of the pros and cons of the various dbm approaches, as well as L<DB_File> for a particularly rich implementation. +You can control which DBM library you use by loading that library +before you call dbmopen(): + + use DB_File; + dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") + or die "Can't open netscape history file: $!"; + =item defined EXPR =item defined @@ -779,7 +850,7 @@ defined values. For example, if you say The pattern match succeeds, and C<$1> is defined, despite the fact that it matched "nothing". But it didn't really match nothing--rather, it -matched something that happened to be C<0> characters long. This is all +matched something that happened to be zero characters long. This is all very above-board and honest. When a function returns an undefined value, it's an admission that it couldn't give you an honest answer. So you should use C<defined()> only when you're questioning the integrity of what @@ -825,9 +896,14 @@ And so does this: delete @HASH{keys %HASH} -(But both of these are slower than just assigning the empty list, or -using C<undef()>.) Note that the EXPR can be arbitrarily complicated as -long as the final operation is a hash element lookup or hash slice: +But both of these are slower than just assigning the empty list +or undefining it: + + %hash = (); # completely empty %hash + undef %hash; # forget %hash every existed + +Note that the EXPR can be arbitrarily complicated as long as the final +operation is a hash element lookup or hash slice: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; @@ -848,7 +924,12 @@ Equivalent examples: If the value of EXPR does not end in a newline, the current script line number and input line number (if any) are also printed, and a newline -is supplied. Hint: sometimes appending C<", stopped"> to your message +is supplied. Note that the "input line number" (also known as "chunk") +is subject to whatever notion of "line" happens to be currently in +effect, and is also available as the special variable C<$.>. +See L<perlvar/"$/"> and L<perlvar/"$.">. + +Hint: sometimes appending C<", stopped"> to your message will cause it to make better sense when the string C<"at foo line 123"> is appended. Suppose you are running script "canasta". @@ -860,7 +941,7 @@ produce, respectively /etc/games is no good at canasta line 123. /etc/games is no good, stopped at canasta line 123. -See also C<exit()> and C<warn()>. +See also exit(), warn(), and the Carp module. If LIST is empty and C<$@> already contains a value (typically from a previous eval) that value is reused after appending C<"\t...propagated">. @@ -871,19 +952,42 @@ This is useful for propagating exceptions: If C<$@> is empty then the string C<"Died"> is used. +die() can also be called with a reference argument. If this happens to be +trapped within an eval(), $@ contains the reference. This behavior permits +a more elaborate exception handling implementation using objects that +maintain arbitary state about the nature of the exception. Such a scheme +is sometimes preferable to matching particular string values of $@ using +regular expressions. Here's an example: + + eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; + if ($@) { + if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) { + # handle Some::Module::Exception + } + else { + # handle all other possible exceptions + } + } + +Since perl will stringify uncaught exception messages before displaying +them, you may want to overload stringification operations on such custom +exception objects. See L<overload> for details about that. + You can arrange for a callback to be run just before the C<die()> does its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler will be called with the error text and can change the error message, if it sees fit, by calling C<die()> again. See L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and L<"eval BLOCK"> for some examples. -Note that the C<$SIG{__DIE__}> hook is called even inside eval()ed -blocks/strings. If one wants the hook to do nothing in such +Note that the C<$SIG{__DIE__}> hook is currently called even inside +eval()ed blocks/strings! If one wants the hook to do nothing in such situations, put die @_ if $^S; -as the first line of the handler (see L<perlvar/$^S>). +as the first line of the handler (see L<perlvar/$^S>). Because this +promotes action at a distance, this counterintuitive behavior may be fixed +in a future release. =item do BLOCK @@ -892,6 +996,10 @@ sequence of commands indicated by BLOCK. When modified by a loop modifier, executes the BLOCK once before testing the loop condition. (On other statements the loop modifiers test the conditional first.) +C<do BLOCK> does I<not> count as a loop, so the loop control statements +C<next>, C<last>, or C<redo> cannot be used to leave or restart the block. +See L<perlsyn> for alternative strategies. + =item do SUBROUTINE(LIST) A deprecated form of subroutine call. See L<perlsub>. @@ -908,17 +1016,16 @@ is just like scalar eval `cat stat.pl`; -except that it's more efficient and concise, keeps track of the -current filename for error messages, and searches all the B<-I> -libraries if the file isn't in the current directory (see also the @INC -array in L<perlvar/Predefined Names>). It is also different in how -code evaluated with C<do FILENAME> doesn't see lexicals in the enclosing -scope like C<eval STRING> does. It's the same, however, in that it does -reparse the file every time you call it, so you probably don't want to -do this inside a loop. +except that it's more efficient and concise, keeps track of the current +filename for error messages, searches the @INC libraries, and updates +C<%INC> if the file is found. See L<perlvar/Predefined Names> for these +variables. It also differs in that code evaluated with C<do FILENAME> +cannot see lexicals in the enclosing scope; C<eval STRING> does. It's the +same, however, in that it does reparse the file every time you call it, +so you probably don't want to do this inside a loop. If C<do> cannot read the file, it returns undef and sets C<$!> to the -error. If C<do> can read the file but cannot compile it, it +error. If C<do> can read the file but cannot compile it, it returns undef and sets an error message in C<$@>. If the file is successfully compiled, C<do> returns the value of the last expression evaluated. @@ -932,7 +1039,8 @@ file. Manual error checking can be done this way: # read in config files: system first, then user for $file ("/share/prog/defaults.rc", - "$ENV{HOME}/.someprogrc") { + "$ENV{HOME}/.someprogrc") + { unless ($return = do $file) { warn "couldn't parse $file: $@" if $@; warn "couldn't do $file: $!" unless defined $return; @@ -942,6 +1050,8 @@ file. Manual error checking can be done this way: =item dump LABEL +=item dump + This causes an immediate core dump. Primarily this is so that you can use the B<undump> program to turn your core dump into an executable binary after having initialized all your variables at the beginning of the @@ -986,9 +1096,13 @@ element in the hash. (Note: Keys may be C<"0"> or C<"">, which are logically false; you may wish to avoid constructs like C<while ($k = each %foo) {}> for this reason.) -Entries are returned in an apparently random order. When the hash is -entirely read, a null array is returned in list context (which when -assigned produces a FALSE (C<0>) value), and C<undef> in +Entries are returned in an apparently random order. The actual random +order is subject to change in future versions of perl, but it is guaranteed +to be in the same order as either the C<keys()> or C<values()> function +would produce on the same (unmodified) hash. + +When the hash is entirely read, a null array is returned in list context +(which when assigned produces a FALSE (C<0>) value), and C<undef> in scalar context. The next call to C<each()> after that will start iterating again. There is a single iterator for each hash, shared by all C<each()>, C<keys()>, and C<values()> function calls in the program; it can be reset by @@ -1003,7 +1117,7 @@ only in a different order: print "$key=$value\n"; } -See also C<keys()> and C<values()>. +See also C<keys()>, C<values()> and C<sort()>. =item eof FILEHANDLE @@ -1020,11 +1134,11 @@ C<eof(FILEHANDLE)> on it) after end-of-file is reached. Filetypes such as terminals may lose the end-of-file condition if you do. An C<eof> without an argument uses the last file read as argument. -Using C<eof()> with empty parentheses is very different. It indicates the pseudo file formed of -the files listed on the command line, i.e., C<eof()> is reasonable to -use inside a C<while (E<lt>E<gt>)> loop to detect the end of only the -last file. Use C<eof(ARGV)> or eof without the parentheses to test -I<EACH> file in a while (E<lt>E<gt>) loop. Examples: +Using C<eof()> with empty parentheses is very different. It indicates +the pseudo file formed of the files listed on the command line, i.e., +C<eof()> is reasonable to use inside a C<while (E<lt>E<gt>)> loop to +detect the end of only the last file. Use C<eof(ARGV)> or eof without the +parentheses to test I<EACH> file in a while (E<lt>E<gt>) loop. Examples: # reset line numbering on each input file while (<>) { @@ -1038,7 +1152,7 @@ I<EACH> file in a while (E<lt>E<gt>) loop. Examples: while (<>) { if (eof()) { # check for end of current file print "--------------\n"; - close(ARGV); # close or break; is needed if we + close(ARGV); # close or last; is needed if we # are reading from the terminal } print; @@ -1107,10 +1221,11 @@ Examples: # a run-time error eval '$answer ='; # sets $@ -When using the C<eval{}> form as an exception trap in libraries, you may -wish not to trigger any C<__DIE__> hooks that user code may have -installed. You can use the C<local $SIG{__DIE__}> construct for this -purpose, as shown in this example: +Due to the current arguably broken state of C<__DIE__> hooks, when using +the C<eval{}> form as an exception trap in libraries, you may wish not +to trigger any C<__DIE__> hooks that user code may have installed. +You can use the C<local $SIG{__DIE__}> construct for this purpose, +as shown in this example: # a very private exception trap for divide-by-zero eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; @@ -1127,6 +1242,9 @@ C<die()> again, which has the effect of changing their error messages: print $@ if $@; # prints "bar lives here" } +Because this promotes action at a distance, this counterintuive behavior +may be fixed in a future release. + With an C<eval()>, you should be especially careful to remember what's being looked at when: @@ -1150,6 +1268,9 @@ normally you I<WOULD> like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6. +C<eval BLOCK> does I<not> count as a loop, so the loop control statements +C<next>, C<last>, or C<redo> cannot be used to leave or restart the block. + =item exec LIST =item exec PROGRAM LIST @@ -1207,9 +1328,9 @@ shell expanding wildcards or splitting up words with whitespace in them. @args = ( "echo surprise" ); - system @args; # subject to shell escapes + exec @args; # subject to shell escapes # if @args == 1 - system { $args[0] } @args; # safe even with one-arg list + exec { $args[0] } @args; # safe even with one-arg list The first version, the one without the indirect object, ran the I<echo> program, passing it C<"surprise"> an argument. The second version @@ -1224,9 +1345,9 @@ any C<DESTROY> methods in your objects. Returns TRUE if the specified hash key exists in its hash array, even if the corresponding value is undefined. - print "Exists\n" if exists $array{$key}; - print "Defined\n" if defined $array{$key}; - print "True\n" if $array{$key}; + print "Exists\n" if exists $array{$key}; + print "Defined\n" if defined $array{$key}; + print "True\n" if $array{$key}; A hash element can be TRUE only if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true. @@ -1234,40 +1355,53 @@ it exists, but the reverse doesn't necessarily hold true. Note that the EXPR can be arbitrarily complicated as long as the final operation is a hash key lookup: - if (exists $ref->{"A"}{"B"}{$key}) { ... } + if (exists $ref->{A}->{B}->{$key}) { } + if (exists $hash{A}{B}{$key}) { } -Although the last element will not spring into existence just because its -existence was tested, intervening ones will. Thus C<$ref-E<gt>{"A"}> -C<$ref-E<gt>{"B"}> will spring into existence due to the existence -test for a $key element. This autovivification may be fixed in a later +Although the last element will not spring into existence just because +its existence was tested, intervening ones will. Thus C<$ref-E<gt>{"A"}> +and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring into existence due to the +existence test for a $key element. This happens anywhere the arrow +operator is used, including even + + undef $ref; + if (exists $ref->{"Some key"}) { } + print $ref; # prints HASH(0x80d3d5c) + +This surprising autovivification in what does not at first--or even +second--glance appear to be an lvalue context may be fixed in a future release. =item exit EXPR -Evaluates EXPR and exits immediately with that value. (Actually, it -calls any defined C<END> routines first, but the C<END> routines may not -abort the exit. Likewise any object destructors that need to be called -are called before exit.) Example: +Evaluates EXPR and exits immediately with that value. Example: $ans = <STDIN>; exit 0 if $ans =~ /^[Xx]/; See also C<die()>. If EXPR is omitted, exits with C<0> status. The only -universally portable values for EXPR are C<0> for success and C<1> for error; -all other values are subject to unpredictable interpretation depending -on the environment in which the Perl program is running. +universally recognized values for EXPR are C<0> for success and C<1> +for error; other values are subject to interpretation depending on the +environment in which the Perl program is running. For example, exiting +69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause +the mailer to return the item undelivered, but that's not true everywhere. -You shouldn't use C<exit()> to abort a subroutine if there's any chance that +Don't use C<exit()> to abort a subroutine if there's any chance that someone might want to trap whatever error happened. Use C<die()> instead, which can be trapped by an C<eval()>. -All C<END{}> blocks are run at exit time. See L<perlsub> for details. +The exit() function does not always exit immediately. It calls any +defined C<END> routines first, but these C<END> routines may not +themselves abort the exit. Likewise any object destructors that need to +be called are called before the real exit. If this is a problem, you +can call C<POSIX:_exit($status)> to avoid END and destructor processing. +See L<perlsub> for details. =item exp EXPR =item exp -Returns I<e> (the natural logarithm base) to the power of EXPR. +Returns I<e> (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives C<exp($_)>. =item fcntl FILEHANDLE,FUNCTION,SCALAR @@ -1284,22 +1418,23 @@ For example: fcntl($filehandle, F_GETFL, $packed_return_buffer) or die "can't fcntl F_GETFL: $!"; -You don't have to check for C<defined()> on the return from -C<fnctl()>. Like C<ioctl()>, it maps a C<0> return from the system -call into "C<0> but true" in Perl. This string is true in -boolean context and C<0> in numeric context. It is also -exempt from the normal B<-w> warnings on improper numeric -conversions. +You don't have to check for C<defined()> on the return from C<fnctl()>. +Like C<ioctl()>, it maps a C<0> return from the system call into "C<0> +but true" in Perl. This string is true in boolean context and C<0> +in numeric context. It is also exempt from the normal B<-w> warnings +on improper numeric conversions. Note that C<fcntl()> will produce a fatal error if used on a machine that -doesn't implement fcntl(2). +doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) +manpage to learn what functions are available on your system. =item fileno FILEHANDLE -Returns the file descriptor for a filehandle. This is useful for -constructing bitmaps for C<select()> and low-level POSIX tty-handling -operations. If FILEHANDLE is an expression, the value is taken as -an indirect filehandle, generally its name. +Returns the file descriptor for a filehandle, or undefined if the +filehandle is not open. This is mainly useful for constructing +bitmaps for C<select()> and low-level POSIX tty-handling operations. +If FILEHANDLE is an expression, the value is taken as an indirect +filehandle, generally its name. You can use this to find out whether two handles refer to the same underlying descriptor: @@ -1310,18 +1445,23 @@ same underlying descriptor: =item flock FILEHANDLE,OPERATION -Calls flock(2), or an emulation of it, on FILEHANDLE. Returns TRUE for -success, FALSE on failure. Produces a fatal error if used on a machine -that doesn't implement flock(2), fcntl(2) locking, or lockf(3). C<flock()> -is Perl's portable file locking interface, although it locks only entire -files, not records. - -On many platforms (including most versions or clones of Unix), locks -established by C<flock()> are B<merely advisory>. Such discretionary locks -are more flexible, but offer fewer guarantees. This means that files -locked with C<flock()> may be modified by programs that do not also use -C<flock()>. Windows NT and OS/2 are among the platforms which -enforce mandatory locking. See your local documentation for details. +Calls flock(2), or an emulation of it, on FILEHANDLE. Returns TRUE +for success, FALSE on failure. Produces a fatal error if used on a +machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). +C<flock()> is Perl's portable file locking interface, although it locks +only entire files, not records. + +Two potentially non-obvious but traditional C<flock> semantics are +that it waits indefinitely until the lock is granted, and that its locks +B<merely advisory>. Such discretionary locks are more flexible, but offer +fewer guarantees. This means that files locked with C<flock()> may be +modified by programs that do not also use C<flock()>. See L<perlport>, +your port's specific documentation, or your system-specific local manpages +for details. It's best to assume traditional behavior if you're writing +portable programs. (But if you're not, you should as always feel perfectly +free to write for your own system's idiosyncrasies (sometimes called +"features"). Slavish adherence to portability concerns shouldn't get +in the way of your getting your job done.) OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but @@ -1332,12 +1472,12 @@ releases a previously requested lock. If LOCK_NB is added to LOCK_SH or LOCK_EX then C<flock()> will return immediately rather than blocking waiting for the lock (check the return status to see if you got it). -To avoid the possibility of mis-coordination, Perl flushes FILEHANDLE -before (un)locking it. +To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE +before locking or unlocking it. Note that the emulation built with lockf(3) doesn't provide shared locks, and it requires that FILEHANDLE be open with write intent. These -are the semantics that lockf(3) implements. Most (all?) systems +are the semantics that lockf(3) implements. Most if not all systems implement lockf(3) in terms of fcntl(2) locking, though, so the differing semantics shouldn't bite too many people. @@ -1370,44 +1510,37 @@ Here's a mailbox appender for BSD systems. print MBOX $msg,"\n\n"; unlock(); +On systems that support a real flock(), locks are inherited across fork() +calls, whereas those that must resort to the more capricious fcntl() +function lose the locks, making it harder to write servers. + See also L<DB_File> for other flock() examples. =item fork -Does a fork(2) system call. Returns the child pid to the parent process, -C<0> to the child process, or C<undef> if the fork is unsuccessful. +Does a fork(2) system call to create a new process running the +same program at the same point. It returns the child pid to the +parent process, C<0> to the child process, or C<undef> if the fork is +unsuccessful. File descriptors (and sometimes locks on those descriptors) +are shared, while everything else is copied. On most systems supporting +fork(), great care has gone into making it extremely efficient (for +example, using copy-on-write technology on data pages), making it the +dominant paradigm for multitasking over the last few decades. Note: unflushed buffers remain unflushed in both processes, which means you may need to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of C<IO::Handle> to avoid duplicate output. -If you C<fork()> without ever waiting on your children, you will accumulate -zombies: - - $SIG{CHLD} = sub { wait }; - -There's also the double-fork trick (error checking on -C<fork()> returns omitted); - - unless ($pid = fork) { - unless (fork) { - exec "what you really wanna do"; - die "no exec"; - # ... or ... - ## (some_perl_code_here) - exit 0; - } - exit 0; - } - waitpid($pid,0); - -See also L<perlipc> for more examples of forking and reaping -moribund children. +If you C<fork()> without ever waiting on your children, you will +accumulate zombies. On some systems, you can avoid this by setting +C<$SIG{CHLD}> to C<"IGNORE">. See also L<perlipc> for more examples of +forking and reaping moribund children. Note that if your forked child inherits system file descriptors like STDIN and STDOUT that are actually connected by a pipe or socket, even -if you exit, then the remote server (such as, say, httpd or rsh) won't think -you're done. You should reopen those to F</dev/null> if it's any issue. +if you exit, then the remote server (such as, say, a CGI script or a +backgrounded job launced from a remote shell) won't think you're done. +You should reopen those to F</dev/null> if it's any issue. =item format @@ -1450,10 +1583,11 @@ C<formline()> always returns TRUE. See L<perlform> for other examples. =item getc Returns the next character from the input file attached to FILEHANDLE, -or the undefined value at end of file, or if there was an error. If -FILEHANDLE is omitted, reads from STDIN. This is not particularly -efficient. It cannot be used to get unbuffered single-characters, -however. For that, try something more like: +or the undefined value at end of file, or if there was an error. +If FILEHANDLE is omitted, reads from STDIN. This is not particularly +efficient. However, it cannot be used by itself to fetch single +characters without waiting for the user to hit enter. For that, try +something more like: if ($BSD_STYLE) { system "stty cbreak </dev/tty >/dev/tty 2>&1"; @@ -1475,10 +1609,10 @@ however. For that, try something more like: Determination of whether $BSD_STYLE should be set is left as an exercise to the reader. -The C<POSIX::getattr()> function can do this more portably on systems -purporting POSIX compliance. -See also the C<Term::ReadKey> module from your nearest CPAN site; -details on CPAN can be found on L<perlmod/CPAN>. +The C<POSIX::getattr()> function can do this more portably on +systems purporting POSIX compliance. See also the C<Term::ReadKey> +module from your nearest CPAN site; details on CPAN can be found on +L<perlmodlib/CPAN>. =item getlogin @@ -1606,21 +1740,26 @@ lookup by name, in which case you get the other thing, whatever it is. $name = getgrent(); #etc. -In I<getpw*()> the fields C<$quota>, C<$comment>, and C<$expire> are special -cases in the sense that in many systems they are unsupported. If the -C<$quota> is unsupported, it is an empty scalar. If it is supported, it -usually encodes the disk quota. If the C<$comment> field is unsupported, -it is an empty scalar. If it is supported it usually encodes some -administrative comment about the user. In some systems the $quota -field may be C<$change> or C<$age>, fields that have to do with password -aging. In some systems the C<$comment> field may be C<$class>. The C<$expire> -field, if present, encodes the expiration period of the account or the -password. For the availability and the exact meaning of these fields -in your system, please consult your getpwnam(3) documentation and your -F<pwd.h> file. You can also find out from within Perl which meaning -your C<$quota> and C<$comment> fields have and whether you have the C<$expire> -field by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>, -C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. +In I<getpw*()> the fields C<$quota>, C<$comment>, and C<$expire> are +special cases in the sense that in many systems they are unsupported. +If the C<$quota> is unsupported, it is an empty scalar. If it is +supported, it usually encodes the disk quota. If the C<$comment> +field is unsupported, it is an empty scalar. If it is supported it +usually encodes some administrative comment about the user. In some +systems the $quota field may be C<$change> or C<$age>, fields that have +to do with password aging. In some systems the C<$comment> field may +be C<$class>. The C<$expire> field, if present, encodes the expiration +period of the account or the password. For the availability and the +exact meaning of these fields in your system, please consult your +getpwnam(3) documentation and your F<pwd.h> file. You can also find +out from within Perl what your C<$quota> and C<$comment> fields mean +and whether you have the C<$expire> field by using the C<Config> module +and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>, +and C<d_pwexpire>. Shadow password files are only supported if your +vendor has implemented them in the intuitive fashion that calling the +regular C library routines gets the shadow versions if you're running +under privilege. Those that incorrectly implement a separate library +call are not supported. The C<$members> value returned by I<getgr*()> is a space separated list of the login names of the members of the group. @@ -1634,6 +1773,15 @@ by saying something like: ($a,$b,$c,$d) = unpack('C4',$addr[0]); +The Socket library makes this slightly easier: + + use Socket; + $iaddr = inet_aton("127.1"); # or whatever address + $name = gethostbyaddr($iaddr, AF_INET); + + # or going the other way + $straddr = inet_ntoa($iaddr"); + If you get tired of remembering which element of the return list contains which return value, by-name interfaces are also provided in modules: C<File::stat>, C<Net::hostent>, C<Net::netent>, C<Net::protoent>, C<Net::servent>, @@ -1664,11 +1812,11 @@ Returns the socket option requested, or undef if there is an error. =item glob -Returns the value of EXPR with filename expansions such as the standard Unix shell F</bin/sh> would -do. This is the internal function implementing the C<E<lt>*.cE<gt>> -operator, but you can use it directly. If EXPR is omitted, C<$_> is used. -The C<E<lt>*.cE<gt>> operator is discussed in more detail in -L<perlop/"I/O Operators">. +Returns the value of EXPR with filename expansions such as the +standard Unix shell F</bin/csh> would do. This is the internal function +implementing the C<E<lt>*.cE<gt>> operator, but you can use it directly. +If EXPR is omitted, C<$_> is used. The C<E<lt>*.cE<gt>> operator is +discussed in more detail in L<perlop/"I/O Operators">. =item gmtime EXPR @@ -1681,9 +1829,12 @@ Typically used as follows: gmtime(time); All array elements are numeric, and come straight out of a struct tm. -In particular this means that C<$mon> has the range C<0..11> and C<$wday> has -the range C<0..6> with sunday as day C<0>. Also, C<$year> is the number of -years since 1900, that is, C<$year> is C<123> in year 2023, I<not> simply the last two digits of the year. +In particular this means that C<$mon> has the range C<0..11> and C<$wday> +has the range C<0..6> with sunday as day C<0>. Also, C<$year> is the +number of years since 1900, that is, C<$year> is C<123> in year 2023, +I<not> simply the last two digits of the year. If you assume it is, +then you create non-Y2K-compliant programs--and you wouldn't want to do +that, would you? If EXPR is omitted, does C<gmtime(time())>. @@ -1694,18 +1845,19 @@ In scalar context, returns the ctime(3) value: Also see the C<timegm()> function provided by the C<Time::Local> module, and the strftime(3) function available via the POSIX module. -This scalar value is B<not> locale dependent, see L<perllocale>, but -instead a Perl builtin. Also see the C<Time::Local> module, and the -strftime(3) and mktime(3) function available via the POSIX module. To +This scalar value is B<not> locale dependent (see L<perllocale>), but +is instead a Perl builtin. Also see the C<Time::Local> module, and the +strftime(3) and mktime(3) functions available via the POSIX module. To get somewhat similar but locale dependent date strings, set up your locale environment variables appropriately (please see L<perllocale>) and try for example: use POSIX qw(strftime); - $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; + $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; -Note that the C<%a> and C<%b>, the short forms of the day of the week -and the month of the year, may not necessarily be three characters wide. +Note that the C<%a> and C<%b> escapes, which represent the short forms +of the day of the week and the month of the year, may not necessarily +be three characters wide in all locales. =item goto LABEL @@ -1741,13 +1893,12 @@ will be able to tell that this routine was called first. =item grep EXPR,LIST -This is similar in spirit to, but not the same as, grep(1) -and its relatives. In particular, it is not limited to using -regular expressions. +This is similar in spirit to, but not the same as, grep(1) and its +relatives. In particular, it is not limited to using regular expressions. Evaluates the BLOCK or EXPR for each element of LIST (locally setting C<$_> to each element) and returns the list value consisting of those -elements for which the expression evaluated to TRUE. In a scalar +elements for which the expression evaluated to TRUE. In scalar context, returns the number of times the expression was TRUE. @foo = grep(!/^#/, @bar); # weed out comments @@ -1756,14 +1907,14 @@ or equivalently, @foo = grep {!/^#/} @bar; # weed out comments -Note that, because C<$_> is a reference into the list value, it can be used -to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named -array. Similarly, grep returns aliases into the original list, -much like the way that a for loop's index variable aliases the list -elements. That is, modifying an element of a list returned by grep -(for example, in a C<foreach>, C<map()> or another C<grep()>) -actually modifies the element in the original list. +Note that, because C<$_> is a reference into the list value, it can +be used to modify the elements of the array. While this is useful and +supported, it can cause bizarre results if the LIST is not a named array. +Similarly, grep returns aliases into the original list, much as a for +loop's index variable aliases the list elements. That is, modifying an +element of a list returned by grep (for example, in a C<foreach>, C<map()> +or another C<grep()>) actually modifies the element in the original list. +This is usually something to be avoided when writing clear code. See also L</map> for an array composed of the results of the BLOCK or EXPR. @@ -1771,9 +1922,9 @@ See also L</map> for an array composed of the results of the BLOCK or EXPR. =item hex -Interprets EXPR as a hex string and returns the corresponding -value. (To convert strings that might start with either 0 or 0x -see L</oct>.) If EXPR is omitted, uses C<$_>. +Interprets EXPR as a hex string and returns the corresponding value. +(To convert strings that might start with either 0, 0x, or 0b, see +L</oct>.) If EXPR is omitted, uses C<$_>. print hex '0xAf'; # prints '175' print hex 'aF'; # same @@ -1789,29 +1940,34 @@ for the package used. See also L</use()>, L<perlmod>, and L<Exporter>. =item index STR,SUBSTR -Returns the position of the first occurrence of SUBSTR in STR at or after -POSITION. If POSITION is omitted, starts searching from the beginning of -the string. The return value is based at C<0> (or whatever you've set the C<$[> -variable to--but don't do that). If the substring is not found, returns -one less than the base, ordinarily C<-1>. +The index function searches for one string within another, but without +the wildcard-like behavior of a full regular-expression pattern match. +It returns the position of the first occurrence of SUBSTR in STR at +or after POSITION. If POSITION is omitted, starts searching from the +beginning of the string. The return value is based at C<0> (or whatever +you've set the C<$[> variable to--but don't do that). If the substring +is not found, returns one less than the base, ordinarily C<-1>. =item int EXPR =item int Returns the integer portion of EXPR. If EXPR is omitted, uses C<$_>. -You should not use this for rounding, because it truncates -towards C<0>, and because machine representations of floating point -numbers can sometimes produce counterintuitive results. Usually C<sprintf()> or C<printf()>, -or the C<POSIX::floor> or C<POSIX::ceil> functions, would serve you better. +You should not use this function for rounding: one because it truncates +towards C<0>, and two because machine representations of floating point +numbers can sometimes produce counterintuitive results. For example, +C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's +because it's really more like -268.99999999999994315658 instead. Usually, +the C<sprintf()>, C<printf()>, or the C<POSIX::floor> and C<POSIX::ceil> +functions will serve you better than will int(). =item ioctl FILEHANDLE,FUNCTION,SCALAR -Implements the ioctl(2) function. You'll probably have to say +Implements the ioctl(2) function. You'll probably first have to say require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph -first to get the correct function definitions. If F<ioctl.ph> doesn't +to get the correct function definitions. If F<ioctl.ph> doesn't exist or doesn't have the correct definitions you'll have to roll your own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>. (There is a Perl script called B<h2ph> that comes with the Perl kit that @@ -1847,19 +2003,18 @@ Thus Perl returns TRUE on success and FALSE on failure, yet you can still easily determine the actual value returned by the operating system: - ($retval = ioctl(...)) || ($retval = -1); + $retval = ioctl(...) || -1; printf "System returned %d\n", $retval; -The special string "C<0> but true" is excempt from B<-w> complaints +The special string "C<0> but true" is exempt from B<-w> complaints about improper numeric conversions. =item join EXPR,LIST -Joins the separate strings of LIST into a single string with -fields separated by the value of EXPR, and returns the string. -Example: +Joins the separate strings of LIST into a single string with fields +separated by the value of EXPR, and returns that new string. Example: - $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); + $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); See L</split>. @@ -1867,9 +2022,11 @@ See L</split>. Returns a list consisting of all the keys of the named hash. (In a scalar context, returns the number of keys.) The keys are returned in -an apparently random order, but it is the same order as either the -C<values()> or C<each()> function produces (given that the hash has not been -modified). As a side effect, it resets HASH's iterator. +an apparently random order. The actual random order is subject to +change in future versions of perl, but it is guaranteed to be the same +order as either the C<values()> or C<each()> function produces (given +that the hash has not been modified). As a side effect, it resets +HASH's iterator. Here is yet another way to print your environment: @@ -1885,7 +2042,7 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } -To sort an array by value, you'll need to use a C<sort()> function. +To sort a hash by value, you'll need to use a C<sort()> function. Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) { @@ -1899,14 +2056,16 @@ an array by assigning a larger number to $#array.) If you say keys %hash = 200; -then C<%hash> will have at least 200 buckets allocated for it--256 of them, in fact, since -it rounds up to the next power of two. These +then C<%hash> will have at least 200 buckets allocated for it--256 of them, +in fact, since it rounds up to the next power of two. These buckets will be retained even if you do C<%hash = ()>, use C<undef %hash> if you want to free the storage while C<%hash> is still in scope. You can't shrink the number of buckets allocated for the hash using C<keys()> in this way (but you needn't worry about doing this by accident, as trying has no effect). +See also C<each()>, C<values()> and C<sort()>. + =item kill LIST Sends a signal to a list of processes. The first element of @@ -1936,6 +2095,10 @@ C<continue> block, if any, is not executed: #... } +C<last> cannot be used to exit a block which returns a value such as +C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +a grep() or map() operation. + See also L</continue> for an illustration of how C<last>, C<next>, and C<redo> work. @@ -1945,7 +2108,7 @@ C<redo> work. Returns an lowercased version of EXPR. This is the internal function implementing the C<\L> escape in double-quoted strings. -Respects current C<LC_CTYPE> locale if C<use locale> in force. See L<perllocale>. +Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>. If EXPR is omitted, uses C<$_>. @@ -1955,7 +2118,7 @@ If EXPR is omitted, uses C<$_>. Returns the value of EXPR with the first character lowercased. This is the internal function implementing the C<\l> escape in double-quoted strings. -Respects current C<LC_CTYPE> locale if C<use locale> in force. See L<perllocale>. +Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>. If EXPR is omitted, uses C<$_>. @@ -1963,30 +2126,32 @@ If EXPR is omitted, uses C<$_>. =item length -Returns the length in bytes of the value of EXPR. If EXPR is -omitted, returns length of C<$_>. +Returns the length in characters of the value of EXPR. If EXPR is +omitted, returns length of C<$_>. Note that this cannot be used on +an entire array or hash to find out how many elements these have. +For that, use C<scalar @array> and C<scalar keys %hash> respectively. =item link OLDFILE,NEWFILE Creates a new filename linked to the old filename. Returns TRUE for -success, FALSE otherwise. +success, FALSE otherwise. =item listen SOCKET,QUEUESIZE Does the same thing that the listen system call does. Returns TRUE if -it succeeded, FALSE otherwise. See example in L<perlipc/"Sockets: Client/Server Communication">. +it succeeded, FALSE otherwise. See the example in L<perlipc/"Sockets: Client/Server Communication">. =item local EXPR +You really probably want to be using C<my()> instead, because C<local()> isn't +what most people think of as "local". See L<perlsub/"Private Variables +via my()"> for details. + A local modifies the listed variables to be local to the enclosing block, file, or eval. If more than one value is listed, the list must be placed in parentheses. See L<perlsub/"Temporary Values via local()"> for details, including issues with tied arrays and hashes. -You really probably want to be using C<my()> instead, because C<local()> isn't -what most people think of as "local". See L<perlsub/"Private Variables -via my()"> for details. - =item localtime EXPR Converts a time as returned by the time function to a 9-element array @@ -1998,9 +2163,12 @@ follows: localtime(time); All array elements are numeric, and come straight out of a struct tm. -In particular this means that C<$mon> has the range C<0..11> and C<$wday> has -the range C<0..6> with sunday as day C<0>. Also, C<$year> is the number of -years since 1900, that is, C<$year> is C<123> in year 2023, and I<not> simply the last two digits of the year. +In particular this means that C<$mon> has the range C<0..11> and C<$wday> +has the range C<0..6> with sunday as day C<0>. Also, C<$year> is the +number of years since 1900, that is, C<$year> is C<123> in year 2023, +and I<not> simply the last two digits of the year. If you assume it is, +then you create non-Y2K-compliant programs--and you wouldn't want to do +that, would you? If EXPR is omitted, uses the current time (C<localtime(time)>). @@ -2016,7 +2184,7 @@ locale environment variables appropriately (please see L<perllocale>) and try for example: use POSIX qw(strftime); - $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; + $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; Note that the C<%a> and C<%b>, the short forms of the day of the week and the month of the year, may not necessarily be three characters wide. @@ -2025,8 +2193,17 @@ and the month of the year, may not necessarily be three characters wide. =item log -Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted, returns log -of C<$_>. +Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted, +returns log of C<$_>. To get the log of another base, use basic algebra: +The base-N log of a number is is equal to the natural log of that number +divided by the natural log of N. For example: + + sub log10 { + my $n = shift; + return log($n)/log(10); + } + +See also L</exp> for the inverse operation. =item lstat FILEHANDLE @@ -2054,6 +2231,8 @@ element) and returns the list value composed of the results of each such evaluation. Evaluates BLOCK or EXPR in a list context, so each element of LIST may produce zero, one, or more elements in the returned value. +In scalar context, returns the total number of elements so generated. + @chars = map(chr, @nums); translates a list of numbers to the corresponding characters. And @@ -2067,17 +2246,25 @@ is just a funny way to write $hash{getkey($_)} = $_; } -Note that, because C<$_> is a reference into the list value, it can be used -to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named -array. See also L</grep> for an array composed of those items of the -original list for which the BLOCK or EXPR evaluates to true. +Note that, because C<$_> is a reference into the list value, it can +be used to modify the elements of the array. While this is useful and +supported, it can cause bizarre results if the LIST is not a named array. +Using a regular C<foreach> loop for this purpose would be clearer in +most cases. See also L</grep> for an array composed of those items of +the original list for which the BLOCK or EXPR evaluates to true. =item mkdir FILENAME,MODE -Creates the directory specified by FILENAME, with permissions specified -by MODE (as modified by umask). If it succeeds it returns TRUE, otherwise -it returns FALSE and sets C<$!> (errno). +Creates the directory specified by FILENAME, with permissions +specified by MODE (as modified by C<umask>). If it succeeds it +returns TRUE, otherwise it returns FALSE and sets C<$!> (errno). + +In general, it is better to create directories with permissive MODEs, +and let the user modify that with their C<umask>, than it is to supply +a restrictive MODE and give the user no way to be more permissive. +The exceptions to this rule are when the file or directory should be +kept private (mail files, for instance). The perlfunc(1) entry on +C<umask> discusses the choice of MODE in more detail. =item msgctl ID,CMD,ARG @@ -2137,6 +2324,10 @@ Note that if there were a C<continue> block on the above, it would get executed even on discarded lines. If the LABEL is omitted, the command refers to the innermost enclosing loop. +C<next> cannot be used to exit a block which returns a value such as +C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +a grep() or map() operation. + See also L</continue> for an illustration of how C<last>, C<next>, and C<redo> work. @@ -2149,8 +2340,9 @@ See the L</use> function, which C<no> is the opposite of. =item oct Interprets EXPR as an octal string and returns the corresponding -value. (If EXPR happens to start off with C<0x>, interprets it as -a hex string instead.) The following will handle decimal, octal, and +value. (If EXPR happens to start off with C<0x>, interprets it as a +hex string. If EXPR starts off with C<0b>, it is interpreted as a +binary string.) The following will handle decimal, binary, octal, and hex in the standard Perl or C notation: $val = oct($val) if $val =~ /^0/; @@ -2170,7 +2362,8 @@ name of the real filehandle wanted. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. (Note that lexical variables--those declared with C<my()>--will not work for this purpose; so if you're using C<my()>, specify EXPR in your call -to open.) +to open.) See L<perlopentut> for a kinder, gentler explanation of opening +files. If the filename begins with C<'E<lt>'> or nothing, the file is opened for input. If the filename begins with C<'E<gt>'>, the file is truncated and opened for @@ -2181,7 +2374,8 @@ you want both read and write access to the file; thus C<'+E<lt>'> is almost always preferred for read/write updates--the C<'+E<gt>'> mode would clobber the file first. You can't usually use either read-write mode for updating textfiles, since they have variable length records. See the B<-i> -switch in L<perlrun> for a better approach. +switch in L<perlrun> for a better approach. The file is created with +permissions of C<0666> modified by the process' C<umask> value. The prefix and the filename may be separated with spaces. These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>, @@ -2189,7 +2383,8 @@ C<'w+'>, C<'a'>, and C<'a+'>. If the filename begins with C<'|'>, the filename is interpreted as a command to which output is to be piped, and if the filename ends with a -C<'|'>, the filename is interpreted See L<perlipc/"Using open() for IPC"> +C<'|'>, the filename is interpreted as a command which pipes output to +us. See L<perlipc/"Using open() for IPC"> for more examples of this. (You are not allowed to C<open()> to a command that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication"> for alternatives.) @@ -2290,7 +2485,6 @@ STDERR: print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; - If you specify C<'E<lt>&=N'>, where C<N> is a number, then Perl will do an equivalent of C's C<fdopen()> of that file descriptor; this is more parsimonious of file descriptors. For example: @@ -2320,7 +2514,9 @@ See L<perlipc/"Safe Pipe Opens"> for more examples of this. NOTE: On any operation that may do a fork, any unflushed buffers remain unflushed in both processes, which means you may need to set C<$|> to -avoid duplicate output. +avoid duplicate output. On systems that support a close-on-exec flag on +files, the flag will be set for the newly opened file descriptor as +determined by the value of $^F. See L<perlvar/$^F>. Closing any piped filehandle causes the parent process to wait for the child to finish, and returns the status value in C<$?>. @@ -2370,7 +2566,7 @@ them, and automatically close whenever and however you leave that scope: $first; # Or here. } -See L</seek()> for some details about mixing reading and writing. +See L</seek> for some details about mixing reading and writing. =item opendir DIRHANDLE,EXPR @@ -2392,8 +2588,10 @@ returning the string containing the structure. The TEMPLATE is a sequence of characters that give the order and type of values, as follows: + a A string with arbitrary binary data, will be null padded. A An ascii string, will be space padded. - a An ascii string, will be null padded. + Z A null terminated (asciz) string, will be null padded. + b A bit string (ascending bit order, like vec()). B A bit string (descending bit order). h A hex string (low nybble first). @@ -2409,7 +2607,7 @@ follows: i A signed integer value. I An unsigned integer value. - (This 'integer' is _at_least_ 32 bits wide. Its exact + (This 'integer' is _at least_ 32 bits wide. Its exact size depends on what a local C compiler calls 'int', and may even be larger than the 'long' described in the next item.) @@ -2426,6 +2624,12 @@ follows: (These 'shorts' and 'longs' are _exactly_ 16 bits and _exactly_ 32 bits, respectively.) + q A signed quad (64-bit) value. + Q An unsigned quad value. + (Available only if your system supports 64-bit integer values + _and_ if Perl has been compiled to support those. + Causes a fatal error otherwise.) + f A single-precision float in the native format. d A double-precision float in the native format. @@ -2443,36 +2647,107 @@ follows: X Back up a byte. @ Null fill to absolute position. +The following rules apply: + +=over 8 + +=item * + Each letter may optionally be followed by a number giving a repeat -count. With all types except C<"a">, C<"A">, C<"b">, C<"B">, C<"h">, C<"H">, and C<"P"> the -pack function will gobble up that many values from the LIST. A C<*> for the -repeat count means to use however many items are left. The C<"a"> and C<"A"> -types gobble just one value, but pack it as a string of length count, -padding with nulls or spaces as necessary. (When unpacking, C<"A"> strips -trailing spaces and nulls, but C<"a"> does not.) Likewise, the C<"b"> and C<"B"> -fields pack a string that many bits long. The C<"h"> and C<"H"> fields pack a -string that many nybbles long. The C<"p"> type packs a pointer to a null- -terminated string. You are responsible for ensuring the string is not a -temporary value (which can potentially get deallocated before you get -around to using the packed result). The C<"P"> packs a pointer to a structure -of the size indicated by the length. A NULL pointer is created if the -corresponding value for C<"p"> or C<"P"> is C<undef>. -Real numbers (floats and doubles) are -in the native machine format only; due to the multiplicity of floating -formats around, and the lack of a standard "network" representation, no -facility for interchange has been made. This means that packed floating -point data written on one machine may not be readable on another - even if -both use IEEE floating point arithmetic (as the endian-ness of the memory -representation is not part of the IEEE spec). Note that Perl uses doubles -internally for all numeric calculation, and converting from double into -float and thence back to double again will lose precision (i.e., -C<unpack("f", pack("f", $foo)>) will not in general equal C<$foo>). +count. With all types except C<"a">, C<"A">, C<"Z">, C<"b">, C<"B">, C<"h">, +C<"H">, and C<"P"> the pack function will gobble up that many values from +the LIST. A C<*> for the repeat count means to use however many items are +left. + +=item * + +The C<"a">, C<"A">, and C<"Z"> types gobble just one value, but pack it as a +string of length count, padding with nulls or spaces as necessary. When +unpacking, C<"A"> strips trailing spaces and nulls, C<"Z"> strips everything +after the first null, and C<"a"> returns data verbatim. + +=item * + +Likewise, the C<"b"> and C<"B"> fields pack a string that many bits long. + +=item * + +The C<"h"> and C<"H"> fields pack a string that many nybbles long. + +=item * + +The C<"p"> type packs a pointer to a null-terminated string. You are +responsible for ensuring the string is not a temporary value (which can +potentially get deallocated before you get around to using the packed result). +The C<"P"> type packs a pointer to a structure of the size indicated by the +length. A NULL pointer is created if the corresponding value for C<"p"> or +C<"P"> is C<undef>. + +=item * + +The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L"> +are inherently non-portable between processors and operating systems +because they obey the native byteorder and endianness. For example a +4-byte integer 0x87654321 (2271560481 decimal) be ordered natively +(arranged in and handled by the CPU registers) into bytes as + + 0x12 0x34 0x56 0x78 # little-endian + 0x78 0x56 0x34 0x12 # big-endian + +Basically, the Intel, Alpha, and VAX CPUs and little-endian, while +everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, +Power, and Cray are big-endian. MIPS can be either: Digital used it +in little-endian mode, SGI uses it in big-endian mode. + +The names `big-endian' and `little-endian' are joking references to +the classic "Gulliver's Travels" (via the paper "On Holy Wars and a +Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and +the egg-eating habits of the lilliputs. + +Some systems may even have weird byte orders such as + + 0x56 0x78 0x12 0x34 + 0x34 0x12 0x78 0x56 + +You can see your system's preference with + + print join(" ", map { sprintf "%#02x", $_ } + unpack("C*",pack("L",0x12345678))), "\n"; + +The byteorder on the platform where Perl was built is also available +via L<Config>: + + use Config; + print $Config{byteorder}, "\n"; + +Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'> +and C<'87654321'> are big-endian. + +If you want portable packed integers use the formats C<"n">, C<"N">, +C<"v">, and C<"V">, their byte endianness and size is known. + +=item * + +Real numbers (floats and doubles) are in the native machine format only; +due to the multiplicity of floating formats around, and the lack of a +standard "network" representation, no facility for interchange has been +made. This means that packed floating point data written on one machine +may not be readable on another - even if both use IEEE floating point +arithmetic (as the endian-ness of the memory representation is not part +of the IEEE spec). + +Note that Perl uses doubles internally for all numeric calculation, and +converting from double into float and thence back to double again will +lose precision (i.e., C<unpack("f", pack("f", $foo)>) will not in general +equal C<$foo>). + +=back Examples: - $foo = pack("cccc",65,66,67,68); + $foo = pack("CCCC",65,66,67,68); # foo eq "ABCD" - $foo = pack("c4",65,66,67,68); + $foo = pack("C4",65,66,67,68); # same thing $foo = pack("ccxxcc",65,66,67,68); @@ -2494,29 +2769,38 @@ Examples: $foo = pack("i9pl", gmtime); # a real struct tm (on my system anyway) + $utmp_template = "Z8 Z8 Z16 L"; + $utmp = pack($utmp_template, @utmp1); + # a struct utmp (BSDish) + + @utmp2 = unpack($utmp_template, $utmp); + # "@utmp1" eq "@utmp2" + sub bintodec { unpack("N", pack("B32", substr("0" x 32 . shift, -32))); } -The same template may generally also be used in the unpack function. +The same template may generally also be used in unpack(). =item package =item package NAMESPACE Declares the compilation unit as being in the given namespace. The scope -of the package declaration is from the declaration itself through the end of -the enclosing block (the same scope as the C<local()> operator). All further -unqualified dynamic identifiers will be in this namespace. A package -statement affects only dynamic variables--including those you've used -C<local()> on--but I<not> lexical variables created with C<my()>. Typically it -would be the first declaration in a file to be included by the C<require> -or C<use> operator. You can switch into a package in more than one place; -it merely influences which symbol table is used by the compiler for the -rest of that block. You can refer to variables and filehandles in other -packages by prefixing the identifier with the package name and a double -colon: C<$Package::Variable>. If the package name is null, the C<main> -package as assumed. That is, C<$::sail> is equivalent to C<$main::sail>. +of the package declaration is from the declaration itself through the end +of the enclosing block, file, or eval (the same as the C<my()> operator). +All further unqualified dynamic identifiers will be in this namespace. +A package statement affects only dynamic variables--including those +you've used C<local()> on--but I<not> lexical variables, which are created +with C<my()>. Typically it would be the first declaration in a file to +be included by the C<require> or C<use> operator. You can switch into a +package in more than one place; it merely influences which symbol table +is used by the compiler for the rest of that block. You can refer to +variables and filehandles in other packages by prefixing the identifier +with the package name and a double colon: C<$Package::Variable>. +If the package name is null, the C<main> package as assumed. That is, +C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>, +still seen in older code). If NAMESPACE is omitted, then there is no current package, and all identifiers must be fully qualified or lexicals. This is stricter @@ -2536,19 +2820,22 @@ after each command, depending on the application. See L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication"> for examples of such things. +On systems that support a close-on-exec flag on files, the flag will be set +for the newly opened file descriptors as determined by the value of $^F. +See L<perlvar/$^F>. + =item pop ARRAY =item pop Pops and returns the last value of the array, shortening the array by -1. Has a similar effect to +one element. Has a similar effect to $tmp = $ARRAY[$#ARRAY--]; If there are no elements in the array, returns the undefined value. -If ARRAY is omitted, pops the -C<@ARGV> array in the main program, and the C<@_> array in subroutines, just -like C<shift()>. +If ARRAY is omitted, pops the C<@ARGV> array in the main program, and +the C<@_> array in subroutines, just like C<shift()>. =item pos SCALAR @@ -2568,20 +2855,20 @@ L<perlop>. Prints a string or a comma-separated list of strings. Returns TRUE if successful. FILEHANDLE may be a scalar variable name, in which case -the variable contains the name of or a reference to the filehandle, thus introducing one -level of indirection. (NOTE: If FILEHANDLE is a variable and the next -token is a term, it may be misinterpreted as an operator unless you -interpose a C<+> or put parentheses around the arguments.) If FILEHANDLE is -omitted, prints by default to standard output (or to the last selected -output channel--see L</select>). If LIST is also omitted, prints C<$_> to -the currently selected output channel. To set the default output channel to something other than -STDOUT use the select operation. Note that, because print takes a -LIST, anything in the LIST is evaluated in list context, and any -subroutine that you call will have one or more of its expressions -evaluated in list context. Also be careful not to follow the print -keyword with a left parenthesis unless you want the corresponding right -parenthesis to terminate the arguments to the print--interpose a C<+> or -put parentheses around all the arguments. +the variable contains the name of or a reference to the filehandle, thus +introducing one level of indirection. (NOTE: If FILEHANDLE is a variable +and the next token is a term, it may be misinterpreted as an operator +unless you interpose a C<+> or put parentheses around the arguments.) +If FILEHANDLE is omitted, prints by default to standard output (or to the +last selected output channel--see L</select>). If LIST is also omitted, +prints C<$_> to the currently selected output channel. To set the default +output channel to something other than STDOUT use the select operation. +Note that, because print takes a LIST, anything in the LIST is evaluated +in list context, and any subroutine that you call will have one or +more of its expressions evaluated in list context. Also be careful +not to follow the print keyword with a left parenthesis unless you want +the corresponding right parenthesis to terminate the arguments to the +print--interpose a C<+> or put parentheses around all the arguments. Note that if you're storing FILEHANDLES in an array or other expression, you will have to use a block returning its value instead: @@ -2609,12 +2896,12 @@ Returns the prototype of a function as a string (or C<undef> if the function has no prototype). FUNCTION is a reference to, or the name of, the function whose prototype you want to retrieve. -If FUNCTION is a string starting with C<CORE::>, the rest is taken as -a name for Perl builtin. If builtin is not I<overridable> (such as +If FUNCTION is a string starting with C<CORE::>, the rest is taken as a +name for Perl builtin. If the builtin is not I<overridable> (such as C<qw//>) or its arguments cannot be expressed by a prototype (such as -C<system()>) - in other words, the builtin does not behave like a Perl -function - returns C<undef>. Otherwise, the string describing the -equivalent prototype is returned. +C<system()>) returns C<undef> because the builtin does not really behave +like a Perl function. Otherwise, the string describing the equivalent +prototype is returned. =item push ARRAY,LIST @@ -2638,7 +2925,7 @@ but is more efficient. Returns the new number of elements in the array. =item qw/STRING/ -Generalized quotes. See L<perlop>. +Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">. =item quotemeta EXPR @@ -2695,10 +2982,17 @@ C<chdir()> there, it would have been testing the wrong file. =item readline EXPR -Reads from the filehandle whose typeglob is contained in EXPR. In scalar context, a single line -is read and returned. In list context, reads until end-of-file is -reached and returns a list of lines (however you've defined lines -with C<$/> or C<$INPUT_RECORD_SEPARATOR>). +Reads from the filehandle whose typeglob is contained in EXPR. In scalar +context, each call reads and returns the next line, until end-of-file is +reached, whereupon the subsequent call returns undef. In list context, +reads until end-of-file is reached and returns a list of lines. Note that +the notion of "line" used here is however you may have defined it +with C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">. + +When C<$/> is set to C<undef>, when readline() is in scalar +context (i.e. file slurp mode), and when an empty file is read, it +returns C<''> the first time, followed by C<undef> subsequently. + This is the internal function implementing the C<E<lt>EXPRE<gt>> operator, but you can use it directly. The C<E<lt>EXPRE<gt>> operator is discussed in more detail in L<perlop/"I/O Operators">. @@ -2726,7 +3020,7 @@ This is the internal function implementing the C<qx/EXPR/> operator, but you can use it directly. The C<qx/EXPR/> operator is discussed in more detail in L<perlop/"I/O Operators">. -=item recv SOCKET,SCALAR,LEN,FLAGS +=item recv SOCKET,SCALAR,LENGTH,FLAGS Receives a message on a socket. Attempts to receive LENGTH bytes of data into variable SCALAR from the specified SOCKET filehandle. @@ -2763,6 +3057,10 @@ themselves about what was just input: print; } +C<redo> cannot be used to retry a block which returns a value such as +C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit +a grep() or map() operation. + See also L</continue> for an illustration of how C<last>, C<next>, and C<redo> work. @@ -2788,16 +3086,24 @@ name is returned instead. You can think of C<ref()> as a C<typeof()> operator. if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; } - if (!ref($r)) { + unless (ref($r)) { print "r is not a reference at all.\n"; } + if (UNIVERSAL::isa($r, "HASH")) { # for subclassing + print "r is a reference to something that isa hash.\n"; + } See also L<perlref>. =item rename OLDNAME,NEWNAME -Changes the name of a file. Returns C<1> for success, C<0> otherwise. Will -not work across file system boundaries. +Changes the name of a file. Returns C<1> for success, C<0> otherwise. +Behavior of this function varies wildly depending on your system +implementation. For example, it will usually not work across file system +boundaries, even though the system I<mv> command sometimes compensates +for this. Other restrictions include whether it works on directories, +open files, or pre-existing files. Check L<perlport> and either the +rename(2) manpage or equivalent system documentation for details. =item require EXPR @@ -2880,12 +3186,13 @@ only variables or searches in the current package. Always returns reset 'X'; # reset all X variables reset 'a-z'; # reset lower case variables - reset; # just reset ?? searches + reset; # just reset ?one-time? searches Resetting C<"A-Z"> is not recommended because you'll wipe out your -C<@ARGV> and C<@INC> arrays and your C<%ENV> hash. Resets only package variables--lexical variables -are unaffected, but they clean themselves up on scope exit anyway, -so you'll probably want to use them instead. See L</my>. +C<@ARGV> and C<@INC> arrays and your C<%ENV> hash. Resets only package +variables--lexical variables are unaffected, but they clean themselves +up on scope exit anyway, so you'll probably want to use them instead. +See L</my>. =item return EXPR @@ -2895,29 +3202,30 @@ Returns from a subroutine, C<eval()>, or C<do FILE> with the value given in EXPR. Evaluation of EXPR may be in list, scalar, or void context, depending on how the return value will be used, and the context may vary from one execution to the next (see C<wantarray()>). If no EXPR -is given, returns an empty list in list context, an undefined value in -scalar context, or nothing in a void context. +is given, returns an empty list in list context, the undefined value in +scalar context, and (of course) nothing at all in a void context. -(Note that in the absence of a return, a subroutine, eval, or do FILE -will automatically return the value of the last expression evaluated.) +(Note that in the absence of a explicit C<return>, a subroutine, eval, +or do FILE will automatically return the value of the last expression +evaluated.) =item reverse LIST In list context, returns a list value consisting of the elements of LIST in the opposite order. In scalar context, concatenates the -elements of LIST, and returns a string value consisting of those bytes, -but in the opposite order. +elements of LIST and returns a string value with all characters +in the opposite order. print reverse <>; # line tac, last line first undef $/; # for efficiency of <> - print scalar reverse <>; # byte tac, last line tsrif + print scalar reverse <>; # character tac, last line tsrif This operator is also handy for inverting a hash, although there are some caveats. If a value is duplicated in the original hash, only one of those can be represented as a key in the inverted hash. Also, this has to unwind one hash and build a whole new one, which may take some time -on a large hash. +on a large hash, such as from a DBM file. %by_name = reverse %by_address; # Invert the hash @@ -2930,7 +3238,7 @@ C<readdir()> routine on DIRHANDLE. =item rindex STR,SUBSTR -Works just like index except that it returns the position of the LAST +Works just like index() except that it returns the position of the LAST occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence at or before that position. @@ -2954,11 +3262,27 @@ of EXPR. @counts = ( scalar @a, scalar @b, scalar @c ); There is no equivalent operator to force an expression to -be interpolated in list context because it's in practice never +be interpolated in list context because in practice, this is never needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple C<(some expression)> suffices. +Since C<scalar> is a unary operator, if you accidentally use for EXPR a +parenthesized list, this behaves as a scalar comma expression, evaluating +all but the last element in void context and returning the final element +evaluated in scalar context. This is seldom what you want. + +The following single statement: + + print uc(scalar(&foo,$bar)),$baz; + +is the moral equivalent of these two: + + &foo; + print(uc($bar),$baz); + +See L<perlop> for more details on unary operators and the comma operator. + =item seek FILEHANDLE,POSITION,WHENCE Sets FILEHANDLE's position, just like the C<fseek()> call of C<stdio()>. @@ -2973,10 +3297,10 @@ If you want to position file for C<sysread()> or C<syswrite()>, don't use C<seek()> -- buffering makes its effect on the file's system position unpredictable and non-portable. Use C<sysseek()> instead. -On some systems you have to do a seek whenever you switch between reading -and writing. Amongst other things, this may have the effect of calling -stdio's clearerr(3). A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving -the file position: +Due to the rules and rigors of ANSI C, on some systems you have to do a +seek whenever you switch between reading and writing. Amongst other +things, this may have the effect of calling stdio's clearerr(3). +A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position: seek(TEST,0,1); @@ -3123,7 +3447,7 @@ Sends a message on a socket. Takes the same flags as the system call of the same name. On unconnected sockets you must specify a destination to send TO, in which case it does a C C<sendto()>. Returns the number of characters sent, or the undefined value if there is an -error. +error. The C system call sendmsg(2) is currently unimplemented. See L<perlipc/"UDP: Message Passing"> for examples. =item setpgrp PID,PGRP @@ -3132,7 +3456,7 @@ Sets the current process group for the specified PID, C<0> for the current process. Will produce a fatal error if used on a machine that doesn't implement setpgrp(2). If the arguments are omitted, it defaults to C<0,0>. Note that the POSIX version of C<setpgrp()> does not accept any -arguments, so only setpgrp C<0,0> is portable. +arguments, so only C<setpgrp(0,0)> is portable. See also C<POSIX::setsid()>. =item setpriority WHICH,WHO,PRIORITY @@ -3188,7 +3512,8 @@ detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return TRUE if successful, or FALSE if there is an error. -See also C<IPC::SysV> documentation. +See also C<IPC::SysV> documentation and the C<IPC::Shareable> module +from CPAN. =item shutdown SOCKET,HOW @@ -3235,7 +3560,7 @@ busy multitasking system. For delays of finer granularity than one second, you may use Perl's C<syscall()> interface to access setitimer(2) if your system supports it, -or else see L</select()> above. +or else see L</select> above. See also the POSIX module's C<sigpause()> function. @@ -3244,7 +3569,7 @@ See also the POSIX module's C<sigpause()> function. Opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. You should "C<use Socket;>" first to get -the proper definitions imported. See the example in L<perlipc/"Sockets: Client/Server Communication">. +the proper definitions imported. See the examples in L<perlipc/"Sockets: Client/Server Communication">. =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL @@ -3583,14 +3908,19 @@ See L<perllocale>. =item sqrt Return the square root of EXPR. If EXPR is omitted, returns square -root of C<$_>. +root of C<$_>. Only works on non-negative operands, unless you've +loaded the standard Math::Complex module. + + use Math::Complex; + print sqrt(-2); # prints 1.4142135623731i =item srand EXPR =item srand Sets the random number seed for the C<rand()> operator. If EXPR is -omitted, uses a semi-random value based on the current time and process +omitted, uses a semi-random value supplied by the kernel (if it supports +the F</dev/urandom> device) or based on the current time and process ID, among other things. In versions of Perl prior to 5.004 the default seed was just the current C<time()>. This isn't a particularly good seed, so many old programs supply their own seed value (often C<time ^ $$> or @@ -3672,10 +4002,26 @@ last stat or filetest are returned. Example: (This works on machines only for which the device number is negative under NFS.) +Because the mode contains both the file type and its permissions, you +should mask off the file type portion and (s)printf using a C<"%o"> +if you want to see the real permissions. + + $mode = (stat($filename))[2]; + printf "Permissions are %04o\n", $mode & 07777; + + In scalar context, C<stat()> returns a boolean value indicating success or failure, and, if successful, sets the information associated with the special filehandle C<_>. +The File::stat module provides a convenient, by-name access mechanism: + + use File::stat; + $sb = stat($filename); + printf "File is %s, size is %s, perm %04o, mtime %s\n", + $filename, $sb->size, $sb->mode & 07777, + scalar localtime $sb->mtime; + =item study SCALAR =item study @@ -3701,9 +4047,9 @@ before any line containing a certain pattern: while (<>) { study; - print ".IX foo\n" if /\bfoo\b/; - print ".IX bar\n" if /\bbar\b/; - print ".IX blurfl\n" if /\bblurfl\b/; + print ".IX foo\n" if /\bfoo\b/; + print ".IX bar\n" if /\bbar\b/; + print ".IX blurfl\n" if /\bblurfl\b/; # ... print; } @@ -3764,16 +4110,16 @@ If you specify a substring that is partly outside the string, the part within the string is returned. If the substring is totally outside the string a warning is produced. -You can use the C<substr()> function -as an lvalue, in which case EXPR must be an lvalue. If you assign -something shorter than LEN, the string will shrink, and if you assign -something longer than LEN, the string will grow to accommodate it. To -keep the string the same length you may need to pad or chop your value -using C<sprintf()>. +You can use the substr() function as an lvalue, in which case EXPR +must itself be an lvalue. If you assign something shorter than LEN, +the string will shrink, and if you assign something longer than LEN, +the string will grow to accommodate it. To keep the string the same +length you may need to pad or chop your value using C<sprintf()>. -An alternative to using C<substr()> as an lvalue is to specify the +An alternative to using substr() as an lvalue is to specify the replacement string as the 4th argument. This allows you to replace -parts of the EXPR and return what was there before in one operation. +parts of the EXPR and return what was there before in one operation, +just as you can with splice(). =item symlink OLDFILE,NEWFILE @@ -3782,7 +4128,7 @@ Returns C<1> for success, C<0> otherwise. On systems that don't support symbolic links, produces a fatal error at run time. To check for that, use eval: - $symlink_exists = eval { symlink("",""); 1 }; + $symlink_exists = eval { symlink("",""); 1 }; =item syscall LIST @@ -3833,44 +4179,35 @@ system-dependent; they are available via the standard module C<Fcntl>. For historical reasons, some values work on almost every system supported by perl: zero means read-only, one means write-only, and two means read/write. We know that these values do I<not> work under -OS/390 Unix and on the Macintosh; you probably don't want to use them -in new code. +OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to +use them in new code. If the file named by FILENAME does not exist and the C<open()> call creates it (typically because MODE includes the C<O_CREAT> flag), then the value of PERMS specifies the permissions of the newly created file. If you omit the PERMS argument to C<sysopen()>, Perl uses the octal value C<0666>. These permission values need to be in octal, and are modified by your -process's current C<umask>. The C<umask> value is a number representing -disabled permissions bits--if your C<umask> were C<027> (group can't write; -others can't read, write, or execute), then passing C<sysopen()> C<0666> would -create a file with mode C<0640> (C<0666 &~ 027> is C<0640>). - -If you find this C<umask()> talk confusing, here's some advice: supply a -creation mode of C<0666> for regular files and one of C<0777> for directories -(in C<mkdir()>) and executable files. This gives users the freedom of -choice: if they want protected files, they might choose process umasks -of C<022>, C<027>, or even the particularly antisocial mask of C<077>. Programs -should rarely if ever make policy decisions better left to the user. -The exception to this is when writing files that should be kept private: -mail files, web browser cookies, I<.rhosts> files, and so on. In short, -seldom if ever use C<0644> as argument to C<sysopen()> because that takes -away the user's option to have a more permissive umask. Better to omit it. +process's current C<umask>. + +You should seldom if ever use C<0644> as argument to C<sysopen()>, because +that takes away the user's option to have a more permissive umask. +Better to omit it. See the perlfunc(1) entry on C<umask> for more +on this. -The C<IO::File> module provides a more object-oriented approach, if you're -into that kind of thing. +See L<perlopentut> for a kinder, gentler explanation of opening files. =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET =item sysread FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE, using the system call read(2). It bypasses -stdio, so mixing this with other kinds of reads, C<print()>, C<write()>, -C<seek()>, or C<tell()> can cause confusion because stdio usually buffers -data. Returns the number of bytes actually read, C<0> at end of file, -or undef if there was an error. SCALAR will be grown or shrunk so that -the last byte actually read is the last byte of the scalar after the read. +specified FILEHANDLE, using the system call read(2). It bypasses stdio, +so mixing this with other kinds of reads, C<print()>, C<write()>, +C<seek()>, C<tell()>, or C<eof()> can cause confusion because stdio +usually buffers data. Returns the number of bytes actually read, C<0> +at end of file, or undef if there was an error. SCALAR will be grown or +shrunk so that the last byte actually read is the last byte of the +scalar after the read. An OFFSET may be specified to place the read data at some place in the string other than the beginning. A negative OFFSET specifies @@ -3879,17 +4216,21 @@ string. A positive OFFSET greater than the length of SCALAR results in the string being padded to the required size with C<"\0"> bytes before the result of the read is appended. +There is no syseof() function, which is ok, since eof() doesn't work +very well on device files (like ttys) anyway. Use sysread() and check +for a return value for 0 to decide whether you're done. + =item sysseek FILEHANDLE,POSITION,WHENCE Sets FILEHANDLE's system position using the system call lseek(2). It bypasses stdio, so mixing this with reads (other than C<sysread()>), -C<print()>, C<write()>, C<seek()>, or C<tell()> may cause confusion. FILEHANDLE may -be an expression whose value gives the name of the filehandle. The -values for WHENCE are C<0> to set the new position to POSITION, C<1> to set -the it to the current position plus POSITION, and C<2> to set it to EOF -plus POSITION (typically negative). For WHENCE, you may use the -constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END> from either the C<IO::Seekable> -or the POSIX module. +C<print()>, C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause +confusion. FILEHANDLE may be an expression whose value gives the name +of the filehandle. The values for WHENCE are C<0> to set the new +position to POSITION, C<1> to set the it to the current position plus +POSITION, and C<2> to set it to EOF plus POSITION (typically negative). +For WHENCE, you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and +C<SEEK_END> from either the C<IO::Seekable> or the POSIX module. Returns the new position, or the undefined value on failure. A position of zero is returned as the string "C<0> but true"; thus C<sysseek()> returns @@ -3900,7 +4241,7 @@ the new position. =item system PROGRAM LIST -Does exactly the same thing as "C<exec LIST>" except that a fork is done +Does exactly the same thing as "C<exec LIST>", except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. If there is more than one argument in LIST, or if LIST is @@ -3944,14 +4285,17 @@ See L<perlop/"`STRING`"> and L</exec> for details. =item syswrite FILEHANDLE,SCALAR,LENGTH +=item syswrite FILEHANDLE,SCALAR + Attempts to write LENGTH bytes of data from variable SCALAR to the -specified FILEHANDLE, using the system call write(2). It bypasses +specified FILEHANDLE, using the system call write(2). If LENGTH is +not specified, writes whole SCALAR. It bypasses stdio, so mixing this with reads (other than C<sysread())>, C<print()>, -C<write()>, C<seek()>, or C<tell()> may cause confusion because stdio usually -buffers data. Returns the number of bytes actually written, or C<undef> -if there was an error. If the LENGTH is greater than the available -data in the SCALAR after the OFFSET, only as much data as is available -will be written. +C<write()>, C<seek()>, C<tell()>, or C<eof()> may cause confusion +because stdio usually buffers data. Returns the number of bytes +actually written, or C<undef> if there was an error. If the LENGTH is +greater than the available data in the SCALAR after the OFFSET, only as +much data as is available will be written. An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing @@ -3964,7 +4308,9 @@ case the SCALAR is empty you can use OFFSET but only zero offset. Returns the current position for FILEHANDLE. FILEHANDLE may be an expression whose value gives the name of the actual filehandle. If -FILEHANDLE is omitted, assumes the file last read. +FILEHANDLE is omitted, assumes the file last read. + +There is no C<systell()> function. Use C<sysseek(FH, 0, 1)> for that. =item telldir DIRHANDLE @@ -3979,11 +4325,11 @@ This function binds a variable to a package class that will provide the implementation for the variable. VARIABLE is the name of the variable to be enchanted. CLASSNAME is the name of a class implementing objects of correct type. Any additional arguments are passed to the "C<new()>" -method of the class (meaning C<TIESCALAR>, C<TIEARRAY>, or C<TIEHASH>). -Typically these are arguments such as might be passed to the C<dbm_open()> -function of C. The object returned by the "C<new()>" method is also -returned by the C<tie()> function, which would be useful if you want to -access other methods in CLASSNAME. +method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>, +or C<TIEHASH>). Typically these are arguments such as might be passed +to the C<dbm_open()> function of C. The object returned by the "C<new()>" +method is also returned by the C<tie()> function, which would be useful +if you want to access other methods in CLASSNAME. Note that functions such as C<keys()> and C<values()> may return huge lists when used on large objects, like DBM files. You may prefer to use the @@ -4000,34 +4346,58 @@ C<each()> function to iterate over such. Example: A class implementing a hash should have the following methods: TIEHASH classname, LIST - DESTROY this FETCH this, key STORE this, key, value DELETE this, key + CLEAR this EXISTS this, key FIRSTKEY this NEXTKEY this, lastkey + DESTROY this A class implementing an ordinary array should have the following methods: TIEARRAY classname, LIST - DESTROY this FETCH this, key STORE this, key, value - [others TBD] + FETCHSIZE this + STORESIZE this, count + CLEAR this + PUSH this, LIST + POP this + SHIFT this + UNSHIFT this, LIST + SPLICE this, offset, length, LIST + EXTEND this, count + DESTROY this + +A class implementing a file handle should have the following methods: + + TIEHANDLE classname, LIST + READ this, scalar, length, offset + READLINE this + GETC this + WRITE this, scalar, length, offset + PRINT this, LIST + PRINTF this, format, LIST + CLOSE this + DESTROY this A class implementing a scalar should have the following methods: TIESCALAR classname, LIST - DESTROY this FETCH this, STORE this, value + DESTROY this + +Not all methods indicated above need be implemented. See L<perltie>, +L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>. Unlike C<dbmopen()>, the C<tie()> function will not use or require a module for you--you need to do that explicitly yourself. See L<DB_File> or the F<Config> module for interesting C<tie()> implementations. -For further details see L<perltie>, L<tied VARIABLE>. +For further details see L<perltie>, L<"tied VARIABLE">. =item tied VARIABLE @@ -4070,6 +4440,7 @@ otherwise. Returns an uppercased version of EXPR. This is the internal function implementing the C<\U> escape in double-quoted strings. Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>. +(It does not attempt to do titlecase mapping on initial letters. See C<ucfirst()> for that.) If EXPR is omitted, uses C<$_>. @@ -4077,7 +4448,7 @@ If EXPR is omitted, uses C<$_>. =item ucfirst -Returns the value of EXPR with the first character uppercased. This is +Returns the value of EXPR with the first character in uppercase. This is the internal function implementing the C<\u> escape in double-quoted strings. Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>. @@ -4090,6 +4461,28 @@ If EXPR is omitted, uses C<$_>. Sets the umask for the process to EXPR and returns the previous value. If EXPR is omitted, merely returns the current umask. +The Unix permission C<rwxr-x---> is represented as three sets of three +bits, or three octal digits: C<0750> (the leading 0 indicates octal +and isn't one of the digits). The C<umask> value is such a number +representing disabled permissions bits. The permission (or "mode") +values you pass C<mkdir> or C<sysopen> are modified by your umask, so +even if you tell C<sysopen> to create a file with permissions C<0777>, +if your umask is C<0022> then the file will actually be created with +permissions C<0755>. If your C<umask> were C<0027> (group can't +write; others can't read, write, or execute), then passing +C<sysopen()> C<0666> would create a file with mode C<0640> (C<0666 &~ +027> is C<0640>). + +Here's some advice: supply a creation mode of C<0666> for regular +files (in C<sysopen()>) and one of C<0777> for directories (in +C<mkdir()>) and executable files. This gives users the freedom of +choice: if they want protected files, they might choose process umasks +of C<022>, C<027>, or even the particularly antisocial mask of C<077>. +Programs should rarely if ever make policy decisions better left to +the user. The exception to this is when writing files that should be +kept private: mail files, web browser cookies, I<.rhosts> files, and +so on. + If umask(2) is not implemented on your system and you are trying to restrict access for I<yourself> (i.e., (EXPR & 0700) > 0), produces a fatal error at run time. If umask(2) is not implemented and you are @@ -4165,14 +4558,16 @@ themselves. Default is a 16-bit checksum. For example, the following computes the same number as the System V sum program: while (<>) { - $checksum += unpack("%16C*", $_); + $checksum += unpack("%32C*", $_); } - $checksum %= 65536; + $checksum %= 65535; The following efficiently counts the number of set bits in a bit vector: $setbits = unpack("%32b*", $selectmask); +See L</pack> for more examples. + =item untie VARIABLE Breaks the binding between a variable and a package. (See C<tie()>.) @@ -4280,10 +4675,20 @@ command if the files already exist: Returns a list consisting of all the values of the named hash. (In a scalar context, returns the number of values.) The values are -returned in an apparently random order, but it is the same order as -either the C<keys()> or C<each()> function would produce on the same hash. -As a side effect, it resets HASH's iterator. See also C<keys()>, C<each()>, -and C<sort()>. +returned in an apparently random order. The actual random order is +subject to change in future versions of perl, but it is guaranteed to +be the same order as either the C<keys()> or C<each()> function would +produce on the same (unmodified) hash. + +Note that you cannot modify the values of a hash this way, because the +returned list is just a copy. You need to use a hash slice for that, +since it's lvaluable in a way that values() is not. + + for (values %hash) { s/foo/bar/g } # FAILS! + for (@hash{keys %hash}) { s/foo/bar/g } # ok + +As a side effect, calling values() resets the HASH's internal iterator. +See also C<keys()>, C<each()>, and C<sort()>. =item vec EXPR,OFFSET,BITS @@ -4298,7 +4703,7 @@ the correct precedence as in Vectors created with C<vec()> can also be manipulated with the logical operators C<|>, C<&>, and C<^>, which will assume a bit vector operation is -desired when both operands are strings. +desired when both operands are strings. See L<perlop/"Bitwise String Operators">. The following code will build up an ASCII string saying C<'PerlPerlPerl'>. The comments show the string after each step. Note that this code works @@ -4327,28 +4732,35 @@ If you know the exact length in bits, it can be used in place of the C<*>. =item wait -Waits for a child process to terminate and returns the pid of the -deceased process, or C<-1> if there are no child processes. The status is -returned in C<$?>. +Behaves like the wait(2) system call on your system: it waits for a child +process to terminate and returns the pid of the deceased process, or +C<-1> if there are no child processes. The status is rketurned in C<$?>. +Note that a return value of C<-1> could mean that child processes are +being automatically reaped, as described in L<perlipc>. =item waitpid PID,FLAGS -Waits for a particular child process to terminate and returns the pid -of the deceased process, or C<-1> if there is no such child process. The -status is returned in C<$?>. If you say +Waits for a particular child process to terminate and returns the pid of +the deceased process, or C<-1> if there is no such child process. On some +systems, a value of 0 indicates that there are processes still running. +The status is returned in C<$?>. If you say use POSIX ":sys_wait_h"; #... - waitpid(-1,&WNOHANG); + do { + $kid = waitpid(-1,&WNOHANG); + } until $kid == -1; -then you can do a non-blocking wait for any process. Non-blocking wait -is available on machines supporting either the waitpid(2) or -wait4(2) system calls. However, waiting for a particular pid with -FLAGS of C<0> is implemented everywhere. (Perl emulates the system call -by remembering the status values of processes that have exited but have -not been harvested by the Perl script yet.) +then you can do a non-blocking wait for all pending zombie processes. +Non-blocking wait is available on machines supporting either the +waitpid(2) or wait4(2) system calls. However, waiting for a particular +pid with FLAGS of C<0> is implemented everywhere. (Perl emulates the +system call by remembering the status values of processes that have +exited but have not been harvested by the Perl script yet.) -See L<perlipc> for other examples. +Note that on some systems, a return value of C<-1> could mean that child +processes are being automatically reaped. See L<perlipc> for details, +and for other examples. =item wantarray @@ -4401,7 +4813,8 @@ warnings (even the so-called mandatory ones). An example: warn "\$foo is alive and $foo!"; # does show up See L<perlvar> for details on setting C<%SIG> entries, and for more -examples. +examples. See the Carp module for other kinds of warnings using its +carp() and cluck() functions. =item write FILEHANDLE diff --git a/contrib/perl5/pod/perlguts.pod b/contrib/perl5/pod/perlguts.pod index 20a07d3..90bb716 100644 --- a/contrib/perl5/pod/perlguts.pod +++ b/contrib/perl5/pod/perlguts.pod @@ -48,8 +48,8 @@ To change the value of an *already-existing* SV, there are seven routines: void sv_setiv(SV*, IV); void sv_setuv(SV*, UV); void sv_setnv(SV*, double); - void sv_setpv(SV*, char*); - void sv_setpvn(SV*, char*, int) + void sv_setpv(SV*, const char*); + void sv_setpvn(SV*, const char*, int) void sv_setpvf(SV*, const char*, ...); void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_setsv(SV*, SV*); @@ -68,7 +68,7 @@ C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify either a pointer to a variable argument list or the address and length of an array of SVs. The last argument points to a boolean; on return, if that boolean is true, then locale-specific information has been used to format -the string, and the string's contents are therefore untrustworty (see +the string, and the string's contents are therefore untrustworthy (see L<perlsec>). This pointer may be NULL if that information is not important. Note that this function requires you to specify the length of the format. @@ -95,9 +95,20 @@ or string. In the C<SvPV> macro, the length of the string returned is placed into the variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do not -care what the length of the data is, use the global variable C<PL_na>. Remember, -however, that Perl allows arbitrary strings of data that may both contain -NULs and might not be terminated by a NUL. +care what the length of the data is, use the global variable C<PL_na> or a +local variable of type C<STRLEN>. However using C<PL_na> can be quite +inefficient because C<PL_na> must be accessed in thread-local storage in +threaded Perl. In any case, remember that Perl allows arbitrary strings of +data that may both contain NULs and might not be terminated by a NUL. + +Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len), +len);>. It might work with your compiler, but it won't work for everyone. +Break this sort of statement up into separate assignments: + + STRLEN len; + char * ptr; + ptr = SvPV(len); + foo(ptr, len); If you want to know if the scalar value is TRUE, you can use: @@ -138,7 +149,7 @@ If you want to append something to the end of string stored in an C<SV*>, you can use the following functions: void sv_catpv(SV*, char*); - void sv_catpvn(SV*, char*, int); + void sv_catpvn(SV*, char*, STRLEN); void sv_catpvf(SV*, const char*, ...); void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_catsv(SV*, SV*); @@ -262,9 +273,9 @@ return value. The C<av_clear> function deletes all the elements in the AV* array, but does not actually delete the array itself. The C<av_undef> function will delete all the elements in the array plus the array itself. The -C<av_extend> function extends the array so that it contains C<key> -elements. If C<key> is less than the current length of the array, then -nothing is done. +C<av_extend> function extends the array so that it contains at least C<key+1> +elements. If C<key+1> is less than the currently allocated length of the array, +then nothing is done. If you know the name of an array variable, you can get a pointer to its AV by using the following: @@ -350,11 +361,9 @@ This returns NULL if the variable does not exist. The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro: - i = klen; hash = 0; - s = key; - while (i--) - hash = hash * 33 + *s++; + while (klen--) + hash = (hash * 33) + *key++; See L<Understanding the Magic of Tied Hashes and Arrays> for more information on how to use the hash access functions on tied hashes. @@ -488,7 +497,7 @@ reference is rv. SV is blessed if C<classname> is non-null. Copies string into an SV whose reference is C<rv>. Set length to 0 to let Perl calculate the string length. SV is blessed if C<classname> is non-null. - SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length); + SV* sv_setref_pvn(SV* rv, char* classname, PV iv, STRLEN length); Tests whether the SV is blessed into the specified class. It does not check inheritance relationships. @@ -861,7 +870,20 @@ C<mg_ptr> field points to a C<ufuncs> structure: When the SV is read from or written to, the C<uf_val> or C<uf_set> function will be called with C<uf_index> as the first arg and a -pointer to the SV as the second. +pointer to the SV as the second. A simple example of how to add 'U' +magic is shown below. Note that the ufuncs structure is copied by +sv_magic, so you can safely allocate it on the stack. + + void + Umagic(sv) + SV *sv; + PREINIT: + struct ufuncs uf; + CODE: + uf.uf_val = &my_get_fn; + uf.uf_set = &my_set_fn; + uf.uf_index = 0; + sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf)); Note that because multiple extensions may be using '~' or 'U' magic, it is important for extensions to take extra care to avoid conflict. @@ -907,6 +929,33 @@ in later releases, and are bracketed with [MAYCHANGE] below. If you find yourself actually applying such information in this section, be aware that the behavior may change in the future, umm, without warning. +The perl tie function associates a variable with an object that implements +the various GET, SET etc methods. To perform the equivalent of the perl +tie function from an XSUB, you must mimic this behaviour. The code below +carries out the necessary steps - firstly it creates a new hash, and then +creates a second hash which it blesses into the class which will implement +the tie methods. Lastly it ties the two hashes together, and returns a +reference to the new tied hash. Note that the code below does NOT call the +TIEHASH method in the MyTie class - +see L<Calling Perl Routines from within C Programs> for details on how +to do this. + + SV* + mytie() + PREINIT: + HV *hash; + HV *stash; + SV *tie; + CODE: + hash = newHV(); + tie = newRV_noinc((SV*)newHV()); + stash = gv_stashpv("MyTie", TRUE); + sv_bless(tie, stash); + hv_magic(hash, tie, 'P'); + RETVAL = newRV_noinc(hash); + OUTPUT: + RETVAL + The C<av_store> function, when given a tied array argument, merely copies the magic of the array onto the value to be "stored", using C<mg_copy>. It may also return NULL, indicating that the value did not @@ -982,13 +1031,13 @@ There is a way to achieve a similar task from C via Perl API: create a I<pseudo-block>, and arrange for some changes to be automatically undone at the end of it, either explicit, or via a non-local exit (via die()). A I<block>-like construct is created by a pair of -C<ENTER>/C<LEAVE> macros (see L<perlcall/EXAMPLE/"Returning a -Scalar">). Such a construct may be created specially for some -important localized task, or an existing one (like boundaries of -enclosing Perl subroutine/block, or an existing pair for freeing TMPs) -may be used. (In the second case the overhead of additional -localization must be almost negligible.) Note that any XSUB is -automatically enclosed in an C<ENTER>/C<LEAVE> pair. +C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">). +Such a construct may be created specially for some important localized +task, or an existing one (like boundaries of enclosing Perl +subroutine/block, or an existing pair for freeing TMPs) may be +used. (In the second case the overhead of additional localization must +be almost negligible.) Note that any XSUB is automatically enclosed in +an C<ENTER>/C<LEAVE> pair. Inside such a I<pseudo-block> the following service is available: @@ -1193,7 +1242,12 @@ consult L<perlcall>. =head2 Memory Allocation -It is suggested that you use the version of malloc that is distributed +All memory meant to be used with the Perl API functions should be manipulated +using the macros described in this section. The macros provide the necessary +transparency between differences in the actual malloc implementation that is +used within perl. + +It is suggested that you enable the version of malloc that is distributed with Perl. It keeps pools of various sizes of unallocated memory in order to satisfy allocation requests more quickly. However, on some platforms, it may cause spurious malloc or free errors. @@ -1460,7 +1514,7 @@ It is strongly recommended that all Perl API functions that don't begin with C<perl> be referenced with an explicit C<Perl_> prefix. The sort order of the listing is case insensitive, with any -occurrences of '_' ignored for the the purpose of sorting. +occurrences of '_' ignored for the purpose of sorting. =over 8 @@ -1594,7 +1648,7 @@ the SV which holds the name of the sub being debugged. This is the C variable which corresponds to Perl's $DB::sub variable. See C<PL_DBsingle>. The sub name can be found by - SvPV( GvSV( PL_DBsub ), PL_na ) + SvPV( GvSV( PL_DBsub ), len ) =item PL_DBtrace @@ -1731,7 +1785,7 @@ method's CV, which can be obtained from the GV with the C<GvCV> macro. =item gv_fetchmethod_autoload Returns the glob which contains the subroutine to call to invoke the -method on the C<stash>. In fact in the presense of autoloading this may +method on the C<stash>. In fact in the presence of autoloading this may be the glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is already setup. @@ -1814,7 +1868,8 @@ Returns the key slot of the hash entry as a C<char*> value, doing any necessary dereferencing of possibly C<SV*> keys. The length of the string is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do not care about what the length of the key is, -you may use the global variable C<PL_na>. Remember though, that hash +you may use the global variable C<PL_na>, though this is rather less +efficient than using a local variable. Remember though, that hash keys in perl are free to contain embedded nulls, so using C<strlen()> or similar is not a good way to find the length of hash keys. This is very similar to the C<SvPV()> macro described elsewhere in @@ -1855,15 +1910,6 @@ Clears a hash, making it empty. void hv_clear (HV* tb) -=item hv_delayfree_ent - -Releases a hash entry, such as while iterating though the hash, but -delays actual freeing of key and value until the end of the current -statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext> -and C<hv_free_ent>. - - void hv_delayfree_ent (HV* hv, HE* entry) - =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the hash @@ -1923,13 +1969,6 @@ information on how to use this function on tied hashes. HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash) -=item hv_free_ent - -Releases a hash entry, such as while iterating though the hash. See -C<hv_iternext> and C<hv_delayfree_ent>. - - void hv_free_ent (HV* hv, HE* entry) - =item hv_iterinit Prepares a starting point to traverse a hash table. @@ -2143,6 +2182,14 @@ Do magic after a value is assigned to the SV. See C<sv_magic>. int mg_set (SV* sv) +=item modglobal + +C<modglobal> is a general purpose, interpreter global HV for use by +extensions that need to keep information on a per-interpreter basis. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. + =item Move The XSUB-writer's interface to the C C<memmove> function. The C<s> is the @@ -2153,8 +2200,9 @@ the type. Can do overlapping moves. See also C<Copy>. =item PL_na -A variable which may be used with C<SvPV> to tell Perl to calculate the -string length. +A convenience variable which is typically used with C<SvPV> when one doesn't +care about the length of the string. It is usually more efficient to +declare a local variable and use that instead. =item New @@ -2632,7 +2680,7 @@ Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. Like C<sv_catpv>, but also handles 'set' magic. - void sv_catpvn (SV* sv, char* ptr) + void sv_catpv_mg (SV* sv, const char* ptr) =item sv_catpvn @@ -2703,7 +2751,7 @@ Returns the length of the string which is in the SV. See C<SvLEN>. Set the length of the string which is in the SV. See C<SvCUR>. - void SvCUR_set (SV* sv, int val ) + void SvCUR_set (SV* sv, int val) =item sv_dec @@ -2713,13 +2761,6 @@ Auto-decrement of the value in the SV. =item sv_derived_from -Returns a boolean indicating whether the SV is a subclass of the -specified class. - - int sv_derived_from(SV* sv, char* class) - -=item sv_derived_from - Returns a boolean indicating whether the SV is derived from the specified class. This is the function that implements C<UNIVERSAL::isa>. It works for class names as well as for objects. @@ -2745,7 +2786,7 @@ identical. Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its argument more than once. - void SvGETMAGIC( SV *sv ) + void SvGETMAGIC(SV *sv) =item SvGROW @@ -2754,7 +2795,7 @@ indicated number of bytes (remember to reserve space for an extra trailing NUL character). Calls C<sv_grow> to perform the expansion if necessary. Returns a pointer to the character buffer. - char* SvGROW( SV* sv, int len ) + char* SvGROW(SV* sv, STRLEN len) =item sv_grow @@ -2825,13 +2866,13 @@ will return false. =item SvIV -Returns the integer which is in the SV. +Coerces the given SV to an integer and returns it. int SvIV (SV* sv) =item SvIVX -Returns the integer which is stored in the SV. +Returns the integer which is stored in the SV, assuming SvIOK is true. int SvIVX (SV* sv) @@ -2923,13 +2964,13 @@ B<private> setting. Use C<SvNOK>. =item SvNV -Returns the double which is stored in the SV. +Coerce the given SV to a double and return it. double SvNV (SV* sv) =item SvNVX -Returns the double which is stored in the SV. +Returns the double which is stored in the SV, assuming SvNOK is true. double SvNVX (SV* sv) @@ -2982,18 +3023,16 @@ Checks the B<private> setting. Use C<SvPOK>. =item SvPV Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. If C<len> is C<PL_na> then Perl will -handle the length on its own. Handles 'get' magic. +if the SV does not contain a string. Handles 'get' magic. - char* SvPV (SV* sv, int len ) + char* SvPV (SV* sv, STRLEN len) =item SvPV_force Like <SvPV> but will force the SV into becoming a string (SvPOK). You want force if you are going to update the SvPVX directly. - char* SvPV_force(SV* sv, int len) - + char* SvPV_force(SV* sv, STRLEN len) =item SvPVX @@ -3081,13 +3120,13 @@ Like C<sv_setnv>, but also handles 'set' magic. Copies a string into an SV. The string must be null-terminated. Does not handle 'set' magic. See C<sv_setpv_mg>. - void sv_setpv (SV* sv, char* ptr) + void sv_setpv (SV* sv, const char* ptr) =item sv_setpv_mg Like C<sv_setpv>, but also handles 'set' magic. - void sv_setpv_mg (SV* sv, char* ptr) + void sv_setpv_mg (SV* sv, const char* ptr) =item sv_setpviv @@ -3107,13 +3146,13 @@ Like C<sv_setpviv>, but also handles 'set' magic. Copies a string into an SV. The C<len> parameter indicates the number of bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>. - void sv_setpvn (SV* sv, char* ptr, STRLEN len) + void sv_setpvn (SV* sv, const char* ptr, STRLEN len) =item sv_setpvn_mg Like C<sv_setpvn>, but also handles 'set' magic. - void sv_setpvn_mg (SV* sv, char* ptr, STRLEN len) + void sv_setpvn_mg (SV* sv, const char* ptr, STRLEN len) =item sv_setpvf @@ -3361,13 +3400,13 @@ appending it. =item SvUV -Returns the unsigned integer which is in the SV. +Coerces the given SV to an unsigned integer and returns it. UV SvUV(SV* sv) =item SvUVX -Returns the unsigned integer which is stored in the SV. +Returns the unsigned integer which is stored in the SV, assuming SvIOK is true. UV SvUVX(SV* sv) diff --git a/contrib/perl5/pod/perlhist.pod b/contrib/perl5/pod/perlhist.pod index 9ed8b6f..5828ea4 100644 --- a/contrib/perl5/pod/perlhist.pod +++ b/contrib/perl5/pod/perlhist.pod @@ -4,10 +4,12 @@ perlhist - the Perl history records -=for RCS +=begin RCS + # -# $Id: perlhist.pod,v 1.48 1998/08/03 08:50:12 jhi Exp $ +# $Id: perlhist.pod,v 1.57 1999/01/26 17:38:07 jhi Exp $ # + =end RCS =head1 DESCRIPTION @@ -265,6 +267,10 @@ the strings?). 5.004_04-m3 1998-May-15 5.004_04-m4 1998-May-19 5.004_04-MT5 1998-Jul-21 + 5.004_04-MT6 1998-Oct-09 + 5.004_04-MT7 1998-Nov-22 + 5.004_04-MT8 1998-Dec-03 + 5.004_04-MT9 1999-***-** Malcolm 5.004_50 1997-Sep-09 The 5.005 development track. 5.004_51 1997-Oct-02 @@ -299,9 +305,21 @@ the strings?). 5.005_02-T1 1998-Aug-02 5.005_02-T2 1998-Aug-05 5.005_02 1998-Aug-08 - Graham 5.005_03 1998- + Graham 5.005_03-MT1 1998-Nov-30 + 5.005_03-MT2 1999-Jan-04 + 5.005_03-MT3 1999-Jan-17 + 5.005_03-MT4 1999-Jan-26 + 5.005_03-MT5 1999-Jan-28 + 5.005_03-MT6 1999-Mar-04 + 5.005_03 1999-Mar-28 Sarathy 5.005_50 1998-Jul-26 The 5.006 development track. + 5.005_51 1998-Aug-10 + 5.005_52 1998-Sep-25 + 5.005_53 1998-Oct-31 + 5.005_54 1998-Nov-30 + 5.005_55 1999-Feb-16 + 5.005_56 1999-Mar-01 =head2 SELECTED RELEASE SIZES @@ -447,11 +465,12 @@ The "diff lines kb" means that for example the patch 5.003_08, to be applied on top of the 5.003_07 (or whatever was before the 5.003_08) added lines for 110 kilobytes, it removed lines for 19 kilobytes, and changed lines for 424 kilobytes. Just the lines themselves are -counted, not their context. The "+ - !" become from the diff(1)s +counted, not their context. The "+ - !" become from the diff(1) context diff output format. Pump- Release Date diff lines kB - king + - ! + king ------------- + + - ! =========================================================================== Chip 5.003_08 1996-Nov-19 110 19 424 diff --git a/contrib/perl5/pod/perlipc.pod b/contrib/perl5/pod/perlipc.pod index 59c5ad9..2f99d10 100644 --- a/contrib/perl5/pod/perlipc.pod +++ b/contrib/perl5/pod/perlipc.pod @@ -56,7 +56,17 @@ So to check whether signal 17 and SIGALRM were the same, do just this: You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as the handler, in which case Perl will try to discard the signal or do the -default thing. Some signals can be neither trapped nor ignored, such as +default thing. + +On most UNIX platforms, the C<CHLD> (sometimes also known as C<CLD>) signal +has special behavior with respect to a value of C<'IGNORE'>. +Setting C<$SIG{CHLD}> to C<'IGNORE'> on such a platform has the effect of +not creating zombie processes when the parent process fails to C<wait()> +on its child processes (i.e. child processes are automatically reaped). +Calling C<wait()> with C<$SIG{CHLD}> set to C<'IGNORE'> usually returns +C<-1> on such platforms. + +Some signals can be neither trapped nor ignored, such as the KILL and STOP (but not the TSTP) signals. One strategy for temporarily ignoring signals is to use a local() statement, which will be automatically restored once your block is exited. (Remember that local() @@ -317,46 +327,33 @@ details). =head2 Complete Dissociation of Child from Parent In some cases (starting server processes, for instance) you'll want to -complete dissociate the child process from the parent. The easiest -way is to use: - - use POSIX qw(setsid); - setsid() or die "Can't start a new session: $!"; - -However, you may not be on POSIX. The following process is reported -to work on most Unixish systems. Non-Unix users should check their -Your_OS::Process module for other solutions. - -=over 4 - -=item * - -Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty(4)> -for details. - -=item * - -Change directory to / - -=item * - -Reopen STDIN, STDOUT, and STDERR so they're not connected to the old -tty. - -=item * - -Background yourself like this: - - fork && exit; - -=item * - -Ignore hangup signals in case you're running on a shell that doesn't -automatically no-hup you: +completely dissociate the child process from the parent. This is +often called daemonization. A well behaved daemon will also chdir() +to the root directory (so it doesn't prevent unmounting the filesystem +containing the directory from which it was launched) and redirect its +standard file descriptors from and to F</dev/null> (so that random +output doesn't wind up on the user's terminal). + + use POSIX 'setsid'; + + sub daemonize { + chdir '/' or die "Can't chdir to /: $!"; + open STDIN, '/dev/null' or die "Can't read /dev/null: $!"; + open STDOUT, '>/dev/null' + or die "Can't write to /dev/null: $!"; + defined(my $pid = fork) or die "Can't fork: $!"; + exit if $pid; + setsid or die "Can't start a new session: $!"; + open STDERR, '>&STDOUT' or die "Can't dup stdout: $!"; + } - $SIG{HUP} = 'IGNORE'; # or whatever you'd like +The fork() has to come before the setsid() to ensure that you aren't a +process group leader (the setsid() will fail if you are). If your +system doesn't have the setsid() function, open F</dev/tty> and use the +C<TIOCNOTTY> ioctl() on it instead. See L<tty(4)> for details. -=back +Non-Unix users should check their Your_OS::Process module for other +solutions. =head2 Safe Pipe Opens @@ -1194,7 +1191,7 @@ you'll have to use the C<sysread> variant of the interactive client above. This server accepts one of five different commands, sending output back to the client. Note that unlike most network servers, this one only handles one incoming client at a time. Multithreaded servers are -covered in Chapter 6 of the Camel as well as later in this manpage. +covered in Chapter 6 of the Camel. Here's the code. We'll diff --git a/contrib/perl5/pod/perllocale.pod b/contrib/perl5/pod/perllocale.pod index 4401be2..08b50e0 100644 --- a/contrib/perl5/pod/perllocale.pod +++ b/contrib/perl5/pod/perllocale.pod @@ -215,6 +215,8 @@ I<SEE ALSO> section). If that fails, try the following command lines: ls /usr/lib/nls + ls /usr/share/locale + and see whether they list something resembling these en_US.ISO8859-1 de_DE.ISO8859-1 ru_RU.ISO8859-5 @@ -225,18 +227,18 @@ and see whether they list something resembling these english.iso88591 german.iso88591 russian.iso88595 english.roman8 russian.koi8r -Sadly, even though the calling interface for setlocale() has -been standardized, names of locales and the directories where the +Sadly, even though the calling interface for setlocale() has been +standardized, names of locales and the directories where the configuration resides have not been. The basic form of the name is -I<language_country/territory>B<.>I<codeset>, but the latter parts after -I<language> are not always present. The I<language> and I<country> are -usually from the standards B<ISO 3166> and B<ISO 639>, the two-letter -abbreviations for the countries and the languages of the world, -respectively. The I<codeset> part often mentions some B<ISO 8859> -character set, the Latin codesets. For example, C<ISO 8859-1> is the -so-called "Western codeset" that can be used to encode most Western -European languages. Again, there are several ways to write even the -name of that one standard. Lamentably. +I<language_territory>B<.>I<codeset>, but the latter parts after +I<language> are not always present. The I<language> and I<country> +are usually from the standards B<ISO 3166> and B<ISO 639>, the +two-letter abbreviations for the countries and the languages of the +world, respectively. The I<codeset> part often mentions some B<ISO +8859> character set, the Latin codesets. For example, C<ISO 8859-1> +is the so-called "Western European codeset" that can be used to encode +most Western European languages adequately. Again, there are several +ways to write even the name of that one standard. Lamentably. Two special locales are worth particular mention: "C" and "POSIX". Currently these are effectively the same locale: the difference is @@ -276,10 +278,10 @@ The two quickest fixes are either to render Perl silent about any locale inconsistencies or to run Perl under the default locale "C". Perl's moaning about locale problems can be silenced by setting the -environment variable PERL_BADLANG to a non-zero value, for example -"1". This method really just sweeps the problem under the carpet: you -tell Perl to shut up even when Perl sees that something is wrong. Do -not be surprised if later something locale-dependent misbehaves. +environment variable PERL_BADLANG to a zero value, for example "0". +This method really just sweeps the problem under the carpet: you tell +Perl to shut up even when Perl sees that something is wrong. Do not +be surprised if later something locale-dependent misbehaves. Perl can be run under the "C" locale by setting the environment variable LC_ALL to "C". This method is perhaps a bit more civilized @@ -330,7 +332,7 @@ Second, if using the listed commands you see something B<exactly> (prefix matches do not count and case usually counts) like "En_US" without the quotes, then you should be okay because you are using a locale name that should be installed and available in your system. -In this case, see L<Fixing system locale configuration>. +In this case, see L<Permanently fixing system locale configuration>. =head2 Permanently fixing your locale configuration @@ -349,7 +351,7 @@ rules for matching locale names are a bit vague because standardization is weak in this area. See again the L<Finding locales> about general rules. -=head2 Permanently fixing system locale configuration +=head2 Fixing system locale configuration Contact a system administrator (preferably your own) and report the exact error message you get, and ask them to read this same documentation you @@ -710,7 +712,7 @@ case-mapping with C<\l>, C<\L>,C<\u> or C<\U>. =item B<In-memory formatting function> (sprintf()): -Result is tainted if "use locale" is in effect. +Result is tainted if C<use locale> is in effect. =item B<Output formatting functions> (printf() and write()): @@ -785,9 +787,10 @@ of a match involving C<\w> while C<use locale> is in effect. A string that can suppress Perl's warning about failed locale settings at startup. Failure can occur if the locale support in the operating system is lacking (broken) in some way--or if you mistyped the name of -a locale when you set up your environment. If this environment variable -is absent, or has a value that does not evaluate to integer zero--that -is, "0" or ""--Perl will complain about locale setting failures. +a locale when you set up your environment. If this environment +variable is absent, or has a value that does not evaluate to integer +zero--that is, "0" or ""-- Perl will complain about locale setting +failures. B<NOTE>: PERL_BADLANG only gives you a way to hide the warning message. The message tells about some problem in your system's locale support, @@ -806,6 +809,20 @@ for controlling an application's opinion on data. C<LC_ALL> is the "override-all" locale environment variable. If set, it overrides all the rest of the locale environment variables. +=item LANGUAGE + +B<NOTE>: C<LANGUAGE> is a GNU extension, it affects you only if you +are using the GNU libc. This is the case if you are using e.g. Linux. +If you are using "commercial" UNIXes you are most probably I<not> +using GNU libc and you can ignore C<LANGUAGE>. + +However, in the case you are using C<LANGUAGE>: it affects the +language of informational, warning, and error messages output by +commands (in other words, it's like C<LC_MESSAGES>) but it has higher +priority than L<LC_ALL>. Moreover, it's not a single value but +instead a "path" (":"-separated list) of I<languages> (not locales). +See the GNU C<gettext> library documentation for more information. + =item LC_CTYPE In the absence of C<LC_ALL>, C<LC_CTYPE> chooses the character type @@ -854,7 +871,7 @@ always in force, even if the program environment suggested otherwise (see L<The setlocale function>). By default, Perl still behaves this way for backward compatibility. If you want a Perl application to pay attention to locale information, you B<must> use the S<C<use locale>> -pragma (see L<The use locale Pragma>) to instruct it to do so. +pragma (see L<The use locale pragma>) to instruct it to do so. Versions of Perl from 5.002 to 5.003 did use the C<LC_CTYPE> information if available; that is, C<\w> did understand what diff --git a/contrib/perl5/pod/perllol.pod b/contrib/perl5/pod/perllol.pod index 0e6796b..56f08c2 100644 --- a/contrib/perl5/pod/perllol.pod +++ b/contrib/perl5/pod/perllol.pod @@ -34,7 +34,7 @@ but rather just a reference to it, you could do something more like this: $ref_to_LoL = [ [ "fred", "barney", "pebbles", "bambam", "dino", ], [ "homer", "bart", "marge", "maggie", ], - [ "george", "jane", "alroy", "judy", ], + [ "george", "jane", "elroy", "judy", ], ]; print $ref_to_LoL->[2][2]; diff --git a/contrib/perl5/pod/perlmod.pod b/contrib/perl5/pod/perlmod.pod index 6da31de..48ebf23 100644 --- a/contrib/perl5/pod/perlmod.pod +++ b/contrib/perl5/pod/perlmod.pod @@ -243,7 +243,7 @@ a file called Some/Module.pm and start with this template: # non-exported package globals go here use vars qw(@more $stuff); - # initalize package globals, first exported ones + # initialize package globals, first exported ones $Var1 = ''; %Hashit = (); diff --git a/contrib/perl5/pod/perlmodinstall.pod b/contrib/perl5/pod/perlmodinstall.pod index 1c65f1c..b6176f0 100644 --- a/contrib/perl5/pod/perlmodinstall.pod +++ b/contrib/perl5/pod/perlmodinstall.pod @@ -178,16 +178,27 @@ B<If you're using a Macintosh,> A. DECOMPRESS -You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in -combination with I<DropStuff with Expander Enhancer> -(shareware), or the freeware MacGzip ( +In general, all Macintosh decompression utilities mentioned here +can be found in the Info-Mac Hyperarchive +( http://hyperarchive.lcs.mit.edu/HyperArchive.html ). +Specificly the "Commpress & Translate" listing +( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ). + + +You can either use the shareware StuffIt Expander +( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/stuffit-expander-401.hqx ) +in combination with I<DropStuff with Expander Enhancer> +( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/drop-stuff-with-ee-40.hqx ) +or the freeware MacGzip ( http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ). + B. UNPACK If you're using DropStuff or Stuffit, you can just extract the tar -archive. Otherwise, you can use the freeware I<suntar> ( -http://www.cirfid.unibo.it/~speranza ). +archive. Otherwise, you can use the freeware I<suntar> +( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/suntar-221.hqx ) +or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/tar-40b.hqx ). C. BUILD @@ -212,6 +223,15 @@ mail to mac-perl-request@iis.ee.ethz.ch. D. INSTALL Make sure the newlines for the modules are in Mac format, not Unix format. +If they are not then you might have decompressed them incorrectly. Check +your decompression and unpacking utilities settings to make sure they are +translating text files properly. +As a last resort, you can use the perl one-liner: + + perl -i.bak -pe 's/(?:\015)?\012/\015/g' filenames + +on the source files. + Move the files manually into the correct folders. Move the files to their final destination: This will diff --git a/contrib/perl5/pod/perlmodlib.pod b/contrib/perl5/pod/perlmodlib.pod index 5d0e5b0..d6c6b32 100644 --- a/contrib/perl5/pod/perlmodlib.pod +++ b/contrib/perl5/pod/perlmodlib.pod @@ -21,7 +21,7 @@ bulletproof. They work somewhat like pragmas in that they tend to affect the compilation of your program, and thus will usually work well only when used within a -C<use>, or C<no>. Most of these are locally scoped, so an inner BLOCK +C<use>, or C<no>. Most of these are lexically scoped, so an inner BLOCK may countermand any of these by saying: no integer; @@ -261,6 +261,14 @@ traverse a file tree create or remove a series of directories +=item File::Spec + +portably perform operations on file names + +=item File::Spec::Functions + +function call interface to File::Spec module + =item File::stat by-name interface to Perl's builtin stat() functions @@ -608,84 +616,133 @@ You should try to choose one close to you: =item * Africa - South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ + South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ + ftp://ftpza.co.za/pub/mirrors/cpan/ =item * Asia - Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ - Japan ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ - South Korea ftp://ftp.nuri.net/pub/CPAN/ - Taiwan ftp://dongpo.math.ncu.edu.tw/perl/CPAN/ - ftp://ftp.wownet.net/pub2/PERL/ + Armenia ftp://sunsite.aua.am/pub/CPAN/ + China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ + Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ + Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ + Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/ + ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ + ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ + ftp://ftp.meisei-u.ac.jp/pub/CPAN/ + ftp://mirror.nucba.ac.jp/mirror/Perl/ + Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ + South Korea ftp://ftp.bora.net/pub/CPAN/ + ftp://ftp.nuri.net/pub/CPAN/ + Taiwan ftp://ftp.wownet.net/pub2/PERL/ + ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ + Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ + ftp://ftp.nectec.or.th/pub/mirrors/CPAN/ =item * Australasia - Australia ftp://ftp.netinfo.com.au/pub/perl/CPAN/ - New Zealand ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/ + Australia ftp://cpan.topend.com.au/pub/CPAN/ + ftp://ftp.labyrinth.net.au/pub/perl/CPAN/ + ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/ + ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ + New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ + ftp://sunsite.net.nz/pub/languages/perl/CPAN/ + +=item * +Central America + + Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ =item * Europe - Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ - Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - Czech Republic ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ - Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ - Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - France ftp://ftp.ibp.fr/pub/perl/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/ - Germany ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/Perl/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - Greece ftp://ftp.ntua.gr/pub/lang/perl/ - Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ - Italy ftp://cis.utovrm.it/CPAN/ - the Netherlands ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/ - ftp://ftp.EU.net/packages/cpan/ - Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ - Poland ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - Portugal ftp://ftp.ci.uminho.pt/pub/lang/perl/ - ftp://ftp.telepac.pt/pub/CPAN/ - Russia ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ - Spain ftp://ftp.etse.urv.es/pub/mirror/perl/ - ftp://ftp.rediris.es/mirror/CPAN/ - Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - UK ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ - ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ - ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ + Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ + Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ + Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/ + Croatia ftp://ftp.linux.hr/pub/CPAN/ + Czech Republic ftp://ftp.fi.muni.cz/pub/perl/ + ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ + Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ + Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/ + Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + France ftp://ftp.lip6.fr/pub/perl/CPAN/ + ftp://ftp.oleane.net/pub/mirrors/CPAN/ + ftp://ftp.pasteur.fr/pub/computing/CPAN/ + Germany ftp://ftp.archive.de.uu.net/pub/CPAN/ + ftp://ftp.gmd.de/packages/CPAN/ + ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/ + ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ + ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ + ftp://ftp.uni-erlangen.de/pub/source/CPAN/ + ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ + Greece ftp://ftp.ntua.gr/pub/lang/perl/ + Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ + Ireland ftp://sunsite.compapp.dcu.ie/pub/perl/ + Italy ftp://cis.uniRoma2.it/CPAN/ + ftp://ftp.flashnet.it/pub/CPAN/ + ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ + Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/ + ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ + Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ + ftp://sunsite.uio.no/pub/languages/perl/CPAN/ + Poland ftp://ftp.man.szczecin.pl/pub/perl/CPAN/ + ftp://ftp.man.torun.pl/pub/doc/CPAN/ + ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ + ftp://sunsite.icm.edu.pl/pub/CPAN/ + Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/ + ftp://ftp.ua.pt/pub/CPAN/ + Romania ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/ + ftp://ftp.dnttm.ro/pub/CPAN/ + Russia ftp://cpan.npi.msu.su/CPAN/ + ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ + Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/ + Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ + Spain ftp://ftp.etse.urv.es/pub/perl/ + ftp://ftp.rediris.es/mirror/CPAN/ + Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ + Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ + Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ + United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ + ftp://ftp.flirble.org/pub/languages/perl/CPAN/ + ftp://ftp.plig.org/pub/CPAN/ + ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ + ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ =item * North America - Ontario ftp://ftp.utilis.com/public/CPAN/ - ftp://enterprise.ic.gc.ca/pub/perl/CPAN/ - Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ - California ftp://ftp.digital.com/pub/plan/perl/CPAN/ - ftp://ftp.cdrom.com/pub/perl/CPAN/ - Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - Florida ftp://ftp.cis.ufl.edu/pub/perl/CPAN/ - Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ - Massachusetts ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ - New York ftp://ftp.rge.com/pub/languages/perl/ - North Carolina ftp://ftp.duke.edu/pub/perl/ - Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ - Oregon http://www.perl.org/CPAN/ - ftp://ftp.orst.edu/pub/packages/CPAN/ - Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ - Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ - ftp://ftp.metronet.com/pub/perl/ + Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ + California ftp://ftp.cdrom.com/pub/perl/CPAN/ + ftp://ftp.digital.com/pub/plan/perl/CPAN/ + Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/ + Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ + Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/ + ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/ + Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ + Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ + ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ + Mexico D.F. ftp://ftp.msg.com.mx/pub/CPAN/ + New York ftp://ftp.rge.com/pub/languages/perl/ + North Carolina ftp://ftp.duke.edu/pub/perl/ + Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ + Ontario ftp://ftp.crc.ca/pub/packages/perl/CPAN/ + Oregon ftp://ftp.orst.edu/pub/packages/CPAN/ + Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ + Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ + Utah ftp://mirror.xmission.com/CPAN/ + Virginia ftp://ftp.perl.org/pub/perl/CPAN/ + ftp://ruff.cs.jmu.edu/pub/CPAN/ + Washington ftp://ftp.spu.edu/pub/CPAN/ =item * South America - Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ + Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/ + Chile ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/ + ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ =back diff --git a/contrib/perl5/pod/perlobj.pod b/contrib/perl5/pod/perlobj.pod index f10fbdf..a997ae0 100644 --- a/contrib/perl5/pod/perlobj.pod +++ b/contrib/perl5/pod/perlobj.pod @@ -84,7 +84,7 @@ that wish to call methods in the class as part of the construction: } If you care about inheritance (and you should; see -L<perlmod/"Modules: Creation, Use, and Abuse">), +L<perlmodlib/"Modules: Creation, Use, and Abuse">), then you want to use the two-arg form of bless so that your constructors may be inherited: @@ -251,7 +251,7 @@ or in one statement, There are times when one syntax is more readable, and times when the other syntax is more readable. The indirect object syntax is less cluttered, but it has the same ambiguity as ordinary list operators. -Indirect object method calls are parsed using the same rule as list +Indirect object method calls are usually parsed using the same rule as list operators: "If it looks like a function, it is a function". (Presuming for the moment that you think two words in a row can look like a function name. C++ programmers seem to think so with some regularity, @@ -268,7 +268,20 @@ would be equivalent to Critter->new('Bam' x 2), 1.4, 45 -which is unlikely to do what you want. +which is unlikely to do what you want. Confusingly, however, this +rule applies only when the indirect object is a bareword package name, +not when it's a scalar, a BLOCK, or a C<Package::> qualified package name. +In those cases, the arguments are parsed in the same way as an +indirect object list operator like print, so + + new Critter:: ('Bam' x 2), 1.4, 45 + +is the same as + + Critter::->new(('Bam' x 2), 1.4, 45) + +For more reasons why the indirect object syntax is ambiguous, see +L<"WARNING"> below. There are times when you wish to specify which class's method to use. In this case, you can call your method as an ordinary subroutine diff --git a/contrib/perl5/pod/perlop.pod b/contrib/perl5/pod/perlop.pod index c7209fa..9f6d965 100644 --- a/contrib/perl5/pod/perlop.pod +++ b/contrib/perl5/pod/perlop.pod @@ -44,7 +44,7 @@ Many operators can be overloaded for objects. See L<overload>. =head2 Terms and List Operators (Leftward) -A TERM has the highest precedence in Perl. They includes variables, +A TERM has the highest precedence in Perl. They include variables, quote and quote-like operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary @@ -620,9 +620,9 @@ the same character fore and aft, but the 4 sorts of brackets "" qq{} Literal yes `` qx{} Command yes (unless '' is delimiter) qw{} Word list no - // m{} Pattern match yes - qr{} Pattern yes - s{}{} Substitution yes + // m{} Pattern match yes (unless '' is delimiter) + qr{} Pattern yes (unless '' is delimiter) + s{}{} Substitution yes (unless '' is delimiter) tr{}{} Transliteration no (but see below) Note that there can be whitespace between the operator and the quoting @@ -645,8 +645,8 @@ a transliteration, the first ten of these sequences may be used. \b backspace (BS) \a alarm (bell) (BEL) \e escape (ESC) - \033 octal char - \x1b hex char + \033 octal char (ESC) + \x1b hex char (ESC) \c[ control char \l lowercase next char @@ -752,22 +752,22 @@ Options are: If "/" is the delimiter then the initial C<m> is optional. With the C<m> you can use any pair of non-alphanumeric, non-whitespace characters -as delimiters (if single quotes are used, no interpretation is done -on the replacement string. Unlike Perl 4, Perl 5 treats backticks as normal -delimiters; the replacement text is not evaluated as a command). -This is particularly useful for matching Unix path names -that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is +as delimiters. This is particularly useful for matching Unix path names +that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is the delimiter, then the match-only-once rule of C<?PATTERN?> applies. +If "'" is the delimiter, no variable interpolation is performed on the +PATTERN. PATTERN may contain variables, which will be interpolated (and the -pattern recompiled) every time the pattern search is evaluated. (Note -that C<$)> and C<$|> might not be interpolated because they look like -end-of-string tests.) If you want such a pattern to be compiled only -once, add a C</o> after the trailing delimiter. This avoids expensive -run-time recompilations, and is useful when the value you are -interpolating won't change over the life of the script. However, mentioning -C</o> constitutes a promise that you won't change the variables in the pattern. -If you change them, Perl won't even notice. +pattern recompiled) every time the pattern search is evaluated, except +for when the delimiter is a single quote. (Note that C<$)> and C<$|> +might not be interpolated because they look like end-of-string tests.) +If you want such a pattern to be compiled only once, add a C</o> after +the trailing delimiter. This avoids expensive run-time recompilations, +and is useful when the value you are interpolating won't change over +the life of the script. However, mentioning C</o> constitutes a promise +that you won't change the variables in the pattern. If you change them, +Perl won't even notice. If the PATTERN evaluates to the empty string, the last I<successfully> matched regular expression is used instead. @@ -829,10 +829,12 @@ Examples: ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g); # scalar context - $/ = ""; $* = 1; # $* deprecated in modern perls - while (defined($paragraph = <>)) { - while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { - $sentences++; + { + local $/ = ""; + while (defined($paragraph = <>)) { + while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { + $sentences++; + } } } print "$sentences\n"; @@ -907,14 +909,50 @@ A double-quoted, interpolated string. if /(tcl|rexx|python)/; # :-) $baz = "\n"; # a one-character string -=item qr/STRING/imosx +=item qr/PATTERN/imosx + +Quote-as-a-regular-expression operator. I<STRING> is interpolated the +same way as I<PATTERN> in C<m/PATTERN/>. If "'" is used as the +delimiter, no variable interpolation is done. Returns a Perl value +which may be used instead of the corresponding C</STRING/imosx> expression. + +For example, + + $rex = qr/my.STRING/is; + s/$rex/foo/; -A string which is (possibly) interpolated and then compiled as a -regular expression. The result may be used as a pattern in a match +is equivalent to + + s/my.STRING/foo/is; + +The result may be used as a subpattern in a match: $re = qr/$pattern/; $string =~ /foo${re}bar/; # can be interpolated in other patterns $string =~ $re; # or used standalone + $string =~ /$re/; # or this way + +Since Perl may compile the pattern at the moment of execution of qr() +operator, using qr() may have speed advantages in I<some> situations, +notably if the result of qr() is used standalone: + + sub match { + my $patterns = shift; + my @compiled = map qr/$_/i, @$patterns; + grep { + my $success = 0; + foreach my $pat @compiled { + $success = 1, last if /$pat/; + } + $success; + } @_; + } + +Precompilation of the pattern into an internal representation at the +moment of qr() avoids a need to recompile the pattern every time a +match C</$pat/> is attempted. (Note that Perl has many other +internal optimizations, but none would be triggered in the above +example if we did not use qr() operator.) Options are: @@ -924,19 +962,6 @@ Options are: s Treat string as single line. x Use extended regular expressions. -The benefit from this is that the pattern is precompiled into an internal -representation, and does not need to be recompiled every time a match -is attempted. This makes it very efficient to do something like: - - foreach $pattern (@pattern_list) { - my $re = qr/$pattern/; - foreach $line (@lines) { - if($line =~ /$re/) { - do_something($line); - } - } - } - See L<perlre> for additional information on valid syntax for STRING, and for a detailed look at the semantics of regular expressions. @@ -1023,6 +1048,12 @@ whitespace as the word delimiters. It is exactly equivalent to This equivalency means that if used in scalar context, you'll get split's (unfortunate) scalar context behavior, complete with mysterious warnings. +However do not rely on this as in a future release it could be changed to +be exactly equivalent to the list + + ('foo', 'bar', 'baz') + +Which in a scalar context would result in C<'baz'>. Some frequently seen examples: @@ -1045,7 +1076,7 @@ variable is searched and modified. (The string specified with C<=~> must be scalar variable, an array element, a hash element, or an assignment to one of those, i.e., an lvalue.) -If the delimiter chosen is single quote, no variable interpolation is +If the delimiter chosen is a single quote, no variable interpolation is done on either the PATTERN or the REPLACEMENT. Otherwise, if the PATTERN contains a $ that looks like a variable rather than an end-of-string test, the variable will be interpolated into the pattern @@ -1148,6 +1179,7 @@ the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is transliterated. (The string specified with =~ must be a scalar variable, an array element, a hash element, or an assignment to one of those, i.e., an lvalue.) + A character range may be specified with a hyphen, so C<tr/A-J/0-9/> does the same replacement as C<tr/ACEGIBDFHJ/0246813579/>. For B<sed> devotees, C<y> is provided as a synonym for C<tr>. If the @@ -1155,6 +1187,13 @@ SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes, e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>. +Note also that the whole range idea is rather unportable between +character sets--and even within character sets they may cause results +you probably didn't expect. A sound principle is to use only ranges +that begin from and end at either alphabets of equal case (a-e, A-E), +or digits (0-4). Anything else is unsafe. If in doubt, spell out the +character sets in full. + Options: c Complement the SEARCHLIST. @@ -1229,6 +1268,13 @@ details discussed in this section is hairy regular expressions. However, the first steps of parsing are the same for all Perl quoting operators, so here they are discussed together. +The most important detail of Perl parsing rules is the first one +discussed below; when processing a quoted construct, Perl I<first> +finds the end of the construct, then it interprets the contents of the +construct. If you understand this rule, you may skip the rest of this +section on the first reading. The other rules would +contradict user's expectations much less frequently than the first one. + Some of the passes discussed below are performed concurrently, but as far as results are the same, we consider them one-by-one. For different quoting constructs Perl performs different number of passes, from @@ -1238,32 +1284,37 @@ one to five, but they are always performed in the same order. =item Finding the end -First pass is finding the end of the quoted construct, be it multichar ender +First pass is finding the end of the quoted construct, be it +a multichar delimiter C<"\nEOF\n"> of C<<<EOF> construct, C</> which terminates C<qq/> construct, C<]> which terminates C<qq[> construct, or C<E<gt>> which terminates a fileglob started with C<<>. -When searching for multichar construct no skipping is performed. When -searching for one-char non-matching delimiter, such as C</>, combinations +When searching for one-char non-matching delimiter, such as C</>, combinations C<\\> and C<\/> are skipped. When searching for one-char matching delimiter, such as C<]>, combinations C<\\>, C<\]> and C<\[> are skipped, and -nested C<[>, C<]> are skipped as well. +nested C<[>, C<]> are skipped as well. When searching for multichar delimiter +no skipping is performed. -For 3-parts constructs, C<s///> etc. the search is repeated once more. +For constructs with 3-part delimiters (C<s///> etc.) the search is +repeated once more. -During this search no attention is paid to the semantic of the construct, thus +During this search no attention is paid to the semantic of the construct, +thus: "$hash{"$foo/$bar"}" -or +or: m/ - bar # This is not a comment, this slash / terminated m//! + bar # NOT a comment, this slash / terminated m//! /x -do not form legal quoted expressions. Note that since the slash which -terminated C<m//> was followed by a C<SPACE>, this is not C<m//x>, -thus C<#> was interpreted as a literal C<#>. +do not form legal quoted expressions, the quoted part ends on the first C<"> +and C</>, and the rest happens to be a syntax error. Note that since the slash +which terminated C<m//> was followed by a C<SPACE>, the above is not C<m//x>, +but rather C<m//> with no 'x' switch. So the embedded C<#> is interpreted +as a literal C<#>. =item Removal of backslashes before delimiters @@ -1297,42 +1348,64 @@ The only interpolation is removal of C<\> from pairs C<\\>. =item C<"">, C<``>, C<qq//>, C<qx//>, C<<file*globE<gt>> C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are converted -to corresponding Perl constructs, thus C<"$foo\Qbaz$bar"> is converted to +to corresponding Perl constructs, thus C<"$foo\Qbaz$bar"> is converted to : $foo . (quotemeta("baz" . $bar)); Other combinations of C<\> with following chars are substituted with -appropriate expansions. +appropriate expansions. + +Let it be stressed that I<whatever is between C<\Q> and C<\E>> is interpolated +in the usual way. Say, C<"\Q\\E"> has no C<\E> inside: it has C<\Q>, C<\\>, +and C<E>, thus the result is the same as for C<"\\\\E">. Generally speaking, +having backslashes between C<\Q> and C<\E> may lead to counterintuitive +results. So, C<"\Q\t\E"> is converted to: + + quotemeta("\t") + +which is the same as C<"\\\t"> (since TAB is not alphanumerical). Note also +that: -Interpolated scalars and arrays are converted to C<join> and C<.> Perl -constructs, thus C<"'@arr'"> becomes + $str = '\t'; + return "\Q$str"; - "'" . (join $", @arr) . "'"; +may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">. -Since all three above steps are performed simultaneously left-to-right, -the is no way to insert a literal C<$> or C<@> inside C<\Q\E> pair: it -cannot be protected by C<\>, since any C<\> (except in C<\E>) is -interpreted as a literal inside C<\Q\E>, and any C<$> is +Interpolated scalars and arrays are internally converted to the C<join> and +C<.> Perl operations, thus C<"$foo >>> '@arr'"> becomes: + + $foo . " >>> '" . (join $", @arr) . "'"; + +All the operations in the above are performed simultaneously left-to-right. + +Since the result of "\Q STRING \E" has all the metacharacters quoted +there is no way to insert a literal C<$> or C<@> inside a C<\Q\E> pair: if +protected by C<\> C<$> will be quoted to became "\\\$", if not, it is interpreted as starting an interpolated scalar. -Note also that the interpolating code needs to make decision where the -interpolated scalar ends, say, whether C<"a $b -E<gt> {c}"> means +Note also that the interpolating code needs to make a decision on where the +interpolated scalar ends. For instance, whether C<"a $b -E<gt> {c}"> means: "a " . $b . " -> {c}"; -or +or: "a " . $b -> {c}; -Most the time the decision is to take the longest possible text which does -not include spaces between components and contains matching braces/brackets. +I<Most of the time> the decision is to take the longest possible text which +does not include spaces between components and contains matching +braces/brackets. Since the outcome may be determined by I<voting> based +on heuristic estimators, the result I<is not strictly predictable>, but +is usually correct for the ambiguous cases. =item C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>, Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> and interpolation happens (almost) as with C<qq//> constructs, but I<the substitution of C<\> followed by -other chars is not performed>! Moreover, inside C<(?{BLOCK})> no processing -is performed at all. +RE-special chars (including C<\>) is not performed>! Moreover, +inside C<(?{BLOCK})>, C<(?# comment )>, and C<#>-comment of +C<//x>-regular expressions no processing is performed at all. +This is the first step where presence of the C<//x> switch is relevant. Interpolation has several quirks: C<$|>, C<$(> and C<$)> are not interpolated, and constructs C<$var[SOMETHING]> are I<voted> (by several different estimators) @@ -1340,15 +1413,25 @@ to be an array element or C<$var> followed by a RE alternative. This is the place where the notation C<${arr[$bar]}> comes handy: C</${arr[0-9]}/> is interpreted as an array element C<-9>, not as a regular expression from variable C<$arr> followed by a digit, which is the interpretation of -C</$arr[0-9]/>. +C</$arr[0-9]/>. Since voting among different estimators may be performed, +the result I<is not predictable>. + +It is on this step that C<\1> is converted to C<$1> in the replacement +text of C<s///>. Note that absence of processing of C<\\> creates specific restrictions on the post-processed text: if the delimiter is C</>, one cannot get the combination C<\/> into the result of this step: C</> will finish the regular expression, C<\/> will be stripped to C</> on the previous step, and C<\\/> will be left as is. Since C</> is equivalent to C<\/> inside a regular expression, this -does not matter unless the delimiter is special character for the RE engine, as -in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>. +does not matter unless the delimiter is a special character for the RE engine, +as in C<s*foo*bar*>, C<m[foo]>, or C<?foo?>, or an alphanumeric char, as in: + + m m ^ a \s* b mmx; + +In the above RE, which is intentionally obfuscated for illustration, the +delimiter is C<m>, the modifier is C<mx>, and after backslash-removal the +RE is the same as for C<m/ ^ a s* b /mx>). =back @@ -1367,32 +1450,48 @@ engine for compilation. Whatever happens in the RE engine is better be discussed in L<perlre>, but for the sake of continuity let us do it here. -This is the first step where presence of the C<//x> switch is relevant. +This is another step where presence of the C<//x> switch is relevant. The RE engine scans the string left-to-right, and converts it to a finite automaton. Backslashed chars are either substituted by corresponding literal -strings, or generate special nodes of the finite automaton. Characters -which are special to the RE engine generate corresponding nodes. C<(?#...)> +strings (as with C<\{>), or generate special nodes of the finite automaton +(as with C<\b>). Characters which are special to the RE engine (such as +C<|>) generate corresponding nodes or groups of nodes. C<(?#...)> comments are ignored. All the rest is either converted to literal strings to match, or is ignored (as is whitespace and C<#>-style comments if C<//x> is present). Note that the parsing of the construct C<[...]> is performed using -absolutely different rules than the rest of the regular expression. -Similarly, the C<(?{...})> is only checked for matching braces. +rather different rules than for the rest of the regular expression. +The terminator of this construct is found using the same rules as for +finding a terminator of a C<{}>-delimited construct, the only exception +being that C<]> immediately following C<[> is considered as if preceded +by a backslash. Similarly, the terminator of C<(?{...})> is found using +the same rules as for finding a terminator of a C<{}>-delimited construct. + +It is possible to inspect both the string given to RE engine, and the +resulting finite automaton. See arguments C<debug>/C<debugcolor> +of C<use L<re>> directive, and/or B<-Dr> option of Perl in +L<perlrun/Switches>. =item Optimization of regular expressions This step is listed for completeness only. Since it does not change semantics, details of this step are not documented and are subject -to change. +to change. This step is performed over the finite automaton generated +during the previous pass. + +However, in older versions of Perl C<L<split>> used to silently +optimize C</^/> to mean C</^/m>. This behaviour, though present +in current versions of Perl, may be deprecated in future. =back =head2 I/O Operators There are several I/O operators you should know about. + A string enclosed by backticks (grave accents) first undergoes variable substitution just like a double quoted string. It is then interpreted as a command, and the output of that command is the value @@ -1410,9 +1509,13 @@ The generalized form of backticks is C<qx//>. (Because backticks always undergo shell expansion as well, see L<perlsec> for security concerns.) -Evaluating a filehandle in angle brackets yields the next line from -that file (newline, if any, included), or C<undef> at end of file. -Ordinarily you must assign that value to a variable, but there is one +In a scalar context, evaluating a filehandle in angle brackets yields the +next line from that file (newline, if any, included), or C<undef> at +end-of-file. When C<$/> is set to C<undef> (i.e. file slurp mode), +and the file is empty, it returns C<''> the first time, followed by +C<undef> subsequently. + +Ordinarily you must assign the returned value to a variable, but there is one situation where an automatic assignment happens. I<If and ONLY if> the input symbol is the only thing inside the conditional of a C<while> or C<for(;;)> loop, the value is automatically assigned to the variable @@ -1449,13 +1552,16 @@ The filehandles STDIN, STDOUT, and STDERR are predefined. (The filehandles C<stdin>, C<stdout>, and C<stderr> will also work except in packages, where they would be interpreted as local identifiers rather than global.) Additional filehandles may be created with the open() -function. See L<perlfunc/open()> for details on this. +function. See L<perlfunc/open> for details on this. If a E<lt>FILEHANDLEE<gt> is used in a context that is looking for a list, a list consisting of all the input lines is returned, one line per list element. It's easy to make a I<LARGE> data space this way, so use with care. +E<lt>FILEHANDLEE<gt> may also be spelt readline(FILEHANDLE). See +L<perlfunc/readline>. + The null filehandle E<lt>E<gt> is special and can be used to emulate the behavior of B<sed> and B<awk>. Input from E<lt>E<gt> comes either from standard input, or from each file listed on the command line. Here's @@ -1622,9 +1728,10 @@ Bitstrings of any size may be manipulated by the bitwise operators (C<~ | & ^>). If the operands to a binary bitwise op are strings of different sizes, -B<or> and B<xor> ops will act as if the shorter operand had additional -zero bits on the right, while the B<and> op will act as if the longer -operand were truncated to the length of the shorter. +B<|> and B<^> ops will act as if the shorter operand had additional +zero bits on the right, while the B<&> op will act as if the longer +operand were truncated to the length of the shorter. Note that the +granularity for such extension or truncation is one or more I<bytes>. # ASCII-based examples print "j p \n" ^ " a h"; # prints "JAPH\n" @@ -1645,6 +1752,9 @@ operation you intend by using C<""> or C<0+>, as in the examples below. $baz = 0+$foo & 0+$bar; # both ops explicitly numeric $biz = "$foo" ^ "$bar"; # both ops explicitly stringy +See L<perlfunc/vec> for information on how to manipulate individual bits +in a bit vector. + =head2 Integer Arithmetic By default Perl assumes that it must do most of its arithmetic in diff --git a/contrib/perl5/pod/perlopentut.pod b/contrib/perl5/pod/perlopentut.pod new file mode 100644 index 0000000..6e6091a --- /dev/null +++ b/contrib/perl5/pod/perlopentut.pod @@ -0,0 +1,862 @@ +=head1 NAME + +perlopentut - tutorial on opening things in Perl + +=head1 DESCRIPTION + +Perl has two simple, built-in ways to open files: the shell way for +convenience, and the C way for precision. The choice is yours. + +=head1 Open E<agrave> la shell + +Perl's C<open> function was designed to mimic the way command-line +redirection in the shell works. Here are some basic examples +from the shell: + + $ myprogram file1 file2 file3 + $ myprogram < inputfile + $ myprogram > outputfile + $ myprogram >> outputfile + $ myprogram | otherprogram + $ otherprogram | myprogram + +And here are some more advanced examples: + + $ otherprogram | myprogram f1 - f2 + $ otherprogram 2>&1 | myprogram - + $ myprogram <&3 + $ myprogram >&4 + +Programmers accustomed to constructs like those above can take comfort +in learning that Perl directly supports these familiar constructs using +virtually the same syntax as the shell. + +=head2 Simple Opens + +The C<open> function takes two arguments: the first is a filehandle, +and the second is a single string comprising both what to open and how +to open it. C<open> returns true when it works, and when it fails, +returns a false value and sets the special variable $! to reflect +the system error. If the filehandle was previously opened, it will +be implicitly closed first. + +For example: + + open(INFO, "datafile") || die("can't open datafile: $!"); + open(INFO, "< datafile") || die("can't open datafile: $!"); + open(RESULTS,"> runstats") || die("can't open runstats: $!"); + open(LOG, ">> logfile ") || die("can't open logfile: $!"); + +If you prefer the low-punctuation version, you could write that this way: + + open INFO, "< datafile" or die "can't open datafile: $!"; + open RESULTS,"> runstats" or die "can't open runstats: $!"; + open LOG, ">> logfile " or die "can't open logfile: $!"; + +A few things to notice. First, the leading less-than is optional. +If omitted, Perl assumes that you want to open the file for reading. + +The other important thing to notice is that, just as in the shell, +any white space before or after the filename is ignored. This is good, +because you wouldn't want these to do different things: + + open INFO, "<datafile" + open INFO, "< datafile" + open INFO, "< datafile" + +Ignoring surround whitespace also helps for when you read a filename in +from a different file, and forget to trim it before opening: + + $filename = <INFO>; # oops, \n still there + open(EXTRA, "< $filename") || die "can't open $filename: $!"; + +This is not a bug, but a feature. Because C<open> mimics the shell in +its style of using redirection arrows to specify how to open the file, it +also does so with respect to extra white space around the filename itself +as well. For accessing files with naughty names, see L</"Dispelling +the Dweomer">. + +=head2 Pipe Opens + +In C, when you want to open a file using the standard I/O library, +you use the C<fopen> function, but when opening a pipe, you use the +C<popen> function. But in the shell, you just use a different redirection +character. That's also the case for Perl. The C<open> call +remains the same--just its argument differs. + +If the leading character is a pipe symbol, C<open) starts up a new +command and open a write-only filehandle leading into that command. +This lets you write into that handle and have what you write show up on +that command's standard input. For example: + + open(PRINTER, "| lpr -Plp1") || die "cannot fork: $!"; + print PRINTER "stuff\n"; + close(PRINTER) || die "can't close lpr: $!"; + +If the trailing character is a pipe, you start up a new command and open a +read-only filehandle leading out of that command. This lets whatever that +command writes to its standard output show up on your handle for reading. +For example: + + open(NET, "netstat -i -n |") || die "cannot fork: $!"; + while (<NET>) { } # do something with input + close(NET) || die "can't close netstat: $!"; + +What happens if you try to open a pipe to or from a non-existent command? +In most systems, such an C<open> will not return an error. That's +because in the traditional C<fork>/C<exec> model, running the other +program happens only in the forked child process, which means that +the failed C<exec> can't be reflected in the return value of C<open>. +Only a failed C<fork> shows up there. See L<perlfaq8/"Why doesn't open() +return an error when a pipe open fails?"> to see how to cope with this. +There's also an explanation in L<perlipc>. + +If you would like to open a bidirectional pipe, the IPC::Open2 +library will handle this for you. Check out L<perlipc/"Bidirectional +Communication with Another Process"> + +=head2 The Minus File + +Again following the lead of the standard shell utilities, Perl's +C<open> function treats a file whose name is a single minus, "-", in a +special way. If you open minus for reading, it really means to access +the standard input. If you open minus for writing, it really means to +access the standard output. + +If minus can be used as the default input or default output? What happens +if you open a pipe into or out of minus? What's the default command it +would run? The same script as you're current running! This is actually +a stealth C<fork> hidden inside an C<open> call. See L<perlipc/"Safe Pipe +Opens"> for details. + +=head2 Mixing Reads and Writes + +It is possible to specify both read and write access. All you do is +add a "+" symbol in front of the redirection. But as in the shell, +using a less-than on a file never creates a new file; it only opens an +existing one. On the other hand, using a greater-than always clobbers +(truncates to zero length) an existing file, or creates a brand-new one +if there isn't an old one. Adding a "+" for read-write doesn't affect +whether it only works on existing files or always clobbers existing ones. + + open(WTMP, "+< /usr/adm/wtmp") + || die "can't open /usr/adm/wtmp: $!"; + + open(SCREEN, "+> /tmp/lkscreen") + || die "can't open /tmp/lkscreen: $!"; + + open(LOGFILE, "+>> /tmp/applog" + || die "can't open /tmp/applog: $!"; + +The first one won't create a new file, and the second one will always +clobber an old one. The third one will create a new file if necessary +and not clobber an old one, and it will allow you to read at any point +in the file, but all writes will always go to the end. In short, +the first case is substantially more common than the second and third +cases, which are almost always wrong. (If you know C, the plus in +Perl's C<open> is historically derived from the one in C's fopen(3S), +which it ultimately calls.) + +In fact, when it comes to updating a file, unless you're working on +a binary file as in the WTMP case above, you probably don't want to +use this approach for updating. Instead, Perl's B<-i> flag comes to +the rescue. The following command takes all the C, C++, or yacc source +or header files and changes all their foo's to bar's, leaving +the old version in the original file name with a ".orig" tacked +on the end: + + $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy] + +This is a short cut for some renaming games that are really +the best way to update textfiles. See the second question in +L<perlfaq5> for more details. + +=head2 Filters + +One of the most common uses for C<open> is one you never +even notice. When you process the ARGV filehandle using +C<E<lt>ARGVE<gt>>, Perl actually does an implicit open +on each file in @ARGV. Thus a program called like this: + + $ myprogram file1 file2 file3 + +Can have all its files opened and processed one at a time +using a construct no more complex than: + + while (<>) { + # do something with $_ + } + +If @ARGV is empty when the loop first begins, Perl pretends you've opened +up minus, that is, the standard input. In fact, $ARGV, the currently +open file during C<E<lt>ARGVE<gt>> processing, is even set to "-" +in these circumstances. + +You are welcome to pre-process your @ARGV before starting the loop to +make sure it's to your liking. One reason to do this might be to remove +command options beginning with a minus. While you can always roll the +simple ones by hand, the Getopts modules are good for this. + + use Getopt::Std; + + # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o + getopts("vDo:"); + + # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o} + getopts("vDo:", \%args); + +Or the standard Getopt::Long module to permit named arguments: + + use Getopt::Long; + GetOptions( "verbose" => \$verbose, # --verbose + "Debug" => \$debug, # --Debug + "output=s" => \$output ); + # --output=somestring or --output somestring + +Another reason for preprocessing arguments is to make an empty +argument list default to all files: + + @ARGV = glob("*") unless @ARGV; + +You could even filter out all but plain, text files. This is a bit +silent, of course, and you might prefer to mention them on the way. + + @ARGV = grep { -f && -T } @ARGV; + +If you're using the B<-n> or B<-p> command-line options, you +should put changes to @ARGV in a C<BEGIN{}> block. + +Remember that a normal C<open> has special properties, in that it might +call fopen(3S) or it might called popen(3S), depending on what its +argument looks like; that's why it's sometimes called "magic open". +Here's an example: + + $pwdinfo = `domainname` =~ /^(\(none\))?$/ + ? '< /etc/passwd' + : 'ypcat passwd |'; + + open(PWD, $pwdinfo) + or die "can't open $pwdinfo: $!"; + +This sort of thing also comes into play in filter processing. Because +C<E<lt>ARGVE<gt>> processing employs the normal, shell-style Perl C<open>, +it respects all the special things we've already seen: + + $ myprogram f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile + +That program will read from the file F<f1>, the process F<cmd1>, standard +input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command, +and finally the F<f3> file. + +Yes, this also means that if you have a file named "-" (and so on) in +your directory, that they won't be processed as literal files by C<open>. +You'll need to pass them as "./-" much as you would for the I<rm> program. +Or you could use C<sysopen> as described below. + +One of the more interesting applications is to change files of a certain +name into pipes. For example, to autoprocess gzipped or compressed +files by decompressing them with I<gzip>: + + @ARGV = map { /^\.(gz|Z)$/ ? "gzip -dc $_ |" : $_ } @ARGV; + +Or, if you have the I<GET> program installed from LWP, +you can fetch URLs before processing them: + + @ARGV = map { m#^\w+://# ? "GET $_ |" : $_ } @ARGV; + +It's not for nothing that this is called magic C<E<lt>ARGVE<gt>>. +Pretty nifty, eh? + +=head1 Open E<agrave> la C + +If you want the convenience of the shell, then Perl's C<open> is +definitely the way to go. On the other hand, if you want finer precision +than C's simplistic fopen(3S) provides, then you should look to Perl's +C<sysopen>, which is a direct hook into the open(2) system call. +That does mean it's a bit more involved, but that's the price of +precision. + +C<sysopen> takes 3 (or 4) arguments. + + sysopen HANDLE, PATH, FLAGS, [MASK] + +The HANDLE argument is a filehandle just as with C<open>. The PATH is +a literal path, one that doesn't pay attention to any greater-thans or +less-thans or pipes or minuses, nor ignore white space. If it's there, +it's part of the path. The FLAGS argument contains one or more values +derived from the Fcntl module that have been or'd together using the +bitwise "|" operator. The final argument, the MASK, is optional; if +present, it is combined with the user's current umask for the creation +mode of the file. You should usually omit this. + +Although the traditional values of read-only, write-only, and read-write +are 0, 1, and 2 respectively, this is known not to hold true on some +systems. Instead, it's best to load in the appropriate constants first +from the Fcntl module, which supplies the following standard flags: + + O_RDONLY Read only + O_WRONLY Write only + O_RDWR Read and write + O_CREAT Create the file if it doesn't exist + O_EXCL Fail if the file already exists + O_APPEND Append to the file + O_TRUNC Truncate the file + O_NONBLOCK Non-blocking access + +Less common flags that are sometimes available on some operating systems +include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>, C<O_DEFER>, +C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>, C<O_NOCTTY>, C<O_NDELAY> +and C<O_LARGEFILE>. Consult your open(2) manpage or its local equivalent +for details. + +Here's how to use C<sysopen> to emulate the simple C<open> calls we had +before. We'll omit the C<|| die $!> checks for clarity, but make sure +you always check the return values in real code. These aren't quite +the same, since C<open> will trim leading and trailing white space, +but you'll get the idea: + +To open a file for reading: + + open(FH, "< $path"); + sysopen(FH, $path, O_RDONLY); + +To open a file for writing, creating a new file if needed or else truncating +an old file: + + open(FH, "> $path"); + sysopen(FH, $path, O_WRONLY | O_TRUNC | O_CREAT); + +To open a file for appending, creating one if necessary: + + open(FH, ">> $path"); + sysopen(FH, $path, O_WRONLY | O_APPEND | O_CREAT); + +To open a file for update, where the file must already exist: + + open(FH, "+< $path"); + sysopen(FH, $path, O_RDWR); + +And here are things you can do with C<sysopen> that you cannot do with +a regular C<open>. As you see, it's just a matter of controlling the +flags in the third argument. + +To open a file for writing, creating a new file which must not previously +exist: + + sysopen(FH, $path, O_WRONLY | O_EXCL | O_CREAT); + +To open a file for appending, where that file must already exist: + + sysopen(FH, $path, O_WRONLY | O_APPEND); + +To open a file for update, creating a new file if necessary: + + sysopen(FH, $path, O_RDWR | O_CREAT); + +To open a file for update, where that file must not already exist: + + sysopen(FH, $path, O_RDWR | O_EXCL | O_CREAT); + +To open a file without blocking, creating one if necessary: + + sysopen(FH, $path, O_WRONLY | O_NONBLOCK | O_CREAT); + +=head2 Permissions E<agrave> la mode + +If you omit the MASK argument to C<sysopen>, Perl uses the octal value +0666. The normal MASK to use for executables and directories should +be 0777, and for anything else, 0666. + +Why so permissive? Well, it isn't really. The MASK will be modified +by your process's current C<umask>. A umask is a number representing +I<disabled> permissions bits; that is, bits that will not be turned on +in the created files' permissions field. + +For example, if your C<umask> were 027, then the 020 part would +disable the group from writing, and the 007 part would disable others +from reading, writing, or executing. Under these conditions, passing +C<sysopen> 0666 would create a file with mode 0640, since C<0666 &~ 027> +is 0640. + +You should seldom use the MASK argument to C<sysopen()>. That takes +away the user's freedom to choose what permission new files will have. +Denying choice is almost always a bad thing. One exception would be for +cases where sensitive or private data is being stored, such as with mail +folders, cookie files, and internal temporary files. + +=head1 Obscure Open Tricks + +=head2 Re-Opening Files (dups) + +Sometimes you already have a filehandle open, and want to make another +handle that's a duplicate of the first one. In the shell, we place an +ampersand in front of a file descriptor number when doing redirections. +For example, C<2E<gt>&1> makes descriptor 2 (that's STDERR in Perl) +be redirected into descriptor 1 (which is usually Perl's STDOUT). +The same is essentially true in Perl: a filename that begins with an +ampersand is treated instead as a file descriptor if a number, or as a +filehandle if a string. + + open(SAVEOUT, ">&SAVEERR") || die "couldn't dup SAVEERR: $!"; + open(MHCONTEXT, "<&4") || die "couldn't dup fd4: $!"; + +That means that if a function is expecting a filename, but you don't +want to give it a filename because you already have the file open, you +can just pass the filehandle with a leading ampersand. It's best to +use a fully qualified handle though, just in case the function happens +to be in a different package: + + somefunction("&main::LOGFILE"); + +This way if somefunction() is planning on opening its argument, it can +just use the already opened handle. This differs from passing a handle, +because with a handle, you don't open the file. Here you have something +you can pass to open. + +If you have one of those tricky, newfangled I/O objects that the C++ +folks are raving about, then this doesn't work because those aren't a +proper filehandle in the native Perl sense. You'll have to use fileno() +to pull out the proper descriptor number, assuming you can: + + use IO::Socket; + $handle = IO::Socket::INET->new("www.perl.com:80"); + $fd = $handle->fileno; + somefunction("&$fd"); # not an indirect function call + +It can be easier (and certainly will be faster) just to use real +filehandles though: + + use IO::Socket; + local *REMOTE = IO::Socket::INET->new("www.perl.com:80"); + die "can't connect" unless defined(fileno(REMOTE)); + somefunction("&main::REMOTE"); + +If the filehandle or descriptor number is preceded not just with a simple +"&" but rather with a "&=" combination, then Perl will not create a +completely new descriptor opened to the same place using the dup(2) +system call. Instead, it will just make something of an alias to the +existing one using the fdopen(3S) library call This is slightly more +parsimonious of systems resources, although this is less a concern +these days. Here's an example of that: + + $fd = $ENV{"MHCONTEXTFD"}; + open(MHCONTEXT, "<&=$fd") or die "couldn't fdopen $fd: $!"; + +If you're using magic C<E<lt>ARGVE<gt>>, you could even pass in as a +command line argument in @ARGV something like C<"E<lt>&=$MHCONTEXTFD">, +but we've never seen anyone actually do this. + +=head2 Dispelling the Dweomer + +Perl is more of a DWIMmer language than something like Java--where DWIM +is an acronym for "do what I mean". But this principle sometimes leads +to more hidden magic than one knows what to do with. In this way, Perl +is also filled with I<dweomer>, an obscure word meaning an enchantment. +Sometimes, Perl's DWIMmer is just too much like dweomer for comfort. + +If magic C<open> is a bit too magical for you, you don't have to turn +to C<sysopen>. To open a file with arbitrary weird characters in +it, it's necessary to protect any leading and trailing whitespace. +Leading whitespace is protected by inserting a C<"./"> in front of a +filename that starts with whitespace. Trailing whitespace is protected +by appending an ASCII NUL byte (C<"\0">) at the end off the string. + + $file =~ s#^(\s)#./$1#; + open(FH, "< $file\0") || die "can't open $file: $!"; + +This assumes, of course, that your system considers dot the current +working directory, slash the directory separator, and disallows ASCII +NULs within a valid filename. Most systems follow these conventions, +including all POSIX systems as well as proprietary Microsoft systems. +The only vaguely popular system that doesn't work this way is the +proprietary Macintosh system, which uses a colon where the rest of us +use a slash. Maybe C<sysopen> isn't such a bad idea after all. + +If you want to use C<E<lt>ARGVE<gt>> processing in a totally boring +and non-magical way, you could do this first: + + # "Sam sat on the ground and put his head in his hands. + # 'I wish I had never come here, and I don't want to see + # no more magic,' he said, and fell silent." + for (@ARGV) { + s#^([^./])#./$1#; + $_ .= "\0"; + } + while (<>) { + # now process $_ + } + +But be warned that users will not appreciate being unable to use "-" +to mean standard input, per the standard convention. + +=head2 Paths as Opens + +You've probably noticed how Perl's C<warn> and C<die> functions can +produce messages like: + + Some warning at scriptname line 29, <FH> chunk 7. + +That's because you opened a filehandle FH, and had read in seven records +from it. But what was the name of the file, not the handle? + +If you aren't running with C<strict refs>, or if you've turn them off +temporarily, then all you have to do is this: + + open($path, "< $path") || die "can't open $path: $!"; + while (<$path>) { + # whatever + } + +Since you're using the pathname of the file as its handle, +you'll get warnings more like + + Some warning at scriptname line 29, </etc/motd> chunk 7. + +=head2 Single Argument Open + +Remember how we said that Perl's open took two arguments? That was a +passive prevarication. You see, it can also take just one argument. +If and only if the variable is a global variable, not a lexical, you +can pass C<open> just one argument, the filehandle, and it will +get the path from the global scalar variable of the same name. + + $FILE = "/etc/motd"; + open FILE or die "can't open $FILE: $!"; + while (<FILE>) { + # whatever + } + +Why is this here? Someone has to cater to the hysterical porpoises. +It's something that's been in Perl since the very beginning, if not +before. + +=head2 Playing with STDIN and STDOUT + +One clever move with STDOUT is to explicitly close it when you're done +with the program. + + END { close(STDOUT) || die "can't close stdout: $!" } + +If you don't do this, and your program fills up the disk partition due +to a command line redirection, it won't report the error exit with a +failure status. + +You don't have to accept the STDIN and STDOUT you were given. You are +welcome to reopen them if you'd like. + + open(STDIN, "< datafile") + || die "can't open datafile: $!"; + + open(STDOUT, "> output") + || die "can't open output: $!"; + +And then these can be read directly or passed on to subprocesses. +This makes it look as though the program were initially invoked +with those redirections from the command line. + +It's probably more interesting to connect these to pipes. For example: + + $pager = $ENV{PAGER} || "(less || more)"; + open(STDOUT, "| $pager") + || die "can't fork a pager: $!"; + +This makes it appear as though your program were called with its stdout +already piped into your pager. You can also use this kind of thing +in conjunction with an implicit fork to yourself. You might do this +if you would rather handle the post processing in your own program, +just in a different process: + + head(100); + while (<>) { + print; + } + + sub head { + my $lines = shift || 20; + return unless $pid = open(STDOUT, "|-"); + die "cannot fork: $!" unless defined $pid; + while (<STDIN>) { + print; + last if --$lines < 0; + } + exit; + } + +This technique can be applied to repeatedly push as many filters on your +output stream as you wish. + +=head1 Other I/O Issues + +These topics aren't really arguments related to C<open> or C<sysopen>, +but they do affect what you do with your open files. + +=head2 Opening Non-File Files + +When is a file not a file? Well, you could say when it exists but +isn't a plain file. We'll check whether it's a symbolic link first, +just in case. + + if (-l $file || ! -f _) { + print "$file is not a plain file\n"; + } + +What other kinds of files are there than, well, files? Directories, +symbolic links, named pipes, Unix-domain sockets, and block and character +devices. Those are all files, too--just not I<plain> files. This isn't +the same issue as being a text file. Not all text files are plain files. +Not all plain files are textfiles. That's why there are separate C<-f> +and C<-T> file tests. + +To open a directory, you should use the C<opendir> function, then +process it with C<readdir>, carefully restoring the directory +name if necessary: + + opendir(DIR, $dirname) or die "can't opendir $dirname: $!"; + while (defined($file = readdir(DIR))) { + # do something with "$dirname/$file" + } + closedir(DIR); + +If you want to process directories recursively, it's better to use the +File::Find module. For example, this prints out all files recursively, +add adds a slash to their names if the file is a directory. + + @ARGV = qw(.) unless @ARGV; + use File::Find; + find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV; + +This finds all bogus symbolic links beneath a particular directory: + + find sub { print "$File::Find::name\n" if -l && !-e }, $dir; + +As you see, with symbolic links, you can just pretend that it is +what it points to. Or, if you want to know I<what> it points to, then +C<readlink> is called for: + + if (-l $file) { + if (defined($whither = readlink($file))) { + print "$file points to $whither\n"; + } else { + print "$file points nowhere: $!\n"; + } + } + +Named pipes are a different matter. You pretend they're regular files, +but their opens will normally block until there is both a reader and +a writer. You can read more about them in L<perlipc/"Named Pipes">. +Unix-domain sockets are rather different beasts as well; they're +described in L<perlipc/"Unix-Domain TCP Clients and Servers">. + +When it comes to opening devices, it can be easy and it can tricky. +We'll assume that if you're opening up a block device, you know what +you're doing. The character devices are more interesting. These are +typically used for modems, mice, and some kinds of printers. This is +described in L<perlfaq8/"How do I read and write the serial port?"> +It's often enough to open them carefully: + + sysopen(TTYIN, "/dev/ttyS1", O_RDWR | O_NDELAY | O_NOCTTY) + # (O_NOCTTY no longer needed on POSIX systems) + or die "can't open /dev/ttyS1: $!"; + open(TTYOUT, "+>&TTYIN") + or die "can't dup TTYIN: $!"; + + $ofh = select(TTYOUT); $| = 1; select($ofh); + + print TTYOUT "+++at\015"; + $answer = <TTYIN>; + +With descriptors that you haven't opened using C<sysopen>, such as a +socket, you can set them to be non-blocking using C<fcntl>: + + use Fcntl; + fcntl(Connection, F_SETFL, O_NONBLOCK) + or die "can't set non blocking: $!"; + +Rather than losing yourself in a morass of twisting, turning C<ioctl>s, +all dissimilar, if you're going to manipulate ttys, it's best to +make calls out to the stty(1) program if you have it, or else use the +portable POSIX interface. To figure this all out, you'll need to read the +termios(3) manpage, which describes the POSIX interface to tty devices, +and then L<POSIX>, which describes Perl's interface to POSIX. There are +also some high-level modules on CPAN that can help you with these games. +Check out Term::ReadKey and Term::ReadLine. + +What else can you open? To open a connection using sockets, you won't use +one of Perl's two open functions. See L<perlipc/"Sockets: Client/Server +Communication"> for that. Here's an example. Once you have it, +you can use FH as a bidirectional filehandle. + + use IO::Socket; + local *FH = IO::Socket::INET->new("www.perl.com:80"); + +For opening up a URL, the LWP modules from CPAN are just what +the doctor ordered. There's no filehandle interface, but +it's still easy to get the contents of a document: + + use LWP::Simple; + $doc = get('http://www.sn.no/libwww-perl/'); + +=head2 Binary Files + +On certain legacy systems with what could charitably be called terminally +convoluted (some would say broken) I/O models, a file isn't a file--at +least, not with respect to the C standard I/O library. On these old +systems whose libraries (but not kernels) distinguish between text and +binary streams, to get files to behave properly you'll have to bend over +backwards to avoid nasty problems. On such infelicitous systems, sockets +and pipes are already opened in binary mode, and there is currently no +way to turn that off. With files, you have more options. + +Another option is to use the C<binmode> function on the appropriate +handles before doing regular I/O on them: + + binmode(STDIN); + binmode(STDOUT); + while (<STDIN>) { print } + +Passing C<sysopen> a non-standard flag option will also open the file in +binary mode on those systems that support it. This is the equivalent of +opening the file normally, then calling C<binmode>ing on the handle. + + sysopen(BINDAT, "records.data", O_RDWR | O_BINARY) + || die "can't open records.data: $!"; + +Now you can use C<read> and C<print> on that handle without worrying +about the system non-standard I/O library breaking your data. It's not +a pretty picture, but then, legacy systems seldom are. CP/M will be +with us until the end of days, and after. + +On systems with exotic I/O systems, it turns out that, astonishingly +enough, even unbuffered I/O using C<sysread> and C<syswrite> might do +sneaky data mutilation behind your back. + + while (sysread(WHENCE, $buf, 1024)) { + syswrite(WHITHER, $buf, length($buf)); + } + +Depending on the vicissitudes of your runtime system, even these calls +may need C<binmode> or C<O_BINARY> first. Systems known to be free of +such difficulties include Unix, the Mac OS, Plan9, and Inferno. + +=head2 File Locking + +In a multitasking environment, you may need to be careful not to collide +with other processes who want to do I/O on the same files as others +are working on. You'll often need shared or exclusive locks +on files for reading and writing respectively. You might just +pretend that only exclusive locks exist. + +Never use the existence of a file C<-e $file> as a locking indication, +because there is a race condition between the test for the existence of +the file and its creation. Atomicity is critical. + +Perl's most portable locking interface is via the C<flock> function, +whose simplicity is emulated on systems that don't directly support it, +such as SysV or WindowsNT. The underlying semantics may affect how +it all works, so you should learn how C<flock> is implemented on your +system's port of Perl. + +File locking I<does not> lock out another process that would like to +do I/O. A file lock only locks out others trying to get a lock, not +processes trying to do I/O. Because locks are advisory, if one process +uses locking and another doesn't, all bets are off. + +By default, the C<flock> call will block until a lock is granted. +A request for a shared lock will be granted as soon as there is no +exclusive locker. A request for a exclusive lock will be granted as +soon as there is no locker of any kind. Locks are on file descriptors, +not file names. You can't lock a file until you open it, and you can't +hold on to a lock once the file has been closed. + +Here's how to get a blocking shared lock on a file, typically used +for reading: + + use 5.004; + use Fcntl qw(:DEFAULT :flock); + open(FH, "< filename") or die "can't open filename: $!"; + flock(FH, LOCK_SH) or die "can't lock filename: $!"; + # now read from FH + +You can get a non-blocking lock by using C<LOCK_NB>. + + flock(FH, LOCK_SH | LOCK_NB) + or die "can't lock filename: $!"; + +This can be useful for producing more user-friendly behaviour by warning +if you're going to be blocking: + + use 5.004; + use Fcntl qw(:DEFAULT :flock); + open(FH, "< filename") or die "can't open filename: $!"; + unless (flock(FH, LOCK_SH | LOCK_NB)) { + $| = 1; + print "Waiting for lock..."; + flock(FH, LOCK_SH) or die "can't lock filename: $!"; + print "got it.\n" + } + # now read from FH + +To get an exclusive lock, typically used for writing, you have to be +careful. We C<sysopen> the file so it can be locked before it gets +emptied. You can get a nonblocking version using C<LOCK_EX | LOCK_NB>. + + use 5.004; + use Fcntl qw(:DEFAULT :flock); + sysopen(FH, "filename", O_WRONLY | O_CREAT) + or die "can't open filename: $!"; + flock(FH, LOCK_EX) + or die "can't lock filename: $!"; + truncate(FH, 0) + or die "can't truncate filename: $!"; + # now write to FH + +Finally, due to the uncounted millions who cannot be dissuaded from +wasting cycles on useless vanity devices called hit counters, here's +how to increment a number in a file safely: + + use Fcntl qw(:DEFAULT :flock); + + sysopen(FH, "numfile", O_RDWR | O_CREAT) + or die "can't open numfile: $!"; + # autoflush FH + $ofh = select(FH); $| = 1; select ($ofh); + flock(FH, LOCK_EX) + or die "can't write-lock numfile: $!"; + + $num = <FH> || 0; + seek(FH, 0, 0) + or die "can't rewind numfile : $!"; + print FH $num+1, "\n" + or die "can't write numfile: $!"; + + truncate(FH, tell(FH)) + or die "can't truncate numfile: $!"; + close(FH) + or die "can't close numfile: $!"; + +=head1 SEE ALSO + +The C<open> and C<sysopen> function in perlfunc(1); +the standard open(2), dup(2), fopen(3), and fdopen(3) manpages; +the POSIX documentation. + +=head1 AUTHOR and COPYRIGHT + +Copyright 1998 Tom Christiansen. + +When included as part of the Standard Version of Perl, or as part of +its complete documentation whether printed or otherwise, this work may +be distributed only under the terms of Perl's Artistic License. Any +distribution of this file or derivatives thereof outside of that +package require that special arrangements be made with copyright +holder. + +Irrespective of its distribution, all code examples in these files are +hereby placed into the public domain. You are permitted and +encouraged to use this code in your own programs for fun or for profit +as you see fit. A simple comment in the code giving credit would be +courteous but is not required. + +=head1 HISTORY + +First release: Sat Jan 9 08:09:11 MST 1999 diff --git a/contrib/perl5/pod/perlpod.pod b/contrib/perl5/pod/perlpod.pod index d20d62d..7fa8290 100644 --- a/contrib/perl5/pod/perlpod.pod +++ b/contrib/perl5/pod/perlpod.pod @@ -171,7 +171,8 @@ here and in commands: (the quotes are optional) L</"sec"> ditto same as above but only 'text' is used for output. - (Text can not contain the characters '|' or '>') + (Text can not contain the characters '/' and '|', + and should contain matched '<' or '>') L<text|name> L<text|name/ident> L<text|name/"sec"> @@ -184,6 +185,8 @@ here and in commands: E<escape> A named character (very similar to HTML escapes) E<lt> A literal < E<gt> A literal > + E<sol> A literal / + E<verbar> A literal | (these are optional except in other interior sequences and when preceded by a capital letter) E<n> Character number n (probably in ASCII) diff --git a/contrib/perl5/pod/perlport.pod b/contrib/perl5/pod/perlport.pod index 79ca767..c1a5483 100644 --- a/contrib/perl5/pod/perlport.pod +++ b/contrib/perl5/pod/perlport.pod @@ -84,7 +84,7 @@ should be considered a perpetual work in progress =head2 Newlines -In most operating systems, lines in files are separated with newlines. +In most operating systems, lines in files are terminated by newlines. Just what is used as a newline may vary from OS to OS. Unix traditionally uses C<\012>, one kind of Windows I/O uses C<\015\012>, and S<Mac OS> uses C<\015>. @@ -148,6 +148,13 @@ And this example is actually better than the previous one even for Unix platforms, because now any C<\015>'s (C<\cM>'s) are stripped out (and there was much rejoicing). +An important thing to remember is that functions that return data +should translate newlines when appropriate. Often one line of code +will suffice: + + $data =~ s/\015?\012/\n/g; + return $data; + =head2 Numbers endianness and Width @@ -175,7 +182,7 @@ transfer and store numbers always in text format, instead of raw binary, or consider using modules like C<Data::Dumper> (included in the standard distribution as of Perl 5.005) and C<Storable>. -=head2 Files +=head2 Files and Filesystems Most platforms these days structure files in a hierarchical fashion. So, it is reasonably safe to assume that any platform supports the @@ -183,9 +190,9 @@ notion of a "path" to uniquely identify a file on the system. Just how that path is actually written, differs. While they are similar, file path specifications differ between Unix, -Windows, S<Mac OS>, OS/2, VMS, S<RISC OS> and probably others. Unix, -for example, is one of the few OSes that has the idea of a single root -directory. +Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS> and probably others. +Unix, for example, is one of the few OSes that has the idea of a single +root directory. VMS, Windows, and OS/2 can work similarly to Unix with C</> as path separator, or in their own idiosyncratic ways (such as having several @@ -194,6 +201,18 @@ LPT:). S<Mac OS> uses C<:> as a path separator instead of C</>. +The filesystem may support neither hard links (C<link()>) nor +symbolic links (C<symlink()>, C<readlink()>, C<lstat()>). + +The filesystem may not support neither access timestamp nor change +timestamp (meaning that about the only portable timestamp is the +modification timestamp), or one second granularity of any timestamps +(e.g. the FAT filesystem limits the time granularity to two seconds). + +VOS perl can emulate Unix filenames with C</> as path separator. The +native pathname characters greater-than, less-than, number-sign, and +percent-sign are always accepted. + C<RISC OS> perl can emulate Unix filenames with C</> as path separator, or go native and use C<.> for path separator and C<:> to signal filing systems and disc names. @@ -224,19 +243,21 @@ Also of use is C<File::Basename>, from the standard distribution, which splits a pathname into pieces (base filename, full path to directory, and file suffix). -Even when on a single platform (if you can call UNIX a single -platform), remember not to count on the existence or the contents of -system-specific files, like F</etc/passwd>, F</etc/sendmail.conf>, or -F</etc/resolv.conf>. For example the F</etc/passwd> may exist but it -may not contain the encrypted passwords because the system is using -some form of enhanced security-- or it may not contain all the -accounts because the system is using NIS. If code does need to rely -on such a file, include a description of the file and its format in -the code's documentation, and make it easy for the user to override -the default location of the file. +Even when on a single platform (if you can call UNIX a single platform), +remember not to count on the existence or the contents of +system-specific files or directories, like F</etc/passwd>, +F</etc/sendmail.conf>, F</etc/resolv.conf>, or even F</tmp/>. For +example, F</etc/passwd> may exist but it may not contain the encrypted +passwords because the system is using some form of enhanced security -- +or it may not contain all the accounts because the system is using NIS. +If code does need to rely on such a file, include a description of the +file and its format in the code's documentation, and make it easy for +the user to override the default location of the file. + +Don't assume a text file will end with a newline. Do not have two files of the same name with different case, like -F<test.pl> and <Test.pl>, as many platforms have case-insensitive +F<test.pl> and F<Test.pl>, as many platforms have case-insensitive filenames. Also, try not to have non-word characters (except for C<.>) in the names, and keep them to the 8.3 convention, for maximum portability. @@ -246,11 +267,17 @@ Likewise, if using C<AutoSplit>, try to keep the split functions to make it so the resulting files have a unique (case-insensitively) first 8 characters. -Don't assume C<E<lt>> won't be the first character of a filename. Always -use C<E<gt>> explicitly to open a file for reading: +There certainly can be whitespace in filenames. Many systems (DOS, +VMS) cannot have more than one C<"."> in their filenames. + +Don't assume C<E<gt>> won't be the first character of a filename. +Always use C<E<lt>> explicitly to open a file for reading. open(FILE, "<$existing_file") or die $!; +Actually, though, if filenames might use strange characters, it is +safest to open it with C<sysopen> instead of C<open>, which is magic. + =head2 System Interaction @@ -280,6 +307,8 @@ C<closedir> instead. Don't count on per-program environment variables, or per-program current directories. +Don't count on specific values of C<$!>. + =head2 Interprocess Communication (IPC) @@ -316,6 +345,7 @@ code, but expose a common interface). The UNIX System V IPC (C<msg*(), sem*(), shm*()>) is not available even in all UNIX platforms. + =head2 External Subroutines (XS) XS code, in general, can be made to work with any platform; but dependent @@ -371,7 +401,7 @@ C<Time::Local>. Assume very little about character sets. Do not assume anything about the numerical values (C<ord()>, C<chr()>) of characters. Do not assume that the alphabetic characters are encoded contiguously (in -numerical sense). Do no assume anything about the ordering of the +numerical sense). Do not assume anything about the ordering of the characters. The lowercase letters may come before or after the uppercase letters, the lowercase and uppercase may be interlaced so that both 'a' and 'A' come before the 'b', the accented and other @@ -381,10 +411,10 @@ before the 'b'. =head2 Internationalisation -If you may assume POSIX (a rather large assumption, that: in practise -that means UNIX) you may read more about the POSIX locale system from +If you may assume POSIX (a rather large assumption, that in practice +means UNIX), you may read more about the POSIX locale system from L<perllocale>. The locale system at least attempts to make things a -little bit more portable or at least more convenient and +little bit more portable, or at least more convenient and native-friendly for non-English users. The system affects character sets and encoding, and date and time formatting, among other things. @@ -476,7 +506,7 @@ Unix flavors: FreeBSD freebsd freebsd-i386 Linux linux i386-linux HP-UX hpux PA-RISC1.1 - IRIX irix irix + IRIX irix irix OSF1 dec_osf alpha-dec_osf SunOS solaris sun4-solaris SunOS solaris i86pc-solaris @@ -547,7 +577,8 @@ Also see: =item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/> =item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>, -C<http://www.juge.com/bbs/Hobb.19.html> +C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html> or +C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx> =item Build instructions for Win32, L<perlwin32>. @@ -578,7 +609,7 @@ limited to 31 characters, and may include any character except C<:>, which is reserved as a path separator. Instead of C<flock>, see C<FSpSetFLock> and C<FSpRstFLock> in the -C<Mac::Files> module. +C<Mac::Files> module, or C<chmod(0444, ...)> and C<chmod(0666, ...)>. In the MacPerl application, you can't run a program from the command line; programs that expect C<@ARGV> to be populated can be edited with something @@ -613,10 +644,9 @@ the application or MPW tool version is running, check: $is_ppc = $MacPerl::Architecture eq 'MacPPC'; $is_68k = $MacPerl::Architecture eq 'Mac68K'; -S<Mac OS X>, to be based on NeXT's OpenStep OS, will be able to run -MacPerl natively (in the Blue Box, and even in the Yellow Box, once some -changes to the toolbox calls are made), but Unix perl will also run -natively. +S<Mac OS X>, to be based on NeXT's OpenStep OS, will (in theory) be able +to run MacPerl natively, but Unix perl will also run natively under the +built-in Unix environment. Also see: @@ -727,18 +757,84 @@ Put words C<SUBSCRIBE VMSPERL> in message body. =back +=head2 VOS + +Perl on VOS is discussed in F<README.vos> in the perl distribution. +Note that perl on VOS can accept either VOS- or Unix-style file +specifications as in either of the following: + + $ perl -ne "print if /perl_setup/i" >system>notices + $ perl -ne "print if /perl_setup/i" /system/notices + +or even a mixture of both as in: + + $ perl -ne "print if /perl_setup/i" >system/notices + +Note that even though VOS allows the slash character to appear in object +names, because the VOS port of Perl interprets it as a pathname +delimiting character, VOS files, directories, or links whose names +contain a slash character cannot be processed. Such files must be +renamed before they can be processed by Perl. + +The following C functions are unimplemented on VOS, and any attempt by +Perl to use them will result in a fatal error message and an immediate +exit from Perl: dup, do_aspawn, do_spawn, fork, waitpid. Once these +functions become available in the VOS POSIX.1 implementation, you can +either recompile and rebind Perl, or you can download a newer port from +ftp.stratus.com. + +The value of C<$^O> on VOS is "VOS". To determine the architecture that +you are running on without resorting to loading all of C<%Config> you +can examine the content of the C<@INC> array like so: + + if (grep(/VOS/, @INC)) { + print "I'm on a Stratus box!\n"; + } else { + print "I'm not on a Stratus box!\n"; + die; + } + + if (grep(/860/, @INC)) { + print "This box is a Stratus XA/R!\n"; + } elsif (grep(/7100/, @INC)) { + print "This box is a Stratus HP 7100 or 8000!\n"; + } elsif (grep(/8000/, @INC)) { + print "This box is a Stratus HP 8000!\n"; + } else { + print "This box is a Stratus 68K...\n"; + } + +Also see: + +=over 4 + +=item L<README.vos> + +=item VOS mailing list + +There is no specific mailing list for Perl on VOS. You can post +comments to the comp.sys.stratus newsgroup, or subscribe to the general +Stratus mailing list. Send a letter with "Subscribe Info-Stratus" in +the message body to majordomo@list.stratagy.com. + +=item VOS Perl on the web at C<http://ftp.stratus.com/pub/vos/vos.html> + +=back + + =head2 EBCDIC Platforms Recent versions of Perl have been ported to platforms such as OS/400 on -AS/400 minicomputers as well as OS/390 for IBM Mainframes. Such computers -use EBCDIC character sets internally (usually Character Code Set ID 00819 -for OS/400 and IBM-1047 for OS/390). Note that on the mainframe perl -currently works under the "Unix system services for OS/390" (formerly -known as OpenEdition). +AS/400 minicomputers as well as OS/390 & VM/ESA for IBM Mainframes. Such +computers use EBCDIC character sets internally (usually Character Code +Set ID 00819 for OS/400 and IBM-1047 for OS/390 & VM/ESA). Note that on +the mainframe perl currently works under the "Unix system services +for OS/390" (formerly known as OpenEdition) and VM/ESA OpenEdition. -As of R2.5 of USS for OS/390 that Unix sub-system did not support the -C<#!> shebang trick for script invocation. Hence, on OS/390 perl scripts -can executed with a header similar to the following simple script: +As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix +sub-systems do not support the C<#!> shebang trick for script invocation. +Hence, on OS/390 and VM/ESA perl scripts can be executed with a header +similar to the following simple script: : # use perl eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}' @@ -752,16 +848,18 @@ an effect on what happens with some perl functions (such as C<chr>, C<pack>, C<print>, C<printf>, C<ord>, C<sort>, C<sprintf>, C<unpack>), as well as bit-fiddling with ASCII constants using operators like C<^>, C<&> and C<|>, not to mention dealing with socket interfaces to ASCII computers -(see L<"NEWLINES">). +(see L<Newlines>). Fortunately, most web servers for the mainframe will correctly translate the C<\n> in the following statement to its ASCII equivalent (note that -C<\r> is the same under both Unix and OS/390): +C<\r> is the same under both Unix and OS/390 & VM/ESA): print "Content-type: text/html\r\n\r\n"; The value of C<$^O> on OS/390 is "os390". +The value of C<$^O> on VM/ESA is "vmesa". + Some simple tricks for determining if you are running on an EBCDIC platform could include any of the following (perhaps all): @@ -834,7 +932,7 @@ C<System$Path> contains a single item list. The filesystem will also expand system variables in filenames if enclosed in angle brackets, so C<E<lt>System$DirE<gt>.Modules> would look for the file S<C<$ENV{'System$Dir'} . 'Modules'>>. The obvious implication of this is -that B<fully qualified filenames can start with C<E<lt>E<gt>> and should +that B<fully qualified filenames can start with C<E<lt>E<gt>>> and should be protected when C<open> is used for input. Because C<.> was in use as a directory separator and filenames could not @@ -1013,9 +1111,11 @@ bits are meaningless. (Win32) Only good for changing "owner" and "other" read-write access. (S<RISC OS>) +Access permissions are mapped onto VOS access-control list changes. (VOS) + =item chown LIST -Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>, VOS) Does nothing, but won't fail. (Win32) @@ -1023,20 +1123,22 @@ Does nothing, but won't fail. (Win32) =item chroot -Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS, VM/ESA) =item crypt PLAINTEXT,SALT May not be available if library or source was not provided when building perl. (Win32) +Not implemented. (VOS) + =item dbmclose HASH -Not implemented. (VMS, Plan9) +Not implemented. (VMS, Plan9, VOS) =item dbmopen HASH,DBNAME,MODE -Not implemented. (VMS, Plan9) +Not implemented. (VMS, Plan9, VOS) =item dump LABEL @@ -1050,19 +1152,21 @@ Invokes VMS debugger. (VMS) Not implemented. (S<Mac OS>) +Implemented via Spawn. (VM/ESA) + =item fcntl FILEHANDLE,FUNCTION,SCALAR Not implemented. (Win32, VMS) =item flock FILEHANDLE,OPERATION -Not implemented (S<Mac OS>, VMS, S<RISC OS>). +Not implemented (S<Mac OS>, VMS, S<RISC OS>, VOS). Available only on Windows NT (not on Windows 95). (Win32) =item fork -Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, AmigaOS, S<RISC OS>, VOS, VM/ESA) =item getlogin @@ -1070,7 +1174,7 @@ Not implemented. (S<Mac OS>, S<RISC OS>) =item getpgrp PID -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS) =item getppid @@ -1078,7 +1182,7 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) =item getpriority WHICH,WHO -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA) =item getpwnam NAME @@ -1118,11 +1222,11 @@ Not implemented. (S<Mac OS>) =item getpwent -Not implemented. (S<Mac OS>, Win32) +Not implemented. (S<Mac OS>, Win32, VM/ESA) =item getgrent -Not implemented. (S<Mac OS>, Win32, VMS) +Not implemented. (S<Mac OS>, Win32, VMS, VM/ESA) =item gethostent @@ -1166,11 +1270,11 @@ Not implemented. (Plan9, Win32, S<RISC OS>) =item endpwent -Not implemented. (S<Mac OS>, Win32) +Not implemented. (S<Mac OS>, Win32, VM/ESA) =item endgrent -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VM/ESA) =item endhostent @@ -1229,6 +1333,9 @@ method of spawning a process. (Win32) Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Link count not updated because hard links are not quite that hard +(They are sort of half-way between hard and soft links). (AmigaOS) + =item lstat FILEHANDLE =item lstat EXPR @@ -1247,7 +1354,7 @@ Return values may be bogus. (Win32) =item msgrcv ID,VAR,SIZE,TYPE,FLAGS -Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, Plan9, S<RISC OS>, VOS) =item open FILEHANDLE,EXPR @@ -1262,6 +1369,8 @@ open to C<|-> and C<-|> are unsupported. (S<Mac OS>, Win32, S<RISC OS>) Not implemented. (S<Mac OS>) +Very limited functionality. (MiNT) + =item readlink EXPR =item readlink @@ -1280,15 +1389,15 @@ Only reliable on sockets. (S<RISC OS>) =item semop KEY,OPSTRING -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS) =item setpgrp PID,PGRP -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS) =item setpriority WHICH,WHO,PRIORITY -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS) =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL @@ -1302,11 +1411,11 @@ Not implemented. (S<Mac OS>, Plan9) =item shmwrite ID,STRING,POS,SIZE -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS) =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA) =item stat FILEHANDLE @@ -1330,14 +1439,14 @@ Not implemented. (Win32, VMS, S<RISC OS>) =item syscall LIST -Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>) +Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA) =item sysopen FILEHANDLE,FILENAME,MODE,PERMS The traditional "0", "1", and "2" MODEs are implemented with different numeric values on some systems. The flags exported by C<Fcntl> (O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac -OS>, OS/390) +OS>, OS/390, VM/ESA) =item system LIST @@ -1359,6 +1468,11 @@ the child program uses a compatible version of the emulation library. I<scalar> will call the native command line direct and no such emulation of a child Unix program will exists. Mileage B<will> vary. (S<RISC OS>) +Far from being POSIX compliant. Because there may be no underlying +/bin/sh tries to work around the problem by forking and execing the +first token in its argument string. Handles basic redirection +("E<lt>" or "E<gt>") on its own behalf. (MiNT) + =item times Only the first entry returned is nonzero. (S<Mac OS>) @@ -1375,12 +1489,22 @@ Not useful. (S<RISC OS>) Not implemented. (VMS) +Truncation to zero-length only. (VOS) + +If a FILEHANDLE is supplied, it must be writable and opened in append +mode (i.e., use C<open(FH, '>>filename')> +or C<sysopen(FH,...,O_APPEND|O_RDWR)>. If a filename is supplied, it +should not be held open elsewhere. (Win32) + =item umask EXPR =item umask Returns undef where unavailable, as of version 5.005. +C<umask()> works but the correct permissions are only set when the file +is finally close()d. (AmigaOS) + =item utime LIST Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>) @@ -1395,7 +1519,7 @@ two seconds. (Win32) =item waitpid PID,FLAGS -Not implemented. (S<Mac OS>) +Not implemented. (S<Mac OS>, VOS) Can only be applied to process handles returned for processes spawned using C<system(1, ...)>. (Win32) @@ -1408,19 +1532,43 @@ Not useful. (S<RISC OS>) =over 4 -=item 1.33, 06 August 1998 +=item v1.39, 11 February, 1999 + +Changes from Jarkko and EMX URL fixes Michael Schwern. Additional +note about newlines added. + +=item v1.38, 31 December 1998 + +More changes from Jarkko. + +=item v1.37, 19 December 1998 + +More minor changes. Merge two separate version 1.35 documents. + +=item v1.36, 9 September 1998 + +Updated for Stratus VOS. Also known as version 1.35. + +=item v1.35, 13 August 1998 + +Integrate more minor changes, plus addition of new sections under +L<"ISSUES">: L<"Numbers endianness and Width">, +L<"Character sets and character encoding">, +L<"Internationalisation">. + +=item v1.33, 06 August 1998 Integrate more minor changes. -=item 1.32, 05 August 1998 +=item v1.32, 05 August 1998 Integrate more minor changes. -=item 1.30, 03 August 1998 +=item v1.30, 03 August 1998 Major update for RISC OS, other minor changes. -=item 1.23, 10 July 1998 +=item v1.23, 10 July 1998 First public release with perl5.005. @@ -1429,16 +1577,20 @@ First public release with perl5.005. =head1 AUTHORS / CONTRIBUTORS Abigail E<lt>abigail@fnx.comE<gt>, -Charles Bailey E<lt>bailey@genetics.upenn.eduE<gt>, +Charles Bailey E<lt>bailey@newman.upenn.eduE<gt>, Graham Barr E<lt>gbarr@pobox.comE<gt>, Tom Christiansen E<lt>tchrist@perl.comE<gt>, Nicholas Clark E<lt>Nicholas.Clark@liverpool.ac.ukE<gt>, Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>, Dominic Dunlop E<lt>domo@vo.luE<gt>, +Neale Ferguson E<lt>neale@mailbox.tabnsw.com.auE<gt> +Paul Green E<lt>Paul_Green@stratus.comE<gt>, M.J.T. Guy E<lt>mjtg@cus.cam.ac.ukE<gt>, +Jarkko Hietaniemi E<lt>jhi@iki.fi<gt>, Luther Huffman E<lt>lutherh@stratcom.comE<gt>, Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>, Andreas J. KE<ouml>nig E<lt>koenig@kulturbox.deE<gt>, +Markus Laker E<lt>mlaker@contax.co.ukE<gt>, Andrew M. Langmead E<lt>aml@world.std.comE<gt>, Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>, Chris Nandor E<lt>pudge@pobox.comE<gt>, @@ -1449,13 +1601,13 @@ Peter Prymmer E<lt>pvhp@forte.comE<gt>, Hugo van der Sanden E<lt>hv@crypt0.demon.co.ukE<gt>, Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>, Paul J. Schinder E<lt>schinder@pobox.comE<gt>, +Michael G Schwern E<lt>schwern@pobox.comE<gt>, Dan Sugalski E<lt>sugalskd@ous.eduE<gt>, Nathan Torkington E<lt>gnat@frii.comE<gt>. -This document is maintained by Chris Nandor. +This document is maintained by Chris Nandor +E<lt>pudge@pobox.comE<gt>. =head1 VERSION -Version 1.34, last modified 07 August 1998. - - +Version 1.39, last modified 11 February 1999 diff --git a/contrib/perl5/pod/perlre.pod b/contrib/perl5/pod/perlre.pod index 382ba65..d4c1dee 100644 --- a/contrib/perl5/pod/perlre.pod +++ b/contrib/perl5/pod/perlre.pod @@ -116,7 +116,11 @@ The following standard quantifiers are recognized: (If a curly bracket occurs in any other context, it is treated as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+" modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited -to integral values less than 65536. +to integral values less than a preset limit defined when perl is built. +This is usually 32766 on the most common platforms. The actual limit can +be seen in the error message generated by code such as this: + + $_ **= $_ , / {$_} / for 2 .. 42; By default, a quantified subpattern is "greedy", that is, it will match as many times as possible (given a particular starting location) while still @@ -458,7 +462,7 @@ the time when used on a similar string with 1000000 C<a>s. Be aware, however, that this pattern currently triggers a warning message under B<-w> saying it C<"matches the null string many times">): -On simple groups, such as the pattern C<(?> [^()]+ )>, a comparable +On simple groups, such as the pattern C<(?E<gt> [^()]+ )>, a comparable effect may be achieved by negative lookahead, as in C<[^()]+ (?! [^()] )>. This was only 4 times slower on a string with 1000000 C<a>s. @@ -730,6 +734,13 @@ following all specify the same class of three characters: C<[-az]>, C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which specifies a class containing twenty-six characters.) +Note also that the whole range idea is rather unportable between +character sets--and even within character sets they may cause results +you probably didn't expect. A sound principle is to use only ranges +that begin from and end at either alphabets of equal case ([a-e], +[A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt, +spell out the character sets in full. + Characters may be specified using a metacharacter syntax much like that used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return, "\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string @@ -752,7 +763,7 @@ start and end. Alternatives are tried from left to right, so the first alternative found for which the entire expression matches, is the one that is chosen. This means that alternatives are not necessarily greedy. For -example: when mathing C<foo|foot> against "barefoot", only the "foo" +example: when matching C<foo|foot> against "barefoot", only the "foo" part will match, as that is the first alternative tried, and it successfully matches the target string. (This might not seem important, but it is important when you are capturing matched text using parentheses.) @@ -805,7 +816,7 @@ with most other power tools, power comes together with the ability to wreak havoc. A common abuse of this power stems from the ability to make infinite -loops using regular expressions, with something as innocous as: +loops using regular expressions, with something as innocuous as: 'foo' =~ m{ ( o? )* }x; diff --git a/contrib/perl5/pod/perlref.pod b/contrib/perl5/pod/perlref.pod index 66b1a7d..596ff72 100644 --- a/contrib/perl5/pod/perlref.pod +++ b/contrib/perl5/pod/perlref.pod @@ -2,6 +2,12 @@ perlref - Perl references and nested data structures +=head1 NOTE + +This is complete documentation about all aspects of references. +For a shorter, tutorial introduction to just the essential features, +see L<perlreftut>. + =head1 DESCRIPTION Before release 5 of Perl it was difficult to represent complex data @@ -89,7 +95,9 @@ a list of references! @list = \($a, @b, %c); # same thing! As a special case, C<\(@foo)> returns a list of references to the contents -of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>. +of C<@foo>, not a reference to C<@foo> itself. Likewise for C<%foo>, +except that the key references are to copies (since the keys are just +strings rather than full-fledged scalars). =item 3. @@ -448,7 +456,7 @@ symbolic references. Lexical variables (declared with my()) aren't in a symbol table, and thus are invisible to this mechanism. For example: local $value = 10; - $ref = \$value; + $ref = "value"; { my $value = 20; print $$ref; @@ -551,7 +559,7 @@ access to those variables even though it doesn't get run until later, such as in a signal handler or a Tk callback. Using a closure as a function template allows us to generate many functions -that act similarly. Suppopose you wanted functions named after the colors +that act similarly. Suppose you wanted functions named after the colors that generated HTML font changes for the various colors: print "Be ", red("careful"), "with that ", green("light"); diff --git a/contrib/perl5/pod/perlreftut.pod b/contrib/perl5/pod/perlreftut.pod new file mode 100644 index 0000000..09bea59 --- /dev/null +++ b/contrib/perl5/pod/perlreftut.pod @@ -0,0 +1,416 @@ + +=head1 NAME + +perlreftut - Mark's very short tutorial about references + +=head1 DESCRIPTION + +One of the most important new features in Perl 5 was the capability to +manage complicated data structures like multidimensional arrays and +nested hashes. To enable these, Perl 5 introduced a feature called +`references', and using references is the key to managing complicated, +structured data in Perl. Unfortunately, there's a lot of funny syntax +to learn, and the main manual page can be hard to follow. The manual +is quite complete, and sometimes people find that a problem, because +it can be hard to tell what is important and what isn't. + +Fortunately, you only need to know 10% of what's in the main page to get +90% of the benefit. This page will show you that 10%. + +=head1 Who Needs Complicated Data Structures? + +One problem that came up all the time in Perl 4 was how to represent a +hash whose values were lists. Perl 4 had hashes, of course, but the +values had to be scalars; they couldn't be lists. + +Why would you want a hash of lists? Let's take a simple example: You +have a file of city and country names, like this: + + Chicago, USA + Frankfurt, Germany + Berlin, Germany + Washington, USA + Helsinki, Finland + New York, USA + +and you want to produce an output like this, with each country mentioned +once, and then an alphabetical list of the cities in that country: + + Finland: Helsinki. + Germany: Berlin, Frankfurt. + USA: Chicago, New York, Washington. + +The natural way to do this is to have a hash whose keys are country +names. Associated with each country name key is a list of the cities in +that country. Each time you read a line of input, split it into a country +and a city, look up the list of cities already known to be in that +country, and append the new city to the list. When you're done reading +the input, iterate over the hash as usual, sorting each list of cities +before you print it out. + +If hash values can't be lists, you lose. In Perl 4, hash values can't +be lists; they can only be strings. You lose. You'd probably have to +combine all the cities into a single string somehow, and then when +time came to write the output, you'd have to break the string into a +list, sort the list, and turn it back into a string. This is messy +and error-prone. And it's frustrating, because Perl already has +perfectly good lists that would solve the problem if only you could +use them. + +=head1 The Solution + +By the time Perl 5 rolled around, we were already stuck with this +design: Hash values must be scalars. The solution to this is +references. + +A reference is a scalar value that I<refers to> an entire array or an +entire hash (or to just about anything else). Names are one kind of +reference that you're already familiar with. Think of the President: +a messy, inconvenient bag of blood and bones. But to talk about him, +or to represent him in a computer program, all you need is the easy, +convenient scalar string "Bill Clinton". + +References in Perl are like names for arrays and hashes. They're +Perl's private, internal names, so you can be sure they're +unambiguous. Unlike "Bill Clinton", a reference only refers to one +thing, and you always know what it refers to. If you have a reference +to an array, you can recover the entire array from it. If you have a +reference to a hash, you can recover the entire hash. But the +reference is still an easy, compact scalar value. + +You can't have a hash whose values are arrays; hash values can only be +scalars. We're stuck with that. But a single reference can refer to +an entire array, and references are scalars, so you can have a hash of +references to arrays, and it'll act a lot like a hash of arrays, and +it'll be just as useful as a hash of arrays. + +We'll come back to this city-country problem later, after we've seen +some syntax for managing references. + + +=head1 Syntax + +There are just two ways to make a reference, and just two ways to use +it once you have it. + +=head2 Making References + +B<Make Rule 1> + +If you put a C<\> in front of a variable, you get a +reference to that variable. + + $aref = \@array; # $aref now holds a reference to @array + $href = \%hash; # $href now holds a reference to %hash + +Once the reference is stored in a variable like $aref or $href, you +can copy it or store it just the same as any other scalar value: + + $xy = $aref; # $xy now holds a reference to @array + $p[3] = $href; # $p[3] now holds a reference to %hash + $z = $p[3]; # $z now holds a reference to %hash + + +These examples show how to make references to variables with names. +Sometimes you want to make an array or a hash that doesn't have a +name. This is analogous to the way you like to be able to use the +string C<"\n"> or the number 80 without having to store it in a named +variable first. + +B<Make Rule 2> + +C<[ ITEMS ]> makes a new, anonymous array, and returns a reference to +that array. C<{ ITEMS }> makes a new, anonymous hash. and returns a +reference to that hash. + + $aref = [ 1, "foo", undef, 13 ]; + # $aref now holds a reference to an array + + $href = { APR => 4, AUG => 8 }; + # $href now holds a reference to a hash + + +The references you get from rule 2 are the same kind of +references that you get from rule 1: + + # This: + $aref = [ 1, 2, 3 ]; + + # Does the same as this: + @array = (1, 2, 3); + $aref = \@array; + + +The first line is an abbreviation for the following two lines, except +that it doesn't create the superfluous array variable C<@array>. + + +=head2 Using References + +What can you do with a reference once you have it? It's a scalar +value, and we've seen that you can store it as a scalar and get it back +again just like any scalar. There are just two more ways to use it: + +B<Use Rule 1> + +If C<$aref> contains a reference to an array, then you +can put C<{$aref}> anywhere you would normally put the name of an +array. For example, C<@{$aref}> instead of C<@array>. + +Here are some examples of that: + +Arrays: + + + @a @{$aref} An array + reverse @a reverse @{$aref} Reverse the array + $a[3] ${$aref}[3] An element of the array + $a[3] = 17; ${$aref}[3] = 17 Assigning an element + + +On each line are two expressions that do the same thing. The +left-hand versions operate on the array C<@a>, and the right-hand +versions operate on the array that is referred to by C<$aref>, but +once they find the array they're operating on, they do the same things +to the arrays. + +Using a hash reference is I<exactly> the same: + + %h %{$href} A hash + keys %h keys %{$href} Get the keys from the hash + $h{'red'} ${$href}{'red'} An element of the hash + $h{'red'} = 17 ${$href}{'red'} = 17 Assigning an element + + +B<Use Rule 2> + +C<${$aref}[3]> is too hard to read, so you can write C<$aref-E<gt>[3]> +instead. + +C<${$href}{red}> is too hard to read, so you can write +C<$href-E<gt>{red}> instead. + +Most often, when you have an array or a hash, you want to get or set a +single element from it. C<${$aref}[3]> and C<${$href}{'red'}> have +too much punctuation, and Perl lets you abbreviate. + +If C<$aref> holds a reference to an array, then C<$aref-E<gt>[3]> is +the fourth element of the array. Don't confuse this with C<$aref[3]>, +which is the fourth element of a totally different array, one +deceptively named C<@aref>. C<$aref> and C<@aref> are unrelated the +same way that C<$item> and C<@item> are. + +Similarly, C<$href-E<gt>{'red'}> is part of the hash referred to by +the scalar variable C<$href>, perhaps even one with no name. +C<$href{'red'}> is part of the deceptively named C<%href> hash. It's +easy to forget to leave out the C<-E<gt>>, and if you do, you'll get +bizarre results when your program gets array and hash elements out of +totally unexpected hashes and arrays that weren't the ones you wanted +to use. + + +=head1 An Example + +Let's see a quick example of how all this is useful. + +First, remember that C<[1, 2, 3]> makes an anonymous array containing +C<(1, 2, 3)>, and gives you a reference to that array. + +Now think about + + @a = ( [1, 2, 3], + [4, 5, 6], + [7, 8, 9] + ); + +@a is an array with three elements, and each one is a reference to +another array. + +C<$a[1]> is one of these references. It refers to an array, the array +containing C<(4, 5, 6)>, and because it is a reference to an array, +B<USE RULE 2> says that we can write C<$a[1]-E<gt>[2]> to get the +third element from that array. C<$a[1]-E<gt>[2]> is the 6. +Similarly, C<$a[0]-E<gt>[1]> is the 2. What we have here is like a +two-dimensional array; you can write C<$a[ROW]-E<gt>[COLUMN]> to get +or set the element in any row and any column of the array. + +The notation still looks a little cumbersome, so there's one more +abbreviation: + +=head1 Arrow Rule + +In between two B<subscripts>, the arrow is optional. + +Instead of C<$a[1]-E<gt>[2]>, we can write C<$a[1][2]>; it means the +same thing. Instead of C<$a[0]-E<gt>[1]>, we can write C<$a[0][1]>; +it means the same thing. + +Now it really looks like two-dimensional arrays! + +You can see why the arrows are important. Without them, we would have +had to write C<${$a[1]}[2]> instead of C<$a[1][2]>. For +three-dimensional arrays, they let us write C<$x[2][3][5]> instead of +the unreadable C<${${$x[2]}[3]}[5]>. + + +=head1 Solution + +Here's the answer to the problem I posed earlier, of reformatting a +file of city and country names. + + 1 while (<>) { + 2 chomp; + 3 my ($city, $country) = split /, /; + 4 push @{$table{$country}}, $city; + 5 } + 6 + 7 foreach $country (sort keys %table) { + 8 print "$country: "; + 9 my @cities = @{$table{$country}}; + 10 print join ', ', sort @cities; + 11 print ".\n"; + 12 } + + +The program has two pieces: Lines 1--5 read the input and build a +data structure, and lines 7--12 analyze the data and print out the +report. + +In the first part, line 4 is the important one. We're going to have a +hash, C<%table>, whose keys are country names, and whose values are +(references to) arrays of city names. After acquiring a city and +country name, the program looks up C<$table{$country}>, which holds (a +reference to) the list of cities seen in that country so far. Line 4 is +totally analogous to + + push @array, $city; + +except that the name C<array> has been replaced by the reference +C<{$table{$country}}>. The C<push> adds a city name to the end of the +referred-to array. + +In the second part, line 9 is the important one. Again, +C<$table{$country}> is (a reference to) the list of cities in the country, so +we can recover the original list, and copy it into the array C<@cities>, +by using C<@{$table{$country}}>. Line 9 is totally analogous to + + @cities = @array; + +except that the name C<array> has been replaced by the reference +C<{$table{$country}}>. The C<@> tells Perl to get the entire array. + +The rest of the program is just familiar uses of C<chomp>, C<split>, C<sort>, +C<print>, and doesn't involve references at all. + +There's one fine point I skipped. Suppose the program has just read +the first line in its input that happens to mention Greece. +Control is at line 4, C<$country> is C<'Greece'>, and C<$city> is +C<'Athens'>. Since this is the first city in Greece, +C<$table{$country}> is undefined---in fact there isn't an C<'Greece'> key +in C<%table> at all. What does line 4 do here? + + 4 push @{$table{$country}}, $city; + + +This is Perl, so it does the exact right thing. It sees that you want +to push C<Athens> onto an array that doesn't exist, so it helpfully +makes a new, empty, anonymous array for you, installs it in the table, +and then pushes C<Athens> onto it. This is called `autovivification'. + + +=head1 The Rest + +I promised to give you 90% of the benefit with 10% of the details, and +that means I left out 90% of the details. Now that you have an +overview of the important parts, it should be easier to read the +L<perlref> manual page, which discusses 100% of the details. + +Some of the highlights of L<perlref>: + +=over 4 + +=item * + +You can make references to anything, including scalars, functions, and +other references. + +=item * + +In B<USE RULE 1>, you can omit the curly brackets whenever the thing +inside them is an atomic scalar variable like C<$aref>. For example, +C<@$aref> is the same as C<@{$aref}>, and C<$$aref[1]> is the same as +C<${$aref}[1]>. If you're just starting out, you may want to adopt +the habit of always including the curly brackets. + +=item * + +To see if a variable contains a reference, use the `ref' function. +It returns true if its argument is a reference. Actually it's a +little better than that: It returns HASH for hash references and +ARRAY for array references. + +=item * + +If you try to use a reference like a string, you get strings like + + ARRAY(0x80f5dec) or HASH(0x826afc0) + +If you ever see a string that looks like this, you'll know you +printed out a reference by mistake. + +A side effect of this representation is that you can use C<eq> to see +if two references refer to the same thing. (But you should usually use +C<==> instead because it's much faster.) + +=item * + +You can use a string as if it were a reference. If you use the string +C<"foo"> as an array reference, it's taken to be a reference to the +array C<@foo>. This is called a I<soft reference> or I<symbolic reference>. + +=back + +You might prefer to go on to L<perllol> instead of L<perlref>; it +discusses lists of lists and multidimensional arrays in detail. After +that, you should move on to L<perldsc>; it's a Data Structure Cookbook +that shows recipes for using and printing out arrays of hashes, hashes +of arrays, and other kinds of data. + +=head1 Summary + +Everyone needs compound data structures, and in Perl the way you get +them is with references. There are four important rules for managing +references: Two for making references and two for using them. Once +you know these rules you can do most of the important things you need +to do with references. + +=head1 Credits + +Author: Mark-Jason Dominus, Plover Systems (C<mjd-perl-ref@plover.com>) + +This article originally appeared in I<The Perl Journal> +(http://tpj.com) volume 3, #2. Reprinted with permission. + +The original title was I<Understand References Today>. + +=head2 Distribution Conditions + +Copyright 1998 The Perl Journal. + +When included as part of the Standard Version of Perl, or as part of +its complete documentation whether printed or otherwise, this work may +be distributed only under the terms of Perl's Artistic License. Any +distribution of this file or derivatives thereof outside of that +package require that special arrangements be made with copyright +holder. + +Irrespective of its distribution, all code examples in these files are +hereby placed into the public domain. You are permitted and +encouraged to use this code in your own programs for fun or for profit +as you see fit. A simple comment in the code giving credit would be +courteous but is not required. + + + + +=cut diff --git a/contrib/perl5/pod/perlrun.pod b/contrib/perl5/pod/perlrun.pod index a0c85b9..7cb9aed 100644 --- a/contrib/perl5/pod/perlrun.pod +++ b/contrib/perl5/pod/perlrun.pod @@ -129,6 +129,21 @@ and a Perl library file. Macintosh perl scripts will have the appropriate Creator and Type, so that double-clicking them will invoke the perl application. +=item VMS + +Put + + $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' ! + $ exit++ + ++$status != 0 and $exit = $status = undef; + +at the top of your script, where C<-mysw> are any command line switches you +want to pass to Perl. You can now invoke the script directly, by saying +C<perl script>, or as a DCL procedure, by saying C<@script> (or implicitly +via F<DCL$PATH> by just using the name of the script). + +This incantation is a bit much to remember, but Perl will display it for +you if you say C<perl "-V:startperl">. + =back Command-interpreters on non-Unix systems have rather different ideas @@ -492,7 +507,7 @@ makes it iterate over filename arguments somewhat like B<sed>: If a file named by an argument cannot be opened for some reason, Perl warns you about it, and moves on to the next file. Note that the -lines are printed automatically. An error occuring during printing is +lines are printed automatically. An error occurring during printing is treated as fatal. To suppress printing use the B<-n> switch. A B<-p> overrides a B<-n> switch. @@ -671,7 +686,8 @@ Command-line options (switches). Switches in this variable are taken as if they were on every Perl command line. Only the B<-[DIMUdmw]> switches are allowed. When running taint checks (because the script was running setuid or setgid, or the B<-T> switch was used), this -variable is ignored. +variable is ignored. If PERL5OPT begins with B<-T>, tainting will be +enabled, and any subsequent options ignored. =item PERLLIB diff --git a/contrib/perl5/pod/perlstyle.pod b/contrib/perl5/pod/perlstyle.pod index cf280ce..04aab98 100644 --- a/contrib/perl5/pod/perlstyle.pod +++ b/contrib/perl5/pod/perlstyle.pod @@ -16,7 +16,7 @@ The C<use sigtrap> and even C<use diagnostics> pragmas may also prove useful. Regarding aesthetics of code lay out, about the only thing Larry -cares strongly about is that the closing curly brace of +cares strongly about is that the closing curly bracket of a multi-line BLOCK should line up with the keyword that started the construct. Beyond that, he has other preferences that aren't so strong: diff --git a/contrib/perl5/pod/perlsub.pod b/contrib/perl5/pod/perlsub.pod index 957b3d8..bfab0fe 100644 --- a/contrib/perl5/pod/perlsub.pod +++ b/contrib/perl5/pod/perlsub.pod @@ -199,7 +199,7 @@ pre-defined things are C<BEGIN>, C<END>, C<AUTOLOAD>, and C<DESTROY>--plus all t functions mentioned in L<perltie>. The 5.005 release adds C<INIT> to this list. -=head2 Private Variables via C<my()> +=head2 Private Variables via my() Synopsis: @@ -381,7 +381,7 @@ unqualified and unqualifiable. This does not work with object methods, however; all object methods have to be in the symbol table of some package to be found. -=head2 Peristent Private Variables +=head2 Persistent Private Variables Just because a lexical variable is lexically (also called statically) scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that @@ -581,6 +581,28 @@ Perl will print This is a test only a test. The array has 6 elements: 0, 1, 2, undef, undef, 5 +Note also that when you C<local>ize a member of a composite type that +B<does not exist previously>, the value is treated as though it were +in an lvalue context, i.e., it is first created and then C<local>ized. +The consequence of this is that the hash or array is in fact permanently +modified. For instance, if you say + + %hash = ( 'This' => 'is', 'a' => 'test' ); + @ary = ( 0..5 ); + { + local($ary[8]) = 0; + local($hash{'b'}) = 'whatever'; + } + printf "%%hash has now %d keys, \@ary %d elements.\n", + scalar(keys(%hash)), scalar(@ary); + +Perl will print + + %hash has now 3 keys, @ary 9 elements. + +The above behavior of local() on non-existent members of composite +types is subject to change in future. + =head2 Passing Symbol Table Entries (typeglobs) [Note: The mechanism described in this section was originally the only @@ -825,7 +847,8 @@ if you call it like a builtin function, then it behaves like a builtin function. If you call it like an old-fashioned subroutine, then it behaves like an old-fashioned subroutine. It naturally falls out from this rule that prototypes have no influence on subroutine references -like C<\&foo> or on indirect subroutine calls like C<&{$subref}>. +like C<\&foo> or on indirect subroutine calls like C<&{$subref}> or +C<$subref-E<gt>()>. Method calls are not influenced by prototypes either, because the function to be called is indeterminate at compile time, because it depends @@ -863,8 +886,10 @@ unbackslashed C<@> or C<%> eats all the rest of the arguments, and forces list context. An argument represented by C<$> forces scalar context. An C<&> requires an anonymous subroutine, which, if passed as the first argument, does not require the "C<sub>" keyword or a subsequent comma. A -C<*> does whatever it has to do to turn the argument into a reference to a -symbol table entry. +C<*> allows the subroutine to accept a bareword, constant, scalar expression, +typeglob, or a reference to a typeglob in that slot. The value will be +available to the subroutine either as a simple scalar, or (in the latter +two cases) as a reference to the typeglob. A semicolon separates mandatory arguments from optional arguments. (It is redundant before C<@> or C<%>.) diff --git a/contrib/perl5/pod/perlsyn.pod b/contrib/perl5/pod/perlsyn.pod index 8321235..a3bc5ab 100644 --- a/contrib/perl5/pod/perlsyn.pod +++ b/contrib/perl5/pod/perlsyn.pod @@ -21,13 +21,13 @@ mandatory default like it is in B<sed> and B<awk>.) =head2 Declarations -Perl is, for the most part, a free-form language. (The only -exception to this is format declarations, for obvious reasons.) Comments -are indicated by the C<"#"> character, and extend to the end of the line. If -you attempt to use C</* */> C-style comments, it will be interpreted -either as division or pattern matching, depending on the context, and C++ -C<//> comments just look like a null regular expression, so don't do -that. +Perl is, for the most part, a free-form language. (The only exception +to this is format declarations, for obvious reasons.) Text from a +C<"#"> character until the end of the line is a comment, and is +ignored. If you attempt to use C</* */> C-style comments, it will be +interpreted either as division or pattern matching, depending on the +context, and C++ C<//> comments just look like a null regular +expression, so don't do that. A declaration can be put anywhere a statement can, but has no effect on the execution of the primary sequence of statements--declarations all diff --git a/contrib/perl5/pod/perlthrtut.pod b/contrib/perl5/pod/perlthrtut.pod new file mode 100644 index 0000000..f2ca3bd --- /dev/null +++ b/contrib/perl5/pod/perlthrtut.pod @@ -0,0 +1,1063 @@ +=head1 NAME + +perlthrtut - tutorial on threads in Perl + +=head1 DESCRIPTION + +One of the most prominent new features of Perl 5.005 is the inclusion +of threads. Threads make a number of things a lot easier, and are a +very useful addition to your bag of programming tricks. + +=head1 What Is A Thread Anyway? + +A thread is a flow of control through a program with a single +execution point. + +Sounds an awful lot like a process, doesn't it? Well, it should. +Threads are one of the pieces of a process. Every process has at least +one thread and, up until now, every process running Perl had only one +thread. With 5.005, though, you can create extra threads. We're going +to show you how, when, and why. + +=head1 Threaded Program Models + +There are three basic ways that you can structure a threaded +program. Which model you choose depends on what you need your program +to do. For many non-trivial threaded programs you'll need to choose +different models for different pieces of your program. + +=head2 Boss/Worker + +The boss/worker model usually has one `boss' thread and one or more +`worker' threads. The boss thread gathers or generates tasks that need +to be done, then parcels those tasks out to the appropriate worker +thread. + +This model is common in GUI and server programs, where a main thread +waits for some event and then passes that event to the appropriate +worker threads for processing. Once the event has been passed on, the +boss thread goes back to waiting for another event. + +The boss thread does relatively little work. While tasks aren't +necessarily performed faster than with any other method, it tends to +have the best user-response times. + +=head2 Work Crew + +In the work crew model, several threads are created that do +essentially the same thing to different pieces of data. It closely +mirrors classical parallel processing and vector processors, where a +large array of processors do the exact same thing to many pieces of +data. + +This model is particularly useful if the system running the program +will distribute multiple threads across different processors. It can +also be useful in ray tracing or rendering engines, where the +individual threads can pass on interim results to give the user visual +feedback. + +=head2 Pipeline + +The pipeline model divides up a task into a series of steps, and +passes the results of one step on to the thread processing the +next. Each thread does one thing to each piece of data and passes the +results to the next thread in line. + +This model makes the most sense if you have multiple processors so two +or more threads will be executing in parallel, though it can often +make sense in other contexts as well. It tends to keep the individual +tasks small and simple, as well as allowing some parts of the pipeline +to block (on I/O or system calls, for example) while other parts keep +going. If you're running different parts of the pipeline on different +processors you may also take advantage of the caches on each +processor. + +This model is also handy for a form of recursive programming where, +rather than having a subroutine call itself, it instead creates +another thread. Prime and Fibonacci generators both map well to this +form of the pipeline model. (A version of a prime number generator is +presented later on.) + +=head1 Native threads + +There are several different ways to implement threads on a system. How +threads are implemented depends both on the vendor and, in some cases, +the version of the operating system. Often the first implementation +will be relatively simple, but later versions of the OS will be more +sophisticated. + +While the information in this section is useful, it's not necessary, +so you can skip it if you don't feel up to it. + +There are three basic categories of threads-user-mode threads, kernel +threads, and multiprocessor kernel threads. + +User-mode threads are threads that live entirely within a program and +its libraries. In this model, the OS knows nothing about threads. As +far as it's concerned, your process is just a process. + +This is the easiest way to implement threads, and the way most OSes +start. The big disadvantage is that, since the OS knows nothing about +threads, if one thread blocks they all do. Typical blocking activities +include most system calls, most I/O, and things like sleep(). + +Kernel threads are the next step in thread evolution. The OS knows +about kernel threads, and makes allowances for them. The main +difference between a kernel thread and a user-mode thread is +blocking. With kernel threads, things that block a single thread don't +block other threads. This is not the case with user-mode threads, +where the kernel blocks at the process level and not the thread level. + +This is a big step forward, and can give a threaded program quite a +performance boost over non-threaded programs. Threads that block +performing I/O, for example, won't block threads that are doing other +things. Each process still has only one thread running at once, +though, regardless of how many CPUs a system might have. + +Since kernel threading can interrupt a thread at any time, they will +uncover some of the implicit locking assumptions you may make in your +program. For example, something as simple as C<$a = $a + 2> can behave +unpredictably with kernel threads if C<$a> is visible to other +threads, as another thread may have changed C<$a> between the time it +was fetched on the right hand side and the time the new value is +stored. + +Multiprocessor Kernel Threads are the final step in thread +support. With multiprocessor kernel threads on a machine with multiple +CPUs, the OS may schedule two or more threads to run simultaneously on +different CPUs. + +This can give a serious performance boost to your threaded program, +since more than one thread will be executing at the same time. As a +tradeoff, though, any of those nagging synchronization issues that +might not have shown with basic kernel threads will appear with a +vengeance. + +In addition to the different levels of OS involvement in threads, +different OSes (and different thread implementations for a particular +OS) allocate CPU cycles to threads in different ways. + +Cooperative multitasking systems have running threads give up control +if one of two things happen. If a thread calls a yield function, it +gives up control. It also gives up control if the thread does +something that would cause it to block, such as perform I/O. In a +cooperative multitasking implementation, one thread can starve all the +others for CPU time if it so chooses. + +Preemptive multitasking systems interrupt threads at regular intervals +while the system decides which thread should run next. In a preemptive +multitasking system, one thread usually won't monopolize the CPU. + +On some systems, there can be cooperative and preemptive threads +running simultaneously. (Threads running with realtime priorities +often behave cooperatively, for example, while threads running at +normal priorities behave preemptively.) + +=head1 What kind of threads are perl threads? + +If you have experience with other thread implementations, you might +find that things aren't quite what you expect. It's very important to +remember when dealing with Perl threads that Perl Threads Are Not X +Threads, for all values of X. They aren't POSIX threads, or +DecThreads, or Java's Green threads, or Win32 threads. There are +similarities, and the broad concepts are the same, but if you start +looking for implementation details you're going to be either +disappointed or confused. Possibly both. + +This is not to say that Perl threads are completely different from +everything that's ever come before--they're not. Perl's threading +model owes a lot to other thread models, especially POSIX. Just as +Perl is not C, though, Perl threads are not POSIX threads. So if you +find yourself looking for mutexes, or thread priorities, it's time to +step back a bit and think about what you want to do and how Perl can +do it. + +=head1 Threadsafe Modules + +The addition of threads has changed Perl's internals +substantially. There are implications for people who write +modules--especially modules with XS code or external libraries. While +most modules won't encounter any problems, modules that aren't +explicitly tagged as thread-safe should be tested before being used in +production code. + +Not all modules that you might use are thread-safe, and you should +always assume a module is unsafe unless the documentation says +otherwise. This includes modules that are distributed as part of the +core. Threads are a beta feature, and even some of the standard +modules aren't thread-safe. + +If you're using a module that's not thread-safe for some reason, you +can protect yourself by using semaphores and lots of programming +discipline to control access to the module. Semaphores are covered +later in the article. Perl Threads Are Different + +=head1 Thread Basics + +The core Thread module provides the basic functions you need to write +threaded programs. In the following sections we'll cover the basics, +showing you what you need to do to create a threaded program. After +that, we'll go over some of the features of the Thread module that +make threaded programming easier. + +=head2 Basic Thread Support + +Thread support is a Perl compile-time option-it's something that's +turned on or off when Perl is built at your site, rather than when +your programs are compiled. If your Perl wasn't compiled with thread +support enabled, then any attempt to use threads will fail. + +Remember that the threading support in 5.005 is in beta release, and +should be treated as such. You should expect that it may not function +entirely properly, and the thread interface may well change some +before it is a fully supported, production release. The beta version +shouldn't be used for mission-critical projects. Having said that, +threaded Perl is pretty nifty, and worth a look. + +Your programs can use the Config module to check whether threads are +enabled. If your program can't run without them, you can say something +like: + + $Config{usethreads} or die "Recompile Perl with threads to run this program."; + +A possibly-threaded program using a possibly-threaded module might +have code like this: + + use Config; + use MyMod; + + if ($Config{usethreads}) { + # We have threads + require MyMod_threaded; + import MyMod_threaded; + } else { + require MyMod_unthreaded; + import MyMod_unthreaded; + } + +Since code that runs both with and without threads is usually pretty +messy, it's best to isolate the thread-specific code in its own +module. In our example above, that's what MyMod_threaded is, and it's +only imported if we're running on a threaded Perl. + +=head2 Creating Threads + +The Thread package provides the tools you need to create new +threads. Like any other module, you need to tell Perl you want to use +it; use Thread imports all the pieces you need to create basic +threads. + +The simplest, straightforward way to create a thread is with new(): + + use Thread; + + $thr = new Thread \&sub1; + + sub sub1 { + print "In the thread\n"; + } + +The new() method takes a reference to a subroutine and creates a new +thread, which starts executing in the referenced subroutine. Control +then passes both to the subroutine and the caller. + +If you need to, your program can pass parameters to the subroutine as +part of the thread startup. Just include the list of parameters as +part of the C<Thread::new> call, like this: + + use Thread; + $Param3 = "foo"; + $thr = new Thread \&sub1, "Param 1", "Param 2", $Param3; + $thr = new Thread \&sub1, @ParamList; + $thr = new Thread \&sub1, qw(Param1 Param2 $Param3); + + sub sub1 { + my @InboundParameters = @_; + print "In the thread\n"; + print "got parameters >", join("<>", @InboundParameters), "<\n"; + } + + +The subroutine runs like a normal Perl subroutine, and the call to new +Thread returns whatever the subroutine returns. + +The last example illustrates another feature of threads. You can spawn +off several threads using the same subroutine. Each thread executes +the same subroutine, but in a separate thread with a separate +environment and potentially separate arguments. + +The other way to spawn a new thread is with async(), which is a way to +spin off a chunk of code like eval(), but into its own thread: + + use Thread qw(async); + + $LineCount = 0; + + $thr = async { + while(<>) {$LineCount++} + print "Got $LineCount lines\n"; + }; + + print "Waiting for the linecount to end\n"; + $thr->join; + print "All done\n"; + +You'll notice we did a use Thread qw(async) in that example. async is +not exported by default, so if you want it, you'll either need to +import it before you use it or fully qualify it as +Thread::async. You'll also note that there's a semicolon after the +closing brace. That's because async() treats the following block as an +anonymous subroutine, so the semicolon is necessary. + +Like eval(), the code executes in the same context as it would if it +weren't spun off. Since both the code inside and after the async start +executing, you need to be careful with any shared resources. Locking +and other synchronization techniques are covered later. + +=head2 Giving up control + +There are times when you may find it useful to have a thread +explicitly give up the CPU to another thread. Your threading package +might not support preemptive multitasking for threads, for example, or +you may be doing something compute-intensive and want to make sure +that the user-interface thread gets called frequently. Regardless, +there are times that you might want a thread to give up the processor. + +Perl's threading package provides the yield() function that does +this. yield() is pretty straightforward, and works like this: + + use Thread qw(yield async); + async { + my $foo = 50; + while ($foo--) { print "first async\n" } + yield; + $foo = 50; + while ($foo--) { print "first async\n" } + }; + async { + my $foo = 50; + while ($foo--) { print "second async\n" } + yield; + $foo = 50; + while ($foo--) { print "second async\n" } + }; + +=head2 Waiting For A Thread To Exit + +Since threads are also subroutines, they can return values. To wait +for a thread to exit and extract any scalars it might return, you can +use the join() method. + + use Thread; + $thr = new Thread \&sub1; + + @ReturnData = $thr->join; + print "Thread returned @ReturnData"; + + sub sub1 { return "Fifty-six", "foo", 2; } + +In the example above, the join() method returns as soon as the thread +ends. In addition to waiting for a thread to finish and gathering up +any values that the thread might have returned, join() also performs +any OS cleanup necessary for the thread. That cleanup might be +important, especially for long-running programs that spawn lots of +threads. If you don't want the return values and don't want to wait +for the thread to finish, you should call the detach() method +instead. detach() is covered later in the article. + +=head2 Errors In Threads + +So what happens when an error occurs in a thread? Any errors that +could be caught with eval() are postponed until the thread is +joined. If your program never joins, the errors appear when your +program exits. + +Errors deferred until a join() can be caught with eval(): + + use Thread qw(async); + $thr = async {$b = 3/0}; # Divide by zero error + $foo = eval {$thr->join}; + if ($@) { + print "died with error $@\n"; + } else { + print "Hey, why aren't you dead?\n"; + } + +eval() passes any results from the joined thread back unmodified, so +if you want the return value of the thread, this is your only chance +to get them. + +=head2 Ignoring A Thread + +join() does three things:it waits for a thread to exit, cleans up +after it, and returns any data the thread may have produced. But what +if you're not interested in the thread's return values, and you don't +really care when the thread finishes? All you want is for the thread +to get cleaned up after when it's done. + +In this case, you use the detach() method. Once a thread is detached, +it'll run until it's finished, then Perl will clean up after it +automatically. + + use Thread; + $thr = new Thread \&sub1; # Spawn the thread + + $thr->detach; # Now we officially don't care any more + + sub sub1 { + $a = 0; + while (1) { + $a++; + print "\$a is $a\n"; + sleep 1; + } + } + + +Once a thread is detached, it may not be joined, and any output that +it might have produced (if it was done and waiting for a join) is +lost. + +=head1 Threads And Data + +Now that we've covered the basics of threads, it's time for our next +topic: data. Threading introduces a couple of complications to data +access that non-threaded programs never need to worry about. + +=head2 Shared And Unshared Data + +The single most important thing to remember when using threads is that +all threads potentially have access to all the data anywhere in your +program. While this is true with a nonthreaded Perl program as well, +it's especially important to remember with a threaded program, since +more than one thread can be accessing this data at once. + +Perl's scoping rules don't change because you're using threads. If a +subroutine (or block, in the case of async()) could see a variable if +you weren't running with threads, it can see it if you are. This is +especially important for the subroutines that create, and makes my +variables even more important. Remember--if your variables aren't +lexically scoped (declared with C<my>) you're probably sharing it between +threads. + +=head2 Thread Pitfall: Races + +While threads bring a new set of useful tools, they also bring a +number of pitfalls. One pitfall is the race condition: + + use Thread; + $a = 1; + $thr1 = Thread->new(\&sub1); + $thr2 = Thread->new(\&sub2); + + sleep 10; + print "$a\n"; + + sub sub1 { $foo = $a; $a = $foo + 1; } + sub sub2 { $bar = $a; $a = $bar + 1; } + +What do you think $a will be? The answer, unfortunately, is "it +depends." Both sub1() and sub2() access the global variable $a, once +to read and once to write. Depending on factors ranging from your +thread implementation's scheduling algorithm to the phase of the moon, +$a can be 2 or 3. + +Race conditions are caused by unsynchronized access to shared +data. Without explicit synchronization, there's no way to be sure that +nothing has happened to the shared data between the time you access it +and the time you update it. Even this simple code fragment has the +possibility of error: + + use Thread qw(async); + $a = 2; + async{ $b = $a; $a = $b + 1; }; + async{ $c = $a; $a = $c + 1; }; + +Two threads both access $a. Each thread can potentially be interrupted +at any point, or be executed in any order. At the end, $a could be 3 +or 4, and both $b and $c could be 2 or 3. + +Whenever your program accesses data or resources that can be accessed +by other threads, you must take steps to coordinate access or risk +data corruption and race conditions. + +=head2 Controlling access: lock() + +The lock() function takes a variable (or subroutine, but we'll get to +that later) and puts a lock on it. No other thread may lock the +variable until the locking thread exits the innermost block containing +the lock. Using lock() is straightforward: + + use Thread qw(async); + $a = 4; + $thr1 = async { + $foo = 12; + { + lock ($a); # Block until we get access to $a + $b = $a; + $a = $b * $foo; + } + print "\$foo was $foo\n"; + }; + $thr2 = async { + $bar = 7; + { + lock ($a); # Block until we can get access to $a + $c = $a; + $a = $c * $bar; + } + print "\$bar was $bar\n"; + }; + $thr1->join; + $thr2->join; + print "\$a is $a\n"; + +lock() blocks the thread until the variable being locked is +available. When lock() returns, your thread can be sure that no other +thread can lock that variable until the innermost block containing the +lock exits. + +It's important to note that locks don't prevent access to the variable +in question, only lock attempts. This is in keeping with Perl's +longstanding tradition of courteous programming, and the advisory file +locking that flock() gives you. Locked subroutines behave differently, +however. We'll cover that later in the article. + +You may lock arrays and hashes as well as scalars. Locking an array, +though, will not block subsequent locks on array elements, just lock +attempts on the array itself. + +Finally, locks are recursive, which means it's okay for a thread to +lock a variable more than once. The lock will last until the outermost +lock() on the variable goes out of scope. + +=head2 Thread Pitfall: Deadlocks + +Locks are a handy tool to synchronize access to data. Using them +properly is the key to safe shared data. Unfortunately, locks aren't +without their dangers. Consider the following code: + + use Thread qw(async yield); + $a = 4; + $b = "foo"; + async { + lock($a); + yield; + sleep 20; + lock ($b); + }; + async { + lock($b); + yield; + sleep 20; + lock ($a); + }; + +This program will probably hang until you kill it. The only way it +won't hang is if one of the two async() routines acquires both locks +first. A guaranteed-to-hang version is more complicated, but the +principle is the same. + +The first thread spawned by async() will grab a lock on $a then, a +second or two later, try to grab a lock on $b. Meanwhile, the second +thread grabs a lock on $b, then later tries to grab a lock on $a. The +second lock attempt for both threads will block, each waiting for the +other to release its lock. + +This condition is called a deadlock, and it occurs whenever two or +more threads are trying to get locks on resources that the others +own. Each thread will block, waiting for the other to release a lock +on a resource. That never happens, though, since the thread with the +resource is itself waiting for a lock to be released. + +There are a number of ways to handle this sort of problem. The best +way is to always have all threads acquire locks in the exact same +order. If, for example, you lock variables $a, $b, and $c, always lock +$a before $b, and $b before $c. It's also best to hold on to locks for +as short a period of time to minimize the risks of deadlock. + +=head2 Queues: Passing Data Around + +A queue is a special thread-safe object that lets you put data in one +end and take it out the other without having to worry about +synchronization issues. They're pretty straightforward, and look like +this: + + use Thread qw(async); + use Thread::Queue; + + my $DataQueue = new Thread::Queue; + $thr = async { + while ($DataElement = $DataQueue->dequeue) { + print "Popped $DataElement off the queue\n"; + } + }; + + $DataQueue->enqueue(12); + $DataQueue->enqueue("A", "B", "C"); + $DataQueue->enqueue(\$thr); + sleep 10; + $DataQueue->enqueue(undef); + +You create the queue with new Thread::Queue. Then you can add lists of +scalars onto the end with enqueue(), and pop scalars off the front of +it with dequeue(). A queue has no fixed size, and can grow as needed +to hold everything pushed on to it. + +If a queue is empty, dequeue() blocks until another thread enqueues +something. This makes queues ideal for event loops and other +communications between threads. + +=head1 Threads And Code + +In addition to providing thread-safe access to data via locks and +queues, threaded Perl also provides general-purpose semaphores for +coarser synchronization than locks provide and thread-safe access to +entire subroutines. + +=head2 Semaphores: Synchronizing Data Access + +Semaphores are a kind of generic locking mechanism. Unlike lock, which +gets a lock on a particular scalar, Perl doesn't associate any +particular thing with a semaphore so you can use them to control +access to anything you like. In addition, semaphores can allow more +than one thread to access a resource at once, though by default +semaphores only allow one thread access at a time. + +=over 4 + +=item Basic semaphores + +Semaphores have two methods, down and up. down decrements the resource +count, while up increments it. down calls will block if the +semaphore's current count would decrement below zero. This program +gives a quick demonstration: + + use Thread qw(yield); + use Thread::Semaphore; + my $semaphore = new Thread::Semaphore; + $GlobalVariable = 0; + + $thr1 = new Thread \&sample_sub, 1; + $thr2 = new Thread \&sample_sub, 2; + $thr3 = new Thread \&sample_sub, 3; + + sub sample_sub { + my $SubNumber = shift @_; + my $TryCount = 10; + my $LocalCopy; + sleep 1; + while ($TryCount--) { + $semaphore->down; + $LocalCopy = $GlobalVariable; + print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n"; + yield; + sleep 2; + $LocalCopy++; + $GlobalVariable = $LocalCopy; + $semaphore->up; + } + } + +The three invocations of the subroutine all operate in sync. The +semaphore, though, makes sure that only one thread is accessing the +global variable at once. + +=item Advanced Semaphores + +By default, semaphores behave like locks, letting only one thread +down() them at a time. However, there are other uses for semaphores. + +Each semaphore has a counter attached to it. down() decrements the +counter and up() increments the counter. By default, semaphores are +created with the counter set to one, down() decrements by one, and +up() increments by one. If down() attempts to decrement the counter +below zero, it blocks until the counter is large enough. Note that +while a semaphore can be created with a starting count of zero, any +up() or down() always changes the counter by at least +one. $semaphore->down(0) is the same as $semaphore->down(1). + +The question, of course, is why would you do something like this? Why +create a semaphore with a starting count that's not one, or why +decrement/increment it by more than one? The answer is resource +availability. Many resources that you want to manage access for can be +safely used by more than one thread at once. + +For example, let's take a GUI driven program. It has a semaphore that +it uses to synchronize access to the display, so only one thread is +ever drawing at once. Handy, but of course you don't want any thread +to start drawing until things are properly set up. In this case, you +can create a semaphore with a counter set to zero, and up it when +things are ready for drawing. + +Semaphores with counters greater than one are also useful for +establishing quotas. Say, for example, that you have a number of +threads that can do I/O at once. You don't want all the threads +reading or writing at once though, since that can potentially swamp +your I/O channels, or deplete your process' quota of filehandles. You +can use a semaphore initialized to the number of concurrent I/O +requests (or open files) that you want at any one time, and have your +threads quietly block and unblock themselves. + +Larger increments or decrements are handy in those cases where a +thread needs to check out or return a number of resources at once. + +=back + +=head2 Attributes: Restricting Access To Subroutines + +In addition to synchronizing access to data or resources, you might +find it useful to synchronize access to subroutines. You may be +accessing a singular machine resource (perhaps a vector processor), or +find it easier to serialize calls to a particular subroutine than to +have a set of locks and sempahores. + +One of the additions to Perl 5.005 is subroutine attributes. The +Thread package uses these to provide several flavors of +serialization. It's important to remember that these attributes are +used in the compilation phase of your program so you can't change a +subroutine's behavior while your program is actually running. + +=head2 Subroutine Locks + +The basic subroutine lock looks like this: + + sub test_sub { + use attrs qw(locked); + } + +This ensures that only one thread will be executing this subroutine at +any one time. Once a thread calls this subroutine, any other thread +that calls it will block until the thread in the subroutine exits +it. A more elaborate example looks like this: + + use Thread qw(yield); + + new Thread \&thread_sub, 1; + new Thread \&thread_sub, 2; + new Thread \&thread_sub, 3; + new Thread \&thread_sub, 4; + + sub sync_sub { + use attrs qw(locked); + my $CallingThread = shift @_; + print "In sync_sub for thread $CallingThread\n"; + yield; + sleep 3; + print "Leaving sync_sub for thread $CallingThread\n"; + } + + sub thread_sub { + my $ThreadID = shift @_; + print "Thread $ThreadID calling sync_sub\n"; + sync_sub($ThreadID); + print "$ThreadID is done with sync_sub\n"; + } + +The use attrs qw(locked) locks sync_sub(), and if you run this, you +can see that only one thread is in it at any one time. + +=head2 Methods + +Locking an entire subroutine can sometimes be overkill, especially +when dealing with Perl objects. When calling a method for an object, +for example, you want to serialize calls to a method, so that only one +thread will be in the subroutine for a particular object, but threads +calling that subroutine for a different object aren't blocked. The +method attribute indicates whether the subroutine is really a method. + + use Thread; + + sub tester { + my $thrnum = shift @_; + my $bar = new Foo; + foreach (1..10) { + print "$thrnum calling per_object\n"; + $bar->per_object($thrnum); + print "$thrnum out of per_object\n"; + yield; + print "$thrnum calling one_at_a_time\n"; + $bar->one_at_a_time($thrnum); + print "$thrnum out of one_at_a_time\n"; + yield; + } + } + + foreach my $thrnum (1..10) { + new Thread \&tester, $thrnum; + } + + package Foo; + sub new { + my $class = shift @_; + return bless [@_], $class; + } + + sub per_object { + use attrs qw(locked method); + my ($class, $thrnum) = @_; + print "In per_object for thread $thrnum\n"; + yield; + sleep 2; + print "Exiting per_object for thread $thrnum\n"; + } + + sub one_at_a_time { + use attrs qw(locked); + my ($class, $thrnum) = @_; + print "In one_at_a_time for thread $thrnum\n"; + yield; + sleep 2; + print "Exiting one_at_a_time for thread $thrnum\n"; + } + +As you can see from the output (omitted for brevity; it's 800 lines) +all the threads can be in per_object() simultaneously, but only one +thread is ever in one_at_a_time() at once. + +=head2 Locking A Subroutine + +You can lock a subroutine as you would lock a variable. Subroutine +locks work the same as a C<use attrs qw(locked)> in the subroutine, +and block all access to the subroutine for other threads until the +lock goes out of scope. When the subroutine isn't locked, any number +of threads can be in it at once, and getting a lock on a subroutine +doesn't affect threads already in the subroutine. Getting a lock on a +subroutine looks like this: + + lock(\&sub_to_lock); + +Simple enough. Unlike use attrs, which is a compile time option, +locking and unlocking a subroutine can be done at runtime at your +discretion. There is some runtime penalty to using lock(\&sub) instead +of use attrs qw(locked), so make sure you're choosing the proper +method to do the locking. + +You'd choose lock(\&sub) when writing modules and code to run on both +threaded and unthreaded Perl, especially for code that will run on +5.004 or earlier Perls. In that case, it's useful to have subroutines +that should be serialized lock themselves if they're running threaded, +like so: + + package Foo; + use Config; + $Running_Threaded = 0; + + BEGIN { $Running_Threaded = $Config{'usethreads'} } + + sub sub1 { lock(\&sub1) if $Running_Threaded } + + +This way you can ensure single-threadedness regardless of which +version of Perl you're running. + +=head1 General Thread Utility Routines + +We've covered the workhorse parts of Perl's threading package, and +with these tools you should be well on your way to writing threaded +code and packages. There are a few useful little pieces that didn't +really fit in anyplace else. + +=head2 What Thread Am I In? + +The Thread->self method provides your program with a way to get an +object representing the thread it's currently in. You can use this +object in the same way as the ones returned from the thread creation. + +=head2 Thread IDs + +tid() is a thread object method that returns the thread ID of the +thread the object represents. Thread IDs are integers, with the main +thread in a program being 0. Currently Perl assigns a unique tid to +every thread ever created in your program, assigning the first thread +to be created a tid of 1, and increasing the tid by 1 for each new +thread that's created. + +=head2 Are These Threads The Same? + +The equal() method takes two thread objects and returns true +if the objects represent the same thread, and false if they don't. + +=head2 What Threads Are Running? + +Thread->list returns a list of thread objects, one for each thread +that's currently running. Handy for a number of things, including +cleaning up at the end of your program: + + # Loop through all the threads + foreach $thr (Thread->list) { + # Don't join the main thread or ourselves + if ($thr->tid && !Thread::equal($thr, Thread->self)) { + $thr->join; + } + } + +The example above is just for illustration. It isn't strictly +necessary to join all the threads you create, since Perl detaches all +the threads before it exits. + +=head1 A Complete Example + +Confused yet? It's time for an example program to show some of the +things we've covered. This program finds prime numbers using threads. + + 1 #!/usr/bin/perl -w + 2 # prime-pthread, courtesy of Tom Christiansen + 3 + 4 use strict; + 5 + 6 use Thread; + 7 use Thread::Queue; + 8 + 9 my $stream = new Thread::Queue; + 10 my $kid = new Thread(\&check_num, $stream, 2); + 11 + 12 for my $i ( 3 .. 1000 ) { + 13 $stream->enqueue($i); + 14 } + 15 + 16 $stream->enqueue(undef); + 17 $kid->join(); + 18 + 19 sub check_num { + 20 my ($upstream, $cur_prime) = @_; + 21 my $kid; + 22 my $downstream = new Thread::Queue; + 23 while (my $num = $upstream->dequeue) { + 24 next unless $num % $cur_prime; + 25 if ($kid) { + 26 $downstream->enqueue($num); + 27 } else { + 28 print "Found prime $num\n"; + 29 $kid = new Thread(\&check_num, $downstream, $num); + 30 } + 31 } + 32 $downstream->enqueue(undef) if $kid; + 33 $kid->join() if $kid; + 34 } + +This program uses the pipeline model to generate prime numbers. Each +thread in the pipeline has an input queue that feeds numbers to be +checked, a prime number that it's responsible for, and an output queue +that it funnels numbers that have failed the check into. If the thread +has a number that's failed its check and there's no child thread, then +the thread must have found a new prime number. In that case, a new +child thread is created for that prime and stuck on the end of the +pipeline. + +This probably sounds a bit more confusing than it really is, so lets +go through this program piece by piece and see what it does. (For +those of you who might be trying to remember exactly what a prime +number is, it's a number that's only evenly divisible by itself and 1) + +The bulk of the work is done by the check_num() subroutine, which +takes a reference to its input queue and a prime number that it's +responsible for. After pulling in the input queue and the prime that +the subroutine's checking (line 20), we create a new queue (line 22) +and reserve a scalar for the thread that we're likely to create later +(line 21). + +The while loop from lines 23 to line 31 grabs a scalar off the input +queue and checks against the prime this thread is responsible +for. Line 24 checks to see if there's a remainder when we modulo the +number to be checked against our prime. If there is one, the number +must not be evenly divisible by our prime, so we need to either pass +it on to the next thread if we've created one (line 26) or create a +new thread if we haven't. + +The new thread creation is line 29. We pass on to it a reference to +the queue we've created, and the prime number we've found. + +Finally, once the loop terminates (because we got a 0 or undef in the +queue, which serves as a note to die), we pass on the notice to our +child and wait for it to exit if we've created a child (Lines 32 and +37). + +Meanwhile, back in the main thread, we create a queue (line 9) and the +initial child thread (line 10), and pre-seed it with the first prime: +2. Then we queue all the numbers from 3 to 1000 for checking (lines +12-14), then queue a die notice (line 16) and wait for the first child +thread to terminate (line 17). Because a child won't die until its +child has died, we know that we're done once we return from the join. + +That's how it works. It's pretty simple; as with many Perl programs, +the explanation is much longer than the program. + +=head1 Conclusion + +A complete thread tutorial could fill a book (and has, many times), +but this should get you well on your way. The final authority on how +Perl's threads behave is the documention bundled with the Perl +distribution, but with what we've covered in this article, you should +be well on your way to becoming a threaded Perl expert. + +=head1 Bibliography + +Here's a short bibliography courtesy of Jürgen Christoffel: + +=head2 Introductory Texts + +Birrell, Andrew D. An Introduction to Programming with +Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report +#35 online as +http://www.research.digital.com/SRC/staff/birrell/bib.html (highly +recommended) + +Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A +Guide to Concurrency, Communication, and +Multithreading. Prentice-Hall, 1996. + +Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with +Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written +introduction to threads). + +Nelson, Greg (editor). Systems Programming with Modula-3. Prentice +Hall, 1991, ISBN 0-13-590464-1. + +Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell. +Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1 +(covers POSIX threads). + +=head2 OS-Related References + +Boykin, Joseph, David Kirschen, Alan Langerman, and Susan +LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN +0-201-52739-1. + +Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, +1995, ISBN 0-13-143934-0 (great textbook). + +Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, +4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4 + +=head2 Other References + +Arnold, Ken and James Gosling. The Java Programming Language, 2nd +ed. Addison-Wesley, 1998, ISBN 0-201-31006-6. + +Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage +Collection on Virtually Shared Memory Architectures" in Memory +Management: Proc. of the International Workshop IWMM 92, St. Malo, +France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer, +1992, ISBN 3540-55940-X (real-life thread applications). + +=head1 Acknowledgements + +Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy +Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua +Pritikin, and Alan Burlison, for their help in reality-checking and +polishing this article. Big thanks to Tom Christiansen for his rewrite +of the prime number generator. + +=head1 AUTHOR + +Dan Sugalski E<lt>sugalskd@ous.eduE<gt> + +=head1 Copyrights + +This article originally appeared in The Perl Journal #10, and is +copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and +The Perl Journal. This document may be distributed under the same terms +as Perl itself. + + diff --git a/contrib/perl5/pod/perltie.pod b/contrib/perl5/pod/perltie.pod index cae0a15..6652658 100644 --- a/contrib/perl5/pod/perltie.pod +++ b/contrib/perl5/pod/perltie.pod @@ -680,9 +680,12 @@ This method will be called when the handle is read from via the C<read> or C<sysread> functions. sub READ { - $r = shift; - my($buf,$len,$offset) = @_; - print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset"; + my $self = shift; + my $$bufref = \$_[0]; + my(undef,$len,$offset) = @_; + print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset"; + # add to $$bufref, set $len to number of characters read + $len; } =item READLINE this @@ -690,7 +693,7 @@ or C<sysread> functions. This method will be called when the handle is read from via <HANDLE>. The method should return undef when there is no more data. - sub READLINE { $r = shift; "PRINT called $$r times\n"; } + sub READLINE { $r = shift; "READLINE called $$r times\n"; } =item GETC this diff --git a/contrib/perl5/pod/perltoc.pod b/contrib/perl5/pod/perltoc.pod index 980ca8f..9dc0b36 100644 --- a/contrib/perl5/pod/perltoc.pod +++ b/contrib/perl5/pod/perltoc.pod @@ -1353,7 +1353,7 @@ $BASETIME, $^T, $WARNING, $^W, $EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, =item Private Variables via C<my()> -=item Peristent Private Variables +=item Persistent Private Variables =item Temporary Values via local() @@ -2263,7 +2263,8 @@ C<http://www.connect.net/gbarr/cpan-test/> The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>, The EMX environment for DOS, OS/2, etc. -C<emx@iaehv.nl>,C<http://www.juge.com/bbs/Hobb.19.html>, Build instructions +C<emx@iaehv.nl>,C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html>, +C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>. Build instructions for Win32, L<perlwin32>, The ActiveState Pages, C<http://www.activestate.com/> diff --git a/contrib/perl5/pod/perlvar.pod b/contrib/perl5/pod/perlvar.pod index 2ed3e97..8d0ded6 100644 --- a/contrib/perl5/pod/perlvar.pod +++ b/contrib/perl5/pod/perlvar.pod @@ -17,6 +17,15 @@ at the top of your program. This will alias all the short names to the long names in the current package. Some even have medium names, generally borrowed from B<awk>. +Due to an unfortunate accident of Perl's implementation, "C<use English>" +imposes a considerable performance penalty on all regular expression +matches in a program, regardless of whether they occur in the scope of +"C<use English>". For that reason, saying "C<use English>" in +libraries is strongly discouraged. See the Devel::SawAmpersand module +documentation from CPAN +(http://www.perl.com/CPAN/modules/by-module/Devel/Devel-SawAmpersand-0.10.readme) +for more information. + To go a step further, those variables that depend on the currently selected filehandle may instead (and preferably) be set by calling an object method on the FileHandle object. (Summary lines below for this @@ -127,6 +136,10 @@ The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: like & in some editors.) This variable is read-only. +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See the +Devel::SawAmpersand module from CPAN for more information. + =item $PREMATCH =item $` @@ -136,6 +149,10 @@ pattern match (not counting any matches hidden within a BLOCK or eval enclosed by the current BLOCK). (Mnemonic: C<`> often precedes a quoted string.) This variable is read-only. +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See the +Devel::SawAmpersand module from CPAN for more information. + =item $POSTMATCH =item $' @@ -151,6 +168,10 @@ string.) Example: This variable is read-only. +The use of this variable anywhere in a program imposes a considerable +performance penalty on all regular expression matches. See the +Devel::SawAmpersand module from CPAN for more information. + =item $LAST_PAREN_MATCH =item $+ @@ -188,7 +209,10 @@ the C</s> and C</m> modifiers on pattern matching. =item $. The current input line number for the last file handle from -which you read (or performed a C<seek> or C<tell> on). An +which you read (or performed a C<seek> or C<tell> on). The value +may be different from the actual physical line number in the file, +depending on what notion of "line" is in effect--see L<$/> on how +to affect that. An explicit close on a filehandle resets the line number. Because "C<E<lt>E<gt>>" never does an explicit close, line numbers increase across ARGV files (but see examples under eof()). Localizing C<$.> has @@ -204,7 +228,8 @@ number.) =item $/ -The input record separator, newline by default. Works like B<awk>'s RS +The input record separator, newline by default. This is used to +influence Perl's idea of what a "line" is. Works like B<awk>'s RS variable, including treating empty lines as delimiters if set to the null string. (Note: An empty line cannot contain any spaces or tabs.) You may set it to a multi-character string to match a multi-character @@ -216,8 +241,8 @@ line. Setting it to C<"\n\n"> will blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / is used to delimit line boundaries when quoting poetry.) - undef $/; - $_ = <FH>; # whole file now here + undef $/; # enable "slurp" mode + $_ = <FH>; # whole file now here s/\n[ \t]+/ /g; Remember: the value of $/ is a string, not a regexp. AWK has to be @@ -241,9 +266,11 @@ get the record back in pieces. On VMS, record reads are done with the equivalent of C<sysread>, so it's best not to mix record and non-record reads on the same file. (This is likely not a problem, as any file you'd want to read in record mode is -proably usable in line mode) Non-VMS systems perform normal I/O, so +probably usable in line mode) Non-VMS systems perform normal I/O, so it's safe to mix record and non-record reads of a file. +Also see L<$.>. + =item autoflush HANDLE EXPR =item $OUTPUT_AUTOFLUSH @@ -626,6 +653,15 @@ of perl in the right bracket?) Example: See also the documentation of C<use VERSION> and C<require VERSION> for a convenient way to fail if the Perl interpreter is too old. +=item $COMPILING + +=item $^C + +The current value of the flag associated with the B<-c> switch. Mainly +of use with B<-MO=...> to allow code to alter its behaviour when being compiled. +(For example to automatically AUTOLOADing at compile time rather than normal +deferred loading.) Setting C<$^C = 1> is similar to calling C<B::minus_c>. + =item $DEBUGGING =item $^D @@ -643,7 +679,7 @@ descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails. (Ordinary file descriptors are closed before the open() is attempted.) Note that the close-on-exec status of a file descriptor will be decided according to the value of -C<$^F> at the time of the open, not the time of the exec. +C<$^F> when the open() or pipe() was called, not the time of the exec(). =item $^H @@ -714,7 +750,7 @@ Start with single-step on. =back -Note that some bits may be relevent at compile-time only, some at +Note that some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change. =item $^R @@ -788,12 +824,16 @@ specified, and the value is the location of the file actually found. The C<require> command uses this array to determine whether a given file has already been included. -=item %ENV $ENV{expr} +=item %ENV + +=item $ENV{expr} The hash %ENV contains your current environment. Setting a value in C<ENV> changes the environment for child processes. -=item %SIG $SIG{expr} +=item %SIG + +=item $SIG{expr} The hash %SIG is used to set signal handlers for various signals. Example: @@ -811,6 +851,10 @@ signals. Example: $SIG{'INT'} = 'DEFAULT'; # restore default action $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT +Using a value of C<'IGNORE'> usually has the effect of ignoring the +signal, except for the C<CHLD> signal. See L<perlipc> for more about +this special case. + The %SIG array contains values for only the signals actually set within the Perl script. Here are some other examples: @@ -867,7 +911,7 @@ respect: they may be called to report (probable) errors found by the parser. In such a case the parser may be in inconsistent state, so any attempt to evaluate Perl code from such a handler will probably result in a segfault. This means that calls which result/may-result -in parsing Perl should be used with extreme causion, like this: +in parsing Perl should be used with extreme caution, like this: require Carp if defined $^S; Carp::confess("Something wrong") if defined &Carp::confess; @@ -934,3 +978,35 @@ pipe C<close>, overwriting the old value. For more details, see the individual descriptions at L<$@>, L<$!>, L<$^E>, and L<$?>. + + +=head2 Technical Note on the Syntax of Variable Names + +Variable names in Perl can have several formats. Usually, they must +begin with a letter or underscore, in which case they can be +arbitrarily long (up to an internal limit of 256 characters) and may +contain letters, digits, underscores, or the special sequence C<::>. +In this case the part before the last C<::> is taken to be a I<package +qualifier>; see L<perlmod>. + +Perl variable names may also be a sequence of digits or a single +punctuation or control character. These names are all reserved for +special uses by Perl; for example, the all-digits names are used to +hold backreferences after a regular expression match. Perl has a +special syntax for the single-control-character names: It understands +C<^X> (caret C<X>) to mean the control-C<X> character. For example, +the notation C<$^W> (dollar-sign caret C<W>) is the scalar variable +whose name is the single character control-C<W>. This is better than +typing a literal control-C<W> into your program. + +All Perl variables that begin with digits, control characters, or +punctuation characters are exempt from the effects of the C<package> +declaration and are always forced to be in package C<main>. A few +other names are also exempt: + + ENV STDIN + INC STDOUT + ARGV STDERR + ARGVOUT + SIG + diff --git a/contrib/perl5/pod/perlxs.pod b/contrib/perl5/pod/perlxs.pod index c578a2e..98a9834 100644 --- a/contrib/perl5/pod/perlxs.pod +++ b/contrib/perl5/pod/perlxs.pod @@ -181,10 +181,10 @@ directive is used which sets ST(0) explicitly. Older versions of this document recommended to use C<void> return value in such cases. It was discovered that this could lead to -segfaults in cases when XSUB was I<truely> C<void>. This practice is +segfaults in cases when XSUB was I<truly> C<void>. This practice is now deprecated, and may be not supported at some future version. Use the return value C<SV *> in such cases. (Currently C<xsubpp> contains -some heuristic code which tries to disambiguate between "truely-void" +some heuristic code which tries to disambiguate between "truly-void" and "old-practice-declared-as-void" functions. Hence your code is at mercy of this heuristics unless you use C<SV *> as return value.) @@ -387,9 +387,9 @@ the same line where the input variable is declared. If the initialization begins with C<;> or C<+>, then it is output after all of the input variables have been declared. The C<=> and C<;> cases replace the initialization normally supplied from the typemap. -For the C<+> case, the initialization from the typemap will preceed +For the C<+> case, the initialization from the typemap will precede the initialization code included after the C<+>. A global -variable, C<%v>, is available for the truely rare case where +variable, C<%v>, is available for the truly rare case where information from one initialization is needed in another initialization. @@ -553,9 +553,10 @@ The XS code, with ellipsis, follows. time_t timep = NO_INIT PREINIT: char *host = "localhost"; + STRLEN n_a; CODE: if( items > 1 ) - host = (char *)SvPV(ST(1), PL_na); + host = (char *)SvPV(ST(1), n_a); RETVAL = rpcb_gettime( host, &timep ); OUTPUT: timep @@ -786,9 +787,10 @@ prototypes. PROTOTYPE: $;$ PREINIT: char *host = "localhost"; + STRLEN n_a; CODE: if( items > 1 ) - host = (char *)SvPV(ST(1), PL_na); + host = (char *)SvPV(ST(1), n_a); RETVAL = rpcb_gettime( host, &timep ); OUTPUT: timep @@ -1212,13 +1214,15 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine. The typemap is a collection of code fragments which are used by the B<xsubpp> compiler to map C function parameters and values to Perl values. The typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and -C<OUTPUT>. The INPUT section tells the compiler how to translate Perl values +C<OUTPUT>. Any unlabelled initial section is assumed to be a C<TYPEMAP> +section if a name is not explicitly specified. The INPUT section tells +the compiler how to translate Perl values into variables of certain C types. The OUTPUT section tells the compiler how to translate the values from certain C types into values Perl can understand. The TYPEMAP section tells the compiler which of the INPUT and OUTPUT code fragments should be used to map a given C type to a Perl value. -Each of the sections of the typemap must be preceded by one of the TYPEMAP, -INPUT, or OUTPUT keywords. +The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin +in the first column on a line by themselves, and must be in uppercase. The default typemap in the C<ext> directory of the Perl source contains many useful types which can be used by Perl extensions. Some extensions define diff --git a/contrib/perl5/pod/perlxstut.pod b/contrib/perl5/pod/perlxstut.pod index 867d42a..69a1a25 100644 --- a/contrib/perl5/pod/perlxstut.pod +++ b/contrib/perl5/pod/perlxstut.pod @@ -465,7 +465,7 @@ include a C source file and a header file. We'll also create a Makefile.PL in this directory. Then we'll make sure that running make at the Mytest2 level will automatically run this Makefile.PL file and the resulting Makefile. -In the testlib directory, create a file mylib.h that looks like this: +In the mylib directory, create a file mylib.h that looks like this: #define TESTVAL 4 diff --git a/contrib/perl5/pod/pod2html.PL b/contrib/perl5/pod/pod2html.PL index 4eec29c..366dc16 100644 --- a/contrib/perl5/pod/pod2html.PL +++ b/contrib/perl5/pod/pod2html.PL @@ -164,7 +164,7 @@ See L<Pod::Html> for a list of known bugs in the translator. =head1 SEE ALSO -L<perlpod>, L<Pod::HTML> +L<perlpod>, L<Pod::Html> =head1 COPYRIGHT diff --git a/contrib/perl5/pod/pod2man.PL b/contrib/perl5/pod/pod2man.PL index 8040bf5..3c55d6e 100644 --- a/contrib/perl5/pod/pod2man.PL +++ b/contrib/perl5/pod/pod2man.PL @@ -318,8 +318,12 @@ $cutting = 1; # running an installed version of Perl to produce documentation from an # uninstalled newer version's pod files. if ($^O ne 'plan9' and $^O ne 'dos' and $^O ne 'os2' and $^O ne 'MSWin32') { - ($version,$patch) = - `\PATH=.:..:\$PATH; perl -v` =~ /version (\d\.\d{3})(?:_(\d{2}))?/; + my $perl = (-x './perl' && -f './perl' ) ? + './perl' : + ((-x '../perl' && -f '../perl') ? + '../perl' : + ''); + ($version,$patch) = `$perl -e 'print $]'` =~ /^(\d\.\d{3})(\d{2})?/ if $perl; } # No luck; we'll just go with the running Perl's version ($version,$patch) = $] =~ /^(.{5})(\d{2})?/ unless $version; @@ -331,6 +335,7 @@ sub makedate { my $secs = shift; my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($secs); my $mname = (qw{Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec})[$mon]; + $year += 1900; return "$mday/$mname/$year"; } diff --git a/contrib/perl5/pod/roffitall b/contrib/perl5/pod/roffitall index 918fe02..9ab7f29 100644 --- a/contrib/perl5/pod/roffitall +++ b/contrib/perl5/pod/roffitall @@ -36,6 +36,7 @@ toroff=` $mandir/perlre.1 \ $mandir/perlrun.1 \ $mandir/perlfunc.1 \ + $mandir/perlopentut.1 \ $mandir/perlvar.1 \ $mandir/perlsub.1 \ $mandir/perlmod.1 \ @@ -44,6 +45,7 @@ toroff=` $mandir/perlform.1 \ $mandir/perllocale.1 \ $mandir/perlref.1 \ + $mandir/perlreftut.1 \ $mandir/perldsc.1 \ $mandir/perllol.1 \ $mandir/perltoot.1 \ @@ -65,6 +67,7 @@ toroff=` $mandir/perlxstut.1 \ $mandir/perlguts.1 \ $mandir/perlcall.1 \ + $mandir/perlthrtut.1 \ $mandir/perlhist.1 \ $mandir/perldelta.1 \ $mandir/perl5004delta.1 \ @@ -149,6 +152,7 @@ toroff=` $libdir/Devel::SelfStubber.3 \ $libdir/DirHandle.3 \ $libdir/DynaLoader.3 \ + $libdir/Dumpvalue.3 \ $libdir/English.3 \ $libdir/Env.3 \ $libdir/Errno.3 \ |
