binmode, close, closedir, dbmclose, dbmopen, die, eof,
fileno, flock, format, getc, print, printf, read, readdir,
-rewinddir, seek, seekdir, select, syscall, sysread,
+rewinddir, seek, seekdir, select, syscall, sysread, sysseek,
syswrite, tell, telldir, truncate, warn, write
=item Functions for fixed length data or records
=item chomp
-This is a slightly safer version of chop (see below). It removes any
+This is a slightly safer version of L</chop>. It removes any
line ending that corresponds to the current value of C<$/> (also known as
$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total
number of characters removed from all its arguments. It's often used to
Closes the file or pipe associated with the file handle, returning TRUE
only if stdio successfully flushes buffers and closes the system file
-descriptor. You don't have to close FILEHANDLE if you are immediately
+descriptor. If the file handle came from a piped open C<close> will
+additionally return FALSE if one of the other system calls involved
+fails or if the program exits with non-zero status. (If the problem was
+that the program exited non-zero $! will be set to 0.)
+You don't have to close FILEHANDLE if you are immediately
going to do another open() on it, because open() will close it for you. (See
open().) However, an explicit close on an input file resets the line
counter ($.), while the implicit close done by open() does not. Also,
See L<perlform> for many details and examples.
-=item formline PICTURE, LIST
+=item formline PICTURE,LIST
This is an internal function used by C<format>s, though you may call it
too. It formats (see L<perlform>) a list of values according to the
A local modifies the listed variables to be local to the enclosing block,
subroutine, C<eval{}>, or C<do>. If more than one value is listed, the
list must be placed in parentheses. See L<perlsub/"Temporary Values via
-local()"> for details.
+local()"> for details, including issues with tied arrays and hashes.
But you really probably want to be using my() instead, because local() isn't
what most people think of as "local"). See L<perlsub/"Private Variables
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
-Explicitly closing any piped filehandle causes the parent process to
-wait for the child to finish, and returns the status value in C<$?>.
-Note: on any operation which may do a fork, unflushed buffers remain
+NOTE: On any operation which may do a fork, unflushed buffers remain
unflushed in both processes, which means you may need to set C<$|> to
avoid duplicate output.
+Closing any piped filehandle causes the parent process to wait for the
+child to finish, and returns the status value in C<$?>.
+
Using the constructor from the IO::Handle package (or one of its
subclasses, such as IO::File or IO::Socket),
you can generate anonymous filehandles which have the scope of whatever
c A signed char value.
C An unsigned char value.
+
s A signed short value.
S An unsigned short value.
+ (This 'short' is _exactly_ 16 bits, which may differ from
+ what a local C compiler calls 'short'.)
+
i A signed integer value.
I An unsigned integer value.
+ (This 'integer' is _at_least_ 32 bits wide. Its exact size
+ depends on what a local C compiler calls 'int', and may
+ even be larger than the 'long' described in the next item.)
+
l A signed long value.
L An unsigned long value.
+ (This 'long' is _exactly_ 32 bits, which may differ from
+ what a local C compiler calls 'long'.)
- n A short in "network" order.
- N A long in "network" order.
+ n A short in "network" (big-endian) order.
+ N A long in "network" (big-endian) order.
v A short in "VAX" (little-endian) order.
V A long in "VAX" (little-endian) order.
+ (These 'shorts' and 'longs' are _exactly_ 16 bits and
+ _exactly_ 32 bits, respectively.)
f A single-precision float in the native format.
d A double-precision float in the native format.
u A uuencoded string.
- w A BER compressed integer. Bytes give an unsigned integer base
- 128, most significant digit first, with as few digits as
- possible, and with the bit 8 of each byte except the last set
- to "1."
+ w A BER compressed integer. Its bytes represent an unsigned
+ integer in base 128, most significant digit first, with as few
+ digits as possible. Bit eight (the high bit) is set on each
+ byte except the last.
x A null byte.
X Back up a byte.
=item rand
-Returns a random fractional number between 0 and the value of EXPR.
-(EXPR should be positive.) If EXPR is omitted, returns a value between
-0 and 1. Automatically calls srand() unless srand() has already been
-called. See also srand().
+Returns a random fractional number greater than or equal to 0 and less
+than the value of EXPR. (EXPR should be positive.) If EXPR is
+omitted, the value 1 is used. Automatically calls srand() unless
+srand() has already been called. See also srand().
(Note: If your rand function consistently returns numbers that are too
large or too small, then your version of Perl was probably compiled
=item seek FILEHANDLE,POSITION,WHENCE
-Randomly positions the file pointer for FILEHANDLE, just like the fseek()
-call of stdio. FILEHANDLE may be an expression whose value gives the name
-of the filehandle. The values for WHENCE are 0 to set the file pointer to
-POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF
-plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for
-this from either the IO::Seekable or the POSIX module. Returns 1 upon
-success, 0 otherwise.
+Sets FILEHANDLE's position, just like the fseek() call of stdio.
+FILEHANDLE may be an expression whose value gives the name of the
+filehandle. The values for WHENCE are 0 to set the new position to
+POSITION, 1 to set it to the current position plus POSITION, and 2 to
+set it to EOF plus POSITION (typically negative). For WHENCE you may
+use the constants SEEK_SET, SEEK_CUR, and SEEK_END from either the
+IO::Seekable or the POSIX module. Returns 1 upon success, 0 otherwise.
-If you want to position a file pointer for sysread() or syswrite(), don't
-use seek() -- buffering makes its effect on the system file pointer
+If you want to position file for sysread() or syswrite(), don't use
+seek() -- buffering makes its effect on the file's system position
unpredictable and non-portable. Use sysseek() instead.
On some systems you have to do a seek whenever you switch between reading
and writing. Amongst other things, this may have the effect of calling
-stdio's clearerr(3). A "whence" of 1 (SEEK_CUR) is useful for not moving
-the file pointer:
+stdio's clearerr(3). A WHENCE of 1 (SEEK_CUR) is useful for not moving
+the file position:
seek(TEST,0,1);
This is also useful for applications emulating C<tail -f>. Once you hit
EOF on your read, and then sleep for a while, you might have to stick in a
-seek() to reset things. First the simple trick listed above to clear the
-filepointer. The seek() doesn't change the current position, but it
-I<does> clear the end-of-file condition on the handle, so that the next
-C<E<lt>FILEE<gt>> makes Perl try again to read something. We hope.
+seek() to reset things. The seek() doesn't change the current position,
+but it I<does> clear the end-of-file condition on the handle, so that the
+next C<E<lt>FILEE<gt>> makes Perl try again to read something. We hope.
If that doesn't work (some stdios are particularly cantankerous), then
you may need something more like this:
=item sprintf FORMAT, LIST
-Returns a string formatted by the usual printf conventions of the C
-language. See L<sprintf(3)> or L<printf(3)> on your system for details.
-(The * character for an indirectly specified length is not
-supported, but you can get the same effect by interpolating a variable
-into the pattern.) 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>.
-Some C libraries' implementations of sprintf() can
-dump core when fed ludicrous arguments.
+Returns a string formatted by the usual printf conventions of the
+C library function sprintf(). See L<sprintf(3)> or L<printf(3)>
+on your system for an explanation of the general principles.
+
+Perl does all of its own sprintf() formatting -- it emulates the C
+function sprintf(), but it doesn't use it (except for floating-point
+numbers, and even then only the standard modifiers are allowed). As a
+result, any non-standard extensions in your local sprintf() are not
+available from Perl.
+
+Perl's sprintf() permits the following universally-known conversions:
+
+ %% a percent sign
+ %c a character with the given number
+ %s a string
+ %d a signed integer, in decimal
+ %u an unsigned integer, in decimal
+ %o an unsigned integer, in octal
+ %x an unsigned integer, in hexadecimal
+ %e a floating-point number, in scientific notation
+ %f a floating-point number, in fixed decimal notation
+ %g a floating-point number, in %e or %f notation
+
+In addition, Perl permits the following widely-supported conversions:
+
+ %X like %x, but using upper-case letters
+ %E like %e, but using an upper-case "E"
+ %G like %g, but with an upper-case "E" (if applicable)
+ %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
+
+Finally, for backward (and we do mean "backward") compatibility, Perl
+permits these unnecessary but widely-supported conversions:
+
+ %i a synonym for %d
+ %D a synonym for %ld
+ %U a synonym for %lu
+ %O a synonym for %lo
+ %F a synonym for %f
+
+Perl permits the following universally-known flags between the C<%>
+and the conversion letter:
+
+ 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 octal with "0", hex with "0x"
+ number minimum field width
+ .number "precision": digits after decimal point for floating-point,
+ max length for string, minimum length for integer
+ l interpret integer as C type "long" or "unsigned long"
+ h interpret integer as C type "short" or "unsigned short"
+
+There is also one Perl-specific flag:
+
+ V interpret integer as Perl's standard integer type
+
+Where a number would appear in the flags, an asterisk ("*") may be
+used instead, in which case Perl uses the next item in the parameter
+list as the given number (that is, as the field width or precision).
+If a field width obtained through "*" is negative, it has the same
+effect as the '-' flag: left-justification.
+
+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>.
=item sqrt EXPR
=item sysread FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the system call read(2). It bypasses
-stdio, so mixing this with other kinds of reads or with seek() may
-cause confusion. Returns the number of bytes actually read, 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.
+specified FILEHANDLE, using the system call read(2). It bypasses stdio,
+so mixing this with other kinds of reads, print(), write(), seek(), or
+tell() can cause confusion. Returns the number of bytes actually read,
+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.
An OFFSET may be specified to place the read data at some place in the
string other than the beginning. A negative OFFSET specifies
=item sysseek FILEHANDLE,POSITION,WHENCE
-Randomly positions the system file pointer for FILEHANDLE using the
-system call lseek(2). It bypasses stdio, so mixing this with read(),
-print(), write(), or seek() may cause confusion. FILEHANDLE may be an
-expression whose value gives the name of the filehandle. The values for
-WHENCE are 0 to set the file pointer to POSITION, 1 to set the it to
-current plus POSITION, and 2 to set it to EOF plus offset. You may use
-the values SEEK_SET, SEEK_CUR, and SEEK_END for this from either the
-IO::Seekable or the POSIX module. Returns 1 upon success, 0 otherwise.
+Sets FILEHANDLE's system position using the system call lseek(2). It
+bypasses stdio, so mixing this with reads (other than sysread()),
+print(), write(), seek(), or tell() may cause confusion. FILEHANDLE may
+be an expression whose value gives the name of the filehandle. The
+values for WHENCE are 0 to set the new position to POSITION, 1 to set
+the it to the current position plus POSITION, and 2 to set it to EOF
+plus POSITION (typically negative). For WHENCE, you may use the
+constants SEEK_SET, SEEK_CUR, and SEEK_END from either the IO::Seekable
+or the POSIX module.
+
+Returns the new position, or the undefined value on failure. A position
+of zero is returned as the string "0 but true"; thus sysseek() returns
+TRUE on success and FALSE on failure, yet you can still easily determine
+the new position.
=item system LIST
Attempts to write LENGTH bytes of data from variable SCALAR to the
specified FILEHANDLE, using the system call write(2). It bypasses
-stdio, so mixing this with prints or with seek() may cause confusion.
-Returns the number of bytes actually written, or undef if there was an
-error. If the length is greater than the available data, only as much
-data as is available will be written.
+stdio, so mixing this with reads (other than sysread()), print(),
+write(), seek(), or tell() may cause confusion. Returns the number of
+bytes actually written, or undef if there was an error. If the length
+is greater than the available data, 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
=item tell
-Returns the current file position for FILEHANDLE. FILEHANDLE may be an
+Returns the current position for FILEHANDLE. FILEHANDLE may be an
expression whose value gives the name of the actual filehandle. If
FILEHANDLE is omitted, assumes the file last read.
projects / p5sagit/p5-mst-13.2.git / blobdiff