various pod tweaks (from M.J.T. Guy <mjtg@cus.cam.ac.uk>)
[p5sagit/p5-mst-13.2.git] / pod / perlfunc.pod
index 13ada36..d8c82bb 100644 (file)
@@ -1412,6 +1412,9 @@ 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.
 
+See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
+used on a pseudo-hash.
+
 =item exit EXPR
 
 Evaluates EXPR and exits immediately with that value.    Example:
@@ -2064,7 +2067,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
 
@@ -2114,17 +2118,21 @@ as trying has no effect).
 
 See also C<each>, C<values> and C<sort>.
 
-=item kill LIST
+=item kill SIGNAL, LIST
 
-Sends a signal to a list of processes.  The first element of
-the list must be the signal to send.  Returns the number of
+Sends a signal to a list of processes.  Returns the number of
 processes successfully signaled (which is not necessarily the
 same as the number actually killed).
 
     $cnt = kill 1, $child1, $child2;
     kill 9, @goners;
 
-Unlike in the shell, in Perl if the I<SIGNAL> is negative, it kills
+If SIGNAL is zero, no signal is sent to the process.  This is a
+useful way to check that the process is alive and hasn't changed
+its UID.  See L<perlport> for notes on the portability of this
+construct.
+
+Unlike in the shell, if SIGNAL is negative, it kills
 process groups instead of processes.  (On System V, a negative I<PROCESS>
 number will also kill process groups, but that's not portable.)  That
 means you usually want to use positive not negative signals.  You may also
@@ -2148,6 +2156,10 @@ 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.
 
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus C<last> can be used to effect an early
+exit out of such a block.
+
 See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
@@ -2366,6 +2378,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
@@ -2391,6 +2405,9 @@ 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.
 
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus C<next> will exit such a block early.
+
 See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
@@ -2697,10 +2714,27 @@ Returns the numeric (ASCII or Unicode) value of the first character of EXPR.  If
 EXPR is omitted, uses C<$_>.  For the reverse, see L</chr>.
 See L<utf8> for more about Unicode.
 
+=item our EXPR
+
+An C<our> declares the listed variables to be valid globals within
+the enclosing block, file, or C<eval>.  That is, it has the same
+scoping rules as a "my" declaration, but does not create a local
+variable.  If more than one value is listed, the list must be placed
+in parentheses.  The C<our> declaration has no semantic effect unless
+"use strict vars" is in effect, in which case it lets you use the
+declared global variable without qualifying it with a package name.
+(But only within the lexical scope of the C<our> declaration.  In this
+it differs from "use vars", which is package scoped.)
+
 =item pack TEMPLATE,LIST
 
-Takes a list of values and packs it into a binary structure,
-returning the string containing the structure.  The TEMPLATE is a
+Takes a LIST of values and converts it into a string using the rules
+given by the TEMPLATE.  The resulting string is the concatenation of
+the converted values.  Typically, each converted value looks
+like its machine-level representation.  For example, on 32-bit machines
+a converted integer may be represented by a sequence of 4 bytes.
+
+The TEMPLATE is a
 sequence of characters that give the order and type of values, as
 follows:
 
@@ -2708,8 +2742,8 @@ follows:
     A  An ascii string, will be space 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).
+    b  A bit string (ascending bit order inside each byte, like vec()).
+    B  A bit string (descending bit order inside each byte).
     h  A hex string (low nybble first).
     H  A hex string (high nybble first).
 
@@ -2777,18 +2811,46 @@ Each letter may optionally be followed by a number giving a repeat
 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.
+left, except for C<"@">, C<"x">, C<"X">, where it is equivalent
+to C<"0">, and C<"u">, where it is equivalent to 1 (or 45, what is the
+same).
+
+When used with C<"Z">, C<*> results in the addition of a trailing null
+byte (so the packed result will be one longer than the byte C<length>
+of the item).
+
+The repeat count for C<"u"> is interpreted as the maximal number of bytes
+to encode per line of output, with 0 and 1 replaced by 45.
 
 =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.
