($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
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<$_>.
=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
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 (<>) {
}
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
=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 $hash{$key};
+ print "Defined\n" if defined $hash{$key};
+ print "True\n" if $hash{$key};
- print "Exists\n" if exists $array{$key};
- print "Defined\n" if defined $array{$key};
- print "True\n" if $array{$key};
+ print "Exists\n" if exists $array[$index];
+ print "Defined\n" if defined $array[$index];
+ print "True\n" if $array[$index];
-A hash element can be true only if it's defined, and defined if
+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"}) { }
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.
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:
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:
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
(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 converts it into a string using the rules
=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, 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
+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
+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
+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. When packing,
-C<"a">, and C<"Z"> are equivalent.
+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
+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">
+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
+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
=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.
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
+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
+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
=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>, similarly for unpack().
+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>,
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
=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
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 *
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
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.
$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.
projects / p5sagit/p5-mst-13.2.git / blobdiff