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