+after the first null, and C<"a"> returns data verbatim.  When packing,
+C<"a">, and C<"Z"> are equivalent.
+
+If the value-to-pack is too long, it is truncated.  If too long and an
+explicit count is provided, C<"Z"> packs only C<$count-1> bytes, followed
+by a null byte.  Thus C<"Z"> always packs a trailing null byte under
+all circumstances.
 
 =item *
 
 Likewise, the C<"b"> and C<"B"> fields pack a string that many bits long.
+Each byte of the input field generates 1 bit of the result basing on
+the least-signifant bit of each input byte, i.e., on C<ord($byte)%2>.
+In particular, bytes C<"0"> and C<"1"> generate bits 0 and 1.
+
+Starting from the beginning of the input string, each 8-tuple of bytes
+is converted to 1 byte of output.  If the length of the input string
+is not divisible by 8, the remainder is packed as if padded by 0s.
+Similarly, during unpack()ing the "extra" bits are ignored.
+
+If the input string is longer than needed, extra bytes are ignored.
+A C<*> for the repeat count of pack() means to use all the bytes of
+the input field.  On unpack()ing the bits are converted to a string
+of C<"0">s and C<"1">s.
 
 =item *
 
@@ -2802,13 +2864,13 @@ 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>.
+C<"P"> is C<undef>, similarly for unpack().
 
 =item *
 
-The C<"#"> character allows packing and unpacking of strings where the
+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>.
+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.
@@ -2820,9 +2882,9 @@ 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"
+    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>.
 
@@ -2858,7 +2920,7 @@ L<Config>:
        print $Config{longsize},     "\n";
        print $Config{longlongsize}, "\n";
 
-(The C<$Config{longlongsize}> will be empty if your system does
+(The C<$Config{longlongsize}> will be undefine if your system does
 not support long longs.) 
 
 =item *
@@ -2866,7 +2928,7 @@ not support long longs.)
 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
+4-byte integer 0x12345678 (305419896 decimal) be ordered natively
 (arranged in and handled by the CPU registers) into bytes as
  
        0x12 0x34 0x56 0x78     # little-endian
@@ -2882,7 +2944,7 @@ 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 Lilliputians.
  
-Some systems may even have weird byte orders such as
+Some systems may have even weirder byte orders such as
  
        0x56 0x78 0x12 0x34
        0x34 0x12 0x78 0x56
@@ -2928,6 +2990,16 @@ 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.
 
+=item *
+
+A comment in a TEMPLATE starts with C<#> and goes to the end of line.
+
+=item *
+
+If TEMPLATE requires more arguments to pack() than actually given, pack()
+assumes additional C<""> arguments.  If TEMPLATE requires less arguments
+to pack() than actually given, extra arguments are ignored.
+
 =back
 
 Examples:
@@ -3228,12 +3300,13 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
 =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.
-Actually does a C C<recvfrom>, so that it can return the address of the
-sender.  Returns the undefined value if there's an error.  SCALAR will
-be grown or shrunk to the length actually read.  Takes the same flags
-as the system call of the same name.
-See L<perlipc/"UDP: Message Passing"> for examples.
+data into variable SCALAR from the specified SOCKET filehandle.  SCALAR
+will be grown or shrunk to the length actually read.  Takes the same
+flags as the system call of the same name.  Returns the address of the
+sender if SOCKET's protocol supports this; returns an empty string
+otherwise.  If there's an error, returns the undefined value.  This call
+is actually implemented in terms of recvfrom(2) system call.  See
+L<perlipc/"UDP: Message Passing"> for examples.
 
 =item redo LABEL
 
@@ -3266,6 +3339,10 @@ 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.
 
+Note that a block by itself is semantically identical to a loop
+that executes once.  Thus C<redo> inside such a block will effectively
+turn it into a looping construct.
+
 See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
@@ -3496,10 +3573,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
@@ -3662,9 +3741,10 @@ See L<perlipc/"UDP: Message Passing"> for examples.
 
 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 C<setpgrp(0,0)> is portable.  See also C<POSIX::setsid()>.
