B::clearsym
[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod
index e7fdc78..0d47260 100644 (file)
@@ -396,8 +396,8 @@ 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.
+It is usually a mistake to intermix C<alarm> and C<sleep> calls.
+(C<sleep> may be internally implemented in your system with C<alarm>)
 
 If you want to use C<alarm> to time out a system call you need to use an
 C<eval>/C<die> pair.  You can't rely on the alarm causing the system call to
@@ -2064,7 +2064,8 @@ separated by the value of EXPR, and returns that new string.  Example:
 
     $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
 
-See L</split>.
+Beware that unlike C<split>, C<join> doesn't take a pattern as its
+first argument.  Compare L</split>.
 
 =item keys HASH
 
@@ -2118,7 +2119,8 @@ See also C<each>, C<values> and C<sort>.
 
 Sends a signal to a list of processes.  The first element of
 the list must be the signal to send.  Returns the number of
-processes successfully signaled.
+processes successfully signaled (which is not necessarily the
+same as the number actually killed).
 
     $cnt = kill 1, $child1, $child2;
     kill 9, @goners;
@@ -2226,11 +2228,13 @@ In scalar context, returns the ctime(3) value:
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
 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
-get somewhat similar but locale dependent date strings, set up your
-locale environment variables appropriately (please see L<perllocale>)
-and try for example:
+instead a Perl builtin.  Also see the C<Time::Local> module
+(to convert the second, minutes, hours, ... back to seconds since the
+stroke of midnight the 1st of January 1970, the value returned by
+time()), and the strftime(3) and mktime(3) function 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", localtime;
@@ -2363,6 +2367,8 @@ there is an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
+=item my EXPR : ATTRIBUTES
+
 A C<my> declares the listed variables to be local (lexically) to the
 enclosing block, file, or C<eval>.  If
 more than one value is listed, the list must be placed in parentheses.  See
@@ -2418,6 +2424,8 @@ to be converted into a file mode, for example. (Although perl will
 automatically convert strings into numbers as needed, this automatic
 conversion assumes base 10.)
 
+=item open FILEHANDLE,MODE,EXPR
+
 =item open FILEHANDLE,EXPR
 
 =item open FILEHANDLE
@@ -2431,9 +2439,9 @@ for this purpose; so if you're using C<my>, specify EXPR in your call
 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
-output, being created if necessary.  If the filename begins with C<'E<gt>E<gt>'>,
+If MODE is C<'E<lt>'> or nothing, the file is opened for input.
+If MODE is C<'E<gt>'>, the file is truncated and opened for
+output, being created if necessary.  If MODE is C<'E<gt>E<gt>'>,
 the file is opened for appending, again being created if necessary. 
 You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
 you want both read and write access to the file; thus C<'+E<lt>'> is almost
@@ -2443,10 +2451,13 @@ textfiles, since they have variable length records.  See the B<-i>
 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'>,
 C<'w+'>, C<'a'>, and C<'a+'>.
 
+In the 2-arguments (and 1-argument) form of the call the mode and
+filename should be concatenated (in this order), possibly separated by
+spaces.  It is possible to omit the mode if the mode is C<'E<lt>'>.
+
 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 as a command which pipes output to
@@ -2455,7 +2466,19 @@ 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.)
 
-Opening C<'-'> opens STDIN and opening C<'E<gt>-'> opens STDOUT.  Open returns
+If MODE is C<'|-'>, the filename is interpreted as a
+command to which output is to be piped, and if MODE is
+C<'-|'>, the filename is interpreted as a command which pipes output to
+us.  In the 2-arguments (and 1-argument) form one should replace dash
+(C<'-'>) with the command.  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.)
+
+In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
+and opening C<'E<gt>-'> opens STDOUT.  
+
+Open returns
 nonzero upon success, the undefined value otherwise.  If the C<open>
 involved a pipe, the return value happens to be the pid of the
 subprocess.
