does. Returns the packed address if it succeeded, false otherwise.
See the example in L<perlipc/"Sockets: Client/Server Communication">.
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptor, as determined by the
+value of $^F. See L<perlvar/$^F>.
+
=item alarm SECONDS
=item alarm
Returns the arctangent of Y/X in the range -PI to PI.
-For the tangent operation, you may use the C<POSIX::tan()>
+For the tangent operation, you may use the C<Math::Trig::tan>
function, or use the familiar relation:
sub tan { sin($_[0]) / cos($_[0]) }
($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
-C<use utf8>.
+compiled with. The C<$hints> value is subject to change between versions
+of Perl, and is not meant for external use.
Furthermore, when called from within the DB package, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
=item chdir EXPR
Changes the working directory to EXPR, if possible. If EXPR is omitted,
-changes to the user's home directory. Returns true upon success,
-false otherwise. See the example under C<die>.
+changes to the directory specified by C<$ENV{HOME}>, if set; if not,
+changes to the directory specified by C<$ENV{LOGDIR}>. If neither is
+set, C<chdir> does nothing. It returns true upon success, false
+otherwise. See the example under C<die>.
=item chmod LIST
$mode = '0644'; chmod oct($mode), 'foo'; # this is better
$mode = 0644; chmod $mode, 'foo'; # this is best
+You can also import the symbolic C<S_I*> constants from the Fcntl
+module:
+
+ use Fcntl ':mode';
+
+ chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
+ # This is identical to the chmod 0755 of the above example.
+
=item chomp VARIABLE
=item chomp LIST
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<$_>.
Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
takes cosine of C<$_>.
-For the inverse cosine operation, you may use the C<POSIX::acos()>
+For the inverse cosine operation, you may use the C<Math::Trig::acos()>
function, or use this relation:
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
=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.
+In the case of an array, if the array elements happen to be at the end,
+the size of the array will shrink to the highest element that tests
+true for exists() (or 0 if no such element exists).
+
+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.
-The following deletes all the values of a hash:
+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. Note that deleting array
+elements in the middle of an array will not shift the index of the ones
+after them down--use splice() for that. 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.
+Given an expression that specifies the name of a subroutine,
+returns true if the specified subroutine has ever been declared, even
+if it is undefined. Mentioning a subroutine name for exists or defined
+does not count as declaring it.
+
+ print "Exists\n" if exists &subroutine;
+ print "Defined\n" if defined &subroutine;
+
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 or subroutine name:
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]) { }
+
+ if (exists &{$ref->{A}{B}{$key}}) { }
+
+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"}) { }
See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
used on a pseudo-hash.
+Use of a subroutine call, rather than a subroutine name, as an argument
+to exists() is an error.
+
+ exists ⊂ # OK
+ exists &sub(); # Error
+
=item exit EXPR
Evaluates EXPR and exits immediately with that value. 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.
OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
-you can use the symbolic names if import them from the Fcntl module,
+you can use the symbolic names if you import them from the Fcntl module,
either individually, or as a group using the ':flock' tag. LOCK_SH
requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
-releases a previously requested lock. If LOCK_NB is added to LOCK_SH or
-LOCK_EX then C<flock> will return immediately rather than blocking
+releases a previously requested lock. If LOCK_NB is bitwise-or'ed with
+LOCK_SH or LOCK_EX then C<flock> will return immediately rather than blocking
waiting for the lock (check the return status to see if you got it).
To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
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:
instead a Perl builtin. Also see the C<Time::Local> module
(to convert the second, minutes, hours, ... back to seconds since the
stroke of midnight the 1st of January 1970, the value returned by
-time()), and the strftime(3) and mktime(3) function available via the
+time()), and the strftime(3) and mktime(3) functions available via the
POSIX module. To get somewhat similar but locale dependent date
strings, set up your locale environment variables appropriately
(please see L<perllocale>) and try for example:
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.
-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.
+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.
-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 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 is longer than needed, extra bytes 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>, 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 *
open files, or pre-existing files. Check L<perlport> and either the
rename(2) manpage or equivalent system documentation for details.
+=item require VERSION
+
=item require EXPR
=item require
Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied. If EXPR is numeric, demands that the current version of Perl
-(C<$]> or $PERL_VERSION) be equal or greater than EXPR.
+supplied. If a version number or tuple is specified, or if EXPR is
+numeric, demands that the current version of Perl
+(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR.
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
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.
+(start of the file, current position, end of the file) from the Fcntl
+module. 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
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<INIT {}>, C<STOP {}>, and C<END {}>
+the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}>
constructs.
See also C<unshift>, C<push>, and C<pop>. C<Shift()> and C<unshift> do the
Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
returns sine of C<$_>.
-For the inverse sine operation, you may use the C<POSIX::asin>
+For the inverse sine operation, you may use the C<Math::Trig::asin>
function, or use this relation:
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
to get the proper definitions imported. See the examples in
L<perlipc/"Sockets: Client/Server Communication">.
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptor, as determined by the
+value of $^F. See L<perlvar/$^F>.
+
=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
Creates an unnamed pair of sockets in the specified domain, of the
for the system call of the same name. If unimplemented, yields a fatal
error. Returns true if successful.
+On systems that support a close-on-exec flag on files, the flag will
+be set for the newly opened file descriptors, as determined by the value
+of $^F. See L<perlvar/$^F>.
+
Some systems defined C<pipe> in terms of C<socketpair>, in which a call
to C<pipe(Rdr, Wtr)> is essentially:
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>.
||
$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
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
+And the following Perl-specific conversion:
+
+ %v a string, output as a tuple of integers ("Perl" is 80.101.114.108)
+
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
See L<perllocale>.
If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively supports quads or that Perl
-has been specifically compiled to support quads), the characters
+either that the platform natively support quads or that Perl
+be specifically compiled to support quads), the characters
d u o x X b i D U O
print "quads\n";
If Perl understands "long doubles" (this requires that the platform
-supports long doubles), the flags
+support long doubles), the flags
e f g E F G
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 "$file is executable NFS file\n";
}
-(This works on machines only for which the device number is negative under NFS.)
+(This works on machines only for which the device number is negative
+under NFS.)
Because the mode contains both the file type and its permissions, you
should mask off the file type portion and (s)printf using a C<"%o">
$filename, $sb->size, $sb->mode & 07777,
scalar localtime $sb->mtime;
+You can import symbolic mode constants (C<S_IF*>) and functions
+(C<S_IS*>) from the Fcntl module:
+
+ use Fcntl ':mode';
+
+ $mode = (stat($filename))[2];
+
+ $user_rwx = ($mode & S_IRWXU) >> 6;
+ $group_read = ($mode & S_IRGRP) >> 3;
+ $other_execute = $mode & S_IXOTH;
+
+ printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+
+ $is_setuid = $mode & S_ISUID;
+ $is_setgid = S_ISDIR($mode);
+
+You could write the last two using the C<-u> and C<-d> operators.
+The commonly available S_IF* constants are
+
+ # Permissions: read, write, execute, for user, group, others.
+
+ S_IRWXU S_IRUSR S_IWUSR S_IXUSR
+ S_IRWXG S_IRGRP S_IWGRP S_IXGRP
+ S_IRWXO S_IROTH S_IWOTH S_IXOTH
+
+ # Setuid/Setgid/Stickiness.
+
+ S_ISUID S_ISGID S_ISVTX S_ISTXT
+
+ # File types. Not necessarily all are available on your system.
+
+ S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+
+ # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
+
+ S_IREAD S_IWRITE S_IEXEC
+
+and the S_IF* functions are
+
+ S_IFMODE($mode) the part of $mode containg the permission bits
+ and the setuid/setgid/sticky bits
+
+ S_IFMT($mode) the part of $mode containing the file type
+ which can be bit-anded with e.g. S_IFREG
+ or with the following functions
+
+ # The operators -f, -d, -l, -b, -c, -p, and -s.
+
+ S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
+ S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
+
+ # No direct -X operator counterpart, but for the first one
+ # the -g operator is often equivalent. The ENFMT stands for
+ # record flocking enforcement, a platform-dependent feature.
+
+ S_ISENFMT($mode) S_ISWHT($mode)
+
+See your native chmod(2) and stat(2) documentation for more details
+about the S_* constants.
+
=item study SCALAR
=item study
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.
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.
+from the Fcntl module.
Returns the new position, or the undefined value on failure. A position
of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
$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.
except that Module I<must> be a bareword.
-If the first argument to C<use> is a number, it is treated as a version
-number instead of a module name. If the version of the Perl interpreter
-is less than VERSION, then an error message is printed and Perl exits
-immediately. This is often useful if you need to check the current
-Perl version before C<use>ing library modules that have changed in
-incompatible ways from older versions of Perl. (We try not to do
-this more than we have to.)
+If the first argument to C<use> is a number or a version tuple, it is
+treated as a version instead of a module name. If the version
+of the Perl interpreter is less than VERSION, then an error message
+is printed and Perl exits immediately.
+
+ use 5.005_03; # version number
+ use v5.6.0; # version tuple
+
+This is often useful if you need to check the current Perl version before
+C<use>ing library modules that have changed in incompatible ways from
+older versions of Perl. (We try not to do this more than we have to.)
The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been
C<import> method any way it likes, though most modules just choose to
derive their C<import> method via inheritance from the C<Exporter> class that
is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
-method can be found then the error is currently silently ignored. This
-may change to a fatal error in a future version.
+method can be found then the call is skipped.
If you don't want your namespace altered, explicitly supply an empty list:
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
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.
+If the selected element is off the end of the string, the value 0 is
+returned. If an element off the end of the string is written to,
+Perl will first extend the string with sufficiently many zero bytes.
+
+Strings created with C<vec> can also be manipulated with the logical
+operators C<|>, C<&>, C<^>, and C<~>. These operators 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'>.
projects / p5sagit/p5-mst-13.2.git / blobdiff