Debian Codegraph @

upstream/debian-unstable/man3/IO::File.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "IO::File 3perl"
58 .TH IO::File 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 IO::File \- supply object methods for filehandles
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use IO::File;
69 \&
70 \& my $fh = IO::File\->new();
71 \& if ($fh\->open("< file")) {
72 \& print <$fh>;
73 \& $fh\->close;
74 \& }
75 \&
76 \& my $fh = IO::File\->new("> file");
77 \& if (defined $fh) {
78 \& print $fh "bar\en";
79 \& $fh\->close;
80 \& }
81 \&
82 \& my $fh = IO::File\->new("file", "r");
83 \& if (defined $fh) {
84 \& print <$fh>;
85 \& undef $fh; # automatically closes the file
86 \& }
87 \&
88 \& my $fh = IO::File\->new("file", O_WRONLY|O_APPEND);
89 \& if (defined $fh) {
90 \& print $fh "corge\en";
91 \&
92 \& my $pos = $fh\->getpos;
93 \& $fh\->setpos($pos);
94 \&
95 \& undef $fh; # automatically closes the file
96 \& }
97 \&
98 \& autoflush STDOUT 1;
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 \&\f(CW\*(C`IO::File\*(C'\fR inherits from \f(CW\*(C`IO::Handle\*(C'\fR and \f(CW\*(C`IO::Seekable\*(C'\fR. It extends
103 these classes with methods that are specific to file handles.
104 .SH CONSTRUCTOR
105 .IX Header "CONSTRUCTOR"
106 .IP "new ( FILENAME [,MODE [,PERMS]] )" 4
107 .IX Item "new ( FILENAME [,MODE [,PERMS]] )"
108 Creates an \f(CW\*(C`IO::File\*(C'\fR. If it receives any parameters, they are passed to
109 the method \f(CW\*(C`open\*(C'\fR; if the open fails, the object is destroyed. Otherwise,
110 it is returned to the caller.
111 .IP new_tmpfile 4
112 .IX Item "new_tmpfile"
113 Creates an \f(CW\*(C`IO::File\*(C'\fR opened for read/write on a newly created temporary
114 file. On systems where this is possible, the temporary file is anonymous
115 (i.e. it is unlinked after creation, but held open). If the temporary
116 file cannot be created or opened, the \f(CW\*(C`IO::File\*(C'\fR object is destroyed.
117 Otherwise, it is returned to the caller.
118 .SH METHODS
119 .IX Header "METHODS"
120 .IP "open( FILENAME [,MODE [,PERMS]] )" 4
121 .IX Item "open( FILENAME [,MODE [,PERMS]] )"
122 .PD 0
123 .IP "open( FILENAME, IOLAYERS )" 4
124 .IX Item "open( FILENAME, IOLAYERS )"
125 .PD
126 \&\f(CW\*(C`open\*(C'\fR accepts one, two or three parameters. With one parameter,
127 it is just a front end for the built-in \f(CW\*(C`open\*(C'\fR function. With two or three
128 parameters, the first parameter is a filename that may include
129 whitespace or other special characters, and the second parameter is
130 the open mode, optionally followed by a file permission value.
131 .Sp
132 If \f(CW\*(C`IO::File::open\*(C'\fR receives a Perl mode string (">", "+<", etc.)
133 or an ANSI C \fBfopen()\fR mode string ("w", "r+", etc.), it uses the basic
134 Perl \f(CW\*(C`open\*(C'\fR operator (but protects any special characters).
135 .Sp
136 If \f(CW\*(C`IO::File::open\*(C'\fR is given a numeric mode, it passes that mode
137 and the optional permissions value to the Perl \f(CW\*(C`sysopen\*(C'\fR operator.
138 The permissions default to 0666.
139 .Sp
140 If \f(CW\*(C`IO::File::open\*(C'\fR is given a mode that includes the \f(CW\*(C`:\*(C'\fR character,
141 it passes all the three arguments to the three-argument \f(CW\*(C`open\*(C'\fR operator.
142 .Sp
143 For convenience, \f(CW\*(C`IO::File\*(C'\fR exports the O_XXX constants from the
144 Fcntl module, if this module is available.
145 .SH NOTE
146 .IX Header "NOTE"
147 Some operating systems may perform \f(CWIO::File::new()\fR or \f(CWIO::File::open()\fR
148 on a directory without errors. This behavior is not portable and not
149 suggested for use. Using \f(CWopendir()\fR and \f(CWreaddir()\fR or \f(CW\*(C`IO::Dir\*(C'\fR are
150 suggested instead.
151 .SH "SEE ALSO"
152 .IX Header "SEE ALSO"
153 perlfunc,
154 "I/O Operators" in perlop,
155 IO::Handle,
156 IO::Seekable,
157 IO::Dir
158 .SH HISTORY
159 .IX Header "HISTORY"
160 Derived from FileHandle.pm by Graham Barr <\[email protected]\fR>.