of scalar arguments or list values; the list values will be included
in the list as if each individual element were interpolated at that
point in the list, forming a longer single-dimensional list value.
-Elements of the LIST should be separated by commas.
+Commas should separate elements of the LIST.
Any function in the list below may be used either with or without
parentheses around its arguments. (The syntax descriptions omit the
C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
C<umask>, C<unlink>, C<utime>
-=item Keywords related to the control flow of your perl program
+=item Keywords related to the control flow of your Perl program
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>
C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
-C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
+C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>,
C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
The C<-T> and C<-B> switches work as follows. The first block or so of the
file is examined for odd characters such as strange control codes or
characters with the high bit set. If too many strange characters (>30%)
-are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file
+are found, it's a C<-B> file; otherwise it's a C<-T> file. Also, any file
containing null in the first block is considered a binary file. If C<-T>
or C<-B> is used on a filehandle, the current IO buffer is examined
rather than the first block. Both C<-T> and C<-B> return true on a null
a system call. (This doesn't work with C<-t>, and you need to remember
that lstat() and C<-l> will leave values in the stat structure for the
symbolic link, not the real file.) (Also, if the stat buffer was filled by
-a C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
+an C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
Example:
print "Can do.\n" if -r $a || -w _ || -x _;
As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
test operators, in a way that C<-f -w -x $file> is equivalent to
-C<-x $file && -w _ && -f _>. (This is only syntax fancy : if you use
+C<-x $file && -w _ && -f _>. (This is only syntax fancy: if you use
the return value of C<-f $file> as an argument to another filetest
operator, no special magic will happen.)
=item alarm
Arranges to have a SIGALRM delivered to this process after the
-specified number of wallclock seconds have elapsed. If SECONDS is not
+specified number of wallclock seconds has elapsed. If SECONDS is not
specified, the value stored in C<$_> is used. (On some machines,
unfortunately, the elapsed time may be up to one second less or more
than you specified because of how seconds are counted, and process
in the CLASSNAME package. If CLASSNAME is omitted, the current package
is used. Because a C<bless> is often the last thing in a constructor,
it returns the reference for convenience. Always use the two-argument
-version if the function doing the blessing might be inherited by a
-derived class. See L<perltoot> and L<perlobj> for more about the blessing
-(and blessings) of objects.
+version if a derived class might inherit the function doing the blessing.
+See L<perltoot> and L<perlobj> for more about the blessing (and blessings)
+of objects.
Consider always blessing objects in CLASSNAMEs that are mixed case.
Namespaces with all lowercase names are considered reserved for
-Perl pragmata. Builtin types have all uppercase names, so to prevent
+Perl pragmata. 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.
=item chdir EXPR
+=item chdir FILEHANDLE
+
+=item chdir DIRHANDLE
+
+=item chdir
+
Changes the working directory to EXPR, if possible. If EXPR is omitted,
changes to the directory specified by C<$ENV{HOME}>, if set; if not,
changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
neither is set, C<chdir> does nothing. It returns true upon success,
false otherwise. See the example under C<die>.
+On systems that support fchdir, you might pass a file handle or
+directory handle as argument. On systems that don't support fchdir,
+passing handles produces a fatal error at run time.
+
=item chmod LIST
Changes the permissions of a list of files. The first element of the
$mode = '0644'; chmod oct($mode), 'foo'; # this is better
$mode = 0644; chmod $mode, 'foo'; # this is best
+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.
+
+ open(my $fh, "<", "foo");
+ my $perm = (stat $fh)[2] & 07777;
+ chmod($perm | 0600, $fh);
+
You can also import the symbolic C<S_I*> constants from the Fcntl
module:
$cnt = chown $uid, $gid, 'foo', 'bar';
chown $uid, $gid, @filenames;
+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.
+
Here's an example that looks up nonnumeric uids in the passwd file:
print "User: ";
to 255 (inclusive) are by default not encoded in UTF-8 Unicode for
backward compatibility reasons (but see L<encoding>).
+Negative values give the Unicode replacement character (chr(0xfffd)),
+except under the L</bytes> pragma, where low eight bits of the value
+(truncated to an integer) are used.
+
If NUMBER is omitted, uses C<$_>.
For the reverse, use L</ord>.
program exited non-zero, C<$!> will be set to C<0>.) Closing a pipe
also waits for the process executing on the pipe to complete, in case you
want to look at the output of the pipe afterwards, and
-implicitly puts the exit status value of that command into C<$?>.
+implicitly puts the exit status value of that command into C<$?> and
+C<${^CHILD_ERROR_NATIVE}>.
Prematurely closing the read end of a pipe (i.e. before the process
writing to it at the other end has closed it) will result in a
=item continue BLOCK
-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<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
be evaluated again, just like the third part of a C<for> loop in C. Thus
it can be used to increment a loop variable, even when the loop has been
=item crypt PLAINTEXT,SALT
-Encrypts a string exactly like the crypt(3) function in the C library
-(assuming that you actually have a version there that has not been
-extirpated as a potential munition). This can prove useful for checking
-the password file for lousy passwords, amongst other things. Only the
-guys wearing white hats should do this.
-
-Note that L<crypt|/crypt> is intended to be a one-way function, much like
-breaking eggs to make an omelette. There is no (known) corresponding
-decrypt function (in other words, the crypt() is a one-way hash
-function). As a result, this function isn't all that useful for
-cryptography. (For that, see your nearby CPAN mirror.)
-
-When verifying an existing encrypted string you should use the
-encrypted text as the salt (like C<crypt($plain, $crypted) eq
-$crypted>). This allows your code to work with the standard L<crypt|/crypt>
-and with more exotic implementations. In other words, do not assume
-anything about the returned string itself, or how many bytes in
-the encrypted string matter.
+Creates a digest string exactly like the crypt(3) function in the C
+library (assuming that you actually have a version there that has not
+been extirpated as a potential munitions).
+
+crypt() is a one-way hash function. The PLAINTEXT and SALT is turned
+into a short string, called a digest, which is returned. The same
+PLAINTEXT and SALT will always return the same string, but there is no
+(known) way to get the original PLAINTEXT from the hash. Small
+changes in the PLAINTEXT or SALT will result in large changes in the
+digest.
+
+There is no decrypt function. This function isn't all that useful for
+cryptography (for that, look for F<Crypt> modules on your nearby CPAN
+mirror) and the name "crypt" is a bit of a misnomer. Instead it is
+primarily used to check if two pieces of text are the same without
+having to transmit or store the text itself. An example is checking
+if a correct password is given. The digest of the password is stored,
+not the password itself. The user types in a password that is
+crypt()'d with the same salt as the stored digest. If the two digests
+match the password is correct.
+
+When verifying an existing digest string you should use the digest as
+the salt (like C<crypt($plain, $digest) eq $digest>). The SALT used
+to create the digest is visible as part of the digest. This ensures
+crypt() will hash the new string with the same salt as the digest.
+This allows your code to work with the standard L<crypt|/crypt> and
+with more exotic implementations. In other words, do not assume
+anything about the returned string itself, or how many bytes in the
+digest matter.
Traditionally the result is a string of 13 bytes: two first bytes of
the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
-the first eight bytes of the encrypted string mattered, but
-alternative hashing schemes (like MD5), higher level security schemes
-(like C2), and implementations on non-UNIX platforms may produce
-different strings.
+the first eight bytes of the digest string mattered, but alternative
+hashing schemes (like MD5), higher level security schemes (like C2),
+and implementations on non-UNIX platforms may produce different
+strings.
When choosing a new salt create a random two character string whose
characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
restrict what salts C<crypt()> accepts.
Here's an example that makes sure that whoever runs this program knows
-their own password:
+their password:
$pwd = (getpwuid($<))[1];
Of course, typing in your own password to whoever asks you
for it is unwise.
-The L<crypt|/crypt> function is unsuitable for encrypting large quantities
+The L<crypt|/crypt> function is unsuitable for hashing large quantities
of data, not least of all because you can't get the information
-back. Look at the F<by-module/Crypt> and F<by-module/PGP> directories
-on your favorite CPAN mirror for a slew of potentially useful
-modules.
+back. Look at the L<Digest> module for more robust algorithms.
If using crypt() on a Unicode string (which I<potentially> has
characters with codepoints above 255), Perl tries to make sense
"ab" =~ /a(.*)b/;
The pattern match succeeds, and C<$1> is defined, despite the fact that it
-matched "nothing". But it didn't really match nothing--rather, it
+matched "nothing". It didn't really fail to match anything. Rather, it
matched something that happened to be zero characters long. This is all
very above-board and honest. When a function returns an undefined value,
it's an admission that it couldn't give you an honest answer. So you
Deleting an array element effectively returns that position of the array
to its initial, uninitialized state. Subsequently testing for the same
-element with exists() will return false. Note that deleting array
-elements in the middle of an array will not shift the index of the ones
-after them down--use splice() for that. See L</exists>.
+element with exists() will return false. Also, deleting array elements
+in the middle of an array will not shift the index of the elements
+after them down. Use splice() for that. See L</exists>.
The following (inefficiently) deletes all the values of %HASH and @ARRAY:
If LIST is empty and C<$@> 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
-C<$@>. ie. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
+C<$@>. i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
were called.
If C<$@> is empty then the string C<"Died"> is used.
is sometimes preferable to matching particular string values of $@ using
regular expressions. Here's an example:
+ use Scalar::Util 'blessed';
+
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
if ($@) {
- if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
+ if (blessed($@) && $@->isa("Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
handler will be called with the error text and can change the error
message, if it sees fit, by calling C<die> again. See
L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and
-L<"eval BLOCK"> for some examples. Although this feature was meant
+L<"eval BLOCK"> for some examples. Although this feature was
to be run only right before your program was to exit, this is not
currently the case--the C<$SIG{__DIE__}> hook is currently called
even inside eval()ed blocks/strings! If one wants the hook to do
=item do SUBROUTINE(LIST)
-A deprecated form of subroutine call. See L<perlsub>.
+This form of subroutine call is deprecated. See L<perlsub>.
=item do EXPR
=item eval BLOCK
+=item eval
+
In the first form, the return value of EXPR is parsed and executed as if it
were a little Perl program. The value of the expression (which is itself
determined within scalar context) is first parsed, and if there weren't any
errors, executed in the lexical context of the current Perl program, so
that any variable settings or subroutine and format definitions remain
-afterwards. Note that the value is parsed every time the eval executes.
+afterwards. Note that the value is parsed every time the C<eval> executes.
If EXPR is omitted, evaluates C<$_>. This form is typically used to
delay parsing and subsequent execution of the text of EXPR until run time.
In the second form, the code within the BLOCK is parsed only once--at the
-same time the code surrounding the eval itself was parsed--and executed
+same time the code surrounding the C<eval> itself was parsed--and executed
within the context of the current Perl program. This form is typically
used to trap exceptions more efficiently than the first (see below), while
also providing the benefit of checking the code within BLOCK at compile
In both forms, the value returned is the value of the last expression
evaluated inside the mini-program; a return statement may be also used, just
as with subroutines. The expression providing the return value is evaluated
-in void, scalar, or list context, depending on the context of the eval itself.
-See L</wantarray> for more on how the evaluation context can be determined.
+in void, scalar, or list context, depending on the context of the C<eval>
+itself. See L</wantarray> for more on how the evaluation context can be
+determined.
If there is a syntax error or runtime error, or a C<die> statement is
executed, an undefined value is returned by C<eval>, and C<$@> is set to the
# a run-time error
eval '$answer ='; # sets $@
-Due to the current arguably broken state of C<__DIE__> hooks, when using
-the C<eval{}> form as an exception trap in libraries, you may wish not
-to trigger any C<__DIE__> hooks that user code may have installed.
+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
+may wish not to trigger any C<__DIE__> hooks that user code may have installed.
You can use the C<local $SIG{__DIE__}> construct for this purpose,
as shown in this example:
=item exit EXPR
+=item exit
+
Evaluates EXPR and exits immediately with that value. Example:
$ans = <STDIN>;
Two potentially non-obvious but traditional C<flock> semantics are
that it waits indefinitely until the lock is granted, and that its locks
B<merely advisory>. Such discretionary locks are more flexible, but offer
-fewer guarantees. This means that files locked with C<flock> may be
-modified by programs that do not also use C<flock>. See L<perlport>,
+fewer guarantees. This means that programs that do not also use C<flock>
+may modify files locked with C<flock>. See L<perlport>,
your port's specific documentation, or your system-specific local manpages
for details. It's best to assume traditional behavior if you're writing
portable programs. (But if you're not, you should as always feel perfectly
contents of PICTURE, placing the output into the format output
accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
Eventually, when a C<write> is done, the contents of
-C<$^A> are written to some filehandle, but you could also read C<$^A>
-yourself and then set C<$^A> back to C<"">. Note that a format typically
+C<$^A> are written to some filehandle. You could also read C<$^A>
+and then set C<$^A> back to C<"">. Note that a format typically
does one C<formline> per line of form, but the C<formline> function itself
doesn't care how many newlines are embedded in the PICTURE. This means
that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
=item getlogin
-Implements the C library function of the same name, which on most
+This implements the C library function of the same name, which on most
systems returns the current login from F</etc/utmp>, if any. If null,
use C<getpwuid>.
files are only supported if your vendor has implemented them in the
intuitive fashion that calling the regular C library routines gets the
shadow versions if you're running under privilege or if there exists
-the shadow(3) functions as found in System V ( this includes Solaris
-and Linux.) Those systems which implement a proprietary shadow password
+the shadow(3) functions as found in System V (this includes Solaris
+and Linux.) Those systems that implement a proprietary shadow password
facility are unlikely to be supported.
The $members value returned by I<getgr*()> is a space separated list of
or C<undef> if there is an error (the error reason will be in $!). What
exactly is in the packed string depends in the LEVEL and OPTNAME, consult
your system documentation for details. A very common case however is that
-the option is an integer, in which case the result will be an packed
+the option is an integer, in which case the result will be a packed
integer which you can decode using unpack with the C<i> (or C<I>) format.
An example testing if Nagle's algorithm is turned on on a socket:
=item gmtime EXPR
+=item gmtime
+
Converts a time as returned by the time function to an 8-element list
with the time localized for the standard Greenwich time zone.
Typically used as follows:
the year, in the range C<0..364> (or C<0..365> in leap years.)
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
+the year. If you assume it is then you create non-Y2K-compliant
programs--and you wouldn't want to do that, would you?
The proper way to get a complete 4-digit year is simply:
instead a Perl builtin. To get somewhat similar but locale dependent date
strings, see the example in L</localtime>.
+See L<perlport/gmtime> for portability concerns.
+
=item goto LABEL
=item goto EXPR
routine was called first.
NAME needn't be the name of a subroutine; it can be a scalar variable
-containing a code reference, or a block which evaluates to a code
+containing a code reference, or a block that evaluates to a code
reference.
=item grep BLOCK LIST
This is usually something to be avoided when writing clear code.
If C<$_> is lexical in the scope where the C<grep> appears (because it has
-been declared with C<my $_>) then, in addition the be locally aliased to
+been declared with C<my $_>) then, in addition to being locally aliased to
the list elements, C<$_> keeps being lexical inside the block; i.e. it
can't be seen from the outside, avoiding any potential side-effects.
unlike oct(). To present something as hex, look into L</printf>,
L</sprintf>, or L</unpack>.
-=item import
+=item import LIST
There is no builtin C<import> function. It is just an ordinary
method (subroutine) defined (or inherited) by modules that wish to export
or after POSITION. If POSITION is omitted, starts searching from the
beginning of the string. The return value is based at C<0> (or whatever
you've set the C<$[> variable to--but don't do that). If the substring
-is not found, returns one less than the base, ordinarily C<-1>.
+is not found, C<index> returns one less than the base, ordinarily C<-1>.
=item int EXPR
Implements the ioctl(2) function. You'll probably first have to say
- require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph
+ require "sys/ioctl.ph"; # probably in $Config{archlib}/ioctl.ph
-to get the correct function definitions. If F<ioctl.ph> doesn't
+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
own, based on your C header files such as F<< <sys/ioctl.h> >>.
(There is a Perl script called B<h2ph> that comes with the Perl kit that
Perl for security reasons (see L<perlsec/"Algorithmic Complexity
Attacks">).
-As a side effect, calling keys() resets the HASH's internal iterator,
-see L</each>. (In particular, calling keys() in void context resets
-the iterator with no other overhead.)
+As a side effect, calling keys() resets the HASH's internal iterator
+(see L</each>). In particular, calling keys() in void context resets
+the iterator with no other overhead.
Here is yet another way to print your environment:
Note that the C<%a> and C<%b>, the short forms of the day of the week
and the month of the year, may not necessarily be three characters wide.
+See L<perlport/localtime> for portability concerns.
+
=item lock THING
This function places an advisory lock on a shared variable, or referenced
the original list for which the BLOCK or EXPR evaluates to true.
If C<$_> is lexical in the scope where the C<map> appears (because it has
-been declared with C<my $_>) then, in addition the be locally aliased to
+been declared with C<my $_>) then, in addition to being locally aliased to
the list elements, C<$_> keeps being lexical inside the block; i.e. it
can't be seen from the outside, avoiding any potential side-effects.
=item mkdir FILENAME
+=item mkdir
+
Creates the directory specified by FILENAME, with permissions
specified by MASK (as modified by C<umask>). If it succeeds it
returns true, otherwise it returns false and sets C<$!> (errno).
-If omitted, MASK defaults to 0777.
+If omitted, MASK defaults to 0777. If omitted, FILENAME defaults
+to C<$_>.
In general, it is better to create directories with permissive MASK,
and let the user modify that with their C<umask>, than it is to supply
use IPC::SysV;
first to get the correct constant definitions. If CMD is C<IPC_STAT>,
-then ARG must be a variable which will hold the returned C<msqid_ds>
+then ARG must be a variable that will hold the returned C<msqid_ds>
structure. Returns like C<ioctl>: the undefined value for error,
C<"0 but true"> for zero, or the actual return value otherwise. See also
L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
the return value from opening a file. The infrequent exception is when
working with an unopened filehandle is actually what you want to do.
-As a special case the 3 arg form with a read/write mode and the third
+As a special case the 3-arg form with a read/write mode and the third
argument being C<undef>:
open(TMP, "+>", undef) or die ...
reading.
Since v5.8.0, perl has built using PerlIO by default. Unless you've
-changed this (ie Configure -Uuseperlio), you can open file handles to
+changed this (i.e. Configure -Uuseperlio), you can open file handles to
"in memory" files held in Perl scalars via:
open($fh, '>', \$variable) || ..
C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
The mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents
-of IO buffers.) If you use the 3 arg form then you can pass either a
+of IO buffers.) If you use the 3-arg form then you can pass either a
number, the name of a filehandle or the normal "reference to a glob".
Here is a script that saves, redirects, and restores C<STDOUT> and
of $^F. See L<perlvar/$^F>.
Closing any piped filehandle causes the parent process to wait for the
-child to finish, and returns the status value in C<$?>.
+child to finish, and returns the status value in C<$?> and
+C<${^CHILD_ERROR_NATIVE}>.
The filename passed to 2-argument (or 1-argument) form of open() will
have leading and trailing whitespace deleted, and the normal
=item our TYPE EXPR : ATTRS
-An C<our> declares the listed variables to be valid globals within
-the enclosing block, file, or C<eval>. That is, it has the same
-scoping rules as a "my" declaration, but does not create a local
-variable. If more than one value is listed, the list must be placed
-in parentheses. The C<our> declaration has no semantic effect unless
-"use strict vars" is in effect, in which case it lets you use the
-declared global variable without qualifying it with a package name.
-(But only within the lexical scope of the C<our> declaration. In this
-it differs from "use vars", which is package scoped.)
+C<our> associates a simple name with a package variable in the current
+package for use within the current scope. When C<use strict 'vars'> is in
+effect, C<our> lets you use declared global variables without qualifying
+them with package names, within the lexical scope of the C<our> declaration.
+In this way C<our> differs from C<use vars>, which is package scoped.
+
+Unlike C<my>, which both allocates storage for a variable and associates
+a simple name with that storage for use within the current scope, C<our>
+associates a simple name with a package variable in the current package,
+for use within the current scope. In other words, C<our> has the same
+scoping rules as C<my>, but does not necessarily create a
+variable.
+
+If more than one value is listed, the list must be placed
+in parentheses.
+
+ our $foo;
+ our($bar, $baz);
An C<our> declaration declares a global variable that will be visible
across its entire lexical scope, even across package boundaries. The
$bar = 20;
package Bar;
- print $bar; # prints 20
+ print $bar; # prints 20, as it refers to $Foo::bar
-Multiple C<our> declarations in the same lexical scope are allowed
-if they are in different packages. If they happened to be in the same
-package, Perl will emit warnings if you have asked for them.
+Multiple C<our> declarations with the same name in the same lexical
+scope are allowed if they are in different packages. If they happen
+to be in the same package, Perl will emit warnings if you have asked
+for them, just like multiple C<my> declarations. Unlike a second
+C<my> declaration, which will bind the name to a fresh variable, a
+second C<our> declaration in the same package, in the same scope, is
+merely redundant.
use warnings;
package Foo;
our $bar = 30; # declares $Bar::bar for rest of lexical scope
print $bar; # prints 30
- our $bar; # emits warning
+ our $bar; # emits warning but has no other effect
+ print $bar; # still prints 30
An C<our> declaration may also have a list of attributes associated
with it.
given by the TEMPLATE. The resulting string is the concatenation of
the converted values. Typically, each converted value looks
like its machine-level representation. For example, on 32-bit machines
-an integer may be represented by a sequence of 4 bytes which will be
+an integer may be represented by a sequence of 4 bytes that will be
converted to a sequence of 4 characters.
The TEMPLATE is a sequence of characters that give the order and type
U A Unicode character number. Encodes to UTF-8 internally
(or UTF-EBCDIC in EBCDIC platforms).
- w A BER compressed integer. Its bytes represent an unsigned
- integer in base 128, most significant digit first, with as
- few digits as possible. Bit eight (the high bit) is set
- on each byte except the last.
+ w A BER compressed integer (not an ASN.1 BER, see perlpacktut for
+ details). Its bytes represent an unsigned integer in base 128,
+ most significant digit first, with as few digits as possible. Bit
+ eight (the high bit) is set on each byte except the last.
x A null byte.
X Back up a byte.
. Null fill or truncate to absolute position specified by value.
( Start of a ()-group.
-Some letters in the TEMPLATE may optionally be followed by one or
-more of these modifiers (the second column lists the letters for
-which the modifier is valid):
+One or more of the modifiers below may optionally follow some letters in the
+TEMPLATE (the second column lists the letters for which the modifier is
+valid):
! sSlLiI Forces native (short, long, int) sizes instead
of fixed (16-/32-bit) sizes.
platforms are using IEEE, there may be subtle differences. Being able
to use C<E<gt>> or C<E<lt>> on floating point values can be very useful,
but also very dangerous if you don't know exactly what you're doing.
-It is definetely not a general way to portably store floating point
+It is definitely not a general way to portably store floating point
values.
When using C<E<gt>> or C<E<lt>> on an C<()>-group, this will affect
=item *
If TEMPLATE requires more arguments to pack() than actually given, pack()
-assumes additional C<""> arguments. If TEMPLATE requires less arguments
+assumes additional C<""> arguments. If TEMPLATE requires fewer arguments
to pack() than actually given, extra arguments are ignored.
=back
Returns the offset of where the last C<m//g> search left off for the variable
in question (C<$_> is used when the variable is not specified). Note that
-0 is a valid match offset, while C<undef> indicates that the search position
+0 is a valid match offset. C<undef> indicates that the search position
is reset (usually due to match failure, but can also be because no match has
yet been performed on the scalar). C<pos> directly accesses the location used
by the regexp engine to store the offset, so assigning to C<pos> will change
the print--interpose a C<+> or put parentheses around all the
arguments.
-Note that if you're storing FILEHANDLES in an array or other expression,
-you will have to use a block returning its value instead:
+Note that if you're storing FILEHANDLEs in an array, or if you're using
+any other expression more complex than a scalar variable to retrieve it,
+you will have to use a block returning the filehandle value instead:
print { $files[$i] } "stuff\n";
print { $OK ? STDOUT : STDERR } "stuff\n";
The C<redo> command restarts the loop block without evaluating the
conditional again. The C<continue> block, if any, is not executed. If
the LABEL is omitted, the command refers to the innermost enclosing
-loop. This command is normally used by programs that want to lie to
-themselves about what was just input:
+loop. Programs that want to lie to themselves about what was just input
+normally use this command:
# a simpleminded Pascal comment stripper
# (warning: assumes no { or } in strings)
unless (ref($r)) {
print "r is not a reference at all.\n";
}
- if (UNIVERSAL::isa($r, "HASH")) { # for subclassing
- print "r is a reference to something that isa hash.\n";
- }
See also L<perlref>.
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 which do not support this syntax. The equivalent numeric
+versions of Perl that do not support this syntax. The equivalent numeric
version should be used instead.
require v5.6.1; # run time version check
require 5.6.1; # ditto
require 5.006_001; # ditto; preferred for backwards compatibility
-Otherwise, demands that a library file be included if it hasn't already
+Otherwise, C<ref> demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
essentially just a variety of C<eval>. Has semantics similar to the
following subroutine:
...
}
-If the hook is an object, it must provide an INC method, that will be
+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:
=item seekdir DIRHANDLE,POS
Sets the current position for the C<readdir> routine on DIRHANDLE. POS
-must be a value returned by C<telldir>. Has the same caveats about
-possible directory compaction as the corresponding system library
+must be a value returned by C<telldir>. C<seekdir> also has the same caveats
+about possible directory compaction as the corresponding system library
routine.
=item select FILEHANDLE
use IPC::SysV;
first to get the correct constant definitions. If CMD is IPC_STAT or
-GETALL, then ARG must be a variable which will hold the returned
+GETALL, then ARG must be a variable that will hold the returned
semid_ds structure or semaphore value array. Returns like C<ioctl>:
the undefined value for error, "C<0 but true>" for zero, or the actual
return value otherwise. The ARG must consist of a vector of native
Calls the System V IPC function semop to perform semaphore operations
such as signalling and waiting. OPSTRING must be a packed array of
semop structures. Each semop structure can be generated with
-C<pack("s!3", $semnum, $semop, $semflag)>. The number of semaphore
-operations is implied by the length of OPSTRING. Returns true if
+C<pack("s!3", $semnum, $semop, $semflag)>. The length of OPSTRING
+implies the number of semaphore operations. Returns true if
successful, or false if there is an error. As an example, the
following code waits on semaphore $semnum of semaphore id $semid:
array by 1 and moving everything down. If there are no elements in the
array, returns the undefined value. If ARRAY is omitted, shifts the
C<@_> array within the lexical scope of subroutines and formats, and the
-C<@ARGV> array at file scopes or within the lexical scopes established by
-the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}>
-constructs.
+C<@ARGV> array outside of a subroutine and also within the lexical scopes
+established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>
+and C<END {}> constructs.
See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the
same thing to the left end of an array that C<pop> and C<push> do to the
use IPC::SysV;
first to get the correct constant definitions. If CMD is C<IPC_STAT>,
-then ARG must be a variable which will hold the returned C<shmid_ds>
+then ARG must be a variable that will hold the returned C<shmid_ds>
structure. Returns like ioctl: the undefined value for error, "C<0> but
true" for zero, or the actual return value otherwise.
See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
$b as lexicals.
In either case, the subroutine may not be recursive. The values to be
-compared are always passed by reference, so don't modify them.
+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>.
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).
+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 sort pragma for
limited control of the sort. Its rather blunt control of the
-underlying algorithm may not persist into future perls, but 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. See L<sort>.
produces the output 'h:i:t:h:e:r:e'.
-Using the empty pattern C<//> specifically matches the null string, and is
-not be confused with the use of C<//> to mean "the last successful pattern
-match".
+As a special case for C<split>, using the empty pattern C<//> specifically
+matches only the null string, and is not be confused with the regular use
+of C<//> to mean "the last successful pattern match". So, for C<split>,
+the following:
-Empty leading (or trailing) fields are produced when there are positive width
-matches at the beginning (or end) of the string; a zero-width match at the
-beginning (or end) of the string does not produce an empty field. For
-example:
+ print join(':', split(//, 'hi there'));
+
+produces the output 'h:i: :t:h:e:r:e'.
+
+Empty leading (or trailing) fields are produced when there are positive
+width matches at the beginning (or end) of the string; a zero-width match
+at the beginning (or end) of the string does not produce an empty field.
+For example:
print join(':', split(/(?=\w)/, 'hi there!'));
An explicit format parameter index, such as C<2$>. By default sprintf
will format the next unused argument in the list, but this allows you
-to take the arguments out of order. Eg:
+to take the arguments out of order, e.g.:
printf '%2$d %1$d', 12, 34; # prints "34 12"
printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
printf "bits are %0*v8b\n", " ", $bits; # random bitstring
You can also explicitly specify the argument number to use for
-the join string using eg C<*2$v>:
+the join string using e.g. C<*2$v>:
printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
Arguments are usually formatted to be only as wide as required to
display the given value. You can override the width by putting
a number here, or get the width from the next argument (with C<*>)
-or from a specified argument (with eg C<*2$>):
+or from a specified argument (with e.g. C<*2$>):
printf '<%s>', "a"; # prints "<a>"
printf '<%6s>', "a"; # prints "< a>"
You can specify a precision (for numeric conversions) or a maximum
width (for string conversions) by specifying a C<.> followed by a number.
For floating point formats, with the exception of 'g' and 'G', this specifies
-the number of decimal places to show (the default being 6), eg:
+the number of decimal places to show (the default being 6), e.g.:
# these examples are subject to system-specific variation
printf '<%f>', 1; # prints "<1.000000>"
printf '<%.1e>', 10; # prints "<1.0e+01>"
For 'g' and 'G', this specifies the maximum number of digits to show,
-including prior to the decimal point as well as after it, eg:
+including prior to the decimal point as well as after it, e.g.:
# these examples are subject to system-specific variation
printf '<%g>', 1; # prints "<1>"
You cannot currently get the precision from a specified number,
but it is intended that this will be possible in the future using
-eg C<.*2$>:
+e.g. C<.*2$>:
printf '<%.*2$x>', 1, 6; # INVALID, but in future will print "<000001>"
programs supply their own seed value (often C<time ^ $$> or C<time ^
($$ + ($$ << 15))>), but that isn't necessary any more.
-Note that you need something much more random than the default seed for
-cryptographic purposes. Checksumming the compressed output of one or more
+For cryptographic purposes, however, you need something much more random
+than the default seed. Checksumming the compressed output of one or more
rapidly changing operating system status programs is the usual method. For
example:
patterns you are searching on, and on the distribution of character
frequencies in the string to be searched--you probably want to compare
run times with and without it to see which runs faster. Those loops
-which scan for many short constant strings (including the constant
+that scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most. You may have only
one C<study> active at a time--if you study a different scalar the first
is "unstudied". (The way C<study> works is this: a linked list of every
parts of the EXPR and return what was there before in one operation,
just as you can with splice().
-Note that the lvalue returned by by the 3-arg version of substr() acts as
+Note that the lvalue returned by the 3-arg version of substr() acts as
a 'magic bullet'; each time it is assigned to, it remembers which part
of the original string is being modified; for example:
of C<IO::Handle> on any open handles.
The return value is the exit status of the program as returned by the
-C<wait> call. To get the actual exit value shift right by eight (see below).
+C<wait> call. To get the actual exit value, shift right by eight (see below).
See also L</exec>. This is I<not> what you want to use to capture
the output from a command, for that you should use merely backticks or
C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
printf "child exited with value %d\n", $? >> 8;
}
-or more portably by using the W*() calls of the POSIX extension;
-see L<perlport> for more information.
+Alternatively you might inspect the value of C<${^CHILD_ERROR_NATIVE}>
+with the W*() calls of the POSIX extension.
When the arguments get executed via the system shell, results
and return codes will be subject to its quirks and capabilities.
Returns the current position of the C<readdir> routines on DIRHANDLE.
Value may be given to C<seekdir> to access a particular location in a
-directory. Has the same caveats about possible directory compaction as
-the corresponding system library routine.
+directory. C<telldir> has the same caveats about possible directory
+compaction as the corresponding system library routine.
=item tie VARIABLE,CLASSNAME,LIST
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 which do not support this syntax. The equivalent numeric
+versions of Perl that do not support this syntax. The equivalent numeric
version should be used instead.
use v5.6.1; # compile time version check
The string should not contain any character with the value > 255 (which
can only happen if you're using UTF-8 encoding). If it does, it will be
-treated as something which is not UTF-8 encoded. When the C<vec> was
+treated as something that is not UTF-8 encoded. When the C<vec> was
assigned to, other parts of your program will also no longer consider the
string to be UTF-8 encoded. In other words, if you do have such characters
in your string, vec() will operate on the actual byte string, and not the
Behaves like the wait(2) system call on your system: it waits for a child
process to terminate and returns the pid of the deceased process, or
-C<-1> if there are no child processes. The status is returned in C<$?>.
+C<-1> if there are no child processes. The status is returned in C<$?>
+and C<{^CHILD_ERROR_NATIVE}>.
Note that a return value of C<-1> could mean that child processes are
being automatically reaped, as described in L<perlipc>.
Waits for a particular child process to terminate and returns the pid of
the deceased process, or C<-1> if there is no such child process. On some
systems, a value of 0 indicates that there are processes still running.
-The status is returned in C<$?>. If you say
+The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say
use POSIX ":sys_wait_h";
#...