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).
+been extirpated as a potential munition).
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
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 digest string mattered, but alternative
+the first eight bytes of PLAINTEXT mattered. But alternative
hashing schemes (like MD5), higher level security schemes (like C2),
and implementations on non-UNIX platforms may produce different
strings.
delete $ref->[$x][$y][$index];
delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
+The C<delete local EXPR> construct can also be used to localize the deletion
+of array/hash elements to the current block.
+See L<perlsub/"Localized deletion of elements of composite types">.
+
=item die LIST
X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
See also exit(), warn(), and the Carp module.
-If LIST is empty and C<$@> already contains a value (typically from a
+If the output is empty and C<$@> already contains a value (typically from a
previous eval) that value is reused after appending C<"\t...propagated">.
This is useful for propagating exceptions:
eval { ... };
die unless $@ =~ /Expected exception/;
-If LIST is empty and C<$@> contains an object reference that has a
+If the output 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<$@>. i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
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
+executed, C<eval> returns an undefined value in scalar context
+or an empty list in list context, and C<$@> is set to the
error message. If there was no error, C<$@> is guaranteed to be a null
string. Beware that using C<eval> neither silences perl from printing
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
Here's a mailbox appender for BSD systems.
- use Fcntl ':flock'; # import LOCK_* constants
+ use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
sub lock {
- flock(MBOX,LOCK_EX);
- # and, in case someone appended
- # while we were waiting...
- seek(MBOX, 0, 2);
+ my ($fh) = @_;
+ flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
+
+ # and, in case someone appended while we were waiting...
+ seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
}
sub unlock {
- flock(MBOX,LOCK_UN);
+ my ($fh) = @_;
+ flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
}
open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
or die "Can't open mailbox: $!";
- lock();
+ lock($mbox);
print $mbox $msg,"\n\n";
- unlock();
+ unlock($mbox);
On systems that support a real flock(), locks are inherited across fork()
calls, whereas those that must resort to the more capricious fcntl()
X<getpriority> X<priority> X<nice>
Returns the current priority for a process, a process group, or a user.
-(See L<getpriority(2)>.) Will raise a fatal exception if used on a
+(See C<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).
=item getpwnam NAME
alive (even if only as a zombie) 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>
-number will also kill process groups, but that's not portable.) That
-means you usually want to use positive not negative signals. You may also
-use a signal name in quotes.
+Unlike in the shell, if SIGNAL is negative, it kills process groups instead
+of processes. That means you usually want to use positive not negative signals.
+You may also use a signal name in quotes.
+
+The behavior of kill when a I<PROCESS> number is zero or negative depends on
+the operating system. For example, on POSIX-conforming systems, zero will
+signal the current process group and -1 will signal all processes.
See L<perlipc/"Signals"> for more details.
be placed in parentheses. See L<perlsub/"Temporary Values via local()">
for details, including issues with tied arrays and hashes.
+The C<delete local EXPR> construct can also be used to localize the deletion
+of array/hash elements to the current block.
+See L<perlsub/"Localized deletion of elements of composite types">.
+
=item localtime EXPR
X<localtime> X<ctime>
=item m//
-The match operator. See L<perlop>.
+The match operator. See L<perlop/"Regexp Quote-Like Operators">.
=item map BLOCK LIST
X<map>
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<< '>&' >>, in which case the rest of the string is interpreted
as the name of a filehandle (or file descriptor, if numeric) to be
-duped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>,
+duped (as C<dup(2)>) and opened. You may use C<&> after C<< > >>,
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
If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
-that file descriptor (and not call L<dup(2)>); this is more
+that file descriptor (and not call C<dup(2)>); this is more
parsimonious of file descriptors. For example:
# open for input, reusing the fileno of $fd
will have exactly the opposite restrictions.
-If you want a "real" C C<open> (see L<open(2)> on your system), then you
+If you want a "real" C C<open> (see C<open(2)> on your system), then you
should use the C<sysopen> function, which involves no such magic (but
may use subtly different filemodes than Perl open(), which is mapped
to C fopen()). This is
The same template may generally also be used in unpack().
-=item package NAMESPACE
-X<package> X<module> X<namespace>
+=item package NAMESPACE VERSION
+X<package> X<module> X<namespace> X<version>
-=item package
+=item package NAMESPACE
Declares the compilation unit as being in the given namespace. The scope
of the package declaration is from the declaration itself through the end
C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
still seen in older code).
+If VERSION is provided, C<package> also sets the C<$VERSION> variable in the
+given namespace. VERSION must be be a numeric literal or v-string; it is
+parsed exactly the same way as a VERSION argument to C<use MODULE VERSION>.
+C<$VERSION> should only be set once per package.
+
See L<perlmod/"Packages"> for more information about packages, modules,
and classes. See L<perlsub> for other scoping issues.
@dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
closedir $dh;
+As of Perl 5.11.2 you can use a bare C<readdir> in a C<while> loop,
+which will set C<$_> on every iteration.
+
+ opendir(my $dh, $some_dir) || die;
+ while(readdir $dh) {
+ print "$some_dir/$_\n";
+ }
+ closedir $dh;
+
=item readline EXPR
=item readline
Reads from the filehandle whose typeglob is contained in EXPR (or from
*ARGV if EXPR is not provided). In scalar context, each call reads and
returns the next line, until end-of-file is reached, whereupon the
-subsequent call returns undef. In list context, reads until end-of-file
+subsequent call returns C<undef>. In list context, reads until end-of-file
is reached and returns a list of lines. Note that the notion of "line"
used here is however you may have defined it with C<$/> or
C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
-When C<$/> is set to C<undef>, when readline() is in scalar
+When C<$/> is set to C<undef>, when C<readline> is in scalar
context (i.e. file slurp mode), and when an empty file is read, it
returns C<''> the first time, followed by C<undef> subsequently.
$line = <STDIN>;
$line = readline(*STDIN); # same thing
-If readline encounters an operating system error, C<$!> will be set with the
-corresponding error message. It can be helpful to check C<$!> when you are
-reading from filehandles you don't trust, such as a tty or a socket. The
-following example uses the operator form of C<readline>, and takes the necessary
-steps to ensure that C<readline> was successful.
+If C<readline> encounters an operating system error, C<$!> will be set
+with the corresponding error message. It can be helpful to check
+C<$!> when you are reading from filehandles you don't trust, such as a
+tty or a socket. The following example uses the operator form of
+C<readline> and dies if the result is not defined.
- for (;;) {
- undef $!;
- unless (defined( $line = <> )) {
- die $! if $!;
- last; # reached EOF
+ while ( ! eof($fh) ) {
+ defined( $_ = <$fh> ) or die "readline failed: $!";
+ ...
+ }
+
+Note that you have can't handle C<readline> errors that way with the
+C<ARGV> filehandle. In that case, you have to open each element of
+C<@ARGV> yourself since C<eof> handles C<ARGV> differently.
+
+ foreach my $arg (@ARGV) {
+ open(my $fh, $arg) or warn "Can't open $arg: $!";
+
+ while ( ! eof($fh) ) {
+ defined( $_ = <$fh> )
+ or die "readline failed for $arg: $!";
+ ...
}
- # ...
}
=item readlink EXPR
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 filehandle, then the subroutine will be
-called to act a simple source filter, with the line as read in C<$_>.
+called to act as 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.
}
# In the main program
- push @INC, new Foo(...);
+ push @INC, Foo->new(...);
Note that these hooks are also permitted to set the %INC entry
corresponding to the files they have loaded. See L<perlvar/%INC>.
=item s///
-The substitution operator. See L<perlop>.
+The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
=item say FILEHANDLE LIST
X<say>
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. See L<sort>.
+independent ways quite probably will. See L<the sort pragma|sort>.
Examples:
use sort '_mergesort'; # note discouraging _
@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:
+
+ @contact = sort { $a cmp $b } find_records @key;
+ @contact = sort +find_records(@key);
+ @contact = sort &find_records(@key);
+ @contact = sort(find_records(@key));
+
+If instead you want to sort the array @key with the comparison routine
+C<find_records()> then you can use:
+
+ @contact = sort { find_records() } @key;
+ @contact = sort find_records(@key);
+ @contact = sort(find_records @key);
+ @contact = sort(find_records (@key));
+
If you're using strict, you I<must not> declare $a
and $b as lexicals. They are package globals. That means
-if you're in the C<main> package and type
+that if you're in the C<main> package and type
@articles = sort {$b <=> $a} @files;
default, empty leading fields are preserved, and empty trailing ones are
deleted. (If all fields are empty, they are considered to be trailing.)
-In scalar context, returns the number of fields found and splits into
-the C<@_> array. Use of split in scalar context is deprecated, however,
-because it clobbers your subroutine arguments.
+In scalar context, returns the number of fields found.
If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted,
splits on whitespace (after skipping any leading whitespace). Anything
If you had the entire header of a normal Unix email message in $header,
you could split it up into fields and their values this way:
- $header =~ s/\n\s+/ /g; # fix continuation lines
+ $header =~ s/\n(?=\s)//g; # fix continuation lines
%hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
The pattern C</PATTERN/> may be replaced with an expression to specify
Returns a string formatted by the usual C<printf> conventions of the C
library function C<sprintf>. See below for more details
-and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
+and see C<sprintf(3)> or C<printf(3)> on your system for an explanation of
the general principles.
For example:
indicates a failure to start the program or an error of the wait(2) system
call (inspect $! for the reason).
+If you'd like to make C<system> (and many other bits of Perl) die on error,
+have a look at the L<autodie> pragma.
+
Like C<exec>, C<system> allows you to lie to a program about its name if
you use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
system(@args) == 0
or die "system @args failed: $?"
-You can check all the failure possibilities by inspecting
-C<$?> like this:
+If you'd like to manually inspect C<system>'s failure, you can check all
+possible failure modes by inspecting C<$?> like this:
if ($? == -1) {
print "failed to execute: $!\n";
=item tr///
-The transliteration operator. Same as C<y///>. See L<perlop>.
+The transliteration operator. Same as C<y///>. See
+L<perlop/"Quote and Quote-like Operators">.
=item truncate FILEHANDLE,LENGTH
X<truncate>
Also, if the specified perl version is greater than or equal to 5.9.5,
C<use VERSION> will also load the C<feature> pragma and enable all
features available in the requested version. See L<feature>.
+Similarly, if the specified perl version is greater than or equal to
+5.11.0, strictures are enabled lexically as with C<use strict> (except
+that the F<strict.pm> file is not actually loaded).
The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been
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<$?>
-and C<{^CHILD_ERROR_NATIVE}>.
+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<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say
+The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say
use POSIX ":sys_wait_h";
#...
not end in a newline, it appends the same file/line number text as C<die>
does.
-If LIST is empty and C<$@> already contains a value (typically from a
+If the output is empty and C<$@> already contains a value (typically from a
previous eval) that value is used after appending C<"\t...caught">
to C<$@>. This is useful for staying almost, but not entirely similar to
C<die>.
=item y///
-The transliteration operator. Same as C<tr///>. See L<perlop>.
+The transliteration operator. Same as C<tr///>. See
+L<perlop/"Quote and Quote-like Operators">.
=back