Commit | Line | Data |
8add82fc |
1 | # |
2 | |
3 | package IO::Seekable; |
4 | |
5 | =head1 NAME |
6 | |
7 | IO::Seekable - supply seek based methods for I/O objects |
8 | |
84dc3c4d |
9 | =head1 SYNOPSIS |
10 | |
27d4819a |
11 | use IO::Seekable; |
12 | package IO::Something; |
13 | @ISA = qw(IO::Seekable); |
84dc3c4d |
14 | |
8add82fc |
15 | =head1 DESCRIPTION |
16 | |
de592821 |
17 | C<IO::Seekable> does not have a constructor of its own as it is intended to |
8add82fc |
18 | be inherited by other C<IO::Handle> based objects. It provides methods |
19 | which allow seeking of the file descriptors. |
20 | |
a6a714bd |
21 | =over 4 |
8add82fc |
22 | |
a6a714bd |
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 |
54d9745e |
34 | position. Returns "0 but true" on success, C<undef> on failure. |
a6a714bd |
35 | |
36 | =back |
bbc7dcd2 |
37 | |
8add82fc |
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: |
a6006777 |
41 | |
a6a714bd |
42 | =over 4 |
43 | |
f4315cfa |
44 | =item $io->seek ( POS, WHENCE ) |
a6a714bd |
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 | |
f4315cfa |
58 | =item WHENCE=2 (SEEK_END) |
a6a714bd |
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. |
8add82fc |
81 | |
a6a714bd |
82 | =back |
bbc7dcd2 |
83 | |
8add82fc |
84 | =head1 SEE ALSO |
85 | |
86 | L<perlfunc>, |
87 | L<perlop/"I/O Operators">, |
27d4819a |
88 | L<IO::Handle> |
89 | L<IO::File> |
8add82fc |
90 | |
91 | =head1 HISTORY |
92 | |
cf7fe8a2 |
93 | Derived from FileHandle.pm by Graham Barr E<lt>gbarr@pobox.comE<gt> |
8add82fc |
94 | |
8add82fc |
95 | =cut |
96 | |
17f410f9 |
97 | require 5.005_64; |
8add82fc |
98 | use Carp; |
7a4c00b4 |
99 | use strict; |
17f410f9 |
100 | our($VERSION, @EXPORT, @ISA); |
d5b0d4de |
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); |
8add82fc |
105 | require Exporter; |
106 | |
107 | @EXPORT = qw(SEEK_SET SEEK_CUR SEEK_END); |
108 | @ISA = qw(Exporter); |
109 | |
76fbd8c4 |
110 | $VERSION = "1.08_00"; |
8add82fc |
111 | |
8add82fc |
112 | sub seek { |
cf7fe8a2 |
113 | @_ == 3 or croak 'usage: $io->seek(POS, WHENCE)'; |
8add82fc |
114 | seek($_[0], $_[1], $_[2]); |
115 | } |
116 | |
cf7fe8a2 |
117 | sub sysseek { |
118 | @_ == 3 or croak 'usage: $io->sysseek(POS, WHENCE)'; |
119 | sysseek($_[0], $_[1], $_[2]); |
120 | } |
121 | |
8add82fc |
122 | sub tell { |
cf7fe8a2 |
123 | @_ == 1 or croak 'usage: $io->tell()'; |
8add82fc |
124 | tell($_[0]); |
125 | } |
126 | |
127 | 1; |