-f File is a plain file.
-d File is a directory.
- -l File is a symbolic link.
+ -l File is a symbolic link (false if symlinks aren't
+ supported by the file system).
-p File is a named pipe (FIFO), or Filehandle is a pipe.
-S File is a socket.
-b File is a block special file.
$wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
= caller($i);
-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
+Here, $subroutine is the function that the caller called (rather than the
+function containing the caller). Note that $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 an C<eval BLOCK> statement,
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
$can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
-Portability issues: L<perlport/chmod>.
+Portability issues: L<perlport/chown>.
=item chr NUMBER
X<chr> X<character> X<ASCII> X<Unicode>
reasons, this call is restricted to the superuser. If FILENAME is
omitted, does a C<chroot> to C<$_>.
+B<NOTE:> It is good security practice to do C<chdir("/")> (to the root
+directory) immediately after a C<chroot()>.
+
Portability issues: L<perlport/chroot>.
=item close FILEHANDLE
delete() may also be used on arrays and array slices, but its behavior is less
straightforward. Although exists() will return false for deleted entries,
deleting array elements never changes indices of existing values; use shift()
-or splice() for that. However, if all deleted elements fall at the end of an
+or splice() for that. However, if any deleted elements fall at the end of an
array, the array's size shrinks to the position of the highest element that
-still tests true for exists(), or to 0 if none do.
+still tests true for exists(), or to 0 if none do. In other words, an
+array won't have trailing nonexistent elements after a delete.
B<WARNING:> Calling delete on array values is deprecated and likely to
be removed in a future version of Perl.
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
See L<perlsyn> for alternative strategies.
-=item do SUBROUTINE(LIST)
-X<do>
-
-This form of subroutine call is deprecated. SUBROUTINE can be a bareword
-or scalar variable.
-
=item do EXPR
X<do>
C<keys> or C<values> on the hash or array. If you add or delete a hash's
elements while iterating over it, the effect on the iterator is
unspecified; for example, entries may be skipped or duplicated--so don't
-do that. Exception: In the current implementation, it is always safe to
-delete the item most recently returned by C<each()>, so the following code
-works properly:
+do that. Exception: It is always safe to delete the item most recently
+returned by C<each()>, so the following code works properly:
while (($key, $value) = each %hash) {
print $key, "\n";
delete $hash{$key}; # This is safe
}
+Tied hashes may have a different ordering behaviour to perl's hash
+implementation.
+
This prints out your environment like the printenv(1) program,
but in a different order:
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
-See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
+See L</warn>, L<perlvar>, and L<warnings>.
Note that, because C<eval> traps otherwise-fatal errors, it is useful for
determining whether a particular feature (such as C<socket> or C<symlink>)
exec ('foo') or print STDERR "couldn't exec foo: $!";
{ exec ('foo') }; print STDERR "couldn't exec foo: $!";
-If there is more than one argument in LIST, or if LIST is an array
-with more than one value, calls execvp(3) with the arguments in LIST.
-If there is only one scalar argument or an array with one element in it,
-the argument is checked for shell metacharacters, and if there are any,
-the entire argument is passed to the system's command shell for parsing
-(this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
-If there are no shell metacharacters in the argument, it is split into
-words and passed directly to C<execvp>, which is more efficient.
-Examples:
+If there is more than one argument in LIST, this calls execvp(3) with the
+arguments in LIST. If there is only one element in LIST, the argument is
+checked for shell metacharacters, and if there are any, the entire
+argument is passed to the system's command shell for parsing (this is
+C</bin/sh -c> on Unix platforms, but varies on other platforms). If
+there are no shell metacharacters in the argument, it is split into words
+and passed directly to C<execvp>, which is more efficient. Examples:
exec '/bin/echo', 'Your arguments are: ', @ARGV;
exec "sort $outfile | uniq";
If you don't really want to execute the first argument, but want to lie
to the program you are executing about its own name, you can specify
the program you actually want to run as an "indirect object" (without a
-comma) in front of the LIST. (This always forces interpretation of the
-LIST as a multivalued list, even if there is only a single scalar in
-the list.) Example:
+comma) in front of the LIST, as in C<exec PROGRAM LIST>. (This always
+forces interpretation of the LIST as a multivalued list, even if there
+is only a single scalar in the list.) Example:
$shell = '/bin/csh';
exec $shell '-sh'; # pretend it's a login shell
it tried to run a program named I<"echo surprise">, didn't find it, and set
C<$?> to a non-zero value indicating failure.
+On Windows, only the C<exec PROGRAM LIST> indirect object syntax will
+reliably avoid using the shell; C<exec LIST>, even with more than one
+element, will fall back to the shell if the first spawn fails.
+
Perl attempts to flush all files opened for output before the exec,
but this may not be supported on some platforms (see L<perlport>).
To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or
system C library. In list context, the return values from the
various get routines are as follows:
- ($name,$passwd,$uid,$gid,
- $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
- ($name,$passwd,$gid,$members) = getgr*
- ($name,$aliases,$addrtype,$length,@addrs) = gethost*
- ($name,$aliases,$addrtype,$net) = getnet*
- ($name,$aliases,$proto) = getproto*
- ($name,$aliases,$port,$proto) = getserv*
+ # 0 1 2 3 4
+ ( $name, $passwd, $gid, $members ) = getgr*
+ ( $name, $aliases, $addrtype, $net ) = getnet*
+ ( $name, $aliases, $port, $proto ) = getserv*
+ ( $name, $aliases, $proto ) = getproto*
+ ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
+ ( $name, $passwd, $uid, $gid, $quota,
+ $comment, $gcos, $dir, $shell, $expire ) = getpw*
+ # 5 6 7 8 9
(If the entry doesn't exist you get an empty list.)
as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
details on why hash order is randomized. Aside from the guarantees
provided here the exact details of Perl's hash algorithm and the hash
-traversal order are subject to change in any release of Perl.
+traversal order are subject to change in any release of Perl. Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
As a side effect, calling keys() resets the internal iterator of the HASH or
ARRAY (see L</each>). In particular, calling keys() in void context resets
=for Pod::Functions send a signal to a process or process group
-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).
+Sends a signal to a list of processes. Returns the number of arguments
+that were successfully used to signal (which is not necessarily the same
+as the number of processes actually killed, e.g. where a process group is
+killed).
$cnt = kill 'HUP', $child1, $child2;
kill 'KILL', @goners;
See L<perlipc/"Signals"> for more details.
-On some platforms such as Windows where the fork() system call is not available.
-Perl can be built to emulate fork() at the interpreter level.
+On some platforms such as Windows where the fork() system call is not
+available, Perl can be built to emulate fork() at the interpreter level.
This emulation has limitations related to kill that have to be considered,
for code running on Windows and in code intended to be portable.
=item If C<use bytes> is in effect:
-The results follow ASCII semantics. Only characters C<A-Z> change, to C<a-z>
-respectively.
+The results follow ASCII rules. Only the characters C<A-Z> change,
+to C<a-z> respectively.
-=item Otherwise, if C<use locale> (but not C<use locale ':not_characters'>) is in effect:
+=item Otherwise, if C<use locale> for C<LC_CTYPE> is in effect:
-Respects current LC_CTYPE locale for code points < 256; and uses Unicode
-semantics for the remaining code points (this last can only happen if
+Respects current C<LC_CTYPE> locale for code points < 256; and uses Unicode
+rules for the remaining code points (this last can only happen if
the UTF8 flag is also set). See L<perllocale>.
-A deficiency in this is that case changes that cross the 255/256
+Starting in v5.20, Perl wil use full Unicode rules if the locale is
+UTF-8. Otherwise, there is a deficiency in this scheme, which is that
+case changes that cross the 255/256
boundary are not well-defined. For example, the lower case of LATIN CAPITAL
-LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
-platforms). But under C<use locale>, the lower case of U+1E9E is
+LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
+platforms). But under C<use locale> (prior to v5.20 or not a UTF-8
+locale), the lower case of U+1E9E is
itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
current locale, and Perl has no way of knowing if that character even
exists in the locale, much less what code point it is. Perl returns
=item Otherwise, If EXPR has the UTF8 flag set:
-Unicode semantics are used for the case change.
+Unicode rules are used for the case change.
=item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'> is in effect:
-Unicode semantics are used for the case change.
+Unicode rules are used for the case change.
=item Otherwise:
-ASCII semantics are used for the case change. The lowercase of any character
+ASCII rules are used for the case change. The lowercase of any character
outside the ASCII range is the character itself.
=back
everyone happy.
To recursively create a directory structure, look at
-the C<mkpath> function of the L<File::Path> module.
+the C<make_path> function of the L<File::Path> module.
=item msgctl ID,CMD,ARG
X<msgctl>
=for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping)
-C<our> makes a lexical alias to a package variable of the same name in the current
-package for use within the current lexical scope.
+C<our> makes a lexical alias to a package (i.e. global) variable of the
+same name in the current package for use within the current lexical scope.
-C<our> has the same scoping rules as C<my> or C<state>, but C<our> only
-declares an alias, whereas C<my> or C<state> both declare a variable name and
-allocate storage for that name within the current scope.
+C<our> has the same scoping rules as C<my> or C<state>, meaning that it is
+only valid within a lexical scope. Unlike C<my> and C<state>, which both
+declare new (lexical) variables, C<our> only creates an alias to an
+existing variable: a package variable of the same name.
This means that when C<use strict 'vars'> is in effect, C<our> lets you use
a package variable without qualifying it with the package name, but only within
-the lexical scope of the C<our> declaration. In this way, C<our> differs from
-C<use vars>, which allows use of an unqualified name I<only> within the
-affected package, but across scopes.
+the lexical scope of the C<our> declaration.
+
+ package Foo;
+ use strict;
+
+ $Foo::foo = 23;
+
+ {
+ our $foo; # alias to $Foo::foo
+ print $foo; # prints 23
+ }
+
+ print $Foo::foo; # prints 23
+
+ print $foo; # ERROR: requires explicit package name
+
+This works even if the package variable has not been used before, as
+package variables spring into existence when first used.
+
+ package Foo;
+ use strict;
+
+ our $foo = 23; # just like $Foo::foo = 23
+
+ print $Foo::foo; # prints 23
If more than one variable is listed, the list must be placed
in parentheses.
- our $foo;
our($bar, $baz);
An C<our> declaration declares an alias for a package variable that will be visible
our ( undef, $min, $hour ) = localtime;
+C<our> differs from C<use vars>, which allows use of an unqualified name
+I<only> within the affected package, but across scopes.
+
=item pack TEMPLATE,LIST
X<pack>
of the list will be interpreted as the C<printf> format. This
means that C<printf(@_)> will use C<$_[0]> as the format. See
L<sprintf|/sprintf FORMAT, LIST> for an
-explanation of the format argument. If C<use locale> (including
-C<use locale ':not_characters'>) is in effect and
+explanation of the format argument. If C<use locale> for C<LC_NUMERIC>
+Look for this throught pod
+is in effect and
POSIX::setlocale() has been called, the character used for the decimal
-separator in formatted floating-point numbers is affected by the LC_NUMERIC
+separator in formatted floating-point numbers is affected by the C<LC_NUMERIC>
locale setting. See L<perllocale> and L<POSIX>.
For historical reasons, if you omit the list, C<$_> is used as the format;
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
into the next argument in the parameter list
+ %a hexadecimal floating point
+ %A like %a, but using upper-case letters
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
exponent less than 100 is system-dependent: it may be three or less
(zero-padded as necessary). In other words, 1.23 times ten to the
-99th may be either "1.23e99" or "1.23e099".
+99th may be either "1.23e99" or "1.23e099". Similarly for C<%a> and C<%A>:
+the exponent or the hexadecimal digits may float: especially the
+"long doubles" Perl configuration option may cause surprises.
Between the C<%> and the format letter, you may specify several
additional attributes controlling the interpretation of the format.
If C<use locale> (including C<use locale 'not_characters'>) is in effect
and POSIX::setlocale() has been called,
the character used for the decimal separator in formatted floating-point
-numbers is affected by the
LC_NUMERIC locale. See L<perllocale>
+numbers is affected by the
C<LC_NUMERIC> locale. See L<perllocale>
and L<POSIX>.
=item sqrt EXPR
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.
+descriptors than that, consider using the POSIX::open() function.
See L<perlopentut> for a kinder, gentler explanation of opening files.
(this is C</bin/sh -c> on Unix platforms, but varies on other
platforms). If there are no shell metacharacters in the argument,
it is split into words and passed directly to C<execvp>, which is
-more efficient.
+more efficient. On Windows, only the C<system PROGRAM LIST> syntax will
+reliably avoid using the shell; C<system LIST>, even with more than one
+element, will fall back to the shell if the first spawn fails.
Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
details on why hash order is randomized. Aside from the guarantees
provided here the exact details of Perl's hash algorithm and the hash
-traversal order are subject to change in any release of Perl.
+traversal order are subject to change in any release of Perl. Tied hashes
+may behave differently to Perl's hashes with respect to changes in order on
+insertion and deletion of items.
As a side effect, calling values() resets the HASH or ARRAY's internal
iterator, see L</each>. (In particular, calling values() in void context
=item gt
-=item if
-
=item le
=item lt
=item foreach
+=item if
+
=item unless
=item until
https://perl5.git.perl.org / perl5.git / blobdiff