+implement POSIX setpgid(2) or BSD setpgrp(2).  If the arguments are omitted,
+it defaults to C<0,0>.  Note that the BSD 4.2 version of C<setpgrp> does not
+accept any arguments, so only C<setpgrp(0,0)> is portable.  See also
+C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
 
@@ -4099,6 +4179,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:
 
@@ -4114,6 +4195,51 @@ 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>.
 
+To cope with broken systems that allow the standard locales to be
+overridden by malicious users, the return value may be tainted
+if any of the floating point formats are used and the conversion
+yields something that doesn't look like a normal C-locale floating
+point number.  This happens regardless of whether C<use locale> is
+in effect or not.
+
+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
@@ -4298,10 +4424,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
 
@@ -4395,11 +4521,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
@@ -4408,6 +4543,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
@@ -4443,13 +4585,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
@@ -4769,8 +4912,14 @@ If LIST is omitted, uses C<$_>.
 =item unpack TEMPLATE,EXPR
 
 C<unpack> does the reverse of C<pack>: it takes a string
-representing a structure and expands it out into a list of values.
+and expands it out into a list of values.
 (In scalar context, it returns merely the first value produced.)
+
+The string is broken into chunks described by the TEMPLATE.  Each chunk
+is converted separately to a value.  Typically, either the string is a result
+of C<pack>, or the bytes of the string represent a C structure of some
+kind.
+
 The TEMPLATE has the same format as in the C<pack> function.
 Here's a subroutine that does substring:
 
@@ -4783,9 +4932,14 @@ and then there's
 
     sub ordinal { unpack("c",$_[0]); } # same as ord()
 
-In addition, you may prefix a field with a %E<lt>numberE<gt> to indicate that
+In addition to fields allowed in pack(), you may prefix a field with
+a %E<lt>numberE<gt> to indicate that
 you want a E<lt>numberE<gt>-bit checksum of the items instead of the items
