Commit | Line | Data |
---|---|---|
920dae64 AT |
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; |