=item Keywords related to the control flow of your Perl program
X<control flow>
-C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
+C<caller>, C<continue>, C<die>, C<do>,
+C<dump>, C<eval>, C<evalbytes> C<exit>,
C<__FILE__>, C<goto>, C<last>, C<__LINE__>, C<next>, C<__PACKAGE__>,
-C<redo>, C<return>, C<sub>, C<wantarray>,
+C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
+
+C<__SUB__> is only available with a C<use v5.16> (or higher) declaration or
+with the C<"current_sub"> feature (see L<feature>).
=item Keywords related to the switch feature
=item Miscellaneous functions
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
+C<defined>, C<dump>, C<eval>, C<evalbytes>,
+C<formline>, C<local>, C<my>, C<our>,
C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
=item Functions for processes and process groups
X<process> X<pid> X<process id>
C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
-C<pipe>, C<qx//>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
+C<pipe>, C<qx//>, C<readpipe>, C<setpgrp>,
+C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>
=item Keywords related to Perl modules
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 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.
+SeeL<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
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.
+If the C<unicode_eval> feature is enabled (which is the default under a
+C<use 5.16> or higher declaration), EXPR or C<$_> is treated as a string of
+characters, so C<use utf8> declarations have no effect, and source filters
+are forbidden. In the absence of the C<unicode_eval> feature, the string
+will sometimes be treated as characters and sometimes as bytes, depending
+on the internal encoding, and source filters activated within the C<eval>
+exhibit the erratic, but historical, behaviour of affecting some outer file
+scope that is still compiling. See also the L</evalbytes> keyword, which
+always treats its input as a byte stream and works properly with source
+filters, and the L<feature> pragma.
+
In the second form, the code within the BLOCK is parsed only once--at the
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
If there is a syntax error or runtime error, or a C<die> statement is
executed, C<eval> returns C<undef> in scalar context
-or an empty list--or, for syntax errors, a list containing a single
-undefined value--in list context, and C<$@> is set to the error
-message. The discrepancy in the return values in list context is
-considered a bug by some, and will probably be fixed in a future
-release. If there was no error, C<$@> is set to the empty string. A
+or an empty list in list context, and C<$@> is set to the error
+message. (Prior to 5.16, a bug caused C<undef> to be returned
+in list context for syntax errors, but not for runtime errors.)
+If there was no error, C<$@> is set to the empty string. A
control flow operator like C<last> or C<goto> can bypass the setting of
C<$@>. Beware that using C<eval> neither silences Perl from printing
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
of code that called it. You don't normally need to worry about this unless
you are writing a Perl debugger.
+=item evalbytes EXPR
+X<evalbytes>
+
+=item evalbytes
+
+This function is like L</eval> with a string argument, except it always
+parses its argument, or C<$_> if EXPR is omitted, as a string of bytes. A
+string containing characters whose ordinal value exceeds 255 results in an
+error. Source filters activated within the evaluated code apply to the
+code itself.
+
+This function is only available under the C<evalbytes> feature, a
+C<use v5.16> (or higher) declaration, or with a C<CORE::> prefix. See
+L<feature> for more information.
+
=item exec LIST
X<exec> X<execute>
each segment as separate pattern. As such, C<glob("*.c *.h")>
matches all files with a F<.c> or F<.h> extension. The expression
C<glob(".* *")> matches all files in the current working directory.
+If you want to glob filenames that might contain whitespace, you'll
+have to use extra quotes around the spacey filename to protect it.
+For example, to glob filenames that have an C<e> followed by a space
+followed by an C<f>, use either of:
+
+ @spacies = <"*e f*">;
+ @spacies = glob '"*e f*"';
+ @spacies = glob q("*e f*");
+
+If you had to get a variable through, you could do this:
+
+ @spacies = glob "'*${var}e f*'";
+ @spacies = glob qq("*${var}e f*");
If non-empty braces are the only wildcard characters used in the
C<glob>, no filenames are matched, but potentially many strings
or after POSITION. If POSITION is omitted, starts searching from the
beginning of the string. POSITION before the beginning of the string
or after its end is treated as if it were the beginning or the end,
-respectively. POSITION and the return value are based at C<0> (or whatever
-you've set the C<$[> variable to--but don't do that). If the substring
-is not found, C<index> returns one less than the base, ordinarily C<-1>.
+respectively. POSITION and the return value are based at zero.
+If the substring is not found, C<index> returns -1.
=item int EXPR
X<int> X<integer> X<truncate> X<trunc> X<floor>
See also C<each>, C<values>, and C<sort>.
=item kill SIGNAL, LIST
+
+=item kill SIGNAL
X<kill> X<signal>
Sends a signal to a list of processes. Returns the number of
See L<perlfork> for more details.
+If there is no I<LIST> of processes, no signal is sent, and the return
+value is 0. This form is sometimes used, however, because it causes
+tainting checks to be run. But see
+L<perlsec/Laundering and Detecting Tainted Data>.
+
Portability issues: L<perlport/kill>.
=item last LABEL
=back
-=item Otherwise, If EXPR has the UTF8 flag set
+=item Otherwise, if C<use locale> is in effect
-Unicode semantics are used for the case change.
+Respects current LC_CTYPE locale for code points < 256; and uses Unicode
+semantics for the remaining code points (this last can only happen if
+the UTF8 flag is also set). See L<perllocale>.
-=item Otherwise, if C<use locale> is in effect
+A deficiency in this is that case changes that cross the 255/256
+boundary are not well-defined. For example, the lower case of LATIN CAPITAL
+LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
+platforms). But under C<use locale>, the lower case of U+1E9E is
+itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
+current locale, and Perl has no way of knowing if that character even
+exists in the locale, much less what code point it is. Perl returns
+the input character unchanged, for all instances (and there aren't
+many) where the 255/256 boundary would otherwise be crossed.
+
+=item Otherwise, If EXPR has the UTF8 flag set
-Respects current LC_CTYPE locale. See L<perllocale>.
+Unicode semantics are used for the case change.
=item Otherwise, if C<use feature 'unicode_strings'> is in effect:
You can put a C<+> in front of the C<< > >> or C<< < >> to
indicate that you want both read and write access to the file; thus
C<< +< >> is almost always preferred for read/write updates--the
-C<< +> >> mode would clobber the file first. You cant usually use
+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>
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 B<open> pragma or the switch B<-CioD>) are ignored.
+Those layers will also be ignored if you specifying 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 C<open> involved a pipe, the return value happens to be the pid of
=item ord
-Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
-or Unicode) value of the first character of EXPR.
+Returns the numeric value of the first character of EXPR.
If EXPR is an empty string, returns 0. If EXPR is omitted, uses C<$_>.
(Note I<character>, not byte.)
on it in security-sensitive situations.> As of this writing, a
number of third-party CPAN modules offer random number generators
intended by their authors to be cryptographically secure,
-including: L<Math::Random::Secure>, L<Math::Random::MT::Perl>, and
-L<Math::TrulyRandom>.
+including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
+and L<Math::TrulyRandom>.
=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
X<read> X<file, read>
below). Note that in the latter case, it is usually highly counter-productive
to declare $a and $b as lexicals.
+If the subroutine is an XSUB, the elements to be compared are pushed on to
+the stack, the way arguments are usually passed to XSUBs. $a and $b are
+not set.
+
The values to be compared are always passed by reference and should not
be modified.
well-defined.
Because C<< <=> >> returns C<undef> when either operand is C<NaN>
-(not-a-number), and also because C<sort> raises an exception unless the
-result of a comparison is defined, be careful when sorting with a
+(not-a-number), be careful when sorting with a
comparison function like C<< $a <=> $b >> any lists that might contain a
C<NaN>. The following example takes advantage that C<NaN != NaN> to
eliminate any C<NaN>s from the input list.
past the end of the array, Perl issues a warning, and splices at the
end of the array.
-The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
+The following equivalences hold (assuming C<< $#a >= $i >> )
push(@a,$x,$y) splice(@a,@a,0,$x,$y)
pop(@a) splice(@a,-1)
%B like %b, but using an upper-case "B" with the # flag
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
- into the next variable in the parameter list
+ into the next argument in the parameter list
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
But there are a few situations in recent Perls where programs are likely to
want to call C<srand>. One is for generating predictable results generally for
testing or debugging. There, you use C<srand($seed)>, with the same C<$seed>
-each time. Another other case is where you need a cryptographically-strong
-starting point rather than the generally acceptable default, which is based on
-time of day, process ID, and memory allocation, or the F</dev/urandom> device
-if available. And still another case is that you may want to call C<srand()>
+each time. Another case is that you may want to call C<srand()>
after a C<fork()> to avoid child processes sharing the same seed value as the
parent (and consequently each other).
programs supply their own seed value (often C<time ^ $$> or C<time ^
($$ + ($$ << 15))>), but that isn't necessary any 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:
-
- srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
-
-If you're particularly concerned with this, search the CPAN for
-random number generator modules instead of rolling out your own.
-
Frequently called programs (like CGI scripts) that simply use
time ^ $$
can test a random subset each time, and should there be a failure, log the seed
used for that run so that it can later be used to reproduce the same results.
+B<C<rand()> is not cryptographically secure. You should not rely
+on it in security-sensitive situations.> As of this writing, a
+number of third-party CPAN modules offer random number generators
+intended by their authors to be cryptographically secure,
+including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
+and L<Math::TrulyRandom>.
+
=item stat FILEHANDLE
X<stat> X<file, status> X<ctime>
However, those variables will never be reinitialized, contrary to
lexical variables that are reinitialized each time their enclosing block
is entered.
+See L<perlsub/"Persistent Private Variables"> for details.
C<state> variables are enabled only when the C<use feature "state"> pragma
is in effect, unless the keyword is written as C<CORE::state>.
-See L<feature>.
+See also L<feature>.
=item study SCALAR
X<study>
references; see L<attributes> and L<Attribute::Handlers> for more
information about attributes.
+=item __SUB__
+X<__SUB__>
+
+A special token that returns the a reference to the current subroutine, or
+C<undef> outside of a subroutine.
+
+This token is only available under C<use v5.16> or the "current_sub"
+feature. See L<feature>.
+
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
X<substr> X<substring> X<mid> X<left> X<right>
=item substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it. First character is at
-offset C<0> (or whatever you've set C<$[> to (but B<<don't do that>)).
-If OFFSET is negative (or more precisely, less than C<$[>), starts
+offset zero. If OFFSET is negative, starts
that far back from the end of the string. If LENGTH is omitted, returns
everything through the end of the string. If LENGTH is negative, leaves that
many characters off the end of the string.
$_ = 'pq'; print $x,"\n"; # prints 5pq9
}
-Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
+With negative offsets, it remembers its position from the end of the string
+when the target string is modified:
+
+ $x = '1234';
+ for (substr($x, -3, 2)) {
+ $_ = 'a'; print $x,"\n"; # prints 1a4, as above
+ $x = 'abcdefg';
+ print $_,"\n"; # prints f
+ }
+
+Prior to Perl version 5.10, the result of using an lvalue multiple times was
+unspecified. Prior to 5.16, the result with negative offsets was
unspecified.
=item symlink OLDFILE,NEWFILE
C<use>ing library modules that won't work with older versions of Perl.
(We try not to do this more than we have to.)
-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>.
+C<use VERSION> also enables all features available in the requested
+version as defined by the C<feature> pragma, disabling any features
+not in the current version's feature bundle. 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).
+5.11.0, strictures are enabled lexically as
+with C<use strict>. Any explicit use of
+C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
+before it. In both cases, the F<feature.pm> and F<strict.pm> files are
+not actually loaded.
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
https://perl5.git.perl.org / perl5.git / blobdiff