This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
MPE/iX fixes from Mark Bixby (a Configure fix is also needed.)
[perl5.git] / ext / IO / lib / IO / Seekable.pm
CommitLineData
8add82fc 1#
2
3package IO::Seekable;
4
5=head1 NAME
6
7IO::Seekable - supply seek based methods for I/O objects
8
84dc3c4d 9=head1 SYNOPSIS
10
27d4819a
JM
11 use IO::Seekable;
12 package IO::Something;
13 @ISA = qw(IO::Seekable);
84dc3c4d 14
8add82fc 15=head1 DESCRIPTION
16
de592821 17C<IO::Seekable> does not have a constructor of its own as it is intended to
8add82fc 18be inherited by other C<IO::Handle> based objects. It provides methods
19which allow seeking of the file descriptors.
20
a6a714bd 21=over 4
8add82fc 22
a6a714bd
NC
23=item $io->getpos
24
25Returns an opaque value that represents the current position of the
26IO::File, or C<undef> if this is not possible (eg an unseekable stream such
27as a terminal, pipe or socket). If the fgetpos() function is available in
28your C library it is used to implements getpos, else perl emulates getpos
29using C's ftell() function.
30
31=item $io->setpos
32
33Uses the value of a previous getpos call to return to a previously visited
54d9745e 34position. Returns "0 but true" on success, C<undef> on failure.
a6a714bd
NC
35
36=back
bbc7dcd2 37
8add82fc 38See L<perlfunc> for complete descriptions of each of the following
39supported C<IO::Seekable> methods, which are just front ends for the
40corresponding built-in functions:
a6006777 41
a6a714bd
NC
42=over 4
43
f4315cfa 44=item $io->seek ( POS, WHENCE )
a6a714bd
NC
45
46Seek the IO::File to position POS, relative to WHENCE:
47
48=over 8
49
50=item WHENCE=0 (SEEK_SET)
51
52POS is absolute position. (Seek relative to the start of the file)
53
54=item WHENCE=1 (SEEK_CUR)
55
56POS is an offset from the current position. (Seek relative to current)
57
f4315cfa 58=item WHENCE=2 (SEEK_END)
a6a714bd
NC
59
60POS is an offset from the end of the file. (Seek relative to end)
61
62=back
63
64The SEEK_* constants can be imported from the C<Fcntl> module if you
65don't wish to use the numbers C<0> C<1> or C<2> in your code.
66
67Returns C<1> upon success, C<0> otherwise.
68
69=item $io->sysseek( POS, WHENCE )
70
71Similar to $io->seek, but sets the IO::File's position using the system
72call lseek(2) directly, so will confuse most perl IO operators except
73sysread and syswrite (see L<perlfunc> for full details)
74
75Returns the new position, or C<undef> on failure. A position
76of zero is returned as the string C<"0 but true">
77
78=item $io->tell
79
80Returns the IO::File's current position, or -1 on error.
8add82fc 81
a6a714bd 82=back
bbc7dcd2 83
8add82fc 84=head1 SEE ALSO
85
86L<perlfunc>,
87L<perlop/"I/O Operators">,
27d4819a
JM
88L<IO::Handle>
89L<IO::File>
8add82fc 90
91=head1 HISTORY
92
cf7fe8a2 93Derived from FileHandle.pm by Graham Barr E<lt>gbarr@pobox.comE<gt>
8add82fc 94
8add82fc 95=cut
96
17f410f9 97require 5.005_64;
8add82fc 98use Carp;
7a4c00b4 99use strict;
17f410f9 100our($VERSION, @EXPORT, @ISA);
d5b0d4de
GS
101use 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;> :-(
104use Fcntl qw(SEEK_SET SEEK_CUR SEEK_END);
8add82fc 105require Exporter;
106
107@EXPORT = qw(SEEK_SET SEEK_CUR SEEK_END);
108@ISA = qw(Exporter);
109
cf7fe8a2 110$VERSION = "1.08";
8add82fc 111
8add82fc 112sub seek {
cf7fe8a2 113 @_ == 3 or croak 'usage: $io->seek(POS, WHENCE)';
8add82fc 114 seek($_[0], $_[1], $_[2]);
115}
116
cf7fe8a2
GS
117sub sysseek {
118 @_ == 3 or croak 'usage: $io->sysseek(POS, WHENCE)';
119 sysseek($_[0], $_[1], $_[2]);
120}
121
8add82fc 122sub tell {
cf7fe8a2 123 @_ == 1 or croak 'usage: $io->tell()';
8add82fc 124 tell($_[0]);
125}
126
1271;