Debian Codegraph @

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