suitable for passing binary data. This includes turning off possible CRLF
translation and marking it as bytes (as opposed to Unicode characters).
Note that, despite what may be implied in I<"Programming Perl"> (the
-Camel) or elsewhere, C<:raw> is I<not> the simply inverse of C<:crlf>
--- other layers which would affect binary nature of the stream are
+Camel) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>
+-- other layers which would affect the binary nature of the stream are
I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
PERLIO environment variable.
we're in a subroutine or C<eval> or C<require>, and the undefined value
otherwise. In list context, returns
+ # 0 1 2
($package, $filename, $line) = caller;
With EXPR, it returns some extra information that the debugger uses to
print a stack trace. The value of EXPR indicates how many call frames
to go back before the current one.
+ # 0 1 2 3 4
($package, $filename, $line, $subroutine, $hasargs,
+
+ # 5 6 7 8 9 10
$wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
- = caller($i);
+ = 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
=item chdir EXPR
X<chdir>
X<cd>
+X<directory, change>
=item chdir FILEHANDLE
=item close
-Closes the file or pipe associated with the file handle, returning
-true only if IO buffers are successfully flushed and closes the system
-file descriptor. Closes the currently selected filehandle if the
-argument is omitted.
+Closes the file or pipe associated with the file handle, flushes the IO
+buffers, and closes the system file descriptor. Returns true if those
+operations have succeeded and if no error was reported by any PerlIO
+layer. Closes the currently selected filehandle if the argument is
+omitted.
You don't have to close FILEHANDLE if you are immediately going to do
another C<open> on it, because C<open> will close it for you. (See
=item crypt PLAINTEXT,SALT
X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
-X<decrypt> X<cryptography> X<passwd>
+X<decrypt> X<cryptography> X<passwd> X<encrypt>
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
a more elaborate exception handling implementation using objects that
maintain arbitrary state about the nature of the exception. Such a scheme
is sometimes preferable to matching particular string values of $@ using
-regular expressions. Here's an example:
+regular expressions. Because $@ is a global variable, and eval() may be
+used within object implementations, care must be taken that analyzing the
+error object doesn't replace the reference in the global variable. The
+easiest solution is to make a local copy of the reference before doing
+other manipulations. Here's an example:
use Scalar::Util 'blessed';
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
- if ($@) {
- if (blessed($@) && $@->isa("Some::Module::Exception")) {
+ if (my $ev_err = $@) {
+ if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
=item eval EXPR
X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
+X<error, handling> X<exception, handling>
=item eval BLOCK
C<formline> always returns true. See L<perlform> for other examples.
=item getc FILEHANDLE
-X<getc> X<getchar>
+X<getc> X<getchar> X<character> X<file, read>
=item getc
=item gmtime
-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 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
-tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the
-specified time. $mday is the day of the month, and $mon is the month
-itself, in the range C<0..11> with 0 indicating January and 11
-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). $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
-programs--and you wouldn't want to do that, would you?
-
-The proper way to get a complete 4-digit year is simply:
-
- $year += 1900;
+Works just like L<localtime> but the returned values are
+localized for the standard Greenwich time zone.
-And to get the last two digits of the year (e.g., '01' in 2001) do:
-
- $year = sprintf("%02d", $year % 100);
-
-If EXPR is omitted, C<gmtime()> uses the current time (C<gmtime(time)>).
-
-In scalar context, C<gmtime()> returns the ctime(3) value:
-
- $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
-
-If you need local time instead of GMT use the L</localtime> builtin.
-See also the C<timegm> function provided by the C<Time::Local> module,
-and the strftime(3) and mktime(3) functions available via the L<POSIX> module.
-
-This scalar value is B<not> locale dependent (see L<perllocale>), but is
-instead a Perl builtin. To get somewhat similar but locale dependent date
-strings, see the example in L</localtime>.
+Note: when called in list context, $isdst, the last value
+returned by gmtime is always C<0>. There is no
+Daylight Saving Time in GMT.
See L<perlport/gmtime> for portability concerns.
is not found, C<index> returns one less than the base, ordinarily C<-1>.
=item int EXPR
-X<int> X<integer> X<truncate> X<trunc>
+X<int> X<integer> X<truncate> X<trunc> X<floor>
=item int
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.
+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>
for details, including issues with tied arrays and hashes.
=item localtime EXPR
-X<localtime>
+X<localtime> X<ctime>
=item localtime
$year += 1900;
+Otherwise you create non-Y2K-compliant programs--and you wouldn't want
+to do that, would you?
+
To get the last two digits of the year (e.g., '01' in 2001) do:
$year = sprintf("%02d", $year % 100);
See L<perlport/localtime> for portability concerns.
+The L<Time::gmtime> and L<Time::localtime> modules provides a convenient,
+by-name access mechanism to the gmtime() and localtime() functions,
+respectively.
+
+For a comprehensive date and time representation look at the
+L<DateTime> module on CPAN.
+
=item lock THING
X<lock>
this right, so Perl automatically removes all trailing slashes to keep
everyone happy.
+In order to recursively create a directory structure look at
+the C<mkpath> function of the L<File::Path> module.
+
=item msgctl ID,CMD,ARG
X<msgctl>
Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
(the output record separator) is not appended. The first argument
of the list will be interpreted as the C<printf> format. See C<sprintf>
-for an explanation of the format argument. If C<use locale> is in effect,
-the character used for the decimal point in formatted real numbers is
-affected by the LC_NUMERIC locale. See L<perllocale>.
+for an explanation of the format argument. If C<use locale> is in effect,
+and POSIX::setlocale() has been called, the character used for the decimal
+separator in formatted floating point numbers is affected by the LC_NUMERIC
+locale. See L<perllocale> and L<POSIX>.
Don't fall into the trap of using a C<printf> when a simple
C<print> would do. The C<print> is more efficient and less
with the wrong number of RANDBITS.)
=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
-X<read>
+X<read> X<file, read>
=item read FILEHANDLE,SCALAR,LENGTH
open files, or pre-existing files. Check L<perlport> and either the
rename(2) manpage or equivalent system documentation for details.
+For a platform independent C<move> function look at the L<File::Copy>
+module.
+
=item require VERSION
X<require>
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 nothing, or a list of up to 4 values in the
+subroutine should return nothing, or a list of up to three 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.
-
+A filehandle, from which the file will be read.
=item 2
-A filehandle, from which the file will be read.
+A reference to a subroutine. If there is no filehandle (previous item),
+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<$_>.
+Again, return 1 for each valid line, and 0 after all lines have been
+returned.
=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]>.
empty. If it succeeds it returns true, otherwise it returns false and
sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
+To remove a directory tree recursively (C<rm -rf> on unix) look at
+the C<rmtree> function of the L<File::Path> module.
+
=item s///
The substitution operator. See L<perlop>.
=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.
+C<say LIST> is simply an abbreviation for C<{ local $/ = "\n"; print
+LIST }>.
This keyword is only available when the "say" feature is
enabled: see L<feature>.
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 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.
+established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
+C<UNITCHECK {}> 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
%E like %e, but using an upper-case "E"
%G like %g, but with an upper-case "E" (if applicable)
%b an unsigned integer, in binary
+ %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
=item flags
one or more of:
+
space prefix positive number with a space
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
- # prefix non-zero octal with "0", non-zero hex with "0x",
- non-zero binary with "0b"
+ # ensure the leading "0" for any octal,
+ prefix non-zero hexadecimal with "0x" or "0X",
+ prefix non-zero binary with "0b" or "0B"
For example:
- printf '<% d>', 12; # prints "< 12>"
- printf '<%+d>', 12; # prints "<+12>"
- printf '<%6s>', 12; # prints "< 12>"
- printf '<%-6s>', 12; # prints "<12 >"
- printf '<%06s>', 12; # prints "<000012>"
- printf '<%#x>', 12; # prints "<0xc>"
+ printf '<% d>', 12; # prints "< 12>"
+ printf '<%+d>', 12; # prints "<+12>"
+ printf '<%6s>', 12; # prints "< 12>"
+ printf '<%-6s>', 12; # prints "<12 >"
+ printf '<%06s>', 12; # prints "<000012>"
+ printf '<%#o>', 12; # prints "<014>"
+ printf '<%#x>', 12; # prints "<0xc>"
+ printf '<%#X>', 12; # prints "<0XC>"
+ printf '<%#b>', 12; # prints "<0b1100>"
+ printf '<%#B>', 12; # prints "<0B1100>"
+
+When a space and a plus sign are given as the flags at once,
+a plus sign is used to prefix a positive number.
+
+ printf '<%+ d>', 12; # prints "<+12>"
+ printf '<% +d>', 12; # prints "<+12>"
+
+When the # flag and a precision are given in the %o conversion,
+the precision is incremented if it's necessary for the leading "0".
+
+ printf '<%#.5o>', 012; # prints "<00012>"
+ printf '<%#.5o>', 012345; # prints "<012345>"
+ printf '<%#.0o>', 0; # prints "<0>"
=item vector flag
printf '<%.4g>', 100.01; # prints "<100>"
For integer conversions, specifying a precision implies that the
-output of the number itself should be zero-padded to this width:
+output of the number itself should be zero-padded to this width,
+where the 0 flag is ignored:
+
+ printf '<%.6d>', 1; # prints "<000001>"
+ printf '<%+.6d>', 1; # prints "<+000001>"
+ printf '<%-10.6d>', 1; # prints "<000001 >"
+ printf '<%10.6d>', 1; # prints "< 000001>"
+ printf '<%010.6d>', 1; # prints "< 000001>"
+ printf '<%+10.6d>', 1; # prints "< +000001>"
printf '<%.6x>', 1; # prints "<000001>"
printf '<%#.6x>', 1; # prints "<0x000001>"
printf '<%-10.6x>', 1; # prints "<000001 >"
+ printf '<%10.6x>', 1; # prints "< 000001>"
+ printf '<%010.6x>', 1; # prints "< 000001>"
+ printf '<%#10.6x>', 1; # prints "< 0x000001>"
For string conversions, specifying a precision truncates the string
to fit in the specified width:
printf '<%.6x>', 1; # prints "<000001>"
printf '<%.*x>', 6, 1; # prints "<000001>"
+If a precision obtained through C<*> is negative, it has the same
+effect as no precision.
+
+ printf '<%.*s>', 7, "string"; # prints "<string>"
+ printf '<%.*s>', 3, "string"; # prints "<str>"
+ printf '<%.*s>', 0, "string"; # prints "<>"
+ printf '<%.*s>', -1, "string"; # prints "<string>"
+
+ printf '<%.*d>', 1, 0; # prints "<0>"
+ printf '<%.*d>', 0, 0; # prints "<>"
+ printf '<%.*d>', -1, 0; # prints "<0>"
+
You cannot currently get the precision from a specified number,
but it is intended that this will be possible in the future using
e.g. C<.*2$>:
=back
-If C<use locale> is in effect, the character used for the decimal
-point in formatted real numbers is affected by the LC_NUMERIC locale.
-See L<perllocale>.
+If C<use locale> is in effect, and POSIX::setlocale() has been called,
+the character used for the decimal separator in formatted floating
+point numbers is affected by the LC_NUMERIC locale. See L<perllocale>
+and L<POSIX>.
=item sqrt EXPR
X<sqrt> X<root> X<square root>
one-third of the time. So don't do that.
=item stat FILEHANDLE
-X<stat> X<file, status>
+X<stat> X<file, status> X<ctime>
=item stat EXPR
or failure, and, if successful, sets the information associated with
the special filehandle C<_>.
-The File::stat module provides a convenient, by-name access mechanism:
+The L<File::stat> module provides a convenient, by-name access mechanism:
use File::stat;
$sb = stat($filename);
printf "Permissions are %04o\n", S_IMODE($mode), "\n";
$is_setuid = $mode & S_ISUID;
- $is_setgid = S_ISDIR($mode);
+ $is_directory = S_ISDIR($mode);
You could write the last two using the C<-u> and C<-d> operators.
The commonly available C<S_IF*> constants are
1904 in the current local time zone for its epoch.
For measuring time in better granularity than one second,
-you may use either the Time::HiRes module (from CPAN, and starting from
+you may use either the L<Time::HiRes> module (from CPAN, and starting from
Perl 5.8 part of the standard distribution), or if you have
gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
See L<perlfaq8> for details.
+For date and time processing look at the many related modules on CPAN.
+For a comprehensive date and time representation look at the
+L<DateTime> module.
+
=item times
X<times>
Note that this is a unary operator, not a list operator.
=item unlink LIST
-X<unlink> X<delete> X<remove> X<rm>
+X<unlink> X<delete> X<remove> X<rm> X<del>
=item unlink
return wantarray ? @a : "@a";
C<wantarray()>'s result is unspecified in the top level of a file,
-in a C<BEGIN>, C<CHECK>, C<INIT> or C<END> block, or in a C<DESTROY>
-method.
+in a C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> or C<END> block, or
+in a C<DESTROY> method.
This function should have been named wantlist() instead.
https://perl5.git.perl.org / perl5.git / blobdiff