@@ -2482,16 +2505,22 @@ Examples:
     open ARTICLE or die "Can't find article $ARTICLE: $!\n";
     while (<ARTICLE>) {...
 
-    open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
+    open(LOG, '>>/usr/spool/news/twitlog');    # (log is reserved)
     # if the open fails, output is discarded
 
-    open(DBASE, '+<dbase.mine')                    # open for update
+    open(DBASE, '+<', 'dbase.mine')            # open for update
+       or die "Can't open 'dbase.mine' for update: $!";
+
+    open(DBASE, '+<dbase.mine')                        # ditto
        or die "Can't open 'dbase.mine' for update: $!";
 
-    open(ARTICLE, "caesar <$article |")     # decrypt article
+    open(ARTICLE, '-|', "caesar <$article")     # decrypt article
+       or die "Can't start caesar: $!";
+
+    open(ARTICLE, "caesar <$article |")                # ditto
        or die "Can't start caesar: $!";
 
-    open(EXTRACT, "|sort >/tmp/Tmp$$")      # $$ is our process id
+    open(EXTRACT, "|sort >/tmp/Tmp$$")         # $$ is our process id
        or die "Can't start sort: $!";
 
     # process argument list of files along with any includes
@@ -2521,11 +2550,13 @@ Examples:
 You may also, in the Bourne shell tradition, specify an EXPR beginning
 with C<'E<gt>&'>, in which case the rest of the string is interpreted as the
 name of a filehandle (or file descriptor, if numeric) to be
-duped and opened.  You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>, C<E<lt>>, C<+E<gt>>,
-C<+E<gt>E<gt>>, and C<+E<lt>>.  The
+duped and opened.  You may use C<&> after C<E<gt>>, C<E<gt>E<gt>>,
+C<E<lt>>, C<+E<gt>>, C<+E<gt>E<gt>>, and C<+E<lt>>.  The
 mode you specify should match the mode of the original filehandle.
 (Duping a filehandle does not take into account any existing contents of
-stdio buffers.)
+stdio buffers.)  Duping file handles is not yet supported for 3-argument
+open().
+
 Here is a script that saves, redirects, and restores STDOUT and
 STDERR:
 
@@ -2533,8 +2564,8 @@ STDERR:
     open(OLDOUT, ">&STDOUT");
     open(OLDERR, ">&STDERR");
 
-    open(STDOUT, ">foo.out") || die "Can't redirect stdout";
-    open(STDERR, ">&STDOUT") || die "Can't dup stdout";
+    open(STDOUT, '>', "foo.out") || die "Can't redirect stdout";
+    open(STDERR, ">&STDOUT")     || die "Can't dup stdout";
 
     select(STDERR); $| = 1;    # make unbuffered
     select(STDOUT); $| = 1;    # make unbuffered
@@ -2557,7 +2588,8 @@ parsimonious of file descriptors.  For example:
 
     open(FILEHANDLE, "<&=$fd")
 
-If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>, then
+If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
+with 2-arguments (or 1-argument) form of open(), then
 there is an implicit fork done, and the return value of open is the pid
 of the child within the parent process, and C<0> within the child
 process.  (Use C<defined($pid)> to determine whether the open was successful.)
@@ -2568,13 +2600,15 @@ the new STDOUT or STDIN.  Typically this is used like the normal
 piped open when you want to exercise more control over just how the
 pipe command gets executed, such as when you are running setuid, and
 don't want to have to scan shell commands for metacharacters.
-The following pairs are more or less equivalent:
+The following triples are more or less equivalent:
 
     open(FOO, "|tr '[a-z]' '[A-Z]'");
-    open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
+    open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
+    open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
 
     open(FOO, "cat -n '$file'|");
-    open(FOO, "-|") || exec 'cat', '-n', $file;
+    open(FOO, '-|', "cat -n '$file'");
+    open(FOO, '-|') || exec 'cat', '-n', $file;
 
 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
 
@@ -2586,7 +2620,8 @@ 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<$?>.
 
-The filename passed to open will have leading and trailing
+The filename passed to 2-argument (or 1-argument) form of open()
+will have leading and trailing
 whitespace deleted, and the normal redirection characters
 honored.  This property, known as "magic open", 
 can often be used to good effect.  A user could specify a filename of
@@ -2595,14 +2630,32 @@ F<"rsh cat file |">, or you could change certain filenames as needed:
     $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
     open(FH, $filename) or die "Can't open $filename: $!";
 
-However, to open a file with arbitrary weird characters in it, it's
-necessary to protect any leading and trailing whitespace:
+Use 3-argument form to open a file with arbitrary weird characters in it,
+
+    open(FOO, '<', $file);
+
+otherwise it's necessary to protect any leading and trailing whitespace:
 
     $file =~ s#^(\s)#./$1#;
     open(FOO, "< $file\0");
 
+(this may not work on some bizzare filesystems).  One should
+conscientiously choose between the the I<magic> and 3-arguments form
+of open():
+
+    open IN, $ARGV[0];
+
+will allow the user to specify an argument of the form C<"rsh cat file |">,
+but will not work on a filename which happens to have a trailing space, while
+
+    open IN, '<', $ARGV[0];
+
+will have exactly the opposite restrictions.
+
 If you want a "real" C C<open> (see L<open(2)> on your system), then you
