-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.
-g File has setgid bit set.
-k File has sticky bit set.
- -T File is an ASCII text file (heuristic guess).
+ -T File is an ASCII or UTF-8 text file (heuristic guess).
-B File is a "binary" file (opposite of -T).
-M Script start time minus file modification time, in days.
in effect. Read the documentation for the C<filetest> pragma for more
information.
-The C<-T> and C<-B> switches work as follows. The first block or so of the
-file is examined for odd characters such as strange control codes or
-characters with the high bit set. If too many strange characters (>30%)
-are found, it's a C<-B> file; otherwise it's a C<-T> file. Also, any file
-containing a zero byte in the first block is considered a binary file. If C<-T>
-or C<-B> is used on a filehandle, the current IO buffer is examined
+The C<-T> and C<-B> switches work as follows. The first block or so of
+the file is examined to see if it is valid UTF-8 that includes non-ASCII
+characters. If, so it's a C<-T> file. Otherwise, that same portion of
+the file is examined for odd characters such as strange control codes or
+characters with the high bit set. If more than a third of the
+characters are strange, it's a C<-B> file; otherwise it's a C<-T> file.
+Also, any file containing a zero byte in the examined portion is
+considered a binary file. (If executed within the scope of a L<S<use
+locale>|perllocale> which includes C<LC_CTYPE>, odd characters are
+anything that isn't a printable nor space in the current locale.) If
+C<-T> or C<-B> is used on a filehandle, the current IO buffer is
+examined
rather than the first block. Both C<-T> and C<-B> return true on an empty
file, or a file at EOF when testing a filehandle. Because you have to
read a file to do the C<-T> test, on most occasions you want to use a C<-f>
context, returns the caller's package name if there I<is> a caller (that is, if
we're in a subroutine or C<eval> or C<require>) and the undefined value
otherwise. caller never returns XS subs and they are skipped. The next pure
-perl sub will appear instead of the XS sub in caller's return values. In list
+perl sub will appear instead of the XS
+sub in caller's return values. In list
context, caller returns
# 0 1 2
= caller($i);
Here, $subroutine is the function that the caller called (rather than the
-function containing the caller). Note that $subroutine may be C<(eval)> if
+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
number of characters removed from all its arguments. It's often used to
remove the newline from the end of an input record when you're worried
that the final record may be missing its newline. When in paragraph
-mode (C<$/ = "">), it removes all trailing newlines from the string.
+mode (C<$/ = ''>), it removes all trailing newlines from the string.
When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
a reference to an integer or the like; see L<perlvar>) chomp() won't
remove anything.
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.
+B<WARNING:> Calling C<delete> on array values is strongly discouraged. The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
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<tied> hash
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:
print "$key=$value\n";
}
-Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold
+Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold a
reference to an unblessed hash or array. The argument will be dereferenced
automatically. This aspect of C<each> is considered highly experimental.
The exact behaviour may change in a future version of Perl.
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
print "True\n" if $hash{$key};
exists may also be called on array elements, but its behavior is much less
-obvious and is strongly tied to the use of L</delete> on arrays. B<Be aware>
-that calling exists on array values is deprecated and likely to be removed in
-a future version of Perl.
+obvious and is strongly tied to the use of L</delete> on arrays.
+
+B<WARNING:> Calling C<exists> on array values is strongly discouraged. The
+notion of deleting or checking the existence of Perl array elements is not
+conceptually coherent, and can lead to surprising behavior.
print "Exists\n" if exists $array[$index];
print "Defined\n" if defined $array[$index];
"not have a real file descriptor\n";
}
+The behavior of C<fileno> on a directory handle depends on the operating
+system. On a system with dirfd(3) or similar, C<fileno> on a directory
+handle returns the underlying file descriptor associated with the
+handle; on systems with no such support, it returns the undefined value,
+and sets C<$!> (errno).
+
=item flock FILEHANDLE,OPERATION
X<flock> X<lock> X<locking>
$comment, $gcos, $dir, $shell, $expire ) = getpw*
# 5 6 7 8 9
-(If the entry doesn't exist you get an empty list.)
+(If the entry doesn't exist, the return value is a single meaningless true
+value.)
The exact meaning of the $gcos field varies but it usually contains
the real name of the user (as opposed to the login name) and other
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
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.
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
+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>.
-Starting in v5.20, Perl wil use full Unicode rules if the locale is
+Starting in v5.20, Perl uses 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
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
-the input character unchanged, for all instances (and there aren't
-many) where the 255/256 boundary would otherwise be crossed.
+a result that is above 255 (almost always the input character unchanged,
+for all instances (and there aren't many) where the 255/256 boundary
+would otherwise be crossed; and starting in v5.22, it raises a
+L<locale|perldiag/Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".> warning.
=item Otherwise, If EXPR has the UTF8 flag set:
doesn't it won't realize something is wrong until it gets to the C<}> and
encounters the missing (or unexpected) comma. The syntax error will be
reported close to the C<}>, but you'll need to change something near the C<{>
-such as using a unary C<+> to give Perl some help:
+such as using a unary C<+> or semicolon to give Perl some help:
%hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
%hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
- %hash = map { ("\L$_" => 1) } @array # this also works
- %hash = map { lc($_) => 1 } @array # as does this.
+ %hash = map {; "\L$_" => 1 } @array # this also works
+ %hash = map { ("\L$_" => 1) } @array # as does this
+ %hash = map { lc($_) => 1 } @array # and this.
%hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
%hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
=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. This applies immediately--even
+within the same statement.
+
+ 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
+
+Because the variable becomes legal immediately under C<use strict 'vars'>, so
+long as there is no variable with that name is already in scope, you can then
+reference the package variable again even within the same statement.
+
+ package Foo;
+ use strict;
+
+ my $foo = $foo; # error, undeclared $foo on right-hand side
+ our $foo = $foo; # no errors
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>
D A float of long-double precision in native format.
(Long doubles are available only if your system supports
long double values _and_ if Perl has been compiled to
- support those. Raises an exception otherwise.)
+ support those. Raises an exception otherwise.
+ Note that there are different long double formats.)
p A pointer to a null-terminated string.
P A pointer to a structure (fixed-length string).
0x56 0x78 0x12 0x34
0x34 0x12 0x78 0x56
+These are called mid-endian, middle-endian, mixed-endian, or just weird.
+
You can determine your system endianness with this incantation:
printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
$ perl -V:byteorder
Byteorders C<"1234"> and C<"12345678"> are little-endian; C<"4321">
-and C<"87654321"> are big-endian.
+and C<"87654321"> are big-endian. Systems with multiarchitecture binaries
+will have C<"ffff">, signifying that static information doesn't work,
+one must use runtime probing.
For portably packed integers, either use the formats C<n>, C<N>, C<v>,
and C<V> or else use the C<< > >> and C<< < >> modifiers described
=item *
+Also floating point numbers have endianness. Usually (but not always)
+this agrees with the integer endianness. Even though most platforms
+these days use the IEEE 754 binary format, there are differences,
+especially if the long doubles are involved. You can see the
+C<Config> variables C<doublekind> and C<longdblkind> (also C<doublesize>,
+C<longdblsize>): the "kind" values are enums, unlike C<byteorder>.
+
+Portability-wise the best option is probably to keep to the IEEE 754
+64-bit doubles, and of agreed-upon endianness. Another possibility
+is the C<"%a">) format of C<printf>.
+
+=item *
+
Starting with Perl 5.10.0, integer and floating-point formats, along with
the C<p> and C<P> formats and C<()> groups, may all be followed by the
C<< > >> or C<< < >> endianness modifiers to respectively enforce big-
=item *
Pack and unpack can operate in two modes: character mode (C<C0> mode) where
-the packed string is processed per character, and UTF-8 mode (C<U0> mode)
+the packed string is processed per character, and UTF-8 byte mode (C<U0> mode)
where the packed string is processed in its UTF-8-encoded Unicode form on
a byte-by-byte basis. Character mode is the default
unless the format string starts with C<U>. You
assumes additional C<""> arguments. If TEMPLATE requires fewer arguments
than given, extra arguments are ignored.
+=item *
+
+Attempting to pack the special floating point values C<Inf> and C<NaN>
+(infinity, also in negative, and not-a-number) into packed integer values
+(like C<"L">) is a fatal error. The reason for this is that there simply
+isn't any sensible mapping for these special values into integers.
+
=back
Examples:
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;
=item prototype FUNCTION
X<prototype>
+=item prototype
+
=for Pod::Functions +5.002 get the prototype (if any) of a subroutine
Returns the prototype of a function as a string (or C<undef> if the
function has no prototype). FUNCTION is a reference to, or the name of,
-the function whose prototype you want to retrieve.
+the function whose prototype you want to retrieve. If FUNCTION is omitted,
+$_ is used.
If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
name for a Perl builtin. If the builtin's arguments
# same thing, but much more efficiently;
# we'll build auxiliary indices instead
# for speed
- my @nums = @caps = ();
+ my (@nums, @caps);
for (@old) {
push @nums, ( /=(\d+)/ ? $1 : undef );
push @caps, fc($_);
@result = sort { $a <=> $b } grep { $_ == $_ } @input;
-=item splice ARRAY or EXPR,OFFSET,LENGTH,LIST
+=item splice ARRAY,OFFSET,LENGTH,LIST
X<splice>
-=item splice ARRAY or EXPR,OFFSET,LENGTH
+=item splice ARRAY,OFFSET,LENGTH
+
+=item splice ARRAY,OFFSET
+
+=item splice ARRAY
+
+=item splice EXPR,OFFSET,LENGTH,LIST
-=item splice ARRAY or EXPR,OFFSET
+=item splice EXPR,OFFSET,LENGTH
-=item splice ARRAY or EXPR
+=item splice EXPR,OFFSET
+
+=item splice EXPR
=for Pod::Functions add or remove elements anywhere in an array
list of its component characters.
As a special case for C<split>, the empty pattern given in
-L<match operator|perlop/"m/PATTERN/msixpodualgc"> syntax (C<//>) specifically matches the empty string, which is contrary to its usual
+L<match operator|perlop/"m/PATTERN/msixpodualngc"> syntax (C<//>)
+specifically matches the empty string, which is contrary to its usual
interpretation as the last successful match.
If PATTERN is C</^/>, then it is treated as if it used the
%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
C<state> variables are enabled only when the C<use feature "state"> pragma
is in effect, unless the keyword is written as C<CORE::state>.
-See also L<feature>.
+See also L<feature>. Alternately, include a C<use v5.10> or later to the
+current scope.
=item study SCALAR
X<study>
=for Pod::Functions optimize input data for repeated searches
-Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
-doing many pattern matches on the string before it is next modified.
+May take extra time to study SCALAR (C<$_> if unspecified) in anticipation
+of doing many pattern matches on the string before it is next modified.
This may or may not save time, depending on the nature and number of
patterns you are searching and the distribution of character
frequencies in the string to be searched; you probably want to compare
run times with and without it to see which is faster. Those loops
that scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most.
+
+Note that since Perl version 5.16 this function has been a no-op, but
+this might change in a future release.
+
(The way C<study> works is this: a linked list of every
character in the string to be searched is made, so we know, for
example, where all the C<'k'> characters are. From each search string,
function calls the underlying operating system's I<open>(2) function with the
parameters FILENAME, MODE, and PERMS.
+Returns true on success and C<undef> otherwise.
+
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module C<Fcntl>. See
the documentation of your operating system's I<open>(2) syscall to see
(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
C<use>ing library modules that won't work with older versions of Perl.
(We try not to do this more than we have to.)
-C<use VERSION> also enables all features available in the requested
+C<use VERSION> also lexically enables all features available in the requested
version as defined by the C<feature> pragma, disabling any features
not in the requested version's feature bundle. See L<feature>.
Similarly, if the specified Perl version is greater than or equal to
5.12.0, strictures are enabled lexically as
with C<use strict>. Any explicit use of
C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
-before it. In both cases, the F<feature.pm> and F<strict.pm> files are
-not actually loaded.
+before it. Later use of C<use VERSION>
+will override all behavior of a previous
+C<use VERSION>, possibly removing the C<strict> and C<feature> added by
+C<use VERSION>. C<use VERSION> does not
+load the F<feature.pm> or F<strict.pm>
+files.
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
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
Note that a return value of C<-1> could mean that child processes are
being automatically reaped, as described in L<perlipc>.
-If you use wait in your handler for $SIG{CHLD} it may accidentally for the
-child created by qx() or system(). See L<perlipc> for details.
+If you use C<wait> in your handler for $SIG{CHLD}, it may accidentally wait
+
for the child created by qx() or system(). See L<perlipc> for details.
Portability issues: L<perlport/wait>.
=item else
-=item elseif
-
=item elsif
=item for
These flow-control keywords are documented in L<perlsyn/"Compound Statements">.
+=item elseif
+
+The "else if" keyword is spelled C<elsif> in Perl. There's no C<elif>
+or C<else if> either. It does parse C<elseif>, but only to warn you
+about not using it.
+
+See the documentation for flow-control keywords in L<perlsyn/"Compound
+Statements">.
+
=back
=over
https://perl5.git.perl.org / perl5.git / blobdiff