diff options
Diffstat (limited to 'pod/perlfunc.pod')
| -rw-r--r-- | pod/perlfunc.pod | 653 |
1 files changed, 521 insertions, 132 deletions
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 82c052148b..d730b43e47 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -515,12 +515,12 @@ to go back before the current one. ($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext, $is_require, $hints) = caller($i); -Here $subroutine may be C<"(eval)"> if the frame is not a subroutine +Here $subroutine may be C<(eval)> if the frame is not a subroutine call, but an C<eval>. In such a case additional elements $evaltext and C<$is_require> are set: C<$is_require> is true if the frame is created by a C<require> or C<use> statement, $evaltext contains the text of the C<eval EXPR> statement. In particular, for a C<eval BLOCK> statement, -$filename is C<"(eval)">, but $evaltext is undefined. (Note also that +$filename is C<(eval)>, but $evaltext is undefined. (Note also that each C<use> statement creates a C<require> frame inside an C<eval EXPR>) frame. C<$hints> contains pragmatic hints that the caller was compiled with. It currently only reflects the hint corresponding to @@ -669,7 +669,7 @@ If NUMBER is omitted, uses C<$_>. This function works like the system call by the same name: it makes the named directory the new root directory for all further pathnames that -begin with a C<"/"> by your process and all its children. (It doesn't +begin with a C</> by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is omitted, does a C<chroot> to C<$_>. @@ -925,35 +925,55 @@ See also L</undef>, L</exists>, L</ref>. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash. -For each key, returns the deleted value associated with that key, or -the undefined value if there was no such key. Deleting from C<$ENV{}> -modifies the environment. Deleting from a hash tied to a DBM file -deletes the entry from the DBM file. (But deleting from a C<tie>d hash -doesn't necessarily return anything.) +Given an expression that specifies a hash element, array element, hash slice, +or array slice, deletes the specified element(s) from the hash or array. +If the array elements happen to be at the end of the array, the size +of the array will shrink by that number of elements. -The following deletes all the values of a hash: +Returns each element so deleted or the undefined value if there was no such +element. Deleting from C<$ENV{}> modifies the environment. Deleting from +a hash tied to a DBM file deletes the entry from the DBM file. Deleting +from a C<tie>d hash or array may not necessarily return anything. + +Deleting an array element effectively returns that position of the array +to its initial, uninitialized state. Subsequently testing for the same +element with exists() will return false. See L</exists>. + +The following (inefficiently) deletes all the values of %HASH and @ARRAY: foreach $key (keys %HASH) { delete $HASH{$key}; } -And so does this: + foreach $index (0 .. $#ARRAY) { + delete $ARRAY[$index]; + } + +And so do these: - delete @HASH{keys %HASH} + delete @HASH{keys %HASH}; + + delete @ARRAY[0 .. $#ARRAY]; But both of these are slower than just assigning the empty list -or undefining it: +or undefining %HASH or @ARRAY: + + %HASH = (); # completely empty %HASH + undef %HASH; # forget %HASH ever existed - %hash = (); # completely empty %hash - undef %hash; # forget %hash every existed + @ARRAY = (); # completely empty @ARRAY + undef @ARRAY; # forget @ARRAY ever existed Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash element lookup or hash slice: +operation is a hash element, array element, hash slice, or array slice +lookup: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; + delete $ref->[$x][$y][$index]; + delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; + =item die LIST Outside an C<eval>, prints the value of LIST to C<STDERR> and @@ -1172,13 +1192,17 @@ interactive context.) Do not read from a terminal file (or call C<eof(FILEHANDLE)> on it) after end-of-file is reached. File types 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 -C<eof> without the parentheses to test I<each> file in a while -(E<lt>E<gt>) loop. Examples: +An C<eof> without an argument uses the last file read. Using C<eof()> +with empty parentheses is very different. It refers to the pseudo file +formed from the files listed on the command line and accessed via the +C<E<lt>E<gt>> operator. Since C<E<lt>E<gt>> isn't explicitly opened, +as a normal filehandle is, an C<eof()> before C<E<lt>E<gt>> has been +used will cause C<@ARGV> to be examined to determine if input is +available. + +In a C<while (E<lt>E<gt>)> loop, C<eof> or C<eof(ARGV)> can be used to +detect the end of each file, C<eof()> will only detect the end of the +last file. Examples: # reset line numbering on each input file while (<>) { @@ -1199,8 +1223,8 @@ C<eof> without the parentheses to test I<each> file in a while } Practical hint: you almost never need to use C<eof> in Perl, because the -input operators return false values when they run out of data, or if there -was an error. +input operators typically return C<undef> when they run out of data, or if +there was an error. =item eval EXPR @@ -1382,27 +1406,36 @@ any C<DESTROY> methods in your objects. =item exists EXPR -Returns true if the specified hash key exists in its hash, even -if the corresponding value is undefined. +Given an expression that specifies a hash element or array element, +returns true if the specified element in the hash or array has ever +been initialized, even if the corresponding value is undefined. The +element is not autovivified if it doesn't exist. - 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 $hash{$key}; + print "Defined\n" if defined $hash{$key}; + print "True\n" if $hash{$key}; -A hash element can be true only if it's defined, and defined if + print "Exists\n" if exists $array[$index]; + print "Defined\n" if defined $array[$index]; + print "True\n" if $array[$index]; + +A hash or array element can be true only if it's defined, and defined if 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: +operation is a hash or array key lookup: 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"}> -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 + if (exists $ref->{A}->{B}->[$ix]) { } + if (exists $hash{A}{B}[$ix]) { } + +Although the deepest nested array or hash will not spring into existence +just because its existence was tested, any 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 the $key element above. +This happens anywhere the arrow operator is used, including even: undef $ref; if (exists $ref->{"Some key"}) { } @@ -1412,6 +1445,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: @@ -1459,8 +1495,8 @@ For example: 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> +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. @@ -1881,6 +1917,14 @@ 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? +The proper way to get a complete 4-digit year is simply: + + $year += 1900; + +And to get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + If EXPR is omitted, does C<gmtime(time())>. In scalar context, returns the ctime(3) value: @@ -1926,13 +1970,20 @@ necessarily recommended if you're optimizing for maintainability: goto ("FOO", "BAR", "GLARCH")[$i]; -The C<goto-&NAME> form is highly magical, and substitutes a call to the -named subroutine for the currently running subroutine. This is used by -C<AUTOLOAD> subroutines that wish to load another subroutine and then -pretend that the other subroutine had been called in the first place -(except that any modifications to C<@_> in the current subroutine are -propagated to the other subroutine.) After the C<goto>, not even C<caller> -will be able to tell that this routine was called first. +The C<goto-&NAME> form is quite different from the other forms of C<goto>. +In fact, it isn't a goto in the normal sense at all, and doesn't have +the stigma associated with other gotos. Instead, it +substitutes a call to the named subroutine for the currently running +subroutine. This is used by C<AUTOLOAD> subroutines that wish to load +another subroutine and then pretend that the other subroutine had been +called in the first place (except that any modifications to C<@_> +in the current subroutine are propagated to the other subroutine.) +After the C<goto>, not even C<caller> will be able to tell that this +routine was called first. + +NAME needn't be the name of a subroutine; it can be a scalar variable +containing a code reference, or a block which evaluates to a code +reference. =item grep BLOCK LIST @@ -1975,7 +2026,7 @@ L</oct>.) If EXPR is omitted, uses C<$_>. print hex 'aF'; # same Hex strings may only represent integers. Strings that would cause -integer overflow trigger a mandatory error message. +integer overflow trigger a warning. =item import @@ -2115,17 +2166,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 @@ -2149,6 +2204,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. @@ -2221,6 +2280,14 @@ 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? +The proper way to get a complete 4-digit year is simply: + + $year += 1900; + +And to get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + If EXPR is omitted, uses the current time (C<localtime(time)>). In scalar context, returns the ctime(3) value: @@ -2338,8 +2405,8 @@ Calls the System V IPC function msgctl(2). You'll probably have to say first to get the correct constant definitions. If CMD is C<IPC_STAT>, then ARG must be a variable which will hold the returned C<msqid_ds> -structure. Returns like C<ioctl>: the undefined value for error, C<"0 but -true"> for zero, or the actual return value otherwise. See also +structure. Returns like C<ioctl>: the undefined value for error, +C<"0 but true"> for zero, or the actual return value otherwise. See also C<IPC::SysV> and C<IPC::Semaphore> documentation. =item msgget KEY,FLAGS @@ -2394,6 +2461,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. @@ -2588,6 +2658,12 @@ parsimonious of file descriptors. For example: open(FILEHANDLE, "<&=$fd") +Note that this feature depends on the fdopen() C library function. +On many UNIX systems, fdopen() is known to fail when file descriptors +exceed a certain value, typically 255. If you need more file +descriptors than that, consider rebuilding Perl to use the C<sfio> +library. + 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 @@ -2712,10 +2788,43 @@ 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.) +An C<our> declaration declares a global variable that will be visible +across its entire lexical scope, even across package boundaries. The +package in which the variable is entered is determined at the point +of the declaration, not at the point of use. This means the following +behavior holds: + + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + print $bar; # prints 20 + +Multiple C<our> declarations in the same lexical scope are allowed +if they are in different packages. If they happened to be in the same +package, Perl will emit warnings if you have asked for them. + + use warnings; + package Foo; + our $bar; # declares $Foo::bar for rest of lexical scope + $bar = 20; + + package Bar; + our $bar = 30; # declares $Bar::bar for rest of lexical scope + print $bar; # prints 30 + + our $bar; # emits warning + =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: @@ -2723,8 +2832,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). @@ -2750,10 +2859,10 @@ follows: 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. - v A short in "VAX" (little-endian) order. - V A long in "VAX" (little-endian) order. + n An unsigned short in "network" (big-endian) order. + N An unsigned long in "network" (big-endian) order. + v An unsigned short in "VAX" (little-endian) order. + V An unsigned long in "VAX" (little-endian) order. (These 'shorts' and 'longs' are _exactly_ 16 bits and _exactly_ 32 bits, respectively.) @@ -2789,47 +2898,105 @@ The following rules apply: =item * 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 +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 +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. +unpacking, C<A> strips trailing spaces and nulls, C<Z> strips everything +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. +Likewise, the C<b> and C<B> fields pack a string that many bits long. +Each byte of the input field of pack() generates 1 bit of the result. +Each result bit is based on the least-significant bit of the corresponding +input byte, i.e., on C<ord($byte)%2>. In particular, bytes C<"0"> and +C<"1"> generate bits 0 and 1, as do bytes C<"\0"> and C<"\1">. + +Starting from the beginning of the input string of pack(), each 8-tuple +of bytes is converted to 1 byte of output. With format C<b> +the first byte of the 8-tuple determines the least-significant bit of a +byte, and with format C<B> it determines the most-significant bit of +a byte. + +If the length of the input string is not exactly divisible by 8, the +remainder is packed as if the input string were padded by null bytes +at the end. Similarly, during unpack()ing the "extra" bits are ignored. + +If the input string of pack() 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 * -The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups, +The C<h> and C<H> fields pack a string that many nybbles (4-bit groups, representable as hexadecimal digits, 0-9a-f) long. +Each byte of the input field of pack() generates 4 bits of the result. +For non-alphabetical bytes the result is based on the 4 least-significant +bits of the input byte, i.e., on C<ord($byte)%16>. In particular, +bytes C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes +C<"\0"> and C<"\1">. For bytes C<"a".."f"> and C<"A".."F"> the result +is compatible with the usual hexadecimal digits, so that C<"a"> and +C<"A"> both generate the nybble C<0xa==10>. The result for bytes +C<"g".."z"> and C<"G".."Z"> is not well-defined. + +Starting from the beginning of the input string of pack(), each pair +of bytes is converted to 1 byte of output. With format C<h> the +first byte of the pair determines the least-significant nybble of the +output byte, and with format C<H> it determines the most-significant +nybble. + +If the length of the input string is not even, it behaves as if padded +by a null byte at the end. Similarly, during unpack()ing the "extra" +nybbles are ignored. + +If the input string of pack() 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 hexadecimal digits. + =item * -The C<"p"> type packs a pointer to a null-terminated string. You are +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>. +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>, similarly for unpack(). =item * -The C<"/"> character allows packing and unpacking of strings where the -packed structure contains a byte count followed by the string itself. +The C</> template 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). +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>, @@ -2841,27 +3008,25 @@ but if you put in the '*' it will be ignored. 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, +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<"!"> suffix to signify native shorts or -longs--as you can see from above for example a bare C<"l"> does mean +The integer types C<s>, C<S>, C<l>, and C<L> may be +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 +see whether using C<!> makes any difference by print length(pack("s")), " ", length(pack("s!")), "\n"; print length(pack("l")), " ", length(pack("l!")), "\n"; -C<"i!"> and C<"I!"> also work but only because of completeness; -they are identical to C<"i"> and C<"I">. +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, longs, and long longs on the platform where Perl was built are also available via @@ -2878,7 +3043,7 @@ not support long longs.) =item * -The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L"> +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 0x12345678 (305419896 decimal) be ordered natively @@ -2887,7 +3052,7 @@ because they obey the native byteorder and endianness. For example a 0x12 0x34 0x56 0x78 # little-endian 0x78 0x56 0x34 0x12 # big-endian -Basically, the Intel, Alpha, and VAX CPUs and little-endian, while +Basically, the Intel, Alpha, and VAX CPUs are 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. @@ -2916,8 +3081,8 @@ via L<Config>: 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. +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 * @@ -2947,6 +3112,12 @@ sequences of bytes. 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: @@ -3247,12 +3418,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 @@ -3285,6 +3457,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. @@ -3353,15 +3529,16 @@ subroutine: foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { + $INC{$filename} = $realfilename; $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } + delete $INC{$filename} if $@ || !$result; die $@ if $@; die "$filename did not return true value" unless $result; - $INC{$filename} = $realfilename; return $result; } @@ -3683,9 +3860,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 @@ -3708,7 +3886,9 @@ array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the C<@_> array within the lexical scope of subroutines and formats, and the C<@ARGV> array at file scopes or within the lexical scopes established by -the C<eval ''>, C<BEGIN {}>, C<END {}>, and C<INIT {}> constructs. +the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<STOP {}>, and C<END {}> +constructs. + See also C<unshift>, C<push>, and C<pop>. C<Shift()> and C<unshift> do the same thing to the left end of an array that C<pop> and C<push> do to the right end. @@ -3836,12 +4016,16 @@ the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. -In the interests of efficiency the normal calling code for subroutines is -bypassed, with the following effects: the subroutine may not be a -recursive subroutine, and the two elements to be compared are passed into -the subroutine not via C<@_> but as the package global variables $a and -$b (see example below). They are passed by reference, so don't -modify $a and $b. And don't try to declare them as lexicals either. +If the subroutine's prototype is C<($$)>, the elements to be compared +are passed by reference in C<@_>, as for a normal subroutine. If not, +the normal calling code for subroutines is bypassed in the interests of +efficiency, and the elements to be compared are passed into the subroutine +as the package global variables $a and $b (see example below). Note that +in the latter case, it is usually counter-productive to declare $a and +$b as lexicals. + +In either case, the subroutine may not be recursive. The values to be +compared are always passed by reference, so don't modify them. You also cannot exit out of the sort block or subroutine using any of the loop control operators described in L<perlsyn> or with C<goto>. @@ -3921,6 +4105,14 @@ Examples: || $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; + + # using a prototype allows you to use any comparison subroutine + # as a sort subroutine (including other package's subroutines) + package other; + sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here + + package main; + @new = sort other::backwards @old; If you're using strict, you I<must not> declare $a and $b as lexicals. They are package globals. That means @@ -4136,13 +4328,6 @@ 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 @@ -4262,9 +4447,9 @@ meaning of the fields: 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes - 8 atime last access time since the epoch - 9 mtime last modify time since the epoch - 10 ctime inode change time (NOT creation time!) since the epoch + 8 atime last access time in seconds since the epoch + 9 mtime last modify time in seconds since the epoch + 10 ctime inode change time (NOT creation time!) in seconds since the epoch 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated @@ -4331,8 +4516,8 @@ before any line containing a certain pattern: print; } -In searching for C</\bfoo\b/>, only those locations in C<$_> that contain C<"f"> -will be looked at, because C<"f"> is rarer than C<"o">. In general, this is +In searching for C</\bfoo\b/>, only those locations in C<$_> that contain C<f> +will be looked at, because C<f> is rarer than C<o>. In general, this is a big win except in pathological cases. The only question is whether it saves you more time than it took to build the linked list in the first place. @@ -4474,8 +4659,7 @@ 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 -se them in new code, use thhe constants discussed in the preceding -paragraph. +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 @@ -4496,6 +4680,12 @@ 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. +Note that C<sysopen> depends on the fdopen() C library function. +On many UNIX systems, fdopen() is known to fail when file descriptors +exceed a certain value, typically 255. If you need more file +descriptors than that, consider rebuilding Perl to use the C<sfio> +library, or perhaps using the POSIX::open() function. + See L<perlopentut> for a kinder, gentler explanation of opening files. =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET @@ -4853,8 +5043,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: @@ -4867,9 +5063,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 { @@ -4881,11 +5082,15 @@ The following efficiently counts the number of set bits in a bit vector: $setbits = unpack("%32b*", $selectmask); -The C<"p"> and C<"P"> formats should be used with care. Since Perl +The C<p> and C<P> formats should be used with care. Since Perl 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 @@ -5014,11 +5219,26 @@ 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 (or 64, if your -platform supports that). +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). + +If BITS is 8, "elements" coincide with bytes of the input string. + +If BITS is 16 or more, bytes of the input string are grouped into chunks +of size BITS/8, and each group is converted to a number as with +pack()/unpack() with big-endian formats C<n>/C<N> (and analoguously +for BITS==64). See L<"pack"> for details. + +If bits is 4 or less, the string is broken into bytes, then the bits +of each byte are broken into 8/BITS groups. Bits of a byte are +numbered in a little-endian-ish way, as in C<0x01>, C<0x02>, +C<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>. For example, +breaking the single input byte C<chr(0x36)> into two groups gives a list +C<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>. C<vec> may also be assigned to, in which case parentheses are needed to give the expression the correct precedence as in @@ -5036,6 +5256,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' @@ -5055,6 +5279,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 |