Here are Perl's functions (including things that look like
functions, like some keywords and named operators)
arranged by category. Some functions appear in more
-than one place.
+than one place. Any warnings, including those produced by
+keywords, are described in L<perldiag> and L<warnings>.
=over 4
L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>, L<C<glob>|/glob EXPR>,
L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>,
L<C<link>|/link OLDFILE,NEWFILE>, L<C<lstat>|/lstat FILEHANDLE>,
-L<C<mkdir>|/mkdir FILENAME,MASK>, L<C<open>|/open FILEHANDLE,EXPR>,
+L<C<mkdir>|/mkdir FILENAME,MODE>, L<C<open>|/open FILEHANDLE,MODE,EXPR>,
L<C<opendir>|/opendir DIRHANDLE,EXPR>, L<C<readlink>|/readlink EXPR>,
L<C<rename>|/rename OLDNAME,NEWNAME>, L<C<rmdir>|/rmdir FILENAME>,
L<C<select>|/select FILEHANDLE>, L<C<stat>|/stat FILEHANDLE>,
L<C<lstat>|/lstat FILEHANDLE>, L<C<msgctl>|/msgctl ID,CMD,ARG>,
L<C<msgget>|/msgget KEY,FLAGS>,
L<C<msgrcv>|/msgrcv ID,VAR,SIZE,TYPE,FLAGS>,
-L<C<msgsnd>|/msgsnd ID,MSG,FLAGS>, L<C<open>|/open FILEHANDLE,EXPR>,
+L<C<msgsnd>|/msgsnd ID,MSG,FLAGS>, L<C<open>|/open FILEHANDLE,MODE,EXPR>,
L<C<pipe>|/pipe READHANDLE,WRITEHANDLE>, L<C<readlink>|/readlink EXPR>,
L<C<rename>|/rename OLDNAME,NEWNAME>,
L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>,
tests STDIN. Unless otherwise documented, it returns C<1> for true and
C<''> for false. If the file doesn't exist or can't be examined, it
returns L<C<undef>|/undef EXPR> and sets L<C<$!>|perlvar/$!> (errno).
+With the exception of the C<-l> test they all follow symbolic links
+because they use C<stat()> and not C<lstat()> (so dangling symlinks can't
+be examined and will therefore report failure).
+
Despite the funny names, precedence is the same as any other named unary
operator. The operator may be any of:
Note that, despite what may be implied in I<"Programming Perl"> (the
Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
Other layers that would affect the binary nature of the stream are
-I<also> disabled. See L<PerlIO>, L<perlrun>, and the discussion about the
-PERLIO environment variable.
+I<also> disabled. See L<PerlIO>, and the discussion about the PERLIO
+environment variable in L<perlrun|perlrun/PERLIO>.
The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
form C<:...>, are called I/O I<layers>. The L<open> pragma can be used to
UTF-8. More details can be found in L<PerlIO::encoding>.
In general, L<C<binmode>|/binmode FILEHANDLE, LAYER> should be called
-after L<C<open>|/open FILEHANDLE,EXPR> but before any I/O is done on the
+after L<C<open>|/open FILEHANDLE,MODE,EXPR> but before any I/O is done on the
filehandle. Calling L<C<binmode>|/binmode FILEHANDLE, LAYER> normally
flushes any pending buffered output data (and perhaps pending input
data) on the handle. An exception to this is the C<:encoding> layer
=for Pod::Functions create an object
This function tells the thingy referenced by REF that it is now an object
-in the CLASSNAME package. If CLASSNAME is omitted, the current package
+in the CLASSNAME package. If CLASSNAME is an empty string, it is
+interpreted as referring to the C<main> package.
+If CLASSNAME is omitted, the current package
is used. Because a L<C<bless>|/bless REF,CLASSNAME> is often the last
thing in a constructor, it returns the reference for convenience.
Always use the two-argument version if a derived class might inherit the
Consider always blessing objects in CLASSNAMEs that are mixed case.
Namespaces with all lowercase names are considered reserved for
Perl pragmas. Builtin types have all uppercase names. To prevent
-confusion, you may wish to avoid such package names as well. Make sure
-that CLASSNAME is a true value.
+confusion, you may wish to avoid such package names as well.
+It is advised to avoid the class name C<0>, because much code erroneously
+uses the result of L<C<ref>|/ref EXPR> as a truth value.
See L<perlmod/"Perl Modules">.
# 0 1 2
my ($package, $filename, $line) = caller;
+Like L<C<__FILE__>|/__FILE__> and L<C<__LINE__>|/__LINE__>, the filename and
+line number returned here may be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
+
With EXPR, it returns some extra information that the debugger uses to
print a stack trace. The value of EXPR indicates how many call frames
to go back before the current one.
reasons, this call is restricted to the superuser. If FILENAME is
omitted, does a L<C<chroot>|/chroot FILENAME> to L<C<$_>|perlvar/$_>.
-B<NOTE:> It is good security practice to do C<chdir("/")>
+B<NOTE:> It is mandatory for security to C<chdir("/")>
(L<C<chdir>|/chdir EXPR> to the root directory) immediately after a
-L<C<chroot>|/chroot FILENAME>.
+L<C<chroot>|/chroot FILENAME>, otherwise the current working directory
+may be outside of the new root.
Portability issues: L<perlport/chroot>.
omitted.
You don't have to close FILEHANDLE if you are immediately going to do
-another L<C<open>|/open FILEHANDLE,EXPR> on it, because
-L<C<open>|/open FILEHANDLE,EXPR> closes it for you. (See
-L<C<open>|/open FILEHANDLE,EXPR>.) However, an explicit
+another L<C<open>|/open FILEHANDLE,MODE,EXPR> on it, because
+L<C<open>|/open FILEHANDLE,MODE,EXPR> closes it for you. (See
+L<C<open>|/open FILEHANDLE,MODE,EXPR>.) However, an explicit
L<C<close>|/close FILEHANDLE> on an input file resets the line counter
(L<C<$.>|perlvar/$.>), while the implicit close done by
-L<C<open>|/open FILEHANDLE,EXPR> does not.
+L<C<open>|/open FILEHANDLE,MODE,EXPR> does not.
If the filehandle came from a piped open, L<C<close>|/close FILEHANDLE>
returns false if one of the other syscalls involved fails or if its
This binds a L<dbm(3)>, L<ndbm(3)>, L<sdbm(3)>, L<gdbm(3)>, or Berkeley
DB file to a hash. HASH is the name of the hash. (Unlike normal
-L<C<open>|/open FILEHANDLE,EXPR>, the first argument is I<not> a
+L<C<open>|/open FILEHANDLE,MODE,EXPR>, the first argument is I<not> a
filehandle, even though it looks like one). DBNAME is the name of the
database (without the F<.dir> or F<.pag> extension if any). If the
database does not exist, it is created with protection specified by MASK
true. Setting a hash element to the undefined value does not remove its
key, but deleting it does; see L<C<exists>|/exists EXPR>.
-In list context, returns the value or values deleted, or the last such
-element in scalar context. The return list's length always matches that of
+In list context, usually returns the value or values deleted, or the last such
+element in scalar context. The return list's length corresponds to that of
the argument list: deleting non-existent elements returns the undefined value
-in their corresponding positions.
+in their corresponding positions. When a
+L<keyE<sol>value hash slice|perldata/KeyE<sol>Value Hash Slices> is passed to
+C<delete>, the return value is a list of key/value pairs (two elements for each
+item deleted from the hash).
L<C<delete>|/delete EXPR> may also be used on arrays and array slices,
but its behavior is less straightforward. Although
=for Pod::Functions raise an exception or bail out
-L<C<die>|/die LIST> raises an exception. Inside an
-L<C<eval>|/eval EXPR> the error message is stuffed into
-L<C<$@>|perlvar/$@> and the L<C<eval>|/eval EXPR> is terminated with the
-undefined value. If the exception is outside of all enclosing
-L<C<eval>|/eval EXPR>s, then the uncaught exception prints LIST to
-C<STDERR> and exits with a non-zero value. If you need to exit the
-process with a specific exit code, see L<C<exit>|/exit EXPR>.
+L<C<die>|/die LIST> raises an exception. Inside an L<C<eval>|/eval EXPR>
+the exception is stuffed into L<C<$@>|perlvar/$@> and the L<C<eval>|/eval
+EXPR> is terminated with the undefined value. If the exception is
+outside of all enclosing L<C<eval>|/eval EXPR>s, then the uncaught
+exception is printed to C<STDERR> and perl exits with an exit code
+indicating failure. If you need to exit the process with a specific
+exit code, see L<C<exit>|/exit EXPR>.
Equivalent examples:
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
-If the last element of LIST does not end in a newline, the current
-script line number and input line number (if any) are also printed,
-and a newline is supplied. Note that the "input line number" (also
+Most of the time, C<die> is called with a string to use as the exception.
+You may either give a single non-reference operand to serve as the
+exception, or a list of two or more items, which will be stringified
+and concatenated to make the exception.
+
+If the string exception does not end in a newline, the current
+script line number and input line number (if any) and a newline
+are appended to it. Note that the "input line number" (also
known as "chunk") is subject to whatever notion of "line" happens to
be currently in effect, and is also available as the special variable
L<C<$.>|perlvar/$.>. See L<perlvar/"$/"> and L<perlvar/"$.">.
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line 123.
-If the output is empty and L<C<$@>|perlvar/$@> already contains a value
-(typically from a previous L<C<eval>|/eval EXPR>) that value is reused after
+If LIST was empty or made an empty string, and L<C<$@>|perlvar/$@>
+already contains an exception value (typically from a previous
+L<C<eval>|/eval EXPR>), then that value is reused after
appending C<"\t...propagated">. This is useful for propagating exceptions:
eval { ... };
die unless $@ =~ /Expected exception/;
-If the output is empty and L<C<$@>|perlvar/$@> contains an object
+If LIST was empty or made an empty string,
+and L<C<$@>|perlvar/$@> contains an object
reference that has a C<PROPAGATE> method, that method will be called
with additional file and line number parameters. The return value
replaces the value in L<C<$@>|perlvar/$@>; i.e., as if
C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> were called.
-If L<C<$@>|perlvar/$@> is empty, then the string C<"Died"> is used.
-
-If an uncaught exception results in interpreter exit, the exit code is
-determined from the values of L<C<$!>|perlvar/$!> and
-L<C<$?>|perlvar/$?> with this pseudocode:
-
- exit $! if $!; # errno
- exit $? >> 8 if $? >> 8; # child exit status
- exit 255; # last resort
-
-As with L<C<exit>|/exit EXPR>, L<C<$?>|perlvar/$?> is set prior to
-unwinding the call stack; any C<DESTROY> or C<END> handlers can then
-alter this value, and thus Perl's exit code.
-
-The intent is to squeeze as much possible information about the likely cause
-into the limited space of the system exit code. However, as
-L<C<$!>|perlvar/$!> is the value of C's C<errno>, which can be set by
-any system call, this means that the value of the exit code used by
-L<C<die>|/die LIST> can be non-predictable, so should not be relied
-upon, other than to be non-zero.
+If LIST was empty or made an empty string, and L<C<$@>|perlvar/$@>
+is also empty, then the string C<"Died"> is used.
You can also call L<C<die>|/die LIST> with a reference argument, and if
this is trapped within an L<C<eval>|/eval EXPR>, L<C<$@>|perlvar/$@>
contains that reference. This permits more elaborate exception handling
using objects that maintain arbitrary state about the exception. Such a
scheme is sometimes preferable to matching particular string values of
-L<C<$@>|perlvar/$@> with regular expressions. Because
-L<C<$@>|perlvar/$@> is a global variable and L<C<eval>|/eval EXPR> may
-be used within object implementations, be careful that analyzing the
-error object doesn't replace the reference in the global variable. It's
+L<C<$@>|perlvar/$@> with regular expressions.
+
+Because Perl stringifies uncaught exception messages before display,
+you'll probably want to overload stringification operations on
+exception objects. See L<overload> for details about that.
+The stringified message should be non-empty, and should end in a newline,
+in order to fit in with the treatment of string exceptions.
+Also, because an exception object reference cannot be stringified
+without destroying it, Perl doesn't attempt to append location or other
+information to a reference exception. If you want location information
+with a complex exception object, you'll have to arrange to put the
+location information into the object yourself.
+
+Because L<C<$@>|perlvar/$@> is a global variable, be careful that
+analyzing an exception caught by C<eval> doesn't replace the reference
+in the global variable. It's
easiest to make a local copy of the reference before any manipulations.
Here's an example:
}
}
-Because Perl stringifies uncaught exception messages before display,
-you'll probably want to overload stringification operations on
-exception objects. See L<overload> for details about that.
+If an uncaught exception results in interpreter exit, the exit code is
+determined from the values of L<C<$!>|perlvar/$!> and
+L<C<$?>|perlvar/$?> with this pseudocode:
+
+ exit $! if $!; # errno
+ exit $? >> 8 if $? >> 8; # child exit status
+ exit 255; # last resort
+
+As with L<C<exit>|/exit EXPR>, L<C<$?>|perlvar/$?> is set prior to
+unwinding the call stack; any C<DESTROY> or C<END> handlers can then
+alter this value, and thus Perl's exit code.
+
+The intent is to squeeze as much possible information about the likely cause
+into the limited space of the system exit code. However, as
+L<C<$!>|perlvar/$!> is the value of C's C<errno>, which can be set by
+any system call, this means that the value of the exit code used by
+L<C<die>|/die LIST> can be non-predictable, so should not be relied
+upon, other than to be non-zero.
You can arrange for a callback to be run just before the
L<C<die>|/die LIST> does its deed, by setting the
L<C<$SIG{__DIE__}>|perlvar/%SIG> hook. The associated handler is called
-with the error text and can change the error message, if it sees fit, by
+with the exception as an argument, and can change the exception,
+if it sees fit, by
calling L<C<die>|/die LIST> again. See L<perlvar/%SIG> for details on
setting L<C<%SIG>|perlvar/%SIG> entries, and L<C<eval>|/eval EXPR> for some
examples. Although this feature was to be run only right before your
=for Pod::Functions create an immediate core dump
This function causes an immediate core dump. See also the B<-u>
-command-line switch in L<perlrun>, which does the same thing.
+command-line switch in L<perlrun|perlrun/-u>, which does the same thing.
Primarily this is so that you can use the B<undump> program (not
supplied) to turn your core dump into an executable binary after
having initialized all your variables at the beginning of the
resulting confusion by Perl.
This function is now largely obsolete, mostly because it's very hard to
-convert a core file into an executable. That's why you should now invoke
-it as C<CORE::dump()> if you don't want to be warned against a possible
-typo.
+convert a core file into an executable. As of Perl 5.30, it must be invoked
+as C<CORE::dump()>.
Unlike most named operators, this has the same precedence as assignment.
It is also exempt from the looks-like-a-function rule, so
L<C<keys>|/keys HASH>, and L<C<values>|/values HASH>. The iterator is
implicitly reset when L<C<each>|/each HASH> has reached the end as just
described; it can be explicitly reset by calling L<C<keys>|/keys HASH>
-or L<C<values>|/values HASH> on the hash or array. If you add or delete
+or L<C<values>|/values HASH> on the hash or array, or by referencing
+the hash (but not array) in list context. 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: It is always safe to delete the item most recently
Tied hashes may have a different ordering behaviour to perl's hash
implementation.
+The iterator used by C<each> is attached to the hash or array, and is
+shared between all iteration operations applied to the same hash or array.
+Thus all uses of C<each> on a single hash or array advance the same
+iterator location. All uses of C<each> are also subject to having the
+iterator reset by any use of C<keys> or C<values> on the same hash or
+array, or by the hash (but not array) being referenced in list context.
+This makes C<each>-based loops quite fragile: it is easy to arrive at
+such a loop with the iterator already part way through the object, or to
+accidentally clobber the iterator state during execution of the loop body.
+It's easy enough to explicitly reset the iterator before starting a loop,
+but there is no way to insulate the iterator state used by a loop from
+the iterator state used by anything else that might execute during the
+loop body. To avoid these problems, use a C<foreach> loop rather than
+C<while>-C<each>.
+
This prints out your environment like the L<printenv(1)> program,
but in a different order:
As of Perl 5.18 you can use a bare L<C<each>|/each HASH> in a C<while>
loop, which will set L<C<$_>|perlvar/$_> on every iteration.
+If either an C<each> expression or an explicit assignment of an C<each>
+expression to a scalar is used as a C<while>/C<for> condition, then
+the condition actually tests for definedness of the expression's value,
+not for its regular truth value.
while (each %ENV) {
print "$_=$ENV{$_}\n";
If you want to trap errors when loading an XS module, some problems with
the binary interface (such as Perl version skew) may be fatal even with
C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See
-L<perlrun>.
+L<perlrun|perlrun/PERL_DL_NONLAZY>.
Using the C<eval {}> form as an exception trap in libraries does have some
issues. Due to the current arguably broken state of C<__DIE__> hooks, you
if (exists $ref->{"Some key"}) { }
print $ref; # prints HASH(0x80d3d5c)
-This surprising autovivification in what does not at first--or even
-second--glance appear to be an lvalue context may be fixed in a future
-release.
-
Use of a subroutine call, rather than a subroutine name, as an argument
to L<C<exists>|/exists EXPR> is an error.
For further information on casefolding, refer to
the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
-available at L<http://www.unicode.org/versions/latest/>, as well as the
-Case Charts available at L<http://www.unicode.org/charts/case/>.
+available at L<https://www.unicode.org/versions/latest/>, as well as the
+Case Charts available at L<https://www.unicode.org/charts/case/>.
If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
=for Pod::Functions the name of the current source file
A special token that returns the name of the file in which it occurs.
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
=item fileno FILEHANDLE
X<fileno>
or undefined if the
filehandle is not open. If there is no real file descriptor at the OS
level, as can happen with filehandles connected to memory objects via
-L<C<open>|/open FILEHANDLE,EXPR> with a reference for the third
+L<C<open>|/open FILEHANDLE,MODE,EXPR> with a reference for the third
argument, -1 is returned.
This is mainly useful for constructing bitmaps for
(See L<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement L<getpriority(2)>.
+C<WHICH> can be any of C<PRIO_PROCESS>, C<PRIO_PGRP> or C<PRIO_USER>
+imported from L<POSIX/RESOURCE CONSTANTS>.
+
Portability issues: L<perlport/getpriority>.
=item getpwnam NAME
they aren't, because a C<File::stat> object is different from
a C<User::pwent> object.
+Many of these functions are not safe in a multi-threaded environment
+where more than one thread can be using them. In particular, functions
+like C<getpwent()> iterate per-process and not per-thread, so if two
+threads are simultaneously iterating, neither will get all the records.
+
+Some systems have thread-safe versions of some of the functions, such as
+C<getpwnam_r()> instead of C<getpwnam()>. There, Perl automatically and
+invisibly substitutes the thread-safe version, without notice. This
+means that code that safely runs on some systems can fail on others that
+lack the thread-safe versions.
+
Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
=item getsockname SOCKET
L<C<bsd_glob>|File::Glob/C<bsd_glob>>, which does not treat whitespace
as a pattern separator.
+If a C<glob> expression is used as the condition of a C<while> or C<for>
+loop, then it will be implicitly assigned to C<$_>. If either a C<glob>
+expression or an explicit assignment of a C<glob> expression to a scalar
+is used as a C<while>/C<for> condition, then the condition actually
+tests for definedness of the expression's value, not for its regular
+truth value.
+
Portability issues: L<perlport/glob>.
=item gmtime EXPR
Use of C<goto LABEL> or C<goto EXPR> to jump into a construct is
deprecated and will issue a warning. Even then, it may not be used to
go into any construct that requires initialization, such as a
-subroutine or a C<foreach> loop. It also can't be used to go into a
+subroutine, a C<foreach> loop, or a C<given>
+block. In general, it may not be used to jump into the parameter
+of a binary or list operator, but it may be used to jump into the
+I<first> parameter of a binary operator. (The C<=>
+assignment operator's "first" operand is its right-hand
+operand.) It also can't be used to go into a
construct that is optimized away.
The C<goto &NAME> form is quite different from the other forms of
insertion and deletion of items.
As a side effect, calling L<C<keys>|/keys HASH> resets the internal
-iterator of the HASH or ARRAY (see L<C<each>|/each HASH>). In
+iterator of the HASH or ARRAY (see L<C<each>|/each HASH>) before
+yielding the keys. In
particular, calling L<C<keys>|/keys HASH> in void context resets the
iterator with no other overhead.
#...
}
-L<C<last>|/last LABEL> cannot be used to exit a block that returns a
-value such as C<eval {}>, C<sub {}>, or C<do {}>, and should not be used
-to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
+L<C<last>|/last LABEL> cannot return a value from a block that typically
+returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
operation.
Note that a block by itself is semantically identical to a loop
=for Pod::Functions the current source line number
A special token that compiles to the current line number.
+It can be altered by the mechanism described at
+L<perlsyn/"Plain Old Comments (Not!)">.
=item link OLDFILE,NEWFILE
X<link>
to get a list of anonymous hashes each with only one entry apiece.
-=item mkdir FILENAME,MASK
+=item mkdir FILENAME,MODE
X<mkdir> X<md> X<directory, create>
=item mkdir FILENAME
=for Pod::Functions create a directory
Creates the directory specified by FILENAME, with permissions
-specified by MASK (as modified by L<C<umask>|/umask EXPR>). If it
+specified by MODE (as modified by L<C<umask>|/umask EXPR>). If it
succeeds it returns true; otherwise it returns false and sets
L<C<$!>|perlvar/$!> (errno).
-MASK defaults to 0777 if omitted, and FILENAME defaults
+MODE defaults to 0777 if omitted, and FILENAME defaults
to L<C<$_>|perlvar/$_> if omitted.
-In general, it is better to create directories with a permissive MASK
+In general, it is better to create directories with a permissive MODE
and let the user modify that with their L<C<umask>|/umask EXPR> than it
is to supply
-a restrictive MASK and give the user no way to be more permissive.
+a restrictive MODE and give the user no way to be more permissive.
The exceptions to this rule are when the file or directory should be
kept private (mail files, for instance). The documentation for
-L<C<umask>|/umask EXPR> discusses the choice of MASK in more detail.
+L<C<umask>|/umask EXPR> discusses the choice of MODE in more detail.
Note that according to the POSIX 1003.1-1996 the FILENAME may have any
number of trailing slashes. Some operating and filesystems do not get
as of Perl 5.18.0, allows a label name to be computed at run time, being
otherwise identical to C<next LABEL>.
-L<C<next>|/next LABEL> cannot be used to exit a block which returns a
-value such as C<eval {}>, C<sub {}>, or C<do {}>, and should not be used
-to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
+L<C<next>|/next LABEL> cannot return a value from a block that typically
+returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
operation.
Note that a block by itself is semantically identical to a loop
non-digits, such as a decimal point (L<C<oct>|/oct EXPR> only handles
non-negative integers, not negative integers or floating point).
-=item open FILEHANDLE,EXPR
-X<open> X<pipe> X<file, open> X<fopen>
-
=item open FILEHANDLE,MODE,EXPR
+X<open> X<pipe> X<file, open> X<fopen>
=item open FILEHANDLE,MODE,EXPR,LIST
=item open FILEHANDLE,MODE,REFERENCE
+=item open FILEHANDLE,EXPR
+
=item open FILEHANDLE
=for Pod::Functions open a file, pipe, or descriptor
-Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE.
+Associates an internal FILEHANDLE with the external file specified by
+EXPR. That filehandle will subsequently allow you to perform
+I/O operations on that file, such as reading from it or writing to it.
+
+Instead of a filename, you may specify an external command
+(plus an optional argument list) or a scalar reference, in order to open
+filehandles on commands or in-memory scalars, respectively.
+
+A thorough reference to C<open> follows. For a gentler introduction to
+the basics of C<open>, see also the L<perlopentut> manual page.
+
+=over
+
+=item Common usage: working with files
+
+Most often, C<open> gets invoked with three arguments: the required
+FILEHANDLE (usually an empty scalar variable), followed by MODE (usually
+a literal describing the I/O mode the filehandle will use), and then the
+filename that the new filehandle will refer to.
+
+=over
-Simple examples to open a file for reading:
+=item Simple examples
+
+Reading from a file:
open(my $fh, "<", "input.txt")
- or die "Can't open < input.txt: $!";
+ or die "Can't open < input.txt: $!";
+
+ # Process every line in input.txt
+ while (my $line = <$fh>) {
+ #
+ # ... do something interesting with $line here ...
+ #
+ }
-and for writing:
+or writing to one:
open(my $fh, ">", "output.txt")
- or die "Can't open > output.txt: $!";
-
-(The following is a comprehensive reference to
-L<C<open>|/open FILEHANDLE,EXPR>: for a gentler introduction you may
-consider L<perlopentut>.)
-
-If FILEHANDLE is an undefined scalar variable (or array or hash element), a
-new filehandle is autovivified, meaning that the variable is assigned a
-reference to a newly allocated anonymous filehandle. Otherwise if
-FILEHANDLE is an expression, its value is the real filehandle. (This is
-considered a symbolic reference, so C<use strict "refs"> should I<not> be
-in effect.)
-
-If three (or more) arguments are specified, the open mode (including
-optional encoding) in the second argument are distinct from the filename in
-the third. If MODE is C<< < >> or nothing, the file is opened for input.
+ or die "Can't open > output.txt: $!";
+
+ print $fh "This line gets printed directly into output.txt.\n";
+
+For a summary of common filehandle operations such as these, see
+L<perlintro/Files and I/O>.
+
+=item About filehandles
+
+The first argument to C<open>, labeled FILEHANDLE in this reference, is
+usually a scalar variable. (Exceptions exist, described in "Other
+considerations", below.) If the call to C<open> succeeds, then the
+expression provided as FILEHANDLE will get assigned an open
+I<filehandle>. That filehandle provides an internal reference to the
+specified external file, conveniently stored in a Perl variable, and
+ready for I/O operations such as reading and writing.
+
+=item About modes
+
+When calling C<open> with three or more arguments, the second argument
+-- labeled MODE here -- defines the I<open mode>. MODE is usually a
+literal string comprising special characters that define the intended
+I/O role of the filehandle being created: whether it's read-only, or
+read-and-write, and so on.
+
+If MODE is C<< < >>, the file is opened for input (read-only).
If MODE is C<< > >>, the file is opened for output, with existing files
first being truncated ("clobbered") and nonexisting files newly created.
If MODE is C<<< >> >>>, the file is opened for appending, again being
C<< +< >> is almost always preferred for read/write updates--the
C<< +> >> mode would clobber the file first. You can't usually use
either read-write mode for updating textfiles, since they have
-variable-length records. See the B<-i> switch in L<perlrun> for a
-better approach. The file is created with permissions of C<0666>
-modified by the process's L<C<umask>|/umask EXPR> value.
+variable-length records. See the B<-i> switch in
+L<perlrun|perlrun/-i[extension]> for a better approach. The file is
+created with permissions of C<0666> modified by the process's
+L<C<umask>|/umask EXPR> value.
These various prefixes correspond to the L<fopen(3)> modes of C<r>,
C<r+>, C<w>, C<w+>, C<a>, and C<a+>.
-In the one- and two-argument forms of the call, the mode and filename
-should be concatenated (in that order), preferably separated by white
-space. You can--but shouldn't--omit the mode in these forms when that mode
-is C<< < >>. It is safe to use the two-argument form of
-L<C<open>|/open FILEHANDLE,EXPR> if the filename argument is a known literal.
+More examples of different modes in action:
-For three or more arguments if MODE is C<|->, the filename is
-interpreted as a command to which output is to be piped, and if MODE
-is C<-|>, the filename is interpreted as a command that pipes
-output to us. In the two-argument (and one-argument) form, one should
-replace dash (C<->) with the command.
-See L<perlipc/"Using open() for IPC"> for more examples of this.
-(You are not allowed to L<C<open>|/open FILEHANDLE,EXPR> to a command
-that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, and
-L<perlipc/"Bidirectional Communication with Another Process"> for
-alternatives.)
+ # Open a file for concatenation
+ open(my $log, ">>", "/usr/spool/news/twitlog")
+ or warn "Couldn't open log file; input will be discarded";
-In the form of pipe opens taking three or more arguments, if LIST is specified
-(extra arguments after the command name) then LIST becomes arguments
-to the command invoked if the platform supports it. The meaning of
-L<C<open>|/open FILEHANDLE,EXPR> with more than three arguments for
-non-pipe modes is not yet defined, but experimental "layers" may give
-extra LIST arguments meaning.
+ # Open a file for reading and writing
+ open(my $dbase, "+<", "dbase.mine")
+ or die "Can't open 'dbase.mine' for update: $!";
-In the two-argument (and one-argument) form, opening C<< <- >>
-or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
+=item Checking the return value
+
+Open returns nonzero on success, the undefined value otherwise. If
+the L<C<open>|/open FILEHANDLE,MODE,EXPR> involved a pipe, the return value
+happens to be the pid of the subprocess.
+
+When opening a file, it's seldom a good idea to continue
+if the request failed, so L<C<open>|/open FILEHANDLE,MODE,EXPR> is frequently
+used with L<C<die>|/die LIST>. Even if you want your code to do
+something other than C<die> on a failed open, you should still always
+check
+the return value from opening a file.
+
+=back
+
+=item Specifying I/O layers in MODE
-You may (and usually should) use the three-argument form of open to specify
-I/O layers (sometimes referred to as "disciplines") to apply to the handle
-that affect how the input and output are processed (see L<open> and
+You can use the three-argument form of open to specify
+I/O layers (sometimes referred to as "disciplines") to apply to the new
+filehanle. These affect how the input and output are processed (see
+L<open> and
L<PerlIO> for more details). For example:
open(my $fh, "<:encoding(UTF-8)", $filename)
|| die "Can't open UTF-8 encoded $filename: $!";
-opens the UTF8-encoded file containing Unicode characters;
+This opens the UTF8-encoded file containing Unicode characters;
see L<perluniintro>. Note that if layers are specified in the
-three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
-usually set by the L<open> pragma or the switch C<-CioD>) are ignored.
+three-argument form, then default layers stored in
+L<C<${^OPEN}>|perlvar/${^OPEN}>
+(usually set by the L<open> pragma or the switch C<-CioD>) are ignored.
Those layers will also be ignored if you specify a colon with no name
following it. In that case the default layer for the operating system
(:raw on Unix, :crlf on Windows) is used.
-Open returns nonzero on success, the undefined value otherwise. If
-the L<C<open>|/open FILEHANDLE,EXPR> involved a pipe, the return value
-happens to be the pid of the subprocess.
-
On some systems (in general, DOS- and Windows-based systems)
L<C<binmode>|/binmode FILEHANDLE, LAYER> is necessary when you're not
working with a text file. For the sake of portability it is a good idea
appropriate. Also, people can set their I/O to be by default
UTF8-encoded Unicode, not bytes.
-When opening a file, it's seldom a good idea to continue
-if the request failed, so L<C<open>|/open FILEHANDLE,EXPR> is frequently
-used with L<C<die>|/die LIST>. Even if L<C<die>|/die LIST> won't do
-what you want (say, in a CGI script,
-where you want to format a suitable error message (but there are
-modules that can help with that problem)) always check
-the return value from opening a file.
-
-The filehandle will be closed when its reference count reaches zero.
-If it is a lexically scoped variable declared with L<C<my>|/my VARLIST>,
-that usually
-means the end of the enclosing scope. However, this automatic close
-does not check for errors, so it is better to explicitly close
-filehandles, especially those used for writing:
-
- close($handle)
- || warn "close failed: $!";
-
-An older style is to use a bareword as the filehandle, as
-
- open(FH, "<", "input.txt")
- or die "Can't open < input.txt: $!";
-
-Then you can use C<FH> as the filehandle, in C<< close FH >> and C<<
-<FH> >> and so on. Note that it's a global variable, so this form is
-not recommended in new code.
-
-As a shortcut a one-argument call takes the filename from the global
-scalar variable of the same name as the filehandle:
-
- $ARTICLE = 100;
- open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
-
-Here C<$ARTICLE> must be a global (package) scalar variable - not one
-declared with L<C<my>|/my VARLIST> or L<C<state>|/state VARLIST>.
+=item Using C<undef> for temporary files
As a special case the three-argument form with a read/write mode and the third
argument being L<C<undef>|/undef EXPR>:
sensible mode to use.) You will need to
L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> to do the reading.
-Perl is built using PerlIO by default. Unless you've
-changed this (such as building Perl with C<Configure -Uuseperlio>), you can
-open filehandles directly to Perl scalars via:
- open(my $fh, ">", \$variable) || ..
+=item Opening a filehandle into an in-memory scalar
+
+You can open filehandles directly to Perl scalars instead of a file or
+other resource external to the program. Accomplish this by providing a
+reference to that scalar as the third argument to C<open>, like so:
+
+ open(my $memory, ">", \$var)
+ or die "Can't open memory file: $!";
+ print $memory "foo!\n"; # output will appear in $var
To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:
Opening in-memory files I<can> fail for a variety of reasons. As with
any other C<open>, check the return value for success.
+I<Technical note>: This feature works only when Perl is built with
+PerlIO -- the default, except with older (pre-5.16) Perl installations
+specifically built without it (e.g. via C<Configure -Uuseperlio>). You
+can see whether your Perl was built with PerlIO by running C<perl
+-V:useperlio>. If it says C<'define'>, you have PerlIO; otherwise you
+don't.
+
See L<perliol> for detailed info on PerlIO.
-General examples:
+=item Opening a filehandle into a command
- open(my $log, ">>", "/usr/spool/news/twitlog");
- # if the open fails, output is discarded
+If MODE is C<|->, then the filename is
+interpreted as a command to which output is to be piped, and if MODE
+is C<-|>, the filename is interpreted as a command that pipes
+output to us. In the two-argument (and one-argument) form, one should
+replace dash (C<->) with the command.
+See L<perlipc/"Using open() for IPC"> for more examples of this.
+(You are not allowed to L<C<open>|/open FILEHANDLE,MODE,EXPR> to a command
+that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, and
+L<perlipc/"Bidirectional Communication with Another Process"> for
+alternatives.)
- open(my $dbase, "+<", "dbase.mine") # open for update
- or die "Can't open 'dbase.mine' for update: $!";
-
- open(my $dbase, "+<dbase.mine") # ditto
- or die "Can't open 'dbase.mine' for update: $!";
open(my $article_fh, "-|", "caesar <$article") # decrypt
# article
or die "Can't start caesar: $!";
-
+
open(my $article_fh, "caesar <$article |") # ditto
or die "Can't start caesar: $!";
open(my $out_fh, "|-", "sort >Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
- # in-memory files
- open(my $memory, ">", \$var)
- or die "Can't open memory file: $!";
- print $memory "foo!\n"; # output will appear in $var
+
+In the form of pipe opens taking three or more arguments, if LIST is specified
+(extra arguments after the command name) then LIST becomes arguments
+to the command invoked if the platform supports it. The meaning of
+L<C<open>|/open FILEHANDLE,MODE,EXPR> with more than three arguments for
+non-pipe modes is not yet defined, but experimental "layers" may give
+extra LIST arguments meaning.
+
+If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
+with the one- or two-argument forms of
+L<C<open>|/open FILEHANDLE,MODE,EXPR>), an implicit L<C<fork>|/fork> is done,
+so L<C<open>|/open FILEHANDLE,MODE,EXPR> returns twice: in the parent process
+it returns the pid
+of the child process, and in the child process it returns (a defined) C<0>.
+Use C<defined($pid)> or C<//> to determine whether the open was successful.
+
+For example, use either
+
+ my $child_pid = open(my $from_kid, "-|") // die "Can't fork: $!";
+
+or
+
+ my $child_pid = open(my $to_kid, "|-") // die "Can't fork: $!";
+
+followed by
+
+ if ($child_pid) {
+ # am the parent:
+ # either write $to_kid or else read $from_kid
+ ...
+ waitpid $child_pid, 0;
+ } else {
+ # am the child; use STDIN/STDOUT normally
+ ...
+ exit;
+ }
+
+The filehandle behaves normally for the parent, but I/O to that
+filehandle is piped from/to the STDOUT/STDIN of the child process.
+In the child process, the filehandle isn't opened--I/O happens from/to
+the new STDOUT/STDIN. Typically this is used like the normal
+piped open when you want to exercise more control over just how the
+pipe command gets executed, such as when running setuid and
+you don't want to have to scan shell commands for metacharacters.
+
+The following blocks are more or less equivalent:
+
+ open(my $fh, "|tr '[a-z]' '[A-Z]'");
+ open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
+ open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
+ open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
+
+ open(my $fh, "cat -n '$file'|");
+ open(my $fh, "-|", "cat -n '$file'");
+ open(my $fh, "-|") || exec "cat", "-n", $file;
+ open(my $fh, "-|", "cat", "-n", $file);
+
+The last two examples in each block show the pipe as "list form", which is
+not yet supported on all platforms. A good rule of thumb is that if
+your platform has a real L<C<fork>|/fork> (in other words, if your platform is
+Unix, including Linux and MacOS X), you can use the list form. You would
+want to use the list form of the pipe so you can pass literal arguments
+to the command without risk of the shell interpreting any shell metacharacters
+in them. However, this also bars you from opening pipes to commands
+that intentionally contain shell metacharacters, such as:
+
+ open(my $fh, "|cat -n | expand -4 | lpr")
+ || die "Can't open pipeline to lpr: $!";
+
+See L<perlipc/"Safe Pipe Opens"> for more examples of this.
+
+=item Duping filehandles
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<< >& >>, in which case the rest of the string is interpreted
L<fdopen(3)> fails when file descriptors exceed a certain value, typically 255.
For Perls 5.8.0 and later, PerlIO is (most often) the default.
-You can see whether your Perl was built with PerlIO by running
-C<perl -V:useperlio>. If it says C<'define'>, you have PerlIO;
-otherwise you don't.
+=item Legacy usage
-If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
-with the one- or two-argument forms of
-L<C<open>|/open FILEHANDLE,EXPR>), an implicit L<C<fork>|/fork> is done,
-so L<C<open>|/open FILEHANDLE,EXPR> returns twice: in the parent process
-it returns the pid
-of the child process, and in the child process it returns (a defined) C<0>.
-Use C<defined($pid)> or C<//> to determine whether the open was successful.
+This section describes ways to call C<open> outside of best practices;
+you may encounter these uses in older code. Perl does not consider their
+use deprecated, exactly, but neither is it recommended in new code, for
+the sake of clarity and readability.
-For example, use either
+=over
- my $child_pid = open(my $from_kid, "-|") // die "Can't fork: $!";
+=item Specifying mode and filename as a single argument
-or
+In the one- and two-argument forms of the call, the mode and filename
+should be concatenated (in that order), preferably separated by white
+space. You can--but shouldn't--omit the mode in these forms when that mode
+is C<< < >>. It is safe to use the two-argument form of
+L<C<open>|/open FILEHANDLE,MODE,EXPR> if the filename argument is a known literal.
- my $child_pid = open(my $to_kid, "|-") // die "Can't fork: $!";
+ open(my $dbase, "+<dbase.mine") # ditto
+ or die "Can't open 'dbase.mine' for update: $!";
-followed by
+In the two-argument (and one-argument) form, opening C<< <- >>
+or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
- if ($child_pid) {
- # am the parent:
- # either write $to_kid or else read $from_kid
- ...
- waitpid $child_pid, 0;
- } else {
- # am the child; use STDIN/STDOUT normally
- ...
- exit;
- }
+New code should favor the three-argument form of C<open> over this older
+form. Declaring the mode and the filename as two distinct arguments
+avoids any confusion between the two.
-The filehandle behaves normally for the parent, but I/O to that
-filehandle is piped from/to the STDOUT/STDIN of the child process.
-In the child process, the filehandle isn't opened--I/O happens from/to
-the new STDOUT/STDIN. Typically this is used like the normal
-piped open when you want to exercise more control over just how the
-pipe command gets executed, such as when running setuid and
-you don't want to have to scan shell commands for metacharacters.
+=item Calling C<open> with one argument via global variables
-The following blocks are more or less equivalent:
+As a shortcut, a one-argument call takes the filename from the global
+scalar variable of the same name as the filehandle:
- open(my $fh, "|tr '[a-z]' '[A-Z]'");
- open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
- open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
- open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
+ $ARTICLE = 100;
+ open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
- open(my $fh, "cat -n '$file'|");
- open(my $fh, "-|", "cat -n '$file'");
- open(my $fh, "-|") || exec "cat", "-n", $file;
- open(my $fh, "-|", "cat", "-n", $file);
+Here C<$ARTICLE> must be a global (package) scalar variable - not one
+declared with L<C<my>|/my VARLIST> or L<C<state>|/state VARLIST>.
-The last two examples in each block show the pipe as "list form", which is
-not yet supported on all platforms. A good rule of thumb is that if
-your platform has a real L<C<fork>|/fork> (in other words, if your platform is
-Unix, including Linux and MacOS X), you can use the list form. You would
-want to use the list form of the pipe so you can pass literal arguments
-to the command without risk of the shell interpreting any shell metacharacters
-in them. However, this also bars you from opening pipes to commands
-that intentionally contain shell metacharacters, such as:
+=item Assigning a filehandle to a bareword
- open(my $fh, "|cat -n | expand -4 | lpr")
- || die "Can't open pipeline to lpr: $!";
+An older style is to use a bareword as the filehandle, as
-See L<perlipc/"Safe Pipe Opens"> for more examples of this.
+ open(FH, "<", "input.txt")
+ or die "Can't open < input.txt: $!";
+
+Then you can use C<FH> as the filehandle, in C<< close FH >> and C<<
+<FH> >> and so on. Note that it's a global variable, so this form is
+not recommended in new code.
+
+=back
+
+=item Other considerations
+
+=over
+
+=item Automatic filehandle closure
+
+The filehandle will be closed when its reference count reaches zero.
+If it is a lexically scoped variable declared with L<C<my>|/my VARLIST>,
+that usually
+means the end of the enclosing scope. However, this automatic close
+does not check for errors, so it is better to explicitly close
+filehandles, especially those used for writing:
+
+ close($handle)
+ || warn "close failed: $!";
+
+=item Automatic pipe flushing
Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
child to finish, then returns the status value in L<C<$?>|perlvar/$?> and
L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}>.
+=item Direct versus by-reference assignment of filehandles
+
+If FILEHANDLE -- the first argument in a call to C<open> -- is an
+undefined scalar variable (or array or hash element), a new filehandle
+is autovivified, meaning that the variable is assigned a reference to a
+newly allocated anonymous filehandle. Otherwise if FILEHANDLE is an
+expression, its value is the real filehandle. (This is considered a
+symbolic reference, so C<use strict "refs"> should I<not> be in effect.)
+
+=item Whitespace and special characters in the filename argument
+
The filename passed to the one- and two-argument forms of
-L<C<open>|/open FILEHANDLE,EXPR> will
+L<C<open>|/open FILEHANDLE,MODE,EXPR> will
have leading and trailing whitespace deleted and normal
redirection characters honored. This property, known as "magic open",
can often be used to good effect. A user could specify a filename of
(this may not work on some bizarre filesystems). One should
conscientiously choose between the I<magic> and I<three-argument> form
-of L<C<open>|/open FILEHANDLE,EXPR>:
+of L<C<open>|/open FILEHANDLE,MODE,EXPR>:
open(my $in, $ARGV[0]) || die "Can't open $ARGV[0]: $!";
support the syntax C<< perl your_program.pl <( rsh cat file ) >>, which
produces a filename that can be opened normally.)
+=item Invoking C-style C<open>
+
If you want a "real" C L<open(2)>, then you should use the
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> function, which involves
no such magic (but uses different filemodes than Perl
-L<C<open>|/open FILEHANDLE,EXPR>, which corresponds to C L<fopen(3)>).
+L<C<open>|/open FILEHANDLE,MODE,EXPR>, which corresponds to C L<fopen(3)>).
This is another way to protect your filenames from interpretation. For
example:
See L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> for some details about
mixing reading and writing.
-Portability issues: L<perlport/open>.
+=item Portability issues
+
+See L<perlport/open>.
+
+=back
+
+=back
+
=item opendir DIRHANDLE,EXPR
X<opendir>
those. Raises an exception otherwise.)
i A signed integer value.
- I A unsigned integer value.
+ I An unsigned integer value.
(This 'integer' is _at_least_ 32 bits wide. Its exact
size depends on what a local C compiler calls 'int'.)
considered to be word characters.
Otherwise, Perl quotes non-ASCII characters using an adaptation from
-Unicode (see L<http://www.unicode.org/reports/tr31/>).
+Unicode (see L<https://www.unicode.org/reports/tr31/>).
The only code points that are quoted are those that have any of the
Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space,
Default_Ignorable_Code_Point, or General_Category=Control.
bytes before the result of the read is appended.
The call is implemented in terms of either Perl's or your system's native
-L<fread(3)> library function. To get a true L<read(2)> system call, see
+L<fread(3)> library function, via the L<PerlIO> layers applied to the
+handle. To get a true L<read(2)> system call, see
L<sysread|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>.
Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read. By default, all
filehandles operate on bytes, but for example if the filehandle has
been opened with the C<:utf8> I/O layer (see
-L<C<open>|/open FILEHANDLE,EXPR>, and the L<open>
+L<C<open>|/open FILEHANDLE,MODE,EXPR>, and the L<open>
pragma), the I/O will operate on UTF8-encoded Unicode
characters, not bytes. Similarly for the C<:encoding> layer:
in that case pretty much any characters can be read.
As of Perl 5.12 you can use a bare L<C<readdir>|/readdir DIRHANDLE> in a
C<while> loop, which will set L<C<$_>|perlvar/$_> on every iteration.
+If either a C<readdir> expression or an explicit assignment of a
+C<readdir> expression to a scalar is used as a C<while>/C<for> condition,
+then the condition actually tests for definedness of the expression's
+value, not for its regular truth value.
opendir(my $dh, $some_dir) || die "Can't open $some_dir: $!";
while (readdir $dh) {
}
}
+Like the C<< <EXPR> >> operator, if a C<readline> expression is
+used as the condition of a C<while> or C<for> loop, then it will be
+implicitly assigned to C<$_>. If either a C<readline> expression or
+an explicit assignment of a C<readline> expression to a scalar is used
+as a C<while>/C<for> condition, then the condition actually tests for
+definedness of the expression's value, not for its regular truth value.
+
=item readlink EXPR
X<readlink>
C<$INPUT_RECORD_SEPARATOR> in L<English>)).
This is the internal function implementing the C<qx/EXPR/>
operator, but you can use it directly. The C<qx/EXPR/>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
+operator is discussed in more detail in L<perlop/"C<qx/I<STRING>/>">.
If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
=item recv SOCKET,SCALAR,LENGTH,FLAGS
This call is actually implemented in terms of the L<recvfrom(2)> system call.
See L<perlipc/"UDP: Message Passing"> for examples.
-Note the I<characters>: depending on the status of the socket, either
-(8-bit) bytes or characters are received. By default all sockets
-operate on bytes, but for example if the socket has been changed using
-L<C<binmode>|/binmode FILEHANDLE, LAYER> to operate with the
-C<:encoding(UTF-8)> I/O layer (see the L<open> pragma), the I/O will
-operate on UTF8-encoded Unicode
-characters, not bytes. Similarly for the C<:encoding> layer: in that
-case pretty much any characters can be read.
+Note that if the socket has been marked as C<:utf8>, C<recv> will
+throw an exception. The C<:encoding(...)> layer implicitly introduces
+the C<:utf8> layer. See L<C<binmode>|/binmode FILEHANDLE, LAYER>.
=item redo LABEL
X<redo>
print;
}
-L<C<redo>|/redo LABEL> cannot be used to retry a block that returns a
-value such as C<eval {}>, C<sub {}>, or C<do {}>, and should not be used
-to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
+L<C<redo>|/redo LABEL> cannot return a value from a block that typically
+returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
+its flow control behavior, which precludes any return value. It should not be
+used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
operation.
Note that a block by itself is semantically identical to a loop
=for Pod::Functions find out the type of thing being referenced
-Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR is not specified, L<C<$_>|perlvar/$_> will be
-used. The value returned depends on the type of thing the reference is
-a reference to.
-
-Builtin types include:
-
- SCALAR
- ARRAY
- HASH
- CODE
- REF
- GLOB
- LVALUE
- FORMAT
- IO
- VSTRING
- Regexp
-
-You can think of L<C<ref>|/ref EXPR> as a C<typeof> operator.
-
- if (ref($r) eq "HASH") {
- print "r is a reference to a hash.\n";
- }
- unless (ref($r)) {
- print "r is not a reference at all.\n";
- }
-
-The return value C<LVALUE> indicates a reference to an lvalue that is not
-a variable. You get this from taking the reference of function calls like
-L<C<pos>|/pos SCALAR> or
-L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT>. C<VSTRING> is
-returned if the reference points to a
-L<version string|perldata/"Version Strings">.
-
-The result C<Regexp> indicates that the argument is a regular expression
-resulting from L<C<qrE<sol>E<sol>>|/qrE<sol>STRINGE<sol>>.
-
-If the referenced object has been blessed into a package, then that package
-name is returned instead. But don't use that, as it's now considered
-"bad practice". For one reason, an object could be using a class called
-C<Regexp> or C<IO>, or even C<HASH>. Also, L<C<ref>|/ref EXPR> doesn't
-take into account subclasses, like
-L<C<isa>|UNIVERSAL/C<< $obj->isa( TYPE ) >>> does.
-
-Instead, use L<C<blessed>|Scalar::Util/blessed> (in the L<Scalar::Util>
-module) for boolean checks, L<C<isa>|UNIVERSAL/C<< $obj->isa( TYPE ) >>>
-for specific class checks and L<C<reftype>|Scalar::Util/reftype> (also
-from L<Scalar::Util>) for type checks. (See L<perlobj> for details and
-a L<C<blessed>|Scalar::Util/blessed>/L<C<isa>|UNIVERSAL/C<< $obj->isa( TYPE ) >>>
-example.)
-
-See also L<perlref>.
+Examines the value of EXPR, expecting it to be a reference, and returns
+a string giving information about the reference and the type of referent.
+If EXPR is not specified, L<C<$_>|perlvar/$_> will be used.
+
+If the operand is not a reference, then the empty string will be returned.
+An empty string will only be returned in this situation. C<ref> is often
+useful to just test whether a value is a reference, which can be done
+by comparing the result to the empty string. It is a common mistake
+to use the result of C<ref> directly as a truth value: this goes wrong
+because C<0> (which is false) can be returned for a reference.
+
+If the operand is a reference to a blessed object, then the name of
+the class into which the referent is blessed will be returned. C<ref>
+doesn't care what the physical type of the referent is; blessing takes
+precedence over such concerns. Beware that exact comparison of C<ref>
+results against a class name doesn't perform a class membership test:
+a class's members also include objects blessed into subclasses, for
+which C<ref> will return the name of the subclass. Also beware that
+class names can clash with the built-in type names (described below).
+
+If the operand is a reference to an unblessed object, then the return
+value indicates the type of object. If the unblessed referent is not
+a scalar, then the return value will be one of the strings C<ARRAY>,
+C<HASH>, C<CODE>, C<FORMAT>, or C<IO>, indicating only which kind of
+object it is. If the unblessed referent is a scalar, then the return
+value will be one of the strings C<SCALAR>, C<VSTRING>, C<REF>, C<GLOB>,
+C<LVALUE>, or C<REGEXP>, depending on the kind of value the scalar
+currently has. But note that C<qr//> scalars are created already
+blessed, so C<ref qr/.../> will likely return C<Regexp>. Beware that
+these built-in type names can also be used as
+class names, so C<ref> returning one of these names doesn't unambiguously
+indicate that the referent is of the kind to which the name refers.
+
+The ambiguity between built-in type names and class names significantly
+limits the utility of C<ref>. For unambiguous information, use
+L<C<Scalar::Util::blessed()>|Scalar::Util/blessed> for information about
+blessing, and L<C<Scalar::Util::reftype()>|Scalar::Util/reftype> for
+information about physical types. Use L<the C<isa> method|UNIVERSAL/C<<
+$obj->isa( TYPE ) >>> for class membership tests, though one must be
+sure of blessedness before attempting a method call.
+
+See also L<perlref> and L<perlobj>.
=item rename OLDNAME,NEWNAME
X<rename> X<move> X<mv> X<ren>
Demands a version of Perl specified by VERSION, or demands some semantics
specified by EXPR or by L<C<$_>|perlvar/$_> if EXPR is not supplied.
-VERSION may be either a numeric argument such as 5.006, which will be
-compared to L<C<$]>|perlvar/$]>, or a literal of the form v5.6.1, which
-will be compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in
-L<English>). An exception is raised if VERSION is greater than the
-version of the current Perl interpreter. Compare with
+VERSION may be either a literal such as v5.24.1, which will be
+compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in L<English>),
+or a numeric argument of the form 5.024001, which will be compared to
+L<C<$]>|perlvar/$]>. An exception is raised if VERSION is greater than
+the version of the current Perl interpreter. Compare with
L<C<use>|/use Module VERSION LIST>, which can do a similar check at
compile time.
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl that do not support this syntax. The equivalent numeric
-version should be used instead.
+Specifying VERSION as a numeric argument of the form 5.024001 should
+generally be avoided as older less readable syntax compared to
+v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose numeric
+form was the only supported syntax, which is why you might see it in
+older code.
- require v5.6.1; # run time version check
- require 5.6.1; # ditto
- require 5.006_001; # ditto; preferred for backwards
- compatibility
+ require v5.24.1; # run time version check
+ require 5.24.1; # ditto
+ require 5.024_001; # ditto; older syntax compatible
+ with perl 5.6
Otherwise, L<C<require>|/require VERSION> demands that a library file be
included if it hasn't already been included. The file is included via
If EXPR is a bareword, L<C<require>|/require VERSION> assumes a F<.pm>
extension and replaces C<::> with C</> in the filename for you,
to make it easy to load standard modules. This form of loading of
-modules does not risk altering your namespace.
+modules does not risk altering your namespace, however it will autovivify
+the stash for the required module.
In other words, if you try this:
require Foo::Bar; # a splendid bareword
The require function will actually look for the F<Foo/Bar.pm> file in the
-directories specified in the L<C<@INC>|perlvar/@INC> array.
+directories specified in the L<C<@INC>|perlvar/@INC> array, and it will
+autovivify the C<Foo::Bar::> stash at compile time.
But if you try this:
eval "require $class";
+or you could do
+
+ require "Foo/Bar.pm";
+
+Neither of these forms will autovivify any stashes at compile time and
+only have run time effects.
+
Now that you understand how L<C<require>|/require VERSION> looks for
files with a bareword argument, there is a little extra functionality
going on behind the scenes. Before L<C<require>|/require VERSION> looks
for a F<.pm> extension, it will first look for a similar filename with a
F<.pmc> extension. If this file is found, it will be loaded in place of
-any file ending in a F<.pm> extension.
+any file ending in a F<.pm> extension. This applies to both the explicit
+C<require "Foo/Bar.pm";> form and the C<require Foo::Bar;> form.
You can also insert hooks into the import facility by putting Perl code
directly into the L<C<@INC>|perlvar/@INC> array. There are three forms
line as read in L<C<$_>|perlvar/$_>.
Again, return 1 for each valid line, and 0 after all lines have been
returned.
+For historical reasons the subroutine will receive a meaningless argument
+(in fact always the numeric value zero) as C<$_[0]>.
=item 4
-Optional state for the subroutine. The state is passed in as C<$_[1]>. A
-reference to the subroutine itself is passed in as C<$_[0]>.
+Optional state for the subroutine. The state is passed in as C<$_[1]>.
=back
loop to clear variables and reset C<m?pattern?> searches so that they
work again. The
expression is interpreted as a list of single characters (hyphens
-allowed for ranges). All variables and arrays beginning with one of
+allowed for ranges). All variables (scalars, arrays, and hashes)
+in the current package beginning with one of
those letters are reset to their pristine state. If the expression is
omitted, one-match searches (C<m?pattern?>) are reset to match again.
Only resets variables or searches in the current package. Always returns
Resetting C<"A-Z"> is not recommended because you'll wipe out your
L<C<@ARGV>|perlvar/@ARGV> and L<C<@INC>|perlvar/@INC> arrays and your
L<C<%ENV>|perlvar/%ENV> hash.
+
Resets only package variables; lexical variables are unaffected, but
they clean themselves up on scope exit anyway, so you'll probably want
to use them instead. See L<C<my>|/my VARLIST>.
Returns from a subroutine, L<C<eval>|/eval EXPR>,
L<C<do FILE>|/do EXPR>, L<C<sort>|/sort SUBNAME LIST> block or regex
-eval block (but not a L<C<grep>|/grep BLOCK LIST> or
-L<C<map>|/map BLOCK LIST> block) with the value
+eval block (but not a L<C<grep>|/grep BLOCK LIST>,
+L<C<map>|/map BLOCK LIST>, or L<C<do BLOCK>|/do BLOCK> block) with the value
given in EXPR. Evaluation of EXPR may be in list, scalar, or void
context, depending on how the return value will be used, and the context
may vary from one execution to the next (see
=for Pod::Functions +say output a list to a filehandle, appending a newline
Just like L<C<print>|/print FILEHANDLE LIST>, but implicitly appends a
-newline. C<say LIST> is simply an abbreviation for
-C<{ local $\ = "\n"; print LIST }>. To use FILEHANDLE without a LIST to
+newline at the end of the LIST instead of any value L<C<$\>|perlvar/$\>
+might have. To use FILEHANDLE without a LIST to
print the contents of L<C<$_>|perlvar/$_> to it, you must use a bareword
filehandle like C<FH>, not an indirect one like C<$fh>.
or the undefined value on error. The L<sendmsg(2)> syscall is currently
unimplemented. See L<perlipc/"UDP: Message Passing"> for examples.
-Note the I<characters>: depending on the status of the socket, either
-(8-bit) bytes or characters are sent. By default all sockets operate
-on bytes, but for example if the socket has been changed using
-L<C<binmode>|/binmode FILEHANDLE, LAYER> to operate with the
-C<:encoding(UTF-8)> I/O layer (see L<C<open>|/open FILEHANDLE,EXPR>, or
-the L<open> pragma), the I/O will operate on UTF-8
-encoded Unicode characters, not bytes. Similarly for the C<:encoding>
-layer: in that case pretty much any characters can be sent.
+Note that if the socket has been marked as C<:utf8>, C<send> will
+throw an exception. The C<:encoding(...)> layer implicitly introduces
+the C<:utf8> layer. See L<C<binmode>|/binmode FILEHANDLE, LAYER>.
=item setpgrp PID,PGRP
X<setpgrp> X<group>
(See L<setpriority(2)>.) Raises an exception when used on a machine
that doesn't implement L<setpriority(2)>.
+C<WHICH> can be any of C<PRIO_PROCESS>, C<PRIO_PGRP> or C<PRIO_USER>
+imported from L<POSIX/RESOURCE CONSTANTS>.
+
Portability issues: L<perlport/setpriority>.
=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
Portability issues: L<perlport/socketpair>.
=item sort SUBNAME LIST
-X<sort> X<qsort> X<quicksort> X<mergesort>
+X<sort>
=item sort BLOCK LIST
actually modifies the element in the original list. This is usually
something to be avoided when writing clear code.
-Perl 5.6 and earlier used a quicksort algorithm to implement sort.
-That algorithm was not stable and I<could> go quadratic. (A I<stable> sort
-preserves the input order of elements that compare equal. Although
-quicksort's run time is O(NlogN) when averaged over all arrays of
-length N, the time can be O(N**2), I<quadratic> behavior, for some
-inputs.) In 5.7, the quicksort implementation was replaced with
-a stable mergesort algorithm whose worst-case behavior is O(NlogN).
-But benchmarks indicated that for some inputs, on some platforms,
-the original quicksort was faster. 5.8 has a L<sort> pragma for
-limited control of the sort. Its rather blunt control of the
-underlying algorithm may not persist into future Perls, but the
-ability to characterize the input or output in implementation
-independent ways quite probably will.
+Historically Perl has varied in whether sorting is stable by default.
+If stability matters, it can be controlled explicitly by using the
+L<sort> pragma.
Examples:
package main;
my @new = sort Other::backwards @old;
- # guarantee stability, regardless of algorithm
+ # guarantee stability
use sort 'stable';
my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
- # force use of mergesort (not portable outside Perl 5.8)
- use sort '_mergesort'; # note discouraging _
- my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
Warning: syntactical care is required when sorting the list returned from
a function. If you want to sort the list returned by the function call
C<find_records(@key)>, you can use:
# prints tinysmallnormalbighuge
-C<$a> and C<$b> are implicitely local to the sort() execution and regain their
+C<$a> and C<$b> are implicitly local to the sort() execution and regain their
former values upon completing the sort.
Sort subroutines written using C<$a> and C<$b> are bound to their calling
h interpret integer as C type "short" or
"unsigned short"
j interpret integer as C type "intmax_t" on Perl
- 5.14 or later, and only with a C99 compiler
- (unportable)
+ 5.14 or later; and prior to Perl 5.30, only with
+ a C99 compiler (unportable)
l interpret integer as C type "long" or
"unsigned long"
q, L, or ll interpret integer as C type "long long",
64-bit integers)
t interpret integer as C type "ptrdiff_t" on Perl
5.14 or later
- z interpret integer as C type "size_t" on Perl 5.14
- or later
+ z interpret integer as C types "size_t" or
+ "ssize_t" on Perl 5.14 or later
As of 5.14, none of these raises an exception if they are not supported on
your platform. However, if warnings are enabled, a warning of the
(This works on machines only for which the device number is negative
under NFS.)
+On some platforms inode numbers are of a type larger than perl knows how
+to handle as integer numerical values. If necessary, an inode number will
+be returned as a decimal string in order to preserve the entire value.
+If used in a numeric context, this will be converted to a floating-point
+numerical value, with rounding, a fate that is best avoided. Therefore,
+you should prefer to compare inode numbers using C<eq> rather than C<==>.
+C<eq> will work fine on inode numbers that are represented numerically,
+as well as those represented as strings.
+
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">
if you want to see the real permissions.
parentheses. With a parenthesised list, L<C<undef>|/undef EXPR> can be
used as a
dummy placeholder. However, since initialization of state variables in
-list context is currently not possible this would serve no purpose.
+such lists is currently not possible this would serve no purpose.
L<C<state>|/state VARLIST> is available only if the
L<C<"state"> feature|feature/The 'state' feature> is enabled or if it is
Returns true on success and L<C<undef>|/undef EXPR> otherwise.
+L<PerlIO> layers will be applied to the handle the same way they would in an
+L<C<open>|/open FILEHANDLE,MODE,EXPR> call that does not specify layers. That is,
+the current value of L<C<${^OPEN}>|perlvar/${^OPEN}> as set by the L<open>
+pragma in a lexical scope, or the C<-C> commandline option or C<PERL_UNICODE>
+environment variable in the main program scope, falling back to the platform
+defaults as described in L<PerlIO/Defaults and how to override them>. If you
+want to remove any layers that may transform the byte stream, use
+L<C<binmode>|/binmode FILEHANDLE, LAYER> after opening it.
+
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module
L<C<Fcntl>|Fcntl>. See the documentation of your operating system's
use them in new code.
If the file named by FILENAME does not exist and the
-L<C<open>|/open FILEHANDLE,EXPR> call creates
+L<C<open>|/open FILEHANDLE,MODE,EXPR> call creates
it (typically because MODE includes the C<O_CREAT> flag), then the value of
PERMS specifies the permissions of the newly created file. If you omit
the PERMS argument to L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>,
that takes away the user's option to have a more permissive umask.
Better to omit it. See L<C<umask>|/umask EXPR> for more on this.
+This function has no direct relation to the usage of
+L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
+L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>,
+or L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>. A handle opened with
+this function can be used with buffered IO just as one opened with
+L<C<open>|/open FILEHANDLE,MODE,EXPR> can be used with unbuffered IO.
+
Note that under Perls older than 5.8.0,
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> depends on the
L<fdopen(3)> C library function. On many Unix systems, L<fdopen(3)> is known
=for Pod::Functions fixed-length unbuffered input from a filehandle
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using L<read(2)>. It bypasses
-buffered IO, so mixing this with other kinds of reads,
+specified FILEHANDLE, using L<read(2)>. It bypasses any L<PerlIO> layers
+including buffered IO (but is affected by the presence of the C<:utf8>
+layer as described later), so mixing this with other kinds of reads,
L<C<print>|/print FILEHANDLE LIST>, L<C<write>|/write FILEHANDLE>,
L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> can cause
confusion because the
-perlio or stdio layers usually buffer data. Returns the number of
+C<:perlio> or C<:crlf> layers usually buffer data. Returns the number of
bytes actually read, C<0> at end of file, or undef if there was an
error (in the latter case L<C<$!>|perlvar/$!> is also set). SCALAR will
be grown or
There is no syseof() function, which is ok, since
L<C<eof>|/eof FILEHANDLE> doesn't work well on device files (like ttys)
anyway. Use L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> and
-check for a return value for 0 to decide whether you're done.
+check for a return value of 0 to decide whether you're done.
-Note that if the filehandle has been marked as C<:utf8>, Unicode
-characters are read instead of bytes (the LENGTH, OFFSET, and the
-return value of L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>
-are in Unicode characters). The C<:encoding(...)> layer implicitly
+Note that if the filehandle has been marked as C<:utf8>, C<sysread> will
+throw an exception. The C<:encoding(...)> layer implicitly
introduces the C<:utf8> layer. See
L<C<binmode>|/binmode FILEHANDLE, LAYER>,
-L<C<open>|/open FILEHANDLE,EXPR>, and the L<open> pragma.
+L<C<open>|/open FILEHANDLE,MODE,EXPR>, and the L<open> pragma.
=item sysseek FILEHANDLE,POSITION,WHENCE
X<sysseek> X<lseek>
Sets FILEHANDLE's system position I<in bytes> using L<lseek(2)>. FILEHANDLE may
be an expression whose value gives the name of the filehandle. The values
-for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it
+for WHENCE are C<0> to set the new position to POSITION; C<1> to set it
to the current position plus POSITION; and C<2> to set it to EOF plus
POSITION, typically negative.
Attempts to write LENGTH bytes of data from variable SCALAR to the
specified FILEHANDLE, using L<write(2)>. If LENGTH is
-not specified, writes whole SCALAR. It bypasses buffered IO, so
+not specified, writes whole SCALAR. It bypasses any L<PerlIO> layers
+including buffered IO (but is affected by the presence of the C<:utf8>
+layer as described later), so
mixing this with reads (other than C<sysread)>),
L<C<print>|/print FILEHANDLE LIST>, L<C<write>|/write FILEHANDLE>,
L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> may cause
-confusion because the perlio and stdio layers usually buffer data.
+confusion because the C<:perlio> and C<:crlf> layers usually buffer data.
Returns the number of bytes actually written, or L<C<undef>|/undef EXPR>
if there was an error (in this case the errno variable
L<C<$!>|perlvar/$!> is also set). If the LENGTH is greater than the
that many characters counting backwards from the end of the string.
If SCALAR is of length zero, you can only use an OFFSET of 0.
-B<WARNING>: If the filehandle is marked C<:utf8>, Unicode characters
-encoded in UTF-8 are written instead of bytes, and the LENGTH, OFFSET, and
-return value of L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>
-are in (UTF8-encoded Unicode) characters.
+B<WARNING>: If the filehandle is marked C<:utf8>, C<syswrite> will raise an exception.
The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
Alternately, if the handle is not marked with an encoding but you
attempt to write characters with code points over 255, raises an exception.
See L<C<binmode>|/binmode FILEHANDLE, LAYER>,
-L<C<open>|/open FILEHANDLE,EXPR>, and the L<open> pragma.
+L<C<open>|/open FILEHANDLE,MODE,EXPR>, and the L<open> pragma.
=item tell FILEHANDLE
X<tell>
bits, or three octal digits: C<0750> (the leading 0 indicates octal
and isn't one of the digits). The L<C<umask>|/umask EXPR> value is such
a number representing disabled permissions bits. The permission (or
-"mode") values you pass L<C<mkdir>|/mkdir FILENAME,MASK> or
+"mode") values you pass L<C<mkdir>|/mkdir FILENAME,MODE> or
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> are modified by your
umask, so even if you tell
L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> to create a file with
Here's some advice: supply a creation mode of C<0666> for regular
files (in L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>) and one of
-C<0777> for directories (in L<C<mkdir>|/mkdir FILENAME,MASK>) and
+C<0777> for directories (in L<C<mkdir>|/mkdir FILENAME,MODE>) and
executable files. This gives users the freedom of
choice: if they want protected files, they might choose process umasks
of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
except that Module I<must> be a bareword.
The importation can be made conditional by using the L<if> module.
-In the peculiar C<use VERSION> form, VERSION may be either a positive
-decimal fraction such as 5.006, which will be compared to
-L<C<$]>|perlvar/$]>, or a v-string of the form v5.6.1, which will be
-compared to L<C<$^V>|perlvar/$^V> (aka $PERL_VERSION). An
-exception is raised if VERSION is greater than the version of the
-current Perl interpreter; Perl will not attempt to parse the rest of the
-file. Compare with L<C<require>|/require VERSION>, which can do a
-similar check at run time.
-Symmetrically, C<no VERSION> allows you to specify that you want a version
-of Perl older than the specified one.
-
-Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl (that is, prior to 5.6.0) that do not support this
-syntax. The equivalent numeric version should be used instead.
-
- use v5.6.1; # compile time version check
- use 5.6.1; # ditto
- use 5.006_001; # ditto; preferred for backwards compatibility
+In the C<use VERSION> form, VERSION may be either a v-string such as
+v5.24.1, which will be compared to L<C<$^V>|perlvar/$^V> (aka
+$PERL_VERSION), or a numeric argument of the form 5.024001, which will
+be compared to L<C<$]>|perlvar/$]>. An exception is raised if VERSION
+is greater than the version of the current Perl interpreter; Perl will
+not attempt to parse the rest of the file. Compare with
+L<C<require>|/require VERSION>, which can do a similar check at run
+time. Symmetrically, C<no VERSION> allows you to specify that you
+want a version of Perl older than the specified one.
+
+Specifying VERSION as a numeric argument of the form 5.024001 should
+generally be avoided as older less readable syntax compared to
+v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric
+form was the only supported syntax, which is why you might see it in
+
+ use v5.24.1; # compile time version check
+ use 5.24.1; # ditto
+ use 5.024_001; # ditto; older syntax compatible with perl 5.6
This is often useful if you need to check the current Perl version before
L<C<use>|/use Module VERSION LIST>ing library modules that won't work
inherited from the L<C<UNIVERSAL>|UNIVERSAL> class, croaks if the given
version is larger than the value of the variable C<$Module::VERSION>.
+The VERSION argument cannot be an arbitrary expression. It only counts
+as a VERSION argument if it is a version number literal, starting with
+either a digit or C<v> followed by a digit. Anything that doesn't
+look like a version literal will be parsed as the start of the LIST.
+Nevertheless, many attempts to use an arbitrary expression as a VERSION
+argument will appear to work, because L<Exporter>'s C<import> method
+handles numeric arguments specially, performing version checks rather
+than treating them as things to export.
+
Again, there is a distinction between omitting LIST (L<C<import>|/import
LIST> called with no arguments) and an explicit empty LIST C<()>
(L<C<import>|/import LIST> not called). Note that there is no comma
use strict qw(subs vars refs);
use subs qw(afunc blurfl);
use warnings qw(all);
- use sort qw(stable _quicksort _mergesort);
+ use sort qw(stable);
Some of these pseudo-modules import semantics into the current
block scope (like L<C<strict>|strict> or L<C<integer>|integer>, unlike
version than its argument and I<not> to undo the feature-enabling side effects
of C<use VERSION>.
-See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
-for the C<-M> and C<-m> command-line options to Perl that give
-L<C<use>|/use Module VERSION LIST> functionality from the command-line.
+See L<perlmodlib> for a list of standard modules and pragmas. See
+L<perlrun|perlrun/-m[-]module> for the C<-M> and C<-m> command-line
+options to Perl that give L<C<use>|/use Module VERSION LIST>
+functionality from the command-line.
=item utime LIST
X<utime>
insertion and deletion of items.
As a side effect, calling L<C<values>|/values HASH> resets the HASH or
-ARRAY's internal iterator, see L<C<each>|/each HASH>. (In particular,
+ARRAY's internal iterator (see L<C<each>|/each HASH>) before yielding the
+values. In particular,
calling L<C<values>|/values HASH> in void context resets the iterator
-with no other overhead. Apart from resetting the iterator,
+with no other overhead.
+
+Apart from resetting the iterator,
C<values @array> in list context is the same as plain C<@array>.
(We recommend that you use void context C<keys @array> for this, but
reasoned that taking C<values @array> out would require more
If the string happens to be encoded as UTF-8 internally (and thus has
the UTF8 flag set), L<C<vec>|/vec EXPR,OFFSET,BITS> tries to convert it
to use a one-byte-per-character internal representation. However, if the
-string contains characters with values of 256 or higher, that conversion
-will fail, and a deprecation message will be raised. In that situation,
-C<vec> will operate on the underlying buffer regardless, in its internal
-UTF-8 representation. In Perl 5.32, this will be a fatal error.
+string contains characters with values of 256 or higher, a fatal error
+will occur.
Strings created with L<C<vec>|/vec EXPR,OFFSET,BITS> can also be
manipulated with the logical
=for Pod::Functions print debugging info
-Prints the value of LIST to STDERR. If the last element of LIST does
-not end in a newline, it appends the same file/line number text as
-L<C<die>|/die LIST> does.
-
-If the output is empty and L<C<$@>|perlvar/$@> already contains a value
-(typically from a previous eval) that value is used after appending
-C<"\t...caught"> to L<C<$@>|perlvar/$@>. This is useful for staying
-almost, but not entirely similar to L<C<die>|/die LIST>.
-
-If L<C<$@>|perlvar/$@> is empty, then the string
-C<"Warning: Something's wrong"> is used.
-
-No message is printed if there is a L<C<$SIG{__WARN__}>|perlvar/%SIG>
-handler
-installed. It is the handler's responsibility to deal with the message
+Emits a warning, usually by printing it to C<STDERR>. C<warn> interprets
+its operand LIST in the same way as C<die>, but is slightly different
+in what it defaults to when LIST is empty or makes an empty string.
+If it is empty and L<C<$@>|perlvar/$@> already contains an exception
+value then that value is used after appending C<"\t...caught">. If it
+is empty and C<$@> is also empty then the string C<"Warning: Something's
+wrong"> is used.
+
+By default, the exception derived from the operand LIST is stringified
+and printed to C<STDERR>. This behaviour can be altered by installing
+a L<C<$SIG{__WARN__}>|perlvar/%SIG> handler. If there is such a
+handler then no message is automatically printed; it is the handler's
+responsibility to deal with the exception
as it sees fit (like, for instance, converting it into a
L<C<die>|/die LIST>). Most
handlers must therefore arrange to actually display the
https://perl5.git.perl.org / perl5.git / blobdiff