db1effda287ae33a92ade4d0cbac51148f14f5d7
[perl.git] / ext / IO / lib / IO / Seekable.pm
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;