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>[email protected]<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;
|
---|