-themselves.  Default is a 16-bit checksum.  For example, the following
+themselves.  Default is a 16-bit checksum.  Checksum is calculated by
+summing numeric values of expanded values (for string fields the sum of
+C<ord($char)> is taken, for bit fields the sum of zeroes and ones).
+
+For example, the following
 computes the same number as the System V sum program:
 
     $checksum = do {
@@ -4802,6 +4956,10 @@ 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.
 
+If the repeat count of a field is larger than what the remainder of
+the input string allows, repeat count is decreased.  If the input string
+is longer than one described by the TEMPLATE, the rest is ignored. 
+
 See L</pack> for more examples and notes.
 
 =item untie VARIABLE
@@ -4875,10 +5033,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,
@@ -4890,7 +5048,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.
 
@@ -4930,18 +5088,22 @@ 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
+Treats the string in EXPR as a bit vector made up of elements of
+width BITS, and returns the value of the element specified by OFFSET
+as an unsigned integer.  BITS therefore specifies the number of bits
+that are reserved for each element 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
@@ -4949,6 +5111,10 @@ in the same way on big-endian or little-endian machines.
 
     my $foo = '';
     vec($foo,  0, 32) = 0x5065726C;    # 'Perl'
+
+    # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
+    print vec($foo, 0, 8);             # prints 80 == 0x50 == ord('P')
+
     vec($foo,  2, 16) = 0x5065;                # 'PerlPe'
     vec($foo,  3, 16) = 0x726C;                # 'PerlPerl'
     vec($foo,  8,  8) = 0x50;          # 'PerlPerlP'
@@ -4968,6 +5134,171 @@ To transform a bit vector into a string or list of 0's and 1's, use these:
 
 If you know the exact length in bits, it can be used in place of the C<*>.
 
+Here is an example to illustrate how the bits actually fall in place:
+
+    #!/usr/bin/perl -wl
+
+    print <<'EOT';
+                                      0         1         2         3  
+                       unpack("V",$_) 01234567890123456789012345678901
+    ------------------------------------------------------------------
+    EOT
+
+    for $w (0..3) {
+        $width = 2**$w;
+        for ($shift=0; $shift < $width; ++$shift) {
+            for ($off=0; $off < 32/$width; ++$off) {
+                $str = pack("B*", "0"x32);
+                $bits = (1<<$shift);
+                vec($str, $off, $width) = $bits;
+                $res = unpack("b*",$str);
+                $val = unpack("V", $str);
+                write;
+            }
+        }
+    }
+
+    format STDOUT =
+    vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+    $off, $width, $bits, $val, $res
+    .
+    __END__
+
+Regardless of the machine architecture on which it is run, the above
+example should print the following table:
+
+                                      0         1         2         3  
+                       unpack("V",$_) 01234567890123456789012345678901
+    ------------------------------------------------------------------
+    vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
+    vec($_, 1, 1) = 1   ==          2 01000000000000000000000000000000
+    vec($_, 2, 1) = 1   ==          4 00100000000000000000000000000000
+    vec($_, 3, 1) = 1   ==          8 00010000000000000000000000000000
+    vec($_, 4, 1) = 1   ==         16 00001000000000000000000000000000
+    vec($_, 5, 1) = 1   ==         32 00000100000000000000000000000000
+    vec($_, 6, 1) = 1   ==         64 00000010000000000000000000000000
+    vec($_, 7, 1) = 1   ==        128 00000001000000000000000000000000
+    vec($_, 8, 1) = 1   ==        256 00000000100000000000000000000000
+    vec($_, 9, 1) = 1   ==        512 00000000010000000000000000000000
+    vec($_,10, 1) = 1   ==       1024 00000000001000000000000000000000
+    vec($_,11, 1) = 1   ==       2048 00000000000100000000000000000000
+    vec($_,12, 1) = 1   ==       4096 00000000000010000000000000000000
+    vec($_,13, 1) = 1   ==       8192 00000000000001000000000000000000
+    vec($_,14, 1) = 1   ==      16384 00000000000000100000000000000000
+    vec($_,15, 1) = 1   ==      32768 00000000000000010000000000000000
+    vec($_,16, 1) = 1   ==      65536 00000000000000001000000000000000
+    vec($_,17, 1) = 1   ==     131072 00000000000000000100000000000000
+    vec($_,18, 1) = 1   ==     262144 00000000000000000010000000000000
+    vec($_,19, 1) = 1   ==     524288 00000000000000000001000000000000
+    vec($_,20, 1) = 1   ==    1048576 00000000000000000000100000000000
+    vec($_,21, 1) = 1   ==    2097152 00000000000000000000010000000000
+    vec($_,22, 1) = 1   ==    4194304 00000000000000000000001000000000
+    vec($_,23, 1) = 1   ==    8388608 00000000000000000000000100000000
+    vec($_,24, 1) = 1   ==   16777216 00000000000000000000000010000000
+    vec($_,25, 1) = 1   ==   33554432 00000000000000000000000001000000
+    vec($_,26, 1) = 1   ==   67108864 00000000000000000000000000100000
+    vec($_,27, 1) = 1   ==  134217728 00000000000000000000000000010000
+    vec($_,28, 1) = 1   ==  268435456 00000000000000000000000000001000
+    vec($_,29, 1) = 1   ==  536870912 00000000000000000000000000000100
+    vec($_,30, 1) = 1   == 1073741824 00000000000000000000000000000010
+    vec($_,31, 1) = 1   == 2147483648 00000000000000000000000000000001
+    vec($_, 0, 2) = 1   ==          1 10000000000000000000000000000000
+    vec($_, 1, 2) = 1   ==          4 00100000000000000000000000000000
+    vec($_, 2, 2) = 1   ==         16 00001000000000000000000000000000
+    vec($_, 3, 2) = 1   ==         64 00000010000000000000000000000000
+    vec($_, 4, 2) = 1   ==        256 00000000100000000000000000000000
+    vec($_, 5, 2) = 1   ==       1024 00000000001000000000000000000000
+    vec($_, 6, 2) = 1   ==       4096 00000000000010000000000000000000
+    vec($_, 7, 2) = 1   ==      16384 00000000000000100000000000000000
+    vec($_, 8, 2) = 1   ==      65536 00000000000000001000000000000000
+    vec($_, 9, 2) = 1   ==     262144 00000000000000000010000000000000
+    vec($_,10, 2) = 1   ==    1048576 00000000000000000000100000000000
+    vec($_,11, 2) = 1   ==    4194304 00000000000000000000001000000000
+    vec($_,12, 2) = 1   ==   16777216 00000000000000000000000010000000
+    vec($_,13, 2) = 1   ==   67108864 00000000000000000000000000100000
+    vec($_,14, 2) = 1   ==  268435456 00000000000000000000000000001000
+    vec($_,15, 2) = 1   == 1073741824 00000000000000000000000000000010
+    vec($_, 0, 2) = 2   ==          2 01000000000000000000000000000000
+    vec($_, 1, 2) = 2   ==          8 00010000000000000000000000000000
+    vec($_, 2, 2) = 2   ==         32 00000100000000000000000000000000
+    vec($_, 3, 2) = 2   ==        128 00000001000000000000000000000000
+    vec($_, 4, 2) = 2   ==        512 00000000010000000000000000000000
+    vec($_, 5, 2) = 2   ==       2048 00000000000100000000000000000000
+    vec($_, 6, 2) = 2   ==       8192 00000000000001000000000000000000
+    vec($_, 7, 2) = 2   ==      32768 00000000000000010000000000000000
+    vec($_, 8, 2) = 2   ==     131072 00000000000000000100000000000000
+    vec($_, 9, 2) = 2   ==     524288 00000000000000000001000000000000
+    vec($_,10, 2) = 2   ==    2097152 00000000000000000000010000000000
+    vec($_,11, 2) = 2   ==    8388608 00000000000000000000000100000000
+    vec($_,12, 2) = 2   ==   33554432 00000000000000000000000001000000
+    vec($_,13, 2) = 2   ==  134217728 00000000000000000000000000010000
+    vec($_,14, 2) = 2   ==  536870912 00000000000000000000000000000100
+    vec($_,15, 2) = 2   == 2147483648 00000000000000000000000000000001
+    vec($_, 0, 4) = 1   ==          1 10000000000000000000000000000000
+    vec($_, 1, 4) = 1   ==         16 00001000000000000000000000000000
+    vec($_, 2, 4) = 1   ==        256 00000000100000000000000000000000
+    vec($_, 3, 4) = 1   ==       4096 00000000000010000000000000000000
+    vec($_, 4, 4) = 1   ==      65536 00000000000000001000000000000000
+    vec($_, 5, 4) = 1   ==    1048576 00000000000000000000100000000000
+    vec($_, 6, 4) = 1   ==   16777216 00000000000000000000000010000000
+    vec($_, 7, 4) = 1   ==  268435456 00000000000000000000000000001000
+    vec($_, 0, 4) = 2   ==          2 01000000000000000000000000000000
+    vec($_, 1, 4) = 2   ==         32 00000100000000000000000000000000
+    vec($_, 2, 4) = 2   ==        512 00000000010000000000000000000000
+    vec($_, 3, 4) = 2   ==       8192 00000000000001000000000000000000
+    vec($_, 4, 4) = 2   ==     131072 00000000000000000100000000000000
+    vec($_, 5, 4) = 2   ==    2097152 00000000000000000000010000000000
+    vec($_, 6, 4) = 2   ==   33554432 00000000000000000000000001000000
+    vec($_, 7, 4) = 2   ==  536870912 00000000000000000000000000000100
+    vec($_, 0, 4) = 4   ==          4 00100000000000000000000000000000
+    vec($_, 1, 4) = 4   ==         64 00000010000000000000000000000000
+    vec($_, 2, 4) = 4   ==       1024 00000000001000000000000000000000
+    vec($_, 3, 4) = 4   ==      16384 00000000000000100000000000000000
+    vec($_, 4, 4) = 4   ==     262144 00000000000000000010000000000000
+    vec($_, 5, 4) = 4   ==    4194304 00000000000000000000001000000000
+    vec($_, 6, 4) = 4   ==   67108864 00000000000000000000000000100000
+    vec($_, 7, 4) = 4   == 1073741824 00000000000000000000000000000010
+    vec($_, 0, 4) = 8   ==          8 00010000000000000000000000000000
+    vec($_, 1, 4) = 8   ==        128 00000001000000000000000000000000
+    vec($_, 2, 4) = 8   ==       2048 00000000000100000000000000000000
+    vec($_, 3, 4) = 8   ==      32768 00000000000000010000000000000000
+    vec($_, 4, 4) = 8   ==     524288 00000000000000000001000000000000
+    vec($_, 5, 4) = 8   ==    8388608 00000000000000000000000100000000
+    vec($_, 6, 4) = 8   ==  134217728 00000000000000000000000000010000
+    vec($_, 7, 4) = 8   == 2147483648 00000000000000000000000000000001
+    vec($_, 0, 8) = 1   ==          1 10000000000000000000000000000000
+    vec($_, 1, 8) = 1   ==        256 00000000100000000000000000000000
+    vec($_, 2, 8) = 1   ==      65536 00000000000000001000000000000000
+    vec($_, 3, 8) = 1   ==   16777216 00000000000000000000000010000000
+    vec($_, 0, 8) = 2   ==          2 01000000000000000000000000000000
+    vec($_, 1, 8) = 2   ==        512 00000000010000000000000000000000
+    vec($_, 2, 8) = 2   ==     131072 00000000000000000100000000000000
+    vec($_, 3, 8) = 2   ==   33554432 00000000000000000000000001000000
+    vec($_, 0, 8) = 4   ==          4 00100000000000000000000000000000
+    vec($_, 1, 8) = 4   ==       1024 00000000001000000000000000000000
+    vec($_, 2, 8) = 4   ==     262144 00000000000000000010000000000000
+    vec($_, 3, 8) = 4   ==   67108864 00000000000000000000000000100000
+    vec($_, 0, 8) = 8   ==          8 00010000000000000000000000000000
+    vec($_, 1, 8) = 8   ==       2048 00000000000100000000000000000000
+    vec($_, 2, 8) = 8   ==     524288 00000000000000000001000000000000
+    vec($_, 3, 8) = 8   ==  134217728 00000000000000000000000000010000
+    vec($_, 0, 8) = 16  ==         16 00001000000000000000000000000000
+    vec($_, 1, 8) = 16  ==       4096 00000000000010000000000000000000
+    vec($_, 2, 8) = 16  ==    1048576 00000000000000000000100000000000
+    vec($_, 3, 8) = 16  ==  268435456 00000000000000000000000000001000
+    vec($_, 0, 8) = 32  ==         32 00000100000000000000000000000000
+    vec($_, 1, 8) = 32  ==       8192 00000000000001000000000000000000
+    vec($_, 2, 8) = 32  ==    2097152 00000000000000000000010000000000
+    vec($_, 3, 8) = 32  ==  536870912 00000000000000000000000000000100
+    vec($_, 0, 8) = 64  ==         64 00000010000000000000000000000000
+    vec($_, 1, 8) = 64  ==      16384 00000000000000100000000000000000
+    vec($_, 2, 8) = 64  ==    4194304 00000000000000000000001000000000
+    vec($_, 3, 8) = 64  == 1073741824 00000000000000000000000000000010
+    vec($_, 0, 8) = 128 ==        128 00000001000000000000000000000000
+    vec($_, 1, 8) = 128 ==      32768 00000000000000010000000000000000
+    vec($_, 2, 8) = 128 ==    8388608 00000000000000000000000100000000
+    vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
+
 =item wait
 
 Behaves like the wait(2) system call on your system: it waits for a child