[Summary view] [Print] [Text view]

   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;