C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
-C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
+C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
C<warn>, C<write>
C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
+=item Keywords related to switch
+
+C<break>, C<continue>
+
+(These are only available if you enable the "switch" feature.
+See L<feature> and L<perlsyn/"Switch statements">.)
+
=item Keywords related to scoping
C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
X<perl5>
C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
-C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
-C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
-C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
+C<import>, C<lc>, C<lcfirst>, C<lock>, C<map>, C<my>, C<no>, C<our>,
+C<prototype>, C<qr>, C<qw>, C<qx>, C<readline>, C<readpipe>, C<ref>,
+C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
* - C<sub> was a keyword in perl4, but in perl5 it is an
operator, which can be used in expressions.
See L<perlmod/"Perl Modules">.
+=item break
+
+Break out of a C<given()> block.
+
+This keyword is enabled by the "switch" feature: see L<feature>
+for more information.
+
=item caller EXPR
X<caller> X<call stack> X<stack> X<stack trace>
to go back before the current one.
($package, $filename, $line, $subroutine, $hasargs,
- $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
+ $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
+ = caller($i);
Here $subroutine may be C<(eval)> if the frame is not a subroutine
call, but an C<eval>. In such a case additional elements $evaltext and
compiled with. The C<$hints> and C<$bitmask> values are subject to change
between versions of Perl, and are not meant for external use.
+C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
+caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
+of this hash, as they are the actual values stored in the optree.
+
Furthermore, when called from within the DB package, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
arguments with which the subroutine was invoked.
On systems that support fchmod, you might pass file handles among the
files. On systems that don't support fchmod, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time. The file handles must be passed
+as globs or references to be recognized. Barewords are considered
+file names.
open(my $fh, "<", "foo");
my $perm = (stat $fh)[2] & 07777;
On systems that support fchown, you might pass file handles among the
files. On systems that don't support fchown, passing file handles
-produces a fatal error at run time.
+produces a fatal error at run time. The file handles must be passed
+as globs or references to be recognized. Barewords are considered
+file names.
Here's an example that looks up nonnumeric uids in the passwd file:
=item continue BLOCK
X<continue>
+=item continue
+
C<continue> is actually a flow control statement rather than a function. If
there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
C<foreach>), it is always executed just before the conditional is about to
empty one, logically enough. In that case, C<next> goes directly back
to check the condition at the top of the loop.
+If the "switch" feature is enabled, C<continue> is also a
+function that will break out of the current C<when> or C<default>
+block, and fall through to the next case. See L<feature> and
+L<perlsyn/"Switch statements"> for more information.
+
+
=item cos EXPR
X<cos> X<cosine> X<acos> X<arccosine>
=item gmtime
-Converts a time as returned by the time function to an 8-element list
+Converts a time as returned by the time function to an 9-element list
with the time localized for the standard Greenwich time zone.
Typically used as follows:
- # 0 1 2 3 4 5 6 7
- ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
+ # 0 1 2 3 4 5 6 7 8
+ ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
gmtime(time);
All list elements are numeric, and come straight out of the C `struct
indicating December. $year is the number of years since 1900. That
is, $year is C<123> in year 2023. $wday is the day of the week, with
0 indicating Sunday and 3 indicating Wednesday. $yday is the day of
-the year, in the range C<0..364> (or C<0..365> in leap years.)
+the year, in the range C<0..364> (or C<0..365> in leap years). $isdst
+is always C<0>.
Note that the $year element is I<not> simply the last two digits of
the year. If you assume it is then you create non-Y2K-compliant
Implements the ioctl(2) function. You'll probably first have to say
- require "sys/ioctl.ph"; # probably in $Config{archlib}/ioctl.ph
+ require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
to get the correct function definitions. If F<sys/ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
$cnt = kill 1, $child1, $child2;
kill 9, @goners;
-If SIGNAL is zero, no signal is sent to the process. This is a
-useful way to check that a child process is alive and hasn't changed
-its UID. See L<perlport> for notes on the portability of this
-construct.
+If SIGNAL is zero, no signal is sent to the process, but the kill(2)
+system call will check whether it's possible to send a signal to it (that
+means, to be brief, that the process is owned by the same user, or we are
+the super-user). This is a useful way to check that a child process is
+alive and hasn't changed its UID. See L<perlport> for notes on the
+portability of this construct.
Unlike in the shell, if SIGNAL is negative, it kills
process groups instead of processes. (On System V, a negative I<PROCESS>
open(FH, "<:utf8", "file")
will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>. (Note that if layers are specified in the
-three-arg form then default layers set by the C<open> pragma are
-ignored.)
+see L<perluniintro>. Note that if layers are specified in the
+three-arg form then default layers stored in ${^OPEN} (see L<perlvar>;
+usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
Open returns nonzero upon success, the undefined value otherwise. If
the C<open> involved a pipe, the return value happens to be the pid of
L<perlsub/"Private Variables via my()"> for details, and L<fields>,
L<attributes>, and L<Attribute::Handlers>.
-The only currently recognized C<our()> attribute is C<unique> which
-indicates that a single copy of the global is to be used by all
-interpreters should the program happen to be running in a
-multi-interpreter environment. (The default behaviour would be for
-each interpreter to have its own copy of the global.) Examples:
-
- our @EXPORT : unique = qw(foo);
- our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
- our $VERSION : unique = "1.00";
-
-Note that this attribute also has the effect of making the global
-readonly when the first new interpreter is cloned (for example,
-when the first new thread is created).
-
-Multi-interpreter environments can come to being either through the
-fork() emulation on Windows platforms, or by embedding perl in a
-multi-threaded application. The C<unique> attribute does nothing in
-all other environments.
-
-Warning: the current implementation of this attribute operates on the
-typeglob associated with the variable; this means that C<our $x : unique>
-also has the effect of C<our @x : unique; our %x : unique>. This may be
-subject to change.
-
=item pack TEMPLATE,LIST
X<pack>
I A unsigned integer value.
(This 'integer' is _at_least_ 32 bits wide. Its exact
size depends on what a local C compiler calls 'int'.)
-
+
n An unsigned short (16-bit) in "network" (big-endian) order.
N An unsigned long (32-bit) in "network" (big-endian) order.
v An unsigned short (16-bit) in "VAX" (little-endian) order.
The C</> template character allows packing and unpacking of a sequence of
items where the packed structure contains a packed item count followed by
the packed items themselves.
-You write I<length-item>C</>I<sequence-item>.
-The I<length-item> can be any C<pack> template letter, and describes
-how the length value is packed. The ones likely to be of most use are
-integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
-SNMP) and C<N> (for Sun XDR).
+For C<pack> you write I<length-item>C</>I<sequence-item> and the
+I<length-item> describes how the length value is packed. The ones likely
+to be of most use are integer-packing ones like C<n> (for Java strings),
+C<w> (for ASN.1 or SNMP) and C<N> (for Sun XDR).
For C<pack>, the I<sequence-item> may have a repeat count, in which case
the minimum of that and the number of available items is used as argument
for the I<length-item>. If it has no repeat count or uses a '*', the number
-of available items is used. For C<unpack> the repeat count is always obtained
-by decoding the packed item count, and the I<sequence-item> must not have a
-repeat count.
+of available items is used.
+
+For C<unpack> an internal stack of integer arguments unpacked so far is
+used. You write C</>I<sequence-item> and the repeat count is obtained by
+popping off the last element from the stack. The I<sequence-item> must not
+have a repeat count.
If the I<sequence-item> refers to a string type (C<"A">, C<"a"> or C<"Z">),
the I<length-item> is a string length, not a number of strings. If there is
an explicit repeat count for pack, the packed string will be adjusted to that
given length.
- unpack 'W/a', "\04Gurusamy"; gives ('Guru')
- unpack 'a3/A* A*', '007 Bond J '; gives (' Bond', 'J')
- pack 'n/a* w/a','hello,','world'; gives "\000\006hello,\005world"
- pack 'a/W2', ord('a') .. ord('z'); gives '2ab'
+ unpack 'W/a', "\04Gurusamy"; gives ('Guru')
+ unpack 'a3/A A*', '007 Bond J '; gives (' Bond', 'J')
+ unpack 'a3 x2 /A A*', '007: Bond, J.'; gives ('Bond, J', '.')
+ pack 'n/a* w/a','hello,','world'; gives "\000\006hello,\005world"
+ pack 'a/W2', ord('a') .. ord('z'); gives '2ab'
The I<length-item> is not returned explicitly from C<unpack>.
REF
GLOB
LVALUE
+ FORMAT
+ IO
+ VSTRING
+ Regexp
If the referenced object has been blessed into a package, then that package
name is returned instead. You can think of C<ref> as a C<typeof> operator.
eval "require $class";
-Now that you understand how C<require> looks for files in the case of
-a bareword argument, there is a little extra functionality going on
-behind the scenes. Before C<require> looks for a "F<.pm>" extension,
-it will first look for a filename with a "F<.pmc>" extension. A file
-with this extension is assumed to be Perl bytecode generated by
-L<B::Bytecode|B::Bytecode>. If this file is found, and its modification
-time is newer than a coinciding "F<.pm>" non-compiled file, it will be
-loaded in place of that non-compiled file ending in a "F<.pm>" extension.
+Now that you understand how C<require> looks for files in the case of a
+bareword argument, there is a little extra functionality going on behind
+the scenes. Before C<require> 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.
You can also insert hooks into the import facility, by putting directly
Perl code into the @INC array. There are three forms of hooks: subroutine
walks through @INC and encounters a subroutine, this subroutine gets
called with two parameters, the first being a reference to itself, and the
second the name of the file to be included (e.g. "F<Foo/Bar.pm>"). The
-subroutine should return C<undef> or a filehandle, from which the file to
-include will be read. If C<undef> is returned, C<require> will look at
-the remaining elements of @INC.
+subroutine should return nothing, or a list of up to 4 values in the
+following order:
+
+=over
+
+=item 1
+
+A reference to a scalar, containing any initial source code to prepend to
+the file or generator output.
+
+
+=item 2
+
+A filehandle, from which the file will be read.
+
+=item 3
+
+A reference to a subroutine. If there is no file handle, then this subroutine
+is expected to generate one line of source code per call, writing the line
+into C<$_> and returning 1, then returning 0 at "end of FILE" If there is a
+file handle then the subroutine will be called to act a simple source filter,
+with the line as read in C<$_>. Again, return 1 for each valid line, and 0
+after all lines have been returned.
+
+=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]>.
+
+=back
+
+If an empty list, C<undef>, or nothing that matches the first 3 values above
+is returned then C<require> will look at the remaining elements of @INC.
+Note that this file handle must be a real file handle (strictly a typeglob,
+or reference to a typeglob, blessed or unblessed) - tied file handles will be
+ignored and return value processing will stop there.
If the hook is an array reference, its first element must be a subroutine
reference. This subroutine is called as above, but the first parameter is
If the hook is an object, it must provide an INC method that will be
called as above, the first parameter being the object itself. (Note that
-you must fully qualify the sub's name, as it is always forced into package
-C<main>.) Here is a typical code layout:
+you must fully qualify the sub's name, as unqualified C<INC> is always forced
+into package C<main>.) Here is a typical code layout:
# In Foo.pm
package Foo;
=item rindex STR,SUBSTR
-Works just like index() except that it returns the position of the LAST
+Works just like index() except that it returns the position of the I<last>
occurrence of SUBSTR in STR. If POSITION is specified, returns the
-last occurrence at or before that position.
+last occurrence beginning at or before that position.
=item rmdir FILENAME
X<rmdir> X<rd> X<directory, remove>
The substitution operator. See L<perlop>.
+=item say FILEHANDLE LIST
+X<say>
+
+=item say LIST
+
+=item say
+
+Just like C<print>, but implicitly appends a newline.
+C<say LIST> is simply an abbreviation for C<print LIST, "\n">,
+and C<say()> works just like C<print($_, "\n")>.
+
+That means that a call to say() appends any output record separator
+I<after> the added newline.
+
+This keyword is only available when the "say" feature is
+enabled: see L<feature>.
+
=item scalar EXPR
X<scalar> X<context>
X<setsockopt>
Sets the socket option requested. Returns undefined if there is an
-error. OPTVAL may be specified as C<undef> if you don't want to pass an
-argument.
+error. Use integer constants provided by the C<Socket> module for
+LEVEL and OPNAME. Values for LEVEL can also be obtained from
+getprotobyname. OPTVAL might either be a packed string or an integer.
+An integer OPTVAL is shorthand for pack("i", OPTVAL).
+
+An example disabling the Nagle's algorithm for a socket:
+
+ use Socket qw(IPPROTO_TCP TCP_NODELAY);
+ setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
=item shift ARRAY
X<shift>
in the latter case, it is usually counter-productive to declare $a and
$b as lexicals.
-In either case, the subroutine may not be recursive. The values to be
-compared are always passed by reference and should not be modified.
+The values to be compared are always passed by reference and should not
+be modified.
You also cannot exit out of the sort block or subroutine using any of the
loop control operators described in L<perlsyn> or with C<goto>.
=item vector flag
-The vector flag C<v>, optionally specifying the join string to use.
-This flag tells perl to interpret the supplied string as a vector
-of integers, one for each character in the string, separated by
-a given string (a dot C<.> by default). This can be useful for
-displaying ordinal values of characters in arbitrary strings:
+This flag tells perl to interpret the supplied string as a vector of
+integers, one for each character in the string. Perl applies the format to
+each integer in turn, then joins the resulting strings with a separator (a
+dot C<.> by default). This can be useful for displaying ordinal values of
+characters in arbitrary strings:
+ printf "%vd", "AB\x{100}"; # prints "65.66.256"
printf "version is v%vd\n", $^V; # Perl's version
Put an asterisk C<*> before the C<v> to override the string to
# File types. Not necessarily all are available on your system.
- S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+ S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
# The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
In scalar context, C<times> returns C<$user>.
+Note that times for children are included only after they terminate.
+
=item tr///
The transliteration operator. Same as C<y///>. See L<perlop>.
The behavior is undefined if LENGTH is greater than the length of the
file.
+The position in the file of FILEHANDLE is left unchanged. You may want to
+call L<seek> before writing to the file.
+
=item uc EXPR
X<uc> X<uppercase> X<toupper>
unlink @goners;
unlink <*.bak>;
-Note: C<unlink> will not delete directories unless you are superuser and
-the B<-U> flag is supplied to Perl. Even if these conditions are
+Note: C<unlink> will not attempt to delete directories unless you are superuser
+and the B<-U> flag is supplied to Perl. Even if these conditions are
met, be warned that unlinking a directory can inflict damage on your
-filesystem. Use C<rmdir> instead.
+filesystem. Finally, using C<unlink> on directories is not supported on
+many operating systems. Use C<rmdir> instead.
If LIST is omitted, uses C<$_>.
described when they are both C<undef>. This case will also trigger an
uninitialized warning.
+On systems that support futimes, you might pass file handles among the
+files. On systems that don't support futimes, passing file handles
+produces a fatal error at run time. The file handles must be passed
+as globs or references to be recognized. Barewords are considered
+file names.
+
=item values HASH
X<values>
#...
do {
$kid = waitpid(-1, WNOHANG);
- } until $kid > 0;
+ } while $kid > 0;
then you can do a non-blocking wait for all pending zombie processes.
Non-blocking wait is available on machines supporting either the
projects / p5sagit/p5-mst-13.2.git / blobdiff