Debian Codegraph @

upstream/opensuse-tumbleweed/man3/FileHandle.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "FileHandle 3pm"
61 .TH FileHandle 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 FileHandle \- supply object methods for filehandles
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use FileHandle;
72 \&
73 \& my $fh = FileHandle\->new;
74 \& if ($fh\->open("< file")) {
75 \& print <$fh>;
76 \& $fh\->close;
77 \& }
78 \&
79 \& my $fh = FileHandle\->new("> FOO");
80 \& if (defined $fh) {
81 \& print $fh "bar\en";
82 \& $fh\->close;
83 \& }
84 \&
85 \& my $fh = FileHandle\->new("file", "r");
86 \& if (defined $fh) {
87 \& print <$fh>;
88 \& undef $fh; # automatically closes the file
89 \& }
90 \&
91 \& my $fh = FileHandle\->new("file", O_WRONLY|O_APPEND);
92 \& if (defined $fh) {
93 \& print $fh "corge\en";
94 \& undef $fh; # automatically closes the file
95 \& }
96 \&
97 \& my $pos = $fh\->getpos;
98 \& $fh\->setpos($pos);
99 \&
100 \& $fh\->setvbuf(my $buffer_var, _IOLBF, 1024);
101 \&
102 \& my ($readfh, $writefh) = FileHandle::pipe;
103 \&
104 \& autoflush STDOUT 1;
105 .Ve
106 .SH DESCRIPTION
107 .IX Header "DESCRIPTION"
108 NOTE: This class is now a front\-end to the IO::* classes.
109 .PP
110 \&\f(CW\*(C`FileHandle::new\*(C'\fR creates a \f(CW\*(C`FileHandle\*(C'\fR, which is a reference to a
111 newly created symbol (see the Symbol package). If it receives any
112 parameters, they are passed to \f(CW\*(C`FileHandle::open\*(C'\fR; if the open fails,
113 the \f(CW\*(C`FileHandle\*(C'\fR object is destroyed. Otherwise, it is returned to
114 the caller.
115 .PP
116 \&\f(CW\*(C`FileHandle::new_from_fd\*(C'\fR creates a \f(CW\*(C`FileHandle\*(C'\fR like \f(CW\*(C`new\*(C'\fR does.
117 It requires two parameters, which are passed to \f(CW\*(C`FileHandle::fdopen\*(C'\fR;
118 if the fdopen fails, the \f(CW\*(C`FileHandle\*(C'\fR object is destroyed.
119 Otherwise, it is returned to the caller.
120 .PP
121 \&\f(CW\*(C`FileHandle::open\*(C'\fR accepts one parameter or two. With one parameter,
122 it is just a front end for the built\-in \f(CW\*(C`open\*(C'\fR function. With two
123 parameters, the first parameter is a filename that may include
124 whitespace or other special characters, and the second parameter is
125 the open mode, optionally followed by a file permission value.
126 .PP
127 If \f(CW\*(C`FileHandle::open\*(C'\fR receives a Perl mode string (">", "+<", etc.)
128 or a POSIX \fBfopen()\fR mode string ("w", "r+", etc.), it uses the basic
129 Perl \f(CW\*(C`open\*(C'\fR operator.
130 .PP
131 If \f(CW\*(C`FileHandle::open\*(C'\fR is given a numeric mode, it passes that mode
132 and the optional permissions value to the Perl \f(CW\*(C`sysopen\*(C'\fR operator.
133 For convenience, \f(CW\*(C`FileHandle::import\*(C'\fR tries to import the O_XXX
134 constants from the Fcntl module. If dynamic loading is not available,
135 this may fail, but the rest of FileHandle will still work.
136 .PP
137 \&\f(CW\*(C`FileHandle::fdopen\*(C'\fR is like \f(CW\*(C`open\*(C'\fR except that its first parameter
138 is not a filename but rather a file handle name, a FileHandle object,
139 or a file descriptor number.
140 .PP
141 If the C functions \fBfgetpos()\fR and \fBfsetpos()\fR are available, then
142 \&\f(CW\*(C`FileHandle::getpos\*(C'\fR returns an opaque value that represents the
143 current position of the FileHandle, and \f(CW\*(C`FileHandle::setpos\*(C'\fR uses
144 that value to return to a previously visited position.
145 .PP
146 If the C function \fBsetvbuf()\fR is available, then \f(CW\*(C`FileHandle::setvbuf\*(C'\fR
147 sets the buffering policy for the FileHandle. The calling sequence
148 for the Perl function is the same as its C counterpart, including the
149 macros \f(CW\*(C`_IOFBF\*(C'\fR, \f(CW\*(C`_IOLBF\*(C'\fR, and \f(CW\*(C`_IONBF\*(C'\fR, except that the buffer
150 parameter specifies a scalar variable to use as a buffer. WARNING: A
151 variable used as a buffer by \f(CW\*(C`FileHandle::setvbuf\*(C'\fR must not be
152 modified in any way until the FileHandle is closed or until
153 \&\f(CW\*(C`FileHandle::setvbuf\*(C'\fR is called again, or memory corruption may
154 result!
155 .PP
156 See perlfunc for complete descriptions of each of the following
157 supported \f(CW\*(C`FileHandle\*(C'\fR methods, which are just front ends for the
158 corresponding built\-in functions:
159 .PP
160 .Vb 8
161 \& close
162 \& fileno
163 \& getc
164 \& gets
165 \& eof
166 \& clearerr
167 \& seek
168 \& tell
169 .Ve
170 .PP
171 See perlvar for complete descriptions of each of the following
172 supported \f(CW\*(C`FileHandle\*(C'\fR methods:
173 .PP
174 .Vb 12
175 \& autoflush
176 \& output_field_separator
177 \& output_record_separator
178 \& input_record_separator
179 \& input_line_number
180 \& format_page_number
181 \& format_lines_per_page
182 \& format_lines_left
183 \& format_name
184 \& format_top_name
185 \& format_line_break_characters
186 \& format_formfeed
187 .Ve
188 .PP
189 Furthermore, for doing normal I/O you might need these:
190 .ie n .IP $fh\->print 4
191 .el .IP \f(CW$fh\fR\->print 4
192 .IX Item "$fh->print"
193 See "print" in perlfunc.
194 .ie n .IP $fh\->printf 4
195 .el .IP \f(CW$fh\fR\->printf 4
196 .IX Item "$fh->printf"
197 See "printf" in perlfunc.
198 .ie n .IP $fh\->getline 4
199 .el .IP \f(CW$fh\fR\->getline 4
200 .IX Item "$fh->getline"
201 This works like <$fh> described in "I/O Operators" in perlop
202 except that it\*(Aqs more readable and can be safely called in a
203 list context but still returns just one line.
204 .ie n .IP $fh\->getlines 4
205 .el .IP \f(CW$fh\fR\->getlines 4
206 .IX Item "$fh->getlines"
207 This works like <$fh> when called in a list context to
208 read all the remaining lines in a file, except that it\*(Aqs more readable.
209 It will also \fBcroak()\fR if accidentally called in a scalar context.
210 .PP
211 There are many other functions available since FileHandle is descended
212 from IO::File, IO::Seekable, and IO::Handle. Please see those
213 respective pages for documentation on more functions.
214 .SH "SEE ALSO"
215 .IX Header "SEE ALSO"
216 The \fBIO\fR extension,
217 perlfunc,
218 "I/O Operators" in perlop.