This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
portability fix for IO::File and FileHandle
[perl5.git] / ext / IO / lib / IO / File.pm
CommitLineData
7a4c00b4
PP
1#
2
8add82fc
PP
3package IO::File;
4
5=head1 NAME
6
7IO::File - supply object methods for filehandles
8
9=head1 SYNOPSIS
10
11 use IO::File;
12
13 $fh = new IO::File;
774d564b 14 if ($fh->open("< file")) {
8add82fc
PP
15 print <$fh>;
16 $fh->close;
17 }
18
774d564b 19 $fh = new IO::File "> file";
8add82fc
PP
20 if (defined $fh) {
21 print $fh "bar\n";
22 $fh->close;
23 }
24
25 $fh = new IO::File "file", "r";
26 if (defined $fh) {
27 print <$fh>;
28 undef $fh; # automatically closes the file
29 }
30
31 $fh = new IO::File "file", O_WRONLY|O_APPEND;
32 if (defined $fh) {
33 print $fh "corge\n";
8add82fc 34
774d564b
PP
35 $pos = $fh->getpos;
36 $fh->setpos($pos);
8add82fc 37
774d564b
PP
38 undef $fh; # automatically closes the file
39 }
8add82fc
PP
40
41 autoflush STDOUT 1;
42
43=head1 DESCRIPTION
44
55497cff 45C<IO::File> inherits from C<IO::Handle> and C<IO::Seekable>. It extends
27d4819a 46these classes with methods that are specific to file handles.
8add82fc 47
27d4819a
JM
48=head1 CONSTRUCTOR
49
50=over 4
51
cf7fe8a2 52=item new ( FILENAME [,MODE [,PERMS]] )
27d4819a
JM
53
54Creates a C<IO::File>. If it receives any parameters, they are passed to
55the method C<open>; if the open fails, the object is destroyed. Otherwise,
56it is returned to the caller.
57
9f01644e
CS
58=item new_tmpfile
59
60Creates an C<IO::File> opened for read/write on a newly created temporary
61file. On systems where this is possible, the temporary file is anonymous
62(i.e. it is unlinked after creation, but held open). If the temporary
63file cannot be created or opened, the C<IO::File> object is destroyed.
64Otherwise, it is returned to the caller.
65
27d4819a
JM
66=back
67
68=head1 METHODS
69
70=over 4
71
72=item open( FILENAME [,MODE [,PERMS]] )
73
74C<open> accepts one, two or three parameters. With one parameter,
cf7fe8a2 75it is just a front end for the built-in C<open> function. With two or three
8add82fc
PP
76parameters, the first parameter is a filename that may include
77whitespace or other special characters, and the second parameter is
223d223e
PP
78the open mode, optionally followed by a file permission value.
79
27d4819a 80If C<IO::File::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
cf7fe8a2
GS
81or a ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic
82Perl C<open> operator (but protects any special characters).
223d223e
PP
83
84If C<IO::File::open> is given a numeric mode, it passes that mode
85and the optional permissions value to the Perl C<sysopen> operator.
cf7fe8a2
GS
86The permissions default to 0666.
87
88For convenience, C<IO::File> exports the O_XXX constants from the
89Fcntl module, if this module is available.
8add82fc 90
27d4819a
JM
91=back
92
8add82fc
PP
93=head1 SEE ALSO
94
95L<perlfunc>,
96L<perlop/"I/O Operators">,
27d4819a
JM
97L<IO::Handle>
98L<IO::Seekable>
8add82fc
PP
99
100=head1 HISTORY
101
cf7fe8a2 102Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
8add82fc 103
8add82fc
PP
104=cut
105
106require 5.000;
7a4c00b4 107use strict;
cf7fe8a2 108use vars qw($VERSION @EXPORT @EXPORT_OK @ISA);
8add82fc
PP
109use Carp;
110use Symbol;
8add82fc 111use SelectSaver;
8add82fc 112use IO::Seekable;
c7070406 113use File::Spec;
8add82fc
PP
114
115require Exporter;
116require DynaLoader;
117
118@ISA = qw(IO::Handle IO::Seekable Exporter DynaLoader);
119
cf7fe8a2 120$VERSION = "1.08";
8add82fc
PP
121
122@EXPORT = @IO::Seekable::EXPORT;
123
cb628fe9
GA
124eval {
125 # Make all Fcntl O_XXX constants available for importing
126 require Fcntl;
127 my @O = grep /^O_/, @Fcntl::EXPORT;
128 Fcntl->import(@O); # first we import what we want to export
129 push(@EXPORT, @O);
130};
8add82fc 131
8add82fc
PP
132################################################
133## Constructor
134##
135
136sub new {
27d4819a
JM
137 my $type = shift;
138 my $class = ref($type) || $type || "IO::File";
139 @_ >= 0 && @_ <= 3
140 or croak "usage: new $class [FILENAME [,MODE [,PERMS]]]";
8add82fc
PP
141 my $fh = $class->SUPER::new();
142 if (@_) {
143 $fh->open(@_)
144 or return undef;
145 }
146 $fh;
147}
148
149################################################
150## Open
151##
152
153sub open {
154 @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
155 my ($fh, $file) = @_;
156 if (@_ > 2) {
157 my ($mode, $perms) = @_[2, 3];
158 if ($mode =~ /^\d+$/) {
159 defined $perms or $perms = 0666;
160 return sysopen($fh, $file, $mode, $perms);
161 }
c7070406
PP
162 if (! File::Spec->file_name_is_absolute($file)) {
163 $file = File::Spec->catfile(File::Spec->curdir(),$file);
164 }
948ecc40 165 $file = IO::Handle::_open_mode_string($mode) . " $file\0";
8add82fc
PP
166 }
167 open($fh, $file);
168}
169
1701;