File Coverage

blib/lib/IO/Seekable.pm
Criterion Covered Total %
statement 18 20 90.0
branch 2 6 33.3
condition n/a
subroutine 7 8 87.5
pod 3 3 100.0
total 30 37 81.0


line stmt bran cond sub pod time code
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 does not have a constructor of its own as it is intended to
18             be inherited by other C 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 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 on failure.
35              
36             =back
37              
38             See L for complete descriptions of each of the following
39             supported C 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 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 for full details)
74              
75             Returns the new position, or C 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,
87             L,
88             L
89             L
90              
91             =head1 HISTORY
92              
93             Derived from FileHandle.pm by Graham Barr Egbarr@pobox.comE
94              
95             =cut
96              
97 13     13   11322 use 5.008_001;
  13         61  
98 13     13   57 use Carp;
  13         19  
  13         668  
99 13     13   75 use strict;
  13         14  
  13         277  
100 13     13   4452 use IO::Handle ();
  13         30  
  13         369  
101             # XXX we can't get these from IO::Handle or we'll get prototype
102             # mismatch warnings on C :-(
103 13     13   68 use Fcntl qw(SEEK_SET SEEK_CUR SEEK_END);
  13         19  
  13         2549  
104             require Exporter;
105              
106             our @EXPORT = qw(SEEK_SET SEEK_CUR SEEK_END);
107             our @ISA = qw(Exporter);
108              
109             our $VERSION = "1.48";
110              
111             sub seek {
112 5 50   5 1 1238 @_ == 3 or croak 'usage: $io->seek(POS, WHENCE)';
113 5         80 seek($_[0], $_[1], $_[2]);
114             }
115              
116             sub sysseek {
117 0 0   0 1 0 @_ == 3 or croak 'usage: $io->sysseek(POS, WHENCE)';
118 0         0 sysseek($_[0], $_[1], $_[2]);
119             }
120              
121             sub tell {
122 1 50   1 1 20 @_ == 1 or croak 'usage: $io->tell()';
123 1         4 tell($_[0]);
124             }
125              
126             1;