-should use the C<sysopen> function, which involves no such magic.  This is
+should use the C<sysopen> function, which involves no such magic (but
+may use subtly different filemodes than Perl open(), which is mapped
+to C fopen()).  This is
 another way to protect your filenames from interpretation.  For example:
 
     use IO::Handle;
@@ -2669,7 +2722,8 @@ follows:
     s  A signed short value.
     S  An unsigned short value.
          (This 'short' is _exactly_ 16 bits, which may differ from
-          what a local C compiler calls 'short'.)
+          what a local C compiler calls 'short'.  If you want
+          native-length shorts, use the '!' suffix.)
 
     i  A signed integer value.
     I  An unsigned integer value.
@@ -2681,7 +2735,8 @@ follows:
     l  A signed long value.
     L  An unsigned long value.
          (This 'long' is _exactly_ 32 bits, which may differ from
-          what a local C compiler calls 'long'.)
+          what a local C compiler calls 'long'.  If you want
+          native-length longs, use the '!' suffix.)
 
     n  A short in "network" (big-endian) order.
     N  A long in "network" (big-endian) order.
@@ -2692,8 +2747,8 @@ follows:
 
     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.
+         (Quads are 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.
@@ -2740,7 +2795,8 @@ 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.
+The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups,
+representable as hexadecimal digits, 0-9a-f) long.
 
 =item *
 
@@ -2753,12 +2809,41 @@ C<"P"> is C<undef>.
 
 =item *
 
+The C<"#"> character allows packing and unpacking of strings where the
+packed structure contains a byte count followed by the string itself.
+You write I<length-item>C<#>I<string-item>.
+
+The I<length-item> can be any C<pack> template letter,
+and describes how the length value is packed.
+The ones likely to be of most use are integer-packing ones like
+C<"n"> (for Java strings), C<"w"> (for ASN.1 or SNMP)
+and C<"N"> (for Sun XDR).
+
+The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
+For C<unpack> the length of the string is obtained from the I<length-item>,
+but if you put in the '*' it will be ignored.
+
+    unpack 'C#a', "\04Gurusamy";        gives 'Guru'
+    unpack 'a3#A* A*', '007 Bond  J ';  gives (' Bond','J')
+    pack 'n#a* w#a*','hello,','world';  gives "\000\006hello,\005world"
+
+The I<length-item> is not returned explicitly from C<unpack>.
+
+Adding a count to the I<length-item> letter
+is unlikely to do anything useful,
+unless that letter is C<"A">, C<"a"> or C<"Z">.
+Packing with a I<length-item> of C<"a"> or C<"Z">
+may introduce C<"\000"> characters,
+which Perl does not regard as legal in numeric strings.
+
+=item *
+
 The integer types C<"s">, C<"S">, C<"l">, and C<"L"> may be
-immediately followed by a C<"!"> to signify native shorts or longs--as
-you can see from above for example a bare C<"l"> does mean exactly 32
-bits, the native C<long> (as seen by the local C compiler) may be
-larger.  This is an issue mainly in 64-bit platforms.  You can see
-whether using C<"!"> makes any difference by
+immediately followed by a C<"!"> suffix to signify native shorts or
+longs--as you can see from above for example a bare C<"l"> does mean
+exactly 32 bits, the native C<long> (as seen by the local C compiler)
+may be larger.  This is an issue mainly in 64-bit platforms.  You can
+see whether using C<"!"> makes any difference by
 
        print length(pack("s")), " ", length(pack("s!")), "\n";
        print length(pack("l")), " ", length(pack("l!")), "\n";
@@ -2766,9 +2851,6 @@ whether using C<"!"> makes any difference by
 C<"i!"> and C<"I!"> also work but only because of completeness;
 they are identical to C<"i"> and C<"I">.
 
-The actual sizes (in bytes) of native shorts, ints, and longs on
-the platform where Perl was built are also available via L<Config>:
-
 The actual sizes (in bytes) of native shorts, ints, longs, and long
 longs on the platform where Perl was built are also available via
 L<Config>:
@@ -2779,6 +2861,9 @@ L<Config>:
        print $Config{longsize},     "\n";
        print $Config{longlongsize}, "\n";
 
+(The C<$Config{longlongsize}> will be empty if your system does
+not support long longs.) 
+
 =item *
 
 The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L">
@@ -2821,6 +2906,7 @@ 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.
+See also L<perlport>.
 
 =item *
 
@@ -2830,13 +2916,21 @@ 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).
+of the IEEE spec).  See also L<perlport>.
 
 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 $foo).
 
