1# 2 3package IO::Seekable; 4 5=head1 NAME 6 7IO::Seekable - supply seek based methods for I/O objects 8 9=head1 SYNOPSIS 10 11 use IO::Seekable; 12 package IO::Something; 13 @ISA = qw(IO::Seekable); 14 15=head1 DESCRIPTION 16 17C<IO::Seekable> does not have a constructor of its own as it is intended to 18be inherited by other C<IO::Handle> based objects. It provides methods 19which allow seeking of the file descriptors. 20 21=over 4 22 23=item $io->getpos 24 25Returns an opaque value that represents the current position of the 26IO::File, or C<undef> if this is not possible (eg an unseekable stream such 27as a terminal, pipe or socket). If the fgetpos() function is available in 28your C library it is used to implements getpos, else perl emulates getpos 29using C's ftell() function. 30 31=item $io->setpos 32 33Uses the value of a previous getpos call to return to a previously visited 34position. Returns "0 but true" on success, C<undef> on failure. 35 36=back 37 38See L<perlfunc> for complete descriptions of each of the following 39supported C<IO::Seekable> methods, which are just front ends for the 40corresponding built-in functions: 41 42=over 4 43 44=item $io->seek ( POS, WHENCE ) 45 46Seek the IO::File to position POS, relative to WHENCE: 47 48=over 8 49 50=item WHENCE=0 (SEEK_SET) 51 52POS is absolute position. (Seek relative to the start of the file) 53 54=item WHENCE=1 (SEEK_CUR) 55 56POS is an offset from the current position. (Seek relative to current) 57 58=item WHENCE=2 (SEEK_END) 59 60POS is an offset from the end of the file. (Seek relative to end) 61 62=back 63 64The SEEK_* constants can be imported from the C<Fcntl> module if you 65don't wish to use the numbers C<0> C<1> or C<2> in your code. 66 67Returns C<1> upon success, C<0> otherwise. 68 69=item $io->sysseek( POS, WHENCE ) 70 71Similar to $io->seek, but sets the IO::File's position using the system 72call lseek(2) directly, so will confuse most perl IO operators except 73sysread and syswrite (see L<perlfunc> for full details) 74 75Returns the new position, or C<undef> on failure. A position 76of zero is returned as the string C<"0 but true"> 77 78=item $io->tell 79 80Returns the IO::File's current position, or -1 on error. 81 82=back 83 84=head1 SEE ALSO 85 86L<perlfunc>, 87L<perlop/"I/O Operators">, 88L<IO::Handle> 89L<IO::File> 90 91=head1 HISTORY 92 93Derived from FileHandle.pm by Graham Barr E<lt>gbarr@pobox.comE<gt> 94 95=cut 96 97use 5.008_001; 98use Carp; 99use strict; 100use IO::Handle (); 101# XXX we can't get these from IO::Handle or we'll get prototype 102# mismatch warnings on C<use POSIX; use IO::File;> :-( 103use Fcntl qw(SEEK_SET SEEK_CUR SEEK_END); 104require Exporter; 105 106our @EXPORT = qw(SEEK_SET SEEK_CUR SEEK_END); 107our @ISA = qw(Exporter); 108 109our $VERSION = "1.55"; 110 111sub seek { 112 @_ == 3 or croak 'usage: $io->seek(POS, WHENCE)'; 113 seek($_[0], $_[1], $_[2]); 114} 115 116sub sysseek { 117 @_ == 3 or croak 'usage: $io->sysseek(POS, WHENCE)'; 118 sysseek($_[0], $_[1], $_[2]); 119} 120 121sub tell { 122 @_ == 1 or croak 'usage: $io->tell()'; 123 tell($_[0]); 124} 125 1261; 127