IO::Seekable(3pm) Perl Programmers Reference Guide IO::Seekable(3pm)NAME
IO::Seekable - supply seek based methods for I/O objects
SYNOPSIS
use IO::Seekable;
package IO::Something;
@ISA = qw(IO::Seekable);
DESCRIPTION
"IO::Seekable" does not have a constructor of its own as it is intended to be inherited by other "IO::Handle" based objects. It provides
methods which allow seeking of the file descriptors.
$io->getpos
Returns an opaque value that represents the current position of the IO::File, or "undef" if this is not possible (eg an unseekable
stream such as a terminal, pipe or socket). If the fgetpos() function is available in your C library it is used to implements getpos,
else perl emulates getpos using C's ftell() function.
$io->setpos
Uses the value of a previous getpos call to return to a previously visited position. Returns "0 but true" on success, "undef" on fail-
ure.
See perlfunc for complete descriptions of each of the following supported "IO::Seekable" methods, which are just front ends for the corre-
sponding built-in functions:
$io->seek ( POS, WHENCE )
Seek the IO::File to position POS, relative to WHENCE:
WHENCE=0 (SEEK_SET)
POS is absolute position. (Seek relative to the start of the file)
WHENCE=1 (SEEK_CUR)
POS is an offset from the current position. (Seek relative to current)
WHENCE=2 (SEEK_END)
POS is an offset from the end of the file. (Seek relative to end)
The SEEK_* constants can be imported from the "Fcntl" module if you don't wish to use the numbers 0 1 or 2 in your code.
Returns 1 upon success, 0 otherwise.
$io->sysseek( POS, WHENCE )
Similar to $io->seek, but sets the IO::File's position using the system call lseek(2) directly, so will confuse most perl IO operators
except sysread and syswrite (see perlfunc for full details)
Returns the new position, or "undef" on failure. A position of zero is returned as the string "0 but true"
$io->tell
Returns the IO::File's current position, or -1 on error.
SEE ALSO
perlfunc, "I/O Operators" in perlop, IO::Handle IO::File
HISTORY
Derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>
perl v5.8.0 2002-06-01 IO::Seekable(3pm)
Check Out this Related Man Page
FileHandle(3pm) Perl Programmers Reference Guide FileHandle(3pm)NAME
FileHandle - supply object methods for filehandles
SYNOPSIS
use FileHandle;
$fh = new FileHandle;
if ($fh->open("< file")) {
print <$fh>;
$fh->close;
}
$fh = new FileHandle "> FOO";
if (defined $fh) {
print $fh "bar
";
$fh->close;
}
$fh = new FileHandle "file", "r";
if (defined $fh) {
print <$fh>;
undef $fh; # automatically closes the file
}
$fh = new FileHandle "file", O_WRONLY|O_APPEND;
if (defined $fh) {
print $fh "corge
";
undef $fh; # automatically closes the file
}
$pos = $fh->getpos;
$fh->setpos($pos);
$fh->setvbuf($buffer_var, _IOLBF, 1024);
($readfh, $writefh) = FileHandle::pipe;
autoflush STDOUT 1;
DESCRIPTION
NOTE: This class is now a front-end to the IO::* classes.
"FileHandle::new" creates a "FileHandle", which is a reference to a newly created symbol (see the "Symbol" package). If it receives any
parameters, they are passed to "FileHandle::open"; if the open fails, the "FileHandle" object is destroyed. Otherwise, it is returned to
the caller.
"FileHandle::new_from_fd" creates a "FileHandle" like "new" does. It requires two parameters, which are passed to "FileHandle::fdopen"; if
the fdopen fails, the "FileHandle" object is destroyed. Otherwise, it is returned to the caller.
"FileHandle::open" accepts one parameter or two. With one parameter, it is just a front end for the built-in "open" function. With two
parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open
mode, optionally followed by a file permission value.
If "FileHandle::open" receives a Perl mode string (">", "+<", etc.) or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
Perl "open" operator.
If "FileHandle::open" is given a numeric mode, it passes that mode and the optional permissions value to the Perl "sysopen" operator. For
convenience, "FileHandle::import" tries to import the O_XXX constants from the Fcntl module. If dynamic loading is not available, this may
fail, but the rest of FileHandle will still work.
"FileHandle::fdopen" is like "open" except that its first parameter is not a filename but rather a file handle name, a FileHandle object,
or a file descriptor number.
If the C functions fgetpos() and fsetpos() are available, then "FileHandle::getpos" returns an opaque value that represents the current
position of the FileHandle, and "FileHandle::setpos" uses that value to return to a previously visited position.
If the C function setvbuf() is available, then "FileHandle::setvbuf" sets the buffering policy for the FileHandle. The calling sequence
for the Perl function is the same as its C counterpart, including the macros "_IOFBF", "_IOLBF", and "_IONBF", except that the buffer
parameter specifies a scalar variable to use as a buffer. WARNING: A variable used as a buffer by "FileHandle::setvbuf" must not be modi-
fied in any way until the FileHandle is closed or until "FileHandle::setvbuf" is called again, or memory corruption may result!
See perlfunc for complete descriptions of each of the following supported "FileHandle" methods, which are just front ends for the corre-
sponding built-in functions:
close
fileno
getc
gets
eof
clearerr
seek
tell
See perlvar for complete descriptions of each of the following supported "FileHandle" methods:
autoflush
output_field_separator
output_record_separator
input_record_separator
input_line_number
format_page_number
format_lines_per_page
format_lines_left
format_name
format_top_name
format_line_break_characters
format_formfeed
Furthermore, for doing normal I/O you might need these:
$fh->print
See "print" in perlfunc.
$fh->printf
See "printf" in perlfunc.
$fh->getline
This works like <$fh> described in "I/O Operators" in perlop except that it's more readable and can be safely called in a list context
but still returns just one line.
$fh->getlines
This works like <$fh> when called in a list context to read all the remaining lines in a file, except that it's more readable. It will
also croak() if accidentally called in a scalar context.
There are many other functions available since FileHandle is descended from IO::File, IO::Seekable, and IO::Handle. Please see those
respective pages for documentation on more functions.
SEE ALSO
The IO extension, perlfunc, "I/O Operators" in perlop.
perl v5.8.0 2002-06-01 FileHandle(3pm)