Debian Codegraph @

upstream/debian-unstable/man1/perlopentut.1

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 "PERLOPENTUT 1"
58 .TH PERLOPENTUT 1 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 perlopentut \- simple recipes for opening files and pipes in Perl
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Whenever you do I/O on a file in Perl, you do so through what in Perl is
68 called a \fBfilehandle\fR. A filehandle is an internal name for an external
69 file. It is the job of the \f(CW\*(C`open\*(C'\fR function to make the association
70 between the internal name and the external name, and it is the job
71 of the \f(CW\*(C`close\*(C'\fR function to break that association.
72 .PP
73 For your convenience, Perl sets up a few special filehandles that are
74 already open when you run. These include \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`STDERR\*(C'\fR,
75 and \f(CW\*(C`ARGV\*(C'\fR. Since those are pre-opened, you can use them right away
76 without having to go to the trouble of opening them yourself:
77 .PP
78 .Vb 1
79 \& print STDERR "This is a debugging message.\en";
80 \&
81 \& print STDOUT "Please enter something: ";
82 \& $response = <STDIN> // die "how come no input?";
83 \& print STDOUT "Thank you!\en";
84 \&
85 \& while (<ARGV>) { ... }
86 .Ve
87 .PP
88 As you see from those examples, \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR are output
89 handles, and \f(CW\*(C`STDIN\*(C'\fR and \f(CW\*(C`ARGV\*(C'\fR are input handles. They are
90 in all capital letters because they are reserved to Perl, much
91 like the \f(CW@ARGV\fR array and the \f(CW%ENV\fR hash are. Their external
92 associations were set up by your shell.
93 .PP
94 You will need to open every other filehandle on your own. Although there
95 are many variants, the most common way to call Perl's \fBopen()\fR function
96 is with three arguments and one return value:
97 .PP
98 \&\f(CW\*(C` \fR\f(CIOK\fR\f(CW = open(\fR\f(CIHANDLE\fR\f(CW, \fR\f(CIMODE\fR\f(CW, \fR\f(CIPATHNAME\fR\f(CW)\*(C'\fR
99 .PP
100 Where:
101 .IP \fIOK\fR 4
102 .IX Item "OK"
103 will be some defined value if the open succeeds, but
104 \&\f(CW\*(C`undef\*(C'\fR if it fails;
105 .IP \fIHANDLE\fR 4
106 .IX Item "HANDLE"
107 should be an undefined scalar variable to be filled in by the
108 \&\f(CW\*(C`open\*(C'\fR function if it succeeds;
109 .IP \fIMODE\fR 4
110 .IX Item "MODE"
111 is the access mode and the encoding format to open the file with;
112 .IP \fIPATHNAME\fR 4
113 .IX Item "PATHNAME"
114 is the external name of the file you want opened.
115 .PP
116 Most of the complexity of the \f(CW\*(C`open\*(C'\fR function lies in the many
117 possible values that the \fIMODE\fR parameter can take on.
118 .PP
119 One last thing before we show you how to open files: opening
120 files does not (usually) automatically lock them in Perl. See
121 perlfaq5 for how to lock.
122 .SH "Opening Text Files"
123 .IX Header "Opening Text Files"
124 .SS "Opening Text Files for Reading"
125 .IX Subsection "Opening Text Files for Reading"
126 If you want to read from a text file, first open it in
127 read-only mode like this:
128 .PP
129 .Vb 3
130 \& my $filename = "/some/path/to/a/textfile/goes/here";
131 \& my $encoding = ":encoding(UTF\-8)";
132 \& my $handle = undef; # this will be filled in on success
133 \&
134 \& open($handle, "< $encoding", $filename)
135 \& || die "$0: can\*(Aqt open $filename for reading: $!";
136 .Ve
137 .PP
138 As with the shell, in Perl the \f(CW"<"\fR is used to open the file in
139 read-only mode. If it succeeds, Perl allocates a brand new filehandle for
140 you and fills in your previously undefined \f(CW$handle\fR argument with a
141 reference to that handle.
142 .PP
143 Now you may use functions like \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, and
144 \&\f(CW\*(C`sysread\*(C'\fR on that handle. Probably the most common input function
145 is the one that looks like an operator:
146 .PP
147 .Vb 2
148 \& $line = readline($handle);
149 \& $line = <$handle>; # same thing
150 .Ve
151 .PP
152 Because the \f(CW\*(C`readline\*(C'\fR function returns \f(CW\*(C`undef\*(C'\fR at end of file or
153 upon error, you will sometimes see it used this way:
154 .PP
155 .Vb 7
156 \& $line = <$handle>;
157 \& if (defined $line) {
158 \& # do something with $line
159 \& }
160 \& else {
161 \& # $line is not valid, so skip it
162 \& }
163 .Ve
164 .PP
165 You can also just quickly \f(CW\*(C`die\*(C'\fR on an undefined value this way:
166 .PP
167 .Vb 1
168 \& $line = <$handle> // die "no input found";
169 .Ve
170 .PP
171 However, if hitting EOF is an expected and normal event, you do not want to
172 exit simply because you have run out of input. Instead, you probably just want
173 to exit an input loop. You can then test to see if an actual error has caused
174 the loop to terminate, and act accordingly:
175 .PP
176 .Vb 6
177 \& while (<$handle>) {
178 \& # do something with data in $_
179 \& }
180 \& if ($!) {
181 \& die "unexpected error while reading from $filename: $!";
182 \& }
183 .Ve
184 .PP
185 \&\fBA Note on Encodings\fR: Having to specify the text encoding every time
186 might seem a bit of a bother. To set up a default encoding for \f(CW\*(C`open\*(C'\fR so
187 that you don't have to supply it each time, you can use the \f(CW\*(C`open\*(C'\fR pragma:
188 .PP
189 .Vb 1
190 \& use open qw< :encoding(UTF\-8) >;
191 .Ve
192 .PP
193 Once you've done that, you can safely omit the encoding part of the
194 open mode:
195 .PP
196 .Vb 2
197 \& open($handle, "<", $filename)
198 \& || die "$0: can\*(Aqt open $filename for reading: $!";
199 .Ve
200 .PP
201 But never use the bare \f(CW"<"\fR without having set up a default encoding
202 first. Otherwise, Perl cannot know which of the many, many, many possible
203 flavors of text file you have, and Perl will have no idea how to correctly
204 map the data in your file into actual characters it can work with. Other
205 common encoding formats including \f(CW"ASCII"\fR, \f(CW"ISO\-8859\-1"\fR,
206 \&\f(CW"ISO\-8859\-15"\fR, \f(CW"Windows\-1252"\fR, \f(CW"MacRoman"\fR, and even \f(CW"UTF\-16LE"\fR.
207 See perlunitut for more about encodings.
208 .SS "Opening Text Files for Writing"
209 .IX Subsection "Opening Text Files for Writing"
210 When you want to write to a file, you first have to decide what to do about
211 any existing contents of that file. You have two basic choices here: to
212 preserve or to clobber.
213 .PP
214 If you want to preserve any existing contents, then you want to open the file
215 in append mode. As in the shell, in Perl you use \f(CW">>"\fR to open an
216 existing file in append mode. \f(CW">>"\fR creates the file if it does not
217 already exist.
218 .PP
219 .Vb 3
220 \& my $handle = undef;
221 \& my $filename = "/some/path/to/a/textfile/goes/here";
222 \& my $encoding = ":encoding(UTF\-8)";
223 \&
224 \& open($handle, ">> $encoding", $filename)
225 \& || die "$0: can\*(Aqt open $filename for appending: $!";
226 .Ve
227 .PP
228 Now you can write to that filehandle using any of \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR,
229 \&\f(CW\*(C`say\*(C'\fR, \f(CW\*(C`write\*(C'\fR, or \f(CW\*(C`syswrite\*(C'\fR.
230 .PP
231 As noted above, if the file does not already exist, then the append-mode open
232 will create it for you. But if the file does already exist, its contents are
233 safe from harm because you will be adding your new text past the end of the
234 old text.
235 .PP
236 On the other hand, sometimes you want to clobber whatever might already be
237 there. To empty out a file before you start writing to it, you can open it
238 in write-only mode:
239 .PP
240 .Vb 3
241 \& my $handle = undef;
242 \& my $filename = "/some/path/to/a/textfile/goes/here";
243 \& my $encoding = ":encoding(UTF\-8)";
244 \&
245 \& open($handle, "> $encoding", $filename)
246 \& || die "$0: can\*(Aqt open $filename in write\-open mode: $!";
247 .Ve
248 .PP
249 Here again Perl works just like the shell in that the \f(CW">"\fR clobbers
250 an existing file.
251 .PP
252 As with the append mode, when you open a file in write-only mode,
253 you can now write to that filehandle using any of \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR,
254 \&\f(CW\*(C`say\*(C'\fR, \f(CW\*(C`write\*(C'\fR, or \f(CW\*(C`syswrite\*(C'\fR.
255 .PP
256 What about read-write mode? You should probably pretend it doesn't exist,
257 because opening text files in read-write mode is unlikely to do what you
258 would like. See perlfaq5 for details.
259 .SH "Opening Binary Files"
260 .IX Header "Opening Binary Files"
261 If the file to be opened contains binary data instead of text characters,
262 then the \f(CW\*(C`MODE\*(C'\fR argument to \f(CW\*(C`open\*(C'\fR is a little different. Instead of
263 specifying the encoding, you tell Perl that your data are in raw bytes.
264 .PP
265 .Vb 3
266 \& my $filename = "/some/path/to/a/binary/file/goes/here";
267 \& my $encoding = ":raw :bytes"
268 \& my $handle = undef; # this will be filled in on success
269 .Ve
270 .PP
271 And then open as before, choosing \f(CW"<"\fR, \f(CW">>"\fR, or
272 \&\f(CW">"\fR as needed:
273 .PP
274 .Vb 2
275 \& open($handle, "< $encoding", $filename)
276 \& || die "$0: can\*(Aqt open $filename for reading: $!";
277 \&
278 \& open($handle, ">> $encoding", $filename)
279 \& || die "$0: can\*(Aqt open $filename for appending: $!";
280 \&
281 \& open($handle, "> $encoding", $filename)
282 \& || die "$0: can\*(Aqt open $filename in write\-open mode: $!";
283 .Ve
284 .PP
285 Alternately, you can change to binary mode on an existing handle this way:
286 .PP
287 .Vb 1
288 \& binmode($handle) || die "cannot binmode handle";
289 .Ve
290 .PP
291 This is especially handy for the handles that Perl has already opened for you.
292 .PP
293 .Vb 2
294 \& binmode(STDIN) || die "cannot binmode STDIN";
295 \& binmode(STDOUT) || die "cannot binmode STDOUT";
296 .Ve
297 .PP
298 You can also pass \f(CW\*(C`binmode\*(C'\fR an explicit encoding to change it on the fly.
299 This isn't exactly "binary" mode, but we still use \f(CW\*(C`binmode\*(C'\fR to do it:
300 .PP
301 .Vb 2
302 \& binmode(STDIN, ":encoding(MacRoman)") || die "cannot binmode STDIN";
303 \& binmode(STDOUT, ":encoding(UTF\-8)") || die "cannot binmode STDOUT";
304 .Ve
305 .PP
306 Once you have your binary file properly opened in the right mode, you can
307 use all the same Perl I/O functions as you used on text files. However,
308 you may wish to use the fixed-size \f(CW\*(C`read\*(C'\fR instead of the variable-sized
309 \&\f(CW\*(C`readline\*(C'\fR for your input.
310 .PP
311 Here's an example of how to copy a binary file:
312 .PP
313 .Vb 3
314 \& my $BUFSIZ = 64 * (2 ** 10);
315 \& my $name_in = "/some/input/file";
316 \& my $name_out = "/some/output/flie";
317 \&
318 \& my($in_fh, $out_fh, $buffer);
319 \&
320 \& open($in_fh, "<", $name_in)
321 \& || die "$0: cannot open $name_in for reading: $!";
322 \& open($out_fh, ">", $name_out)
323 \& || die "$0: cannot open $name_out for writing: $!";
324 \&
325 \& for my $fh ($in_fh, $out_fh) {
326 \& binmode($fh) || die "binmode failed";
327 \& }
328 \&
329 \& while (read($in_fh, $buffer, $BUFSIZ)) {
330 \& unless (print $out_fh $buffer) {
331 \& die "couldn\*(Aqt write to $name_out: $!";
332 \& }
333 \& }
334 \&
335 \& close($in_fh) || die "couldn\*(Aqt close $name_in: $!";
336 \& close($out_fh) || die "couldn\*(Aqt close $name_out: $!";
337 .Ve
338 .SH "Opening Pipes"
339 .IX Header "Opening Pipes"
340 Perl also lets you open a filehandle into an external program or shell
341 command rather than into a file. You can do this in order to pass data
342 from your Perl program to an external command for further processing, or
343 to receive data from another program for your own Perl program to
344 process.
345 .PP
346 Filehandles into commands are also known as \fIpipes\fR, since they work on
347 similar inter-process communication principles as Unix pipelines. Such a
348 filehandle has an active program instead of a static file on its
349 external end, but in every other sense it works just like a more typical
350 file-based filehandle, with all the techniques discussed earlier in this
351 article just as applicable.
352 .PP
353 As such, you open a pipe using the same \f(CW\*(C`open\*(C'\fR call that you use for
354 opening files, setting the second (\f(CW\*(C`MODE\*(C'\fR) argument to special
355 characters that indicate either an input or an output pipe. Use \f(CW"\-|"\fR for a
356 filehandle that will let your Perl program read data from an external
357 program, and \f(CW"|\-"\fR for a filehandle that will send data to that
358 program instead.
359 .SS "Opening a pipe for reading"
360 .IX Subsection "Opening a pipe for reading"
361 Let's say you'd like your Perl program to process data stored in a nearby
362 directory called \f(CW\*(C`unsorted\*(C'\fR, which contains a number of textfiles.
363 You'd also like your program to sort all the contents from these files
364 into a single, alphabetically sorted list of unique lines before it
365 starts processing them.
366 .PP
367 You could do this through opening an ordinary filehandle into each of
368 those files, gradually building up an in-memory array of all the file
369 contents you load this way, and finally sorting and filtering that array
370 when you've run out of files to load. \fIOr\fR, you could offload all that
371 merging and sorting into your operating system's own \f(CW\*(C`sort\*(C'\fR command by
372 opening a pipe directly into its output, and get to work that much
373 faster.
374 .PP
375 Here's how that might look:
376 .PP
377 .Vb 2
378 \& open(my $sort_fh, \*(Aq\-|\*(Aq, \*(Aqsort \-u unsorted/*.txt\*(Aq)
379 \& or die "Couldn\*(Aqt open a pipe into sort: $!";
380 \&
381 \& # And right away, we can start reading sorted lines:
382 \& while (my $line = <$sort_fh>) {
383 \& #
384 \& # ... Do something interesting with each $line here ...
385 \& #
386 \& }
387 .Ve
388 .PP
389 The second argument to \f(CW\*(C`open\*(C'\fR, \f(CW"\-|"\fR, makes it a read-pipe into a
390 separate program, rather than an ordinary filehandle into a file.
391 .PP
392 Note that the third argument to \f(CW\*(C`open\*(C'\fR is a string containing the
393 program name (\f(CW\*(C`sort\*(C'\fR) plus all its arguments: in this case, \f(CW\*(C`\-u\*(C'\fR to
394 specify unqiue sort, and then a fileglob specifying the files to sort.
395 The resulting filehandle \f(CW$sort_fh\fR works just like a read-only (\f(CW"<"\fR) filehandle, and your program can subsequently read data
396 from it as if it were opened onto an ordinary, single file.
397 .SS "Opening a pipe for writing"
398 .IX Subsection "Opening a pipe for writing"
399 Continuing the previous example, let's say that your program has
400 completed its processing, and the results sit in an array called
401 \&\f(CW@processed\fR. You want to print these lines to a file called
402 \&\f(CW\*(C`numbered.txt\*(C'\fR with a neatly formatted column of line-numbers.
403 .PP
404 Certainly you could write your own code to do this — or, once again,
405 you could kick that work over to another program. In this case, \f(CW\*(C`cat\*(C'\fR,
406 running with its own \f(CW\*(C`\-n\*(C'\fR option to activate line numbering, should do
407 the trick:
408 .PP
409 .Vb 2
410 \& open(my $cat_fh, \*(Aq|\-\*(Aq, \*(Aqcat \-n > numbered.txt\*(Aq)
411 \& or die "Couldn\*(Aqt open a pipe into cat: $!";
412 \&
413 \& for my $line (@processed) {
414 \& print $cat_fh $line;
415 \& }
416 .Ve
417 .PP
418 Here, we use a second \f(CW\*(C`open\*(C'\fR argument of \f(CW"|\-"\fR, signifying that the
419 filehandle assigned to \f(CW$cat_fh\fR should be a write-pipe. We can then
420 use it just as we would a write-only ordinary filehandle, including the
421 basic function of \f(CW\*(C`print\*(C'\fR\-ing data to it.
422 .PP
423 Note that the third argument, specifying the command that we wish to
424 pipe to, sets up \f(CW\*(C`cat\*(C'\fR to redirect its output via that \f(CW">"\fR
425 symbol into the file \f(CW\*(C`numbered.txt\*(C'\fR. This can start to look a little
426 tricky, because that same symbol would have meant something
427 entirely different had it showed it in the second argument to \f(CW\*(C`open\*(C'\fR!
428 But here in the third argument, it's simply part of the shell command that
429 Perl will open the pipe into, and Perl itself doesn't invest any special
430 meaning to it.
431 .SS "Expressing the command as a list"
432 .IX Subsection "Expressing the command as a list"
433 For opening pipes, Perl offers the option to call \f(CW\*(C`open\*(C'\fR with a list
434 comprising the desired command and all its own arguments as separate
435 elements, rather than combining them into a single string as in the
436 examples above. For instance, we could have phrased the \f(CW\*(C`open\*(C'\fR call in
437 the first example like this:
438 .PP
439 .Vb 2
440 \& open(my $sort_fh, \*(Aq\-|\*(Aq, \*(Aqsort\*(Aq, \*(Aq\-u\*(Aq, glob(\*(Aqunsorted/*.txt\*(Aq))
441 \& or die "Couldn\*(Aqt open a pipe into sort: $!";
442 .Ve
443 .PP
444 When you call \f(CW\*(C`open\*(C'\fR this way, Perl invokes the given command directly,
445 bypassing the shell. As such, the shell won't try to interpret any
446 special characters within the command's argument list, which might
447 overwise have unwanted effects. This can make for safer, less
448 error-prone \f(CW\*(C`open\*(C'\fR calls, useful in cases such as passing in variables
449 as arguments, or even just referring to filenames with spaces in them.
450 .PP
451 However, when you \fIdo\fR want to pass a meaningful metacharacter to the
452 shell, such with the \f(CW"*"\fR inside that final \f(CW\*(C`unsorted/*.txt\*(C'\fR argument
453 here, you can't use this alternate syntax. In this case, we have worked
454 around it via Perl's handy \f(CW\*(C`glob\*(C'\fR built-in function, which evaluates
455 its argument into a list of filenames — and we can safely pass that
456 resulting list right into \f(CW\*(C`open\*(C'\fR, as shown above.
457 .PP
458 Note also that representing piped-command arguments in list form like
459 this doesn't work on every platform. It will work on any Unix-based OS
460 that provides a real \f(CW\*(C`fork\*(C'\fR function (e.g. macOS or Linux), as well as
461 on Windows when running Perl 5.22 or later.
462 .SH "SEE ALSO"
463 .IX Header "SEE ALSO"
464 The full documentation for \f(CW\*(C`open\*(C'\fR
465 provides a thorough reference to this function, beyond the best-practice
466 basics covered here.
467 .SH "AUTHOR and COPYRIGHT"
468 .IX Header "AUTHOR and COPYRIGHT"
469 Copyright 2013 Tom Christiansen; now maintained by Perl5 Porters
470 .PP
471 This documentation is free; you can redistribute it and/or modify it under
472 the same terms as Perl itself.