ext/IO/lib/IO/Seekable.pm

   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 require 5.005_64;
  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.08";
 111
 112 sub seek {
 113     @_ == 3 or croak 'usage: $io->seek(POS, WHENCE)';
 114     seek($_[0], $_[1], $_[2]);
 115 }
 116
 117 sub sysseek {
 118     @_ == 3 or croak 'usage: $io->sysseek(POS, WHENCE)';
 119     sysseek($_[0], $_[1], $_[2]);
 120 }
 121
 122 sub tell {
 123     @_ == 1 or croak 'usage: $io->tell()';
 124     tell($_[0]);
 125 }
 126
 127 1;