mode on systems where the run-time libraries distinguish between
binary and text files. If FILEHANDLE is an expression, the value is
taken as the name of the filehandle. Returns true on success,
-C<undef> on failure.
+otherwise it returns C<undef> and sets C<$!> (errno).
If LAYER is omitted or specified as C<:raw> the filehandle is made
suitable for passing binary data. This includes turning off possible CRLF
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
+Note that as a very special case, an C<eval ''> executed within the C<DB>
+package doesn't see the usual surrounding lexical scope, but rather the
+scope of the first non-DB piece of code that called it. You don't normally
+need to worry about this unless you are writing a Perl debugger.
+
=item exec LIST
=item exec PROGRAM LIST
=item getc
Returns the next character from the input file attached to FILEHANDLE,
-or the undefined value at end of file, or if there was an error.
-If FILEHANDLE is omitted, reads from STDIN. This is not particularly
-efficient. However, it cannot be used by itself to fetch single
-characters without waiting for the user to hit enter. For that, try
-something more like:
+or the undefined value at end of file, or if there was an error (in
+the latter case C<$!> is set). If FILEHANDLE is omitted, reads from
+STDIN. This is not particularly efficient. However, it cannot be
+used by itself to fetch single characters without waiting for the user
+to hit enter. For that, try something more like:
if ($BSD_STYLE) {
system "stty cbreak </dev/tty >/dev/tty 2>&1";
Does the same thing as the C<stat> function (including setting the
special C<_> filehandle) but stats a symbolic link instead of the file
the symbolic link points to. If symbolic links are unimplemented on
-your system, a normal C<stat> is done.
+your system, a normal C<stat> is done. For much more detailed
+information, please see the documentation for C<stat>.
If EXPR is omitted, stats C<$_>.
Attempts to read LENGTH I<characters> of data into variable SCALAR
from the specified FILEHANDLE. Returns the number of characters
-actually read, C<0> at end of file, or undef if there was an error.
-SCALAR will be grown or shrunk to the length actually read. If SCALAR
-needs growing, the new bytes will be zero bytes. An OFFSET may be
-specified to place the read data into some other place in SCALAR than
-the beginning. The call is actually implemented in terms of either
-Perl's or system's fread() call. To get a true read(2) system call,
-see C<sysread>.
+actually read, C<0> at end of file, or undef if there was an error (in
+the latter case C<$!> is also set). SCALAR will be grown or shrunk to
+the length actually read. If SCALAR needs growing, the new bytes will
+be zero bytes. An OFFSET may be specified to place the read data into
+some other place in SCALAR than the beginning. The call is actually
+implemented in terms of either Perl's or system's fread() call. To
+get a true read(2) system call, see C<sysread>.
Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read. By default all
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, this specifies the number of decimal places
-to show (the default being 6), eg:
+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:
# these examples are subject to system-specific variation
printf '<%f>', 1; # prints "<1.000000>"
printf '<%e>', 10; # prints "<1.000000e+01>"
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:
+
+ # these examples are subject to system-specific variation
+ printf '<%g>', 1; # prints "<1>"
+ printf '<%.10g>', 1; # prints "<1>"
+ printf '<%g>', 100; # prints "<100>"
+ printf '<%.1g>', 100; # prints "<1e+02>"
+ printf '<%.2g>', 100.01; # prints "<1e+02>"
+ printf '<%.5g>', 100.01; # prints "<100.01>"
+ 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:
=item size
For numeric conversions, you can specify the size to interpret the
-number as using C<l>, C<h>, C<V>, C<q>, C<L> or C<ll>. For integer
-conversions, numbers are usually assumed to be whatever the default
-integer size is on your platform (usually 32 or 64 bits), but you
-can override this to use instead one of the standard C types, as
-supported by the compiler used to build Perl:
+number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
+conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
+whatever the default integer size is on your platform (usually 32 or 64
+bits), but you can override this to use instead one of the standard C types,
+as supported by the compiler used to build Perl:
l interpret integer as C type "long" or "unsigned long"
h interpret integer as C type "short" or "unsigned short"
- q, L or ll interpret integer as C type "long long" or "unsigned long long"
- (if your platform supports such a type, else it is an error)
+ q, L or ll interpret integer as C type "long long", "unsigned long long".
+ or "quads" (typically 64-bit integers)
+
+The last will produce errors if Perl does not understand "quads" in your
+installation. (This requires that either the platform natively supports quads
+or Perl was specifically compiled to support quads.) You can find out
+whether your Perl supports quads via L<Config>:
+
+ use Config;
+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
+ print "quads\n";
+
+For floating point conversions (C<e f g E F G>), numbers are usually assumed
+to be the default floating point size on your platform (double or long double),
+but you can force 'long double' with C<q>, C<L>, or C<ll> if your
+platform supports them. You can find out whether your Perl supports long
+doubles via L<Config>:
-For floating point conversions, numbers are usually assumed to be
-the default floating point size on your platform (double or long double),
-but you can force 'long double' with C<q>, C<L> or C<ll> if your
-platform supports them.
+ use Config;
+ $Config{d_longdbl} eq 'define' && print "long doubles\n";
+
+You can find out whether Perl considers 'long double' to be the default
+floating point size to use on your platform via L<Config>:
+
+ use Config;
+ ($Config{uselongdouble} eq 'define') &&
+ print "long doubles by default\n";
+
+It can also be the case that long doubles and doubles are the same thing:
-The size specifier 'V' has no effect for Perl code, but it supported
+ use Config;
+ ($Config{doublesize} == $Config{longdblsize}) &&
+ print "doubles are long doubles\n";
+
+The size specifier C<V> has no effect for Perl code, but it is supported
for compatibility with XS code; it means 'use the standard size for
a Perl integer (or floating-point number)', which is already the
default for Perl code.
point in formatted real numbers is affected by the LC_NUMERIC locale.
See L<perllocale>.
-If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively support quads or that Perl
-be specifically compiled to support quads), the characters
-
- d u o x X b i D U O
-
-print quads, and they may optionally be preceded by
-
- ll L q
-
-For example
-
- %lld %16LX %qo
-
-You can find out whether your Perl supports quads via L<Config>:
-
- use Config;
- ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
- print "quads\n";
-
-If Perl understands "long doubles" (this requires that the platform
-support long doubles), the flags
-
- e f g E F G
-
-may optionally be preceded by
-
- ll L
-
-For example
-
- %llf %Lg
-
-You can find out whether your Perl supports long doubles via L<Config>:
-
- use Config;
- $Config{d_longdbl} eq 'define' && print "long doubles\n";
-
=item sqrt EXPR
=item sqrt
S_ISENFMT($mode) S_ISWHT($mode)
See your native chmod(2) and stat(2) documentation for more details
-about the S_* constants.
+about the S_* constants. To get status info for a symbolic link
+instead of the target file behind the link, use the C<lstat> function.
=item study SCALAR
=item sysread FILEHANDLE,SCALAR,LENGTH
-Attempts to read LENGTH I<characters> of data into variable SCALAR from
-the specified FILEHANDLE, using the system call read(2). It bypasses
-buffered IO, so mixing this with other kinds of reads, C<print>,
-C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because
-stdio usually buffers data. Returns the number of characters actually
-read, C<0> at end of file, or undef if there was an error. SCALAR
-will be grown or shrunk so that the last byte actually read is the
-last byte of the scalar after the read.
+Attempts to read LENGTH I<characters> of data into variable SCALAR
+from the specified FILEHANDLE, using the system call read(2). It
+bypasses buffered IO, so mixing this with other kinds of reads,
+C<print>, C<write>, C<seek>, C<tell>, or C<eof> can cause confusion
+because stdio usually buffers data. Returns the number of characters
+actually read, C<0> at end of file, or undef if there was an error (in
+the latter case C<$!> is also set). SCALAR will be grown or shrunk so
+that the last byte actually read is the last byte of the scalar after
+the read.
Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read. By default all
mixing this with reads (other than C<sysread())>, C<print>, C<write>,
C<seek>, C<tell>, or C<eof> may cause confusion because stdio usually
buffers data. Returns the number of characters actually written, or
-C<undef> if there was an error. If the LENGTH is greater than the
-available data in the SCALAR after the OFFSET, only as much data as is
-available will be written.
+C<undef> if there was an error (in this case the errno variable C<$!>
+is also set). If the LENGTH is greater than the available data in the
+SCALAR after the OFFSET, only as much data as is available will be
+written.
An OFFSET may be specified to write the data from some part of the
string other than the beginning. A negative OFFSET specifies writing