+=item *
+
+You must yourself do any alignment or padding by inserting for example
+enough C<'x'>es while packing.  There is no way to pack() and unpack()
+could know where the bytes are going to or coming from.  Therefore
+C<pack> (and C<unpack>) handle their output and input as flat
+sequences of bytes.
+
 =back
 
 Examples:
@@ -2851,6 +2945,11 @@ Examples:
     $foo = pack("ccxxcc",65,66,67,68);
     # foo eq "AB\0\0CD"
 
+    # note: the above examples featuring "C" and "c" are true
+    # only on ASCII and ASCII-derived systems such as ISO Latin 1
+    # and UTF-8.  In EBCDIC the first example would be
+    # $foo = pack("CCCC",193,194,195,196);
+
     $foo = pack("s2",1,2);
     # "\1\0\2\0" on little-endian
     # "\0\1\0\2" on big-endian
@@ -2878,6 +2977,12 @@ Examples:
        unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
     }
 
+    $foo = pack('sx2l', 12, 34);
+    # short 12, two zero bytes padding, long 34
+    $bar = pack('s@4l', 12, 34);
+    # short 12, zero fill to position 4, long 34
+    # $foo eq $bar
+
 The same template may generally also be used in unpack().
 
 =item package 
@@ -3394,10 +3499,12 @@ See L<perlop> for more details on unary operators and the comma operator.
 Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
 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 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 C<1> upon success, C<0> otherwise.
+POSITION, C<1> to set 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>
+(start of the file, current position, end of the file) from any of the
+modules Fcntl, C<IO::Seekable>, or POSIX.  Returns C<1> upon success,
+C<0> otherwise.
 
 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
@@ -3665,8 +3772,9 @@ however, because your process might not be scheduled right away in a
 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.
+C<syscall> interface to access setitimer(2) if your system supports
+it, or else see L</select> above.  The Time::HiRes module from CPAN
+may also help.
 
 See also the POSIX module's C<sigpause> function.
 
@@ -3996,6 +4104,7 @@ and the conversion letter:
            for integer
    l       interpret integer as C type "long" or "unsigned long"
    h       interpret integer as C type "short" or "unsigned short"
+           If no flags, interpret integer as C type "int" or "unsigned"
 
 There is also one Perl-specific flag:
 
@@ -4011,6 +4120,44 @@ If C<use locale> is in effect, the character used for the decimal
 point in formatted real numbers is affected by the LC_NUMERIC locale.
 See L<perllocale>.
 
+If Perl understands "quads" (64-bit integers) (this requires
+either that the platform natively supports quads or that Perl
+has been specifically compiled to support quads), the characters
+
+       d u o x X b i D U O
+
+print quads, and they may optionally be preceded by
+
+       ll L q
+
+For example
+
+       %lld %16LX %qo
+
+You can find out whether your Perl supports quads via L<Config>:
+
+       use Config;
+       ($Config{use64bits} eq 'define' || $Config{longsize} == 8) &&
+               print "quads\n";
+
+If Perl understands "long doubles" (this requires that the platform
+supports long doubles), the flags
+
+       e f g E F G
+
+may optionally be preceded by
+
+       ll L
+
+For example
+
+       %llf %Lg
+
+You can find out whether your Perl supports long doubles via L<Config>:
+
+       use Config;
+       $Config{d_longdbl} eq 'define' && print "long doubles\n";
+
 =item sqrt EXPR
 
 =item sqrt
@@ -4195,10 +4342,10 @@ out the names of those files that contain a match:
 =item sub NAME BLOCK
 
 This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes), it's just a forward declaration.  Without
-a NAME, it's an anonymous function declaration, and does actually return a
-value: the CODE ref of the closure you just created.  See L<perlsub> and
-L<perlref> for details.
+NAME (and possibly prototypes or attributes), it's just a forward declaration.
+Without a NAME, it's an anonymous function declaration, and does actually
+return a value: the CODE ref of the closure you just created.  See L<perlsub>
+and L<perlref> for details.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 
@@ -4292,11 +4439,20 @@ FILENAME, MODE, PERMS.
 
 The possible values and flag bits of the MODE parameter are
 system-dependent; they are available via the standard module C<Fcntl>.
+See the documentation of your operating system's C<open> to see which
+values and flag bits are available.  You may combine several flags
+using the C<|>-operator.
+
+Some of the most common values are C<O_RDONLY> for opening the file in
+read-only mode, C<O_WRONLY> for opening the file in write-only mode,
+and C<O_RDWR> for opening the file in read-write mode, and.
+
 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 & VM/ESA Unix and on the Macintosh; you probably don't want to
