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
second--glance appear to be an lvalue context may be fixed in a future
release.
-See L<perlref/"Pseudo-hashes: Using an array as a hash"> for specifics
-on how exists() acts when used on a pseudo-hash.
-
Use of a subroutine call, rather than a subroutine name, as an argument
to exists() is an error.
=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";
Returns the process id of the parent process.
+Note for Linux users: on Linux, the C functions C<getpid()> and
+C<getppid()> return different values from different threads. In order to
+be portable, this behavior is not reflected by the perl-level function
+C<getppid()>, that returns a consistent value across threads. If you want
+to call the underlying C<getppid()>, you may use the CPAN module
+C<Linux::Pid>.
+
=item getpriority WHICH,WHO
Returns the current priority for a process, a process group, or a user.
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
- $name = getgrgid($num;
+ $name = getgrgid($num);
$name = getgrent();
#etc.
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<$_>.
Returns a random fractional number greater than or equal to C<0> and less
than the value of EXPR. (EXPR should be positive.) If EXPR is
-omitted, or a C<0>, the value C<1> is used. Automatically calls C<srand>
-unless C<srand> has already been called. See also C<srand>.
+omitted, the value C<1> is used. Currently EXPR with the value C<0> is
+also special-cased as C<1> - this has not been documented before perl 5.8.0
+and is subject to change in future versions of perl. Automatically calls
+C<srand> unless C<srand> has already been called. See also C<srand>.
Apply C<int()> to the value returned by C<rand()> if you want random
integers instead of random fractional numbers. For example,
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
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</use>.
+independent ways quite probably will. See L<sort>.
Examples:
patterns that vary at runtime. (To do runtime compilation only once,
use C</$variable/o>.)
-As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split> with no arguments does. Thus, C<split(' ')> can
-be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
+As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
+white space just as C<split> with no arguments does. Thus, S<C<split(' ')>> can
+be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
will give you as many null initial fields as there are leading spaces.
-A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
+A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
whitespace produces a null first field. A C<split> with no arguments
-really does a C<split(' ', $_)> internally.
+really does a S<C<split(' ', $_)>> internally.
A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
much use otherwise.
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, 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.
+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>:
-The size specifier 'V' has no effect for Perl code, but it supported
+ 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:
+
+ 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
7 size total size of file, in bytes
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
- 10 ctime inode change time (NOT creation time!) in seconds since the epoch
+ 10 ctime inode change time in seconds since the epoch (*)
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocated
(The epoch was at 00:00 January 1, 1970 GMT.)
+(*) The ctime field is non-portable, in particular you cannot expect
+it to be a "creation time", see L<perlport/"Files and Filesystems">
+for details.
+
If stat is passed the special filehandle consisting of an underline, no
stat is done, but the current contents of the stat structure from the
last stat or filetest are returned. Example:
$group_read = ($mode & S_IRGRP) >> 3;
$other_execute = $mode & S_IXOTH;
- printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+ printf "Permissions are %04o\n", S_IMODE($mode), "\n";
$is_setuid = $mode & S_ISUID;
$is_setgid = S_ISDIR($mode);
S_IRWXG S_IRGRP S_IWGRP S_IXGRP
S_IRWXO S_IROTH S_IWOTH S_IXOTH
- # Setuid/Setgid/Stickiness.
+ # Setuid/Setgid/Stickiness/SaveText.
+ # Note that the exact meaning of these is system dependent.
S_ISUID S_ISGID S_ISVTX S_ISTXT
and the S_IF* functions are
- S_IFMODE($mode) the part of $mode containing the permission bits
+ S_IMODE($mode) the part of $mode containing the permission bits
and the setuid/setgid/sticky bits
S_IFMT($mode) the part of $mode containing the file type
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
projects / p5sagit/p5-mst-13.2.git / blobdiff