xref: /openbsd-src/gnu/usr.bin/perl/dist/IO/lib/IO/File.pm (revision 3d61058aa5c692477b6d18acfbbdb653a9930ff9)
1#
2
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    my $fh = IO::File->new();
14    if ($fh->open("< file")) {
15        print <$fh>;
16        $fh->close;
17    }
18
19    my $fh = IO::File->new("> file");
20    if (defined $fh) {
21        print $fh "bar\n";
22        $fh->close;
23    }
24
25    my $fh = IO::File->new("file", "r");
26    if (defined $fh) {
27        print <$fh>;
28        undef $fh;       # automatically closes the file
29    }
30
31    my $fh = IO::File->new("file", O_WRONLY|O_APPEND);
32    if (defined $fh) {
33        print $fh "corge\n";
34
35        my $pos = $fh->getpos;
36        $fh->setpos($pos);
37
38        undef $fh;       # automatically closes the file
39    }
40
41    autoflush STDOUT 1;
42
43=head1 DESCRIPTION
44
45C<IO::File> inherits from C<IO::Handle> and C<IO::Seekable>. It extends
46these classes with methods that are specific to file handles.
47
48=head1 CONSTRUCTOR
49
50=over 4
51
52=item new ( FILENAME [,MODE [,PERMS]] )
53
54Creates an 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
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
66=back
67
68=head1 METHODS
69
70=over 4
71
72=item open( FILENAME [,MODE [,PERMS]] )
73
74=item open( FILENAME, IOLAYERS )
75
76C<open> accepts one, two or three parameters.  With one parameter,
77it is just a front end for the built-in C<open> function.  With two or three
78parameters, the first parameter is a filename that may include
79whitespace or other special characters, and the second parameter is
80the open mode, optionally followed by a file permission value.
81
82If C<IO::File::open> receives a Perl mode string ("E<gt>", "+E<lt>", etc.)
83or an ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic
84Perl C<open> operator (but protects any special characters).
85
86If C<IO::File::open> is given a numeric mode, it passes that mode
87and the optional permissions value to the Perl C<sysopen> operator.
88The permissions default to 0666.
89
90If C<IO::File::open> is given a mode that includes the C<:> character,
91it passes all the three arguments to the three-argument C<open> operator.
92
93For convenience, C<IO::File> exports the O_XXX constants from the
94Fcntl module, if this module is available.
95
96=back
97
98=head1 NOTE
99
100Some operating systems may perform  C<IO::File::new()> or C<IO::File::open()>
101on a directory without errors.  This behavior is not portable and not
102suggested for use.  Using C<opendir()> and C<readdir()> or C<IO::Dir> are
103suggested instead.
104
105=head1 SEE ALSO
106
107L<perlfunc>,
108L<perlop/"I/O Operators">,
109L<IO::Handle>,
110L<IO::Seekable>,
111L<IO::Dir>
112
113=head1 HISTORY
114
115Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
116
117=cut
118
119use 5.008_001;
120use strict;
121use Carp;
122use Symbol;
123use SelectSaver;
124use IO::Seekable;
125
126require Exporter;
127
128our @ISA = qw(IO::Handle IO::Seekable Exporter);
129
130our $VERSION = "1.55";
131
132our @EXPORT = @IO::Seekable::EXPORT;
133
134eval {
135    # Make all Fcntl O_XXX constants available for importing
136    require Fcntl;
137    my @O = grep /^O_/, @Fcntl::EXPORT;
138    Fcntl->import(@O);  # first we import what we want to export
139    push(@EXPORT, @O);
140};
141
142################################################
143## Constructor
144##
145
146sub new {
147    my $type = shift;
148    my $class = ref($type) || $type || "IO::File";
149    @_ >= 0 && @_ <= 3
150	or croak "usage: $class->new([FILENAME [,MODE [,PERMS]]])";
151    my $fh = $class->SUPER::new();
152    if (@_) {
153	$fh->open(@_)
154	    or return undef;
155    }
156    $fh;
157}
158
159################################################
160## Open
161##
162
163sub open {
164    @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
165    my ($fh, $file) = @_;
166    if (@_ > 2) {
167	my ($mode, $perms) = @_[2, 3];
168	if ($mode =~ /^\d+$/) {
169	    defined $perms or $perms = 0666;
170	    return sysopen($fh, $file, $mode, $perms);
171	} elsif ($mode =~ /:/) {
172	    return open($fh, $mode, $file) if @_ == 3;
173	    croak 'usage: $fh->open(FILENAME, IOLAYERS)';
174	} else {
175            return open($fh, IO::Handle::_open_mode_string($mode), $file);
176        }
177    }
178    open($fh, $file);
179}
180
1811;
182