home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 March / PCWorld_2003-03_cd.bin / Software / Topware / activeperl / ActivePerl / Perl / lib / IO / Seekable.pm < prev    next >
Encoding:
Perl POD Document  |  2002-06-19  |  3.0 KB  |  129 lines
  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.08_00";
  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;
  129.