-use them in new code.
+se them in new code, use thhe constants discussed in the preceding
+paragraph.
 
 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
@@ -4305,6 +4461,13 @@ 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>.
 
+In many systems the C<O_EXCL> flag is available for opening files in
+exclusive mode.  This is B<not> locking: exclusiveness means here that
+if the file already exists, sysopen() fails.  The C<O_EXCL> wins
+C<O_TRUNC>.
+
+Sometimes you may want to truncate an already-existing file: C<O_TRUNC>.
+
 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
@@ -4340,13 +4503,14 @@ for a return value for 0 to decide whether you're done.
 
 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>, 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.
+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 also use the constants C<SEEK_SET>, C<SEEK_CUR>, and
+C<SEEK_END> (start of the file, current position, end of the file)
+from any of the modules Fcntl, C<IO::Seekable>, or POSIX.
 
 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
@@ -4377,7 +4541,8 @@ The return value is the exit status of the program as
 returned by the C<wait> call.  To get the actual exit value divide by
 256.  See also L</exec>.  This is I<not> what you want to use to capture
 the output from a command, for that you should use merely backticks or
-C<qx//>, as described in L<perlop/"`STRING`">.
+C<qx//>, as described in L<perlop/"`STRING`">.  Return value of -1
+indicates a failure to start the program (inspect $! for the reason).
 
 Like C<exec>, C<system> allows you to lie to a program about its name if
 you use the C<system PROGRAM LIST> syntax.  Again, see L</exec>.
@@ -4532,6 +4697,11 @@ considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
 and 00:00:00 UTC, January 1, 1970 for most other systems).
 Suitable for feeding to C<gmtime> and C<localtime>.
 
+For measuring time in better granularity than one second,
+you may use either the Time::HiRes module from CPAN, or
+if you have gettimeofday(2), you may be able to use the
+C<syscall> interface of Perl, see L<perlfaq8> for details.
+
 =item times
 
 Returns a four-element list giving the user and system times, in
@@ -4693,7 +4863,7 @@ has no way of checking whether the value passed to C<unpack()>
 corresponds to a valid memory location, passing a pointer value that's
 not known to be valid is likely to have disastrous consequences.
 
-See L</pack> for more examples.
+See L</pack> for more examples and notes.
 
 =item untie VARIABLE
 
@@ -4766,10 +4936,10 @@ are also implemented this way.  Currently implemented pragmas are:
 
     use integer;
     use diagnostics;
-    use sigtrap qw(SEGV BUS);
-    use strict  qw(subs vars refs);
-    use subs    qw(afunc blurfl);
-    use warning qw(all);
+    use sigtrap  qw(SEGV BUS);
+    use strict   qw(subs vars refs);
+    use subs     qw(afunc blurfl);
+    use warnings qw(all);
 
 Some of these pseudo-modules import semantics into the current
 block scope (like C<strict> or C<integer>, unlike ordinary modules,
@@ -4781,7 +4951,7 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
 
     no integer;
     no strict 'refs';
-    no warning;
+    no warnings;
 
 If no C<unimport> method can be found the call fails with a fatal error.
 
@@ -4792,7 +4962,7 @@ See L<perlmod> for a list of standard modules and pragmas.
 Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 and modification times, in that order.  Returns the number of files
-successfully changed.  The inode modification time of each file is set
+successfully changed.  The inode change time of each file is set
 to the current time.  This code has the same effect as the C<touch>
 command if the files already exist:
 
@@ -4822,17 +4992,20 @@ See also C<keys>, C<each>, and C<sort>.
 =item vec EXPR,OFFSET,BITS
 
 Treats the string in EXPR as a vector of unsigned integers, and
-returns the value of the bit field specified by OFFSET.  BITS specifies
-the number of bits that are reserved for each entry in the bit
-vector.  This must be a power of two from 1 to 32.  C<vec> may also be
-assigned to, in which case parentheses are needed to give the expression
-the correct precedence as in
+returns the value of the bit field specified by OFFSET.  BITS
+specifies the number of bits that are reserved for each entry in the
+bit vector.  This must be a power of two from 1 to 32 (or 64, if your
+platform supports that).
+
+C<vec> may also be assigned to, in which case parentheses are needed
+to give the expression the correct precedence as in
 
     vec($image, $max_x * $x + $y, 8) = 3;
 
 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.  See L<perlop/"Bitwise String Operators">.
+operators C<|>, C<&>, and C<^>, which will assume a bit vector
+operation is 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