1PERLOPENTUT(1) Perl Programmers Reference Guide PERLOPENTUT(1)
2
3
4
6 perlopentut - tutorial on opening things in Perl
7
9 Perl has two simple, built-in ways to open files: the shell way for
10 convenience, and the C way for precision. The shell way also has 2-
11 and 3-argument forms, which have different semantics for handling the
12 filename. The choice is yours.
13
15 Perl's "open" function was designed to mimic the way command-line redi‐
16 rection in the shell works. Here are some basic examples from the
17 shell:
18
19 $ myprogram file1 file2 file3
20 $ myprogram < inputfile
21 $ myprogram > outputfile
22 $ myprogram >> outputfile
23 $ myprogram ⎪ otherprogram
24 $ otherprogram ⎪ myprogram
25
26 And here are some more advanced examples:
27
28 $ otherprogram ⎪ myprogram f1 - f2
29 $ otherprogram 2>&1 ⎪ myprogram -
30 $ myprogram <&3
31 $ myprogram >&4
32
33 Programmers accustomed to constructs like those above can take comfort
34 in learning that Perl directly supports these familiar constructs using
35 virtually the same syntax as the shell.
36
37 Simple Opens
38
39 The "open" function takes two arguments: the first is a filehandle, and
40 the second is a single string comprising both what to open and how to
41 open it. "open" returns true when it works, and when it fails, returns
42 a false value and sets the special variable $! to reflect the system
43 error. If the filehandle was previously opened, it will be implicitly
44 closed first.
45
46 For example:
47
48 open(INFO, "datafile") ⎪⎪ die("can't open datafile: $!");
49 open(INFO, "< datafile") ⎪⎪ die("can't open datafile: $!");
50 open(RESULTS,"> runstats") ⎪⎪ die("can't open runstats: $!");
51 open(LOG, ">> logfile ") ⎪⎪ die("can't open logfile: $!");
52
53 If you prefer the low-punctuation version, you could write that this
54 way:
55
56 open INFO, "< datafile" or die "can't open datafile: $!";
57 open RESULTS,"> runstats" or die "can't open runstats: $!";
58 open LOG, ">> logfile " or die "can't open logfile: $!";
59
60 A few things to notice. First, the leading less-than is optional. If
61 omitted, Perl assumes that you want to open the file for reading.
62
63 Note also that the first example uses the "⎪⎪" logical operator, and
64 the second uses "or", which has lower precedence. Using "⎪⎪" in the
65 latter examples would effectively mean
66
67 open INFO, ( "< datafile" ⎪⎪ die "can't open datafile: $!" );
68
69 which is definitely not what you want.
70
71 The other important thing to notice is that, just as in the shell, any
72 whitespace before or after the filename is ignored. This is good,
73 because you wouldn't want these to do different things:
74
75 open INFO, "<datafile"
76 open INFO, "< datafile"
77 open INFO, "< datafile"
78
79 Ignoring surrounding whitespace also helps for when you read a filename
80 in from a different file, and forget to trim it before opening:
81
82 $filename = <INFO>; # oops, \n still there
83 open(EXTRA, "< $filename") ⎪⎪ die "can't open $filename: $!";
84
85 This is not a bug, but a feature. Because "open" mimics the shell in
86 its style of using redirection arrows to specify how to open the file,
87 it also does so with respect to extra whitespace around the filename
88 itself as well. For accessing files with naughty names, see "Dis‐
89 pelling the Dweomer".
90
91 There is also a 3-argument version of "open", which lets you put the
92 special redirection characters into their own argument:
93
94 open( INFO, ">", $datafile ) ⎪⎪ die "Can't create $datafile: $!";
95
96 In this case, the filename to open is the actual string in $datafile,
97 so you don't have to worry about $datafile containing characters that
98 might influence the open mode, or whitespace at the beginning of the
99 filename that would be absorbed in the 2-argument version. Also, any
100 reduction of unnecessary string interpolation is a good thing.
101
102 Indirect Filehandles
103
104 "open"'s first argument can be a reference to a filehandle. As of perl
105 5.6.0, if the argument is uninitialized, Perl will automatically create
106 a filehandle and put a reference to it in the first argument, like so:
107
108 open( my $in, $infile ) or die "Couldn't read $infile: $!";
109 while ( <$in> ) {
110 # do something with $_
111 }
112 close $in;
113
114 Indirect filehandles make namespace management easier. Since filehan‐
115 dles are global to the current package, two subroutines trying to open
116 "INFILE" will clash. With two functions opening indirect filehandles
117 like "my $infile", there's no clash and no need to worry about future
118 conflicts.
119
120 Another convenient behavior is that an indirect filehandle automati‐
121 cally closes when it goes out of scope or when you undefine it:
122
123 sub firstline {
124 open( my $in, shift ) && return scalar <$in>;
125 # no close() required
126 }
127
128 Pipe Opens
129
130 In C, when you want to open a file using the standard I/O library, you
131 use the "fopen" function, but when opening a pipe, you use the "popen"
132 function. But in the shell, you just use a different redirection char‐
133 acter. That's also the case for Perl. The "open" call remains the
134 same--just its argument differs.
135
136 If the leading character is a pipe symbol, "open" starts up a new com‐
137 mand and opens a write-only filehandle leading into that command. This
138 lets you write into that handle and have what you write show up on that
139 command's standard input. For example:
140
141 open(PRINTER, "⎪ lpr -Plp1") ⎪⎪ die "can't run lpr: $!";
142 print PRINTER "stuff\n";
143 close(PRINTER) ⎪⎪ die "can't close lpr: $!";
144
145 If the trailing character is a pipe, you start up a new command and
146 open a read-only filehandle leading out of that command. This lets
147 whatever that command writes to its standard output show up on your
148 handle for reading. For example:
149
150 open(NET, "netstat -i -n ⎪") ⎪⎪ die "can't fork netstat: $!";
151 while (<NET>) { } # do something with input
152 close(NET) ⎪⎪ die "can't close netstat: $!";
153
154 What happens if you try to open a pipe to or from a non-existent com‐
155 mand? If possible, Perl will detect the failure and set $! as usual.
156 But if the command contains special shell characters, such as ">" or
157 "*", called 'metacharacters', Perl does not execute the command
158 directly. Instead, Perl runs the shell, which then tries to run the
159 command. This means that it's the shell that gets the error indica‐
160 tion. In such a case, the "open" call will only indicate failure if
161 Perl can't even run the shell. See "How can I capture STDERR from an
162 external command?" in perlfaq8 to see how to cope with this. There's
163 also an explanation in perlipc.
164
165 If you would like to open a bidirectional pipe, the IPC::Open2 library
166 will handle this for you. Check out "Bidirectional Communication with
167 Another Process" in perlipc
168
169 The Minus File
170
171 Again following the lead of the standard shell utilities, Perl's "open"
172 function treats a file whose name is a single minus, "-", in a special
173 way. If you open minus for reading, it really means to access the
174 standard input. If you open minus for writing, it really means to
175 access the standard output.
176
177 If minus can be used as the default input or default output, what hap‐
178 pens if you open a pipe into or out of minus? What's the default com‐
179 mand it would run? The same script as you're currently running! This
180 is actually a stealth "fork" hidden inside an "open" call. See "Safe
181 Pipe Opens" in perlipc for details.
182
183 Mixing Reads and Writes
184
185 It is possible to specify both read and write access. All you do is
186 add a "+" symbol in front of the redirection. But as in the shell,
187 using a less-than on a file never creates a new file; it only opens an
188 existing one. On the other hand, using a greater-than always clobbers
189 (truncates to zero length) an existing file, or creates a brand-new one
190 if there isn't an old one. Adding a "+" for read-write doesn't affect
191 whether it only works on existing files or always clobbers existing
192 ones.
193
194 open(WTMP, "+< /usr/adm/wtmp")
195 ⎪⎪ die "can't open /usr/adm/wtmp: $!";
196
197 open(SCREEN, "+> lkscreen")
198 ⎪⎪ die "can't open lkscreen: $!";
199
200 open(LOGFILE, "+>> /var/log/applog"
201 ⎪⎪ die "can't open /var/log/applog: $!";
202
203 The first one won't create a new file, and the second one will always
204 clobber an old one. The third one will create a new file if necessary
205 and not clobber an old one, and it will allow you to read at any point
206 in the file, but all writes will always go to the end. In short, the
207 first case is substantially more common than the second and third
208 cases, which are almost always wrong. (If you know C, the plus in
209 Perl's "open" is historically derived from the one in C's fopen(3S),
210 which it ultimately calls.)
211
212 In fact, when it comes to updating a file, unless you're working on a
213 binary file as in the WTMP case above, you probably don't want to use
214 this approach for updating. Instead, Perl's -i flag comes to the res‐
215 cue. The following command takes all the C, C++, or yacc source or
216 header files and changes all their foo's to bar's, leaving the old ver‐
217 sion in the original filename with a ".orig" tacked on the end:
218
219 $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]
220
221 This is a short cut for some renaming games that are really the best
222 way to update textfiles. See the second question in perlfaq5 for more
223 details.
224
225 Filters
226
227 One of the most common uses for "open" is one you never even notice.
228 When you process the ARGV filehandle using "<ARGV>", Perl actually does
229 an implicit open on each file in @ARGV. Thus a program called like
230 this:
231
232 $ myprogram file1 file2 file3
233
234 Can have all its files opened and processed one at a time using a con‐
235 struct no more complex than:
236
237 while (<>) {
238 # do something with $_
239 }
240
241 If @ARGV is empty when the loop first begins, Perl pretends you've
242 opened up minus, that is, the standard input. In fact, $ARGV, the cur‐
243 rently open file during "<ARGV>" processing, is even set to "-" in
244 these circumstances.
245
246 You are welcome to pre-process your @ARGV before starting the loop to
247 make sure it's to your liking. One reason to do this might be to
248 remove command options beginning with a minus. While you can always
249 roll the simple ones by hand, the Getopts modules are good for this:
250
251 use Getopt::Std;
252
253 # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
254 getopts("vDo:");
255
256 # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
257 getopts("vDo:", \%args);
258
259 Or the standard Getopt::Long module to permit named arguments:
260
261 use Getopt::Long;
262 GetOptions( "verbose" => \$verbose, # --verbose
263 "Debug" => \$debug, # --Debug
264 "output=s" => \$output );
265 # --output=somestring or --output somestring
266
267 Another reason for preprocessing arguments is to make an empty argument
268 list default to all files:
269
270 @ARGV = glob("*") unless @ARGV;
271
272 You could even filter out all but plain, text files. This is a bit
273 silent, of course, and you might prefer to mention them on the way.
274
275 @ARGV = grep { -f && -T } @ARGV;
276
277 If you're using the -n or -p command-line options, you should put
278 changes to @ARGV in a "BEGIN{}" block.
279
280 Remember that a normal "open" has special properties, in that it might
281 call fopen(3S) or it might called popen(3S), depending on what its
282 argument looks like; that's why it's sometimes called "magic open".
283 Here's an example:
284
285 $pwdinfo = `domainname` =~ /^(\(none\))?$/
286 ? '< /etc/passwd'
287 : 'ypcat passwd ⎪';
288
289 open(PWD, $pwdinfo)
290 or die "can't open $pwdinfo: $!";
291
292 This sort of thing also comes into play in filter processing. Because
293 "<ARGV>" processing employs the normal, shell-style Perl "open", it
294 respects all the special things we've already seen:
295
296 $ myprogram f1 "cmd1⎪" - f2 "cmd2⎪" f3 < tmpfile
297
298 That program will read from the file f1, the process cmd1, standard
299 input (tmpfile in this case), the f2 file, the cmd2 command, and
300 finally the f3 file.
301
302 Yes, this also means that if you have files named "-" (and so on) in
303 your directory, they won't be processed as literal files by "open".
304 You'll need to pass them as "./-", much as you would for the rm pro‐
305 gram, or you could use "sysopen" as described below.
306
307 One of the more interesting applications is to change files of a cer‐
308 tain name into pipes. For example, to autoprocess gzipped or com‐
309 pressed files by decompressing them with gzip:
310
311 @ARGV = map { /^\.(gz⎪Z)$/ ? "gzip -dc $_ ⎪" : $_ } @ARGV;
312
313 Or, if you have the GET program installed from LWP, you can fetch URLs
314 before processing them:
315
316 @ARGV = map { m#^\w+://# ? "GET $_ ⎪" : $_ } @ARGV;
317
318 It's not for nothing that this is called magic "<ARGV>". Pretty nifty,
319 eh?
320
322 If you want the convenience of the shell, then Perl's "open" is defi‐
323 nitely the way to go. On the other hand, if you want finer precision
324 than C's simplistic fopen(3S) provides you should look to Perl's
325 "sysopen", which is a direct hook into the open(2) system call. That
326 does mean it's a bit more involved, but that's the price of precision.
327
328 "sysopen" takes 3 (or 4) arguments.
329
330 sysopen HANDLE, PATH, FLAGS, [MASK]
331
332 The HANDLE argument is a filehandle just as with "open". The PATH is a
333 literal path, one that doesn't pay attention to any greater-thans or
334 less-thans or pipes or minuses, nor ignore whitespace. If it's there,
335 it's part of the path. The FLAGS argument contains one or more values
336 derived from the Fcntl module that have been or'd together using the
337 bitwise "⎪" operator. The final argument, the MASK, is optional; if
338 present, it is combined with the user's current umask for the creation
339 mode of the file. You should usually omit this.
340
341 Although the traditional values of read-only, write-only, and read-
342 write are 0, 1, and 2 respectively, this is known not to hold true on
343 some systems. Instead, it's best to load in the appropriate constants
344 first from the Fcntl module, which supplies the following standard
345 flags:
346
347 O_RDONLY Read only
348 O_WRONLY Write only
349 O_RDWR Read and write
350 O_CREAT Create the file if it doesn't exist
351 O_EXCL Fail if the file already exists
352 O_APPEND Append to the file
353 O_TRUNC Truncate the file
354 O_NONBLOCK Non-blocking access
355
356 Less common flags that are sometimes available on some operating sys‐
357 tems include "O_BINARY", "O_TEXT", "O_SHLOCK", "O_EXLOCK", "O_DEFER",
358 "O_SYNC", "O_ASYNC", "O_DSYNC", "O_RSYNC", "O_NOCTTY", "O_NDELAY" and
359 "O_LARGEFILE". Consult your open(2) manpage or its local equivalent
360 for details. (Note: starting from Perl release 5.6 the "O_LARGEFILE"
361 flag, if available, is automatically added to the sysopen() flags
362 because large files are the default.)
363
364 Here's how to use "sysopen" to emulate the simple "open" calls we had
365 before. We'll omit the "⎪⎪ die $!" checks for clarity, but make sure
366 you always check the return values in real code. These aren't quite
367 the same, since "open" will trim leading and trailing whitespace, but
368 you'll get the idea.
369
370 To open a file for reading:
371
372 open(FH, "< $path");
373 sysopen(FH, $path, O_RDONLY);
374
375 To open a file for writing, creating a new file if needed or else trun‐
376 cating an old file:
377
378 open(FH, "> $path");
379 sysopen(FH, $path, O_WRONLY ⎪ O_TRUNC ⎪ O_CREAT);
380
381 To open a file for appending, creating one if necessary:
382
383 open(FH, ">> $path");
384 sysopen(FH, $path, O_WRONLY ⎪ O_APPEND ⎪ O_CREAT);
385
386 To open a file for update, where the file must already exist:
387
388 open(FH, "+< $path");
389 sysopen(FH, $path, O_RDWR);
390
391 And here are things you can do with "sysopen" that you cannot do with a
392 regular "open". As you'll see, it's just a matter of controlling the
393 flags in the third argument.
394
395 To open a file for writing, creating a new file which must not previ‐
396 ously exist:
397
398 sysopen(FH, $path, O_WRONLY ⎪ O_EXCL ⎪ O_CREAT);
399
400 To open a file for appending, where that file must already exist:
401
402 sysopen(FH, $path, O_WRONLY ⎪ O_APPEND);
403
404 To open a file for update, creating a new file if necessary:
405
406 sysopen(FH, $path, O_RDWR ⎪ O_CREAT);
407
408 To open a file for update, where that file must not already exist:
409
410 sysopen(FH, $path, O_RDWR ⎪ O_EXCL ⎪ O_CREAT);
411
412 To open a file without blocking, creating one if necessary:
413
414 sysopen(FH, $path, O_WRONLY ⎪ O_NONBLOCK ⎪ O_CREAT);
415
416 Permissions A la mode
417
418 If you omit the MASK argument to "sysopen", Perl uses the octal value
419 0666. The normal MASK to use for executables and directories should be
420 0777, and for anything else, 0666.
421
422 Why so permissive? Well, it isn't really. The MASK will be modified
423 by your process's current "umask". A umask is a number representing
424 disabled permissions bits; that is, bits that will not be turned on in
425 the created files' permissions field.
426
427 For example, if your "umask" were 027, then the 020 part would disable
428 the group from writing, and the 007 part would disable others from
429 reading, writing, or executing. Under these conditions, passing
430 "sysopen" 0666 would create a file with mode 0640, since "0666 & ~027"
431 is 0640.
432
433 You should seldom use the MASK argument to "sysopen()". That takes
434 away the user's freedom to choose what permission new files will have.
435 Denying choice is almost always a bad thing. One exception would be
436 for cases where sensitive or private data is being stored, such as with
437 mail folders, cookie files, and internal temporary files.
438
440 Re-Opening Files (dups)
441
442 Sometimes you already have a filehandle open, and want to make another
443 handle that's a duplicate of the first one. In the shell, we place an
444 ampersand in front of a file descriptor number when doing redirections.
445 For example, "2>&1" makes descriptor 2 (that's STDERR in Perl) be redi‐
446 rected into descriptor 1 (which is usually Perl's STDOUT). The same is
447 essentially true in Perl: a filename that begins with an ampersand is
448 treated instead as a file descriptor if a number, or as a filehandle if
449 a string.
450
451 open(SAVEOUT, ">&SAVEERR") ⎪⎪ die "couldn't dup SAVEERR: $!";
452 open(MHCONTEXT, "<&4") ⎪⎪ die "couldn't dup fd4: $!";
453
454 That means that if a function is expecting a filename, but you don't
455 want to give it a filename because you already have the file open, you
456 can just pass the filehandle with a leading ampersand. It's best to
457 use a fully qualified handle though, just in case the function happens
458 to be in a different package:
459
460 somefunction("&main::LOGFILE");
461
462 This way if somefunction() is planning on opening its argument, it can
463 just use the already opened handle. This differs from passing a han‐
464 dle, because with a handle, you don't open the file. Here you have
465 something you can pass to open.
466
467 If you have one of those tricky, newfangled I/O objects that the C++
468 folks are raving about, then this doesn't work because those aren't a
469 proper filehandle in the native Perl sense. You'll have to use
470 fileno() to pull out the proper descriptor number, assuming you can:
471
472 use IO::Socket;
473 $handle = IO::Socket::INET->new("www.perl.com:80");
474 $fd = $handle->fileno;
475 somefunction("&$fd"); # not an indirect function call
476
477 It can be easier (and certainly will be faster) just to use real file‐
478 handles though:
479
480 use IO::Socket;
481 local *REMOTE = IO::Socket::INET->new("www.perl.com:80");
482 die "can't connect" unless defined(fileno(REMOTE));
483 somefunction("&main::REMOTE");
484
485 If the filehandle or descriptor number is preceded not just with a sim‐
486 ple "&" but rather with a "&=" combination, then Perl will not create a
487 completely new descriptor opened to the same place using the dup(2)
488 system call. Instead, it will just make something of an alias to the
489 existing one using the fdopen(3S) library call This is slightly more
490 parsimonious of systems resources, although this is less a concern
491 these days. Here's an example of that:
492
493 $fd = $ENV{"MHCONTEXTFD"};
494 open(MHCONTEXT, "<&=$fd") or die "couldn't fdopen $fd: $!";
495
496 If you're using magic "<ARGV>", you could even pass in as a command
497 line argument in @ARGV something like "<&=$MHCONTEXTFD", but we've
498 never seen anyone actually do this.
499
500 Dispelling the Dweomer
501
502 Perl is more of a DWIMmer language than something like Java--where DWIM
503 is an acronym for "do what I mean". But this principle sometimes leads
504 to more hidden magic than one knows what to do with. In this way, Perl
505 is also filled with dweomer, an obscure word meaning an enchantment.
506 Sometimes, Perl's DWIMmer is just too much like dweomer for comfort.
507
508 If magic "open" is a bit too magical for you, you don't have to turn to
509 "sysopen". To open a file with arbitrary weird characters in it, it's
510 necessary to protect any leading and trailing whitespace. Leading
511 whitespace is protected by inserting a "./" in front of a filename that
512 starts with whitespace. Trailing whitespace is protected by appending
513 an ASCII NUL byte ("\0") at the end of the string.
514
515 $file =~ s#^(\s)#./$1#;
516 open(FH, "< $file\0") ⎪⎪ die "can't open $file: $!";
517
518 This assumes, of course, that your system considers dot the current
519 working directory, slash the directory separator, and disallows ASCII
520 NULs within a valid filename. Most systems follow these conventions,
521 including all POSIX systems as well as proprietary Microsoft systems.
522 The only vaguely popular system that doesn't work this way is the
523 "Classic" Macintosh system, which uses a colon where the rest of us use
524 a slash. Maybe "sysopen" isn't such a bad idea after all.
525
526 If you want to use "<ARGV>" processing in a totally boring and non-mag‐
527 ical way, you could do this first:
528
529 # "Sam sat on the ground and put his head in his hands.
530 # 'I wish I had never come here, and I don't want to see
531 # no more magic,' he said, and fell silent."
532 for (@ARGV) {
533 s#^([^./])#./$1#;
534 $_ .= "\0";
535 }
536 while (<>) {
537 # now process $_
538 }
539
540 But be warned that users will not appreciate being unable to use "-" to
541 mean standard input, per the standard convention.
542
543 Paths as Opens
544
545 You've probably noticed how Perl's "warn" and "die" functions can pro‐
546 duce messages like:
547
548 Some warning at scriptname line 29, <FH> line 7.
549
550 That's because you opened a filehandle FH, and had read in seven
551 records from it. But what was the name of the file, rather than the
552 handle?
553
554 If you aren't running with "strict refs", or if you've turned them off
555 temporarily, then all you have to do is this:
556
557 open($path, "< $path") ⎪⎪ die "can't open $path: $!";
558 while (<$path>) {
559 # whatever
560 }
561
562 Since you're using the pathname of the file as its handle, you'll get
563 warnings more like
564
565 Some warning at scriptname line 29, </etc/motd> line 7.
566
567 Single Argument Open
568
569 Remember how we said that Perl's open took two arguments? That was a
570 passive prevarication. You see, it can also take just one argument.
571 If and only if the variable is a global variable, not a lexical, you
572 can pass "open" just one argument, the filehandle, and it will get the
573 path from the global scalar variable of the same name.
574
575 $FILE = "/etc/motd";
576 open FILE or die "can't open $FILE: $!";
577 while (<FILE>) {
578 # whatever
579 }
580
581 Why is this here? Someone has to cater to the hysterical porpoises.
582 It's something that's been in Perl since the very beginning, if not
583 before.
584
585 Playing with STDIN and STDOUT
586
587 One clever move with STDOUT is to explicitly close it when you're done
588 with the program.
589
590 END { close(STDOUT) ⎪⎪ die "can't close stdout: $!" }
591
592 If you don't do this, and your program fills up the disk partition due
593 to a command line redirection, it won't report the error exit with a
594 failure status.
595
596 You don't have to accept the STDIN and STDOUT you were given. You are
597 welcome to reopen them if you'd like.
598
599 open(STDIN, "< datafile")
600 ⎪⎪ die "can't open datafile: $!";
601
602 open(STDOUT, "> output")
603 ⎪⎪ die "can't open output: $!";
604
605 And then these can be accessed directly or passed on to subprocesses.
606 This makes it look as though the program were initially invoked with
607 those redirections from the command line.
608
609 It's probably more interesting to connect these to pipes. For example:
610
611 $pager = $ENV{PAGER} ⎪⎪ "(less ⎪⎪ more)";
612 open(STDOUT, "⎪ $pager")
613 ⎪⎪ die "can't fork a pager: $!";
614
615 This makes it appear as though your program were called with its stdout
616 already piped into your pager. You can also use this kind of thing in
617 conjunction with an implicit fork to yourself. You might do this if
618 you would rather handle the post processing in your own program, just
619 in a different process:
620
621 head(100);
622 while (<>) {
623 print;
624 }
625
626 sub head {
627 my $lines = shift ⎪⎪ 20;
628 return if $pid = open(STDOUT, "⎪-"); # return if parent
629 die "cannot fork: $!" unless defined $pid;
630 while (<STDIN>) {
631 last if --$lines < 0;
632 print;
633 }
634 exit;
635 }
636
637 This technique can be applied to repeatedly push as many filters on
638 your output stream as you wish.
639
641 These topics aren't really arguments related to "open" or "sysopen",
642 but they do affect what you do with your open files.
643
644 Opening Non-File Files
645
646 When is a file not a file? Well, you could say when it exists but
647 isn't a plain file. We'll check whether it's a symbolic link first,
648 just in case.
649
650 if (-l $file ⎪⎪ ! -f _) {
651 print "$file is not a plain file\n";
652 }
653
654 What other kinds of files are there than, well, files? Directories,
655 symbolic links, named pipes, Unix-domain sockets, and block and charac‐
656 ter devices. Those are all files, too--just not plain files. This
657 isn't the same issue as being a text file. Not all text files are plain
658 files. Not all plain files are text files. That's why there are sepa‐
659 rate "-f" and "-T" file tests.
660
661 To open a directory, you should use the "opendir" function, then
662 process it with "readdir", carefully restoring the directory name if
663 necessary:
664
665 opendir(DIR, $dirname) or die "can't opendir $dirname: $!";
666 while (defined($file = readdir(DIR))) {
667 # do something with "$dirname/$file"
668 }
669 closedir(DIR);
670
671 If you want to process directories recursively, it's better to use the
672 File::Find module. For example, this prints out all files recursively
673 and adds a slash to their names if the file is a directory.
674
675 @ARGV = qw(.) unless @ARGV;
676 use File::Find;
677 find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;
678
679 This finds all bogus symbolic links beneath a particular directory:
680
681 find sub { print "$File::Find::name\n" if -l && !-e }, $dir;
682
683 As you see, with symbolic links, you can just pretend that it is what
684 it points to. Or, if you want to know what it points to, then "read‐
685 link" is called for:
686
687 if (-l $file) {
688 if (defined($whither = readlink($file))) {
689 print "$file points to $whither\n";
690 } else {
691 print "$file points nowhere: $!\n";
692 }
693 }
694
695 Opening Named Pipes
696
697 Named pipes are a different matter. You pretend they're regular files,
698 but their opens will normally block until there is both a reader and a
699 writer. You can read more about them in "Named Pipes" in perlipc.
700 Unix-domain sockets are rather different beasts as well; they're
701 described in "Unix-Domain TCP Clients and Servers" in perlipc.
702
703 When it comes to opening devices, it can be easy and it can be tricky.
704 We'll assume that if you're opening up a block device, you know what
705 you're doing. The character devices are more interesting. These are
706 typically used for modems, mice, and some kinds of printers. This is
707 described in "How do I read and write the serial port?" in perlfaq8
708 It's often enough to open them carefully:
709
710 sysopen(TTYIN, "/dev/ttyS1", O_RDWR ⎪ O_NDELAY ⎪ O_NOCTTY)
711 # (O_NOCTTY no longer needed on POSIX systems)
712 or die "can't open /dev/ttyS1: $!";
713 open(TTYOUT, "+>&TTYIN")
714 or die "can't dup TTYIN: $!";
715
716 $ofh = select(TTYOUT); $⎪ = 1; select($ofh);
717
718 print TTYOUT "+++at\015";
719 $answer = <TTYIN>;
720
721 With descriptors that you haven't opened using "sysopen", such as sock‐
722 ets, you can set them to be non-blocking using "fcntl":
723
724 use Fcntl;
725 my $old_flags = fcntl($handle, F_GETFL, 0)
726 or die "can't get flags: $!";
727 fcntl($handle, F_SETFL, $old_flags ⎪ O_NONBLOCK)
728 or die "can't set non blocking: $!";
729
730 Rather than losing yourself in a morass of twisting, turning "ioctl"s,
731 all dissimilar, if you're going to manipulate ttys, it's best to make
732 calls out to the stty(1) program if you have it, or else use the porta‐
733 ble POSIX interface. To figure this all out, you'll need to read the
734 termios(3) manpage, which describes the POSIX interface to tty devices,
735 and then POSIX, which describes Perl's interface to POSIX. There are
736 also some high-level modules on CPAN that can help you with these
737 games. Check out Term::ReadKey and Term::ReadLine.
738
739 Opening Sockets
740
741 What else can you open? To open a connection using sockets, you won't
742 use one of Perl's two open functions. See "Sockets: Client/Server Com‐
743 munication" in perlipc for that. Here's an example. Once you have it,
744 you can use FH as a bidirectional filehandle.
745
746 use IO::Socket;
747 local *FH = IO::Socket::INET->new("www.perl.com:80");
748
749 For opening up a URL, the LWP modules from CPAN are just what the doc‐
750 tor ordered. There's no filehandle interface, but it's still easy to
751 get the contents of a document:
752
753 use LWP::Simple;
754 $doc = get('http://www.linpro.no/lwp/');
755
756 Binary Files
757
758 On certain legacy systems with what could charitably be called termi‐
759 nally convoluted (some would say broken) I/O models, a file isn't a
760 file--at least, not with respect to the C standard I/O library. On
761 these old systems whose libraries (but not kernels) distinguish between
762 text and binary streams, to get files to behave properly you'll have to
763 bend over backwards to avoid nasty problems. On such infelicitous sys‐
764 tems, sockets and pipes are already opened in binary mode, and there is
765 currently no way to turn that off. With files, you have more options.
766
767 Another option is to use the "binmode" function on the appropriate han‐
768 dles before doing regular I/O on them:
769
770 binmode(STDIN);
771 binmode(STDOUT);
772 while (<STDIN>) { print }
773
774 Passing "sysopen" a non-standard flag option will also open the file in
775 binary mode on those systems that support it. This is the equivalent
776 of opening the file normally, then calling "binmode" on the handle.
777
778 sysopen(BINDAT, "records.data", O_RDWR ⎪ O_BINARY)
779 ⎪⎪ die "can't open records.data: $!";
780
781 Now you can use "read" and "print" on that handle without worrying
782 about the non-standard system I/O library breaking your data. It's not
783 a pretty picture, but then, legacy systems seldom are. CP/M will be
784 with us until the end of days, and after.
785
786 On systems with exotic I/O systems, it turns out that, astonishingly
787 enough, even unbuffered I/O using "sysread" and "syswrite" might do
788 sneaky data mutilation behind your back.
789
790 while (sysread(WHENCE, $buf, 1024)) {
791 syswrite(WHITHER, $buf, length($buf));
792 }
793
794 Depending on the vicissitudes of your runtime system, even these calls
795 may need "binmode" or "O_BINARY" first. Systems known to be free of
796 such difficulties include Unix, the Mac OS, Plan 9, and Inferno.
797
798 File Locking
799
800 In a multitasking environment, you may need to be careful not to col‐
801 lide with other processes who want to do I/O on the same files as you
802 are working on. You'll often need shared or exclusive locks on files
803 for reading and writing respectively. You might just pretend that only
804 exclusive locks exist.
805
806 Never use the existence of a file "-e $file" as a locking indication,
807 because there is a race condition between the test for the existence of
808 the file and its creation. It's possible for another process to create
809 a file in the slice of time between your existence check and your
810 attempt to create the file. Atomicity is critical.
811
812 Perl's most portable locking interface is via the "flock" function,
813 whose simplicity is emulated on systems that don't directly support it
814 such as SysV or Windows. The underlying semantics may affect how it
815 all works, so you should learn how "flock" is implemented on your sys‐
816 tem's port of Perl.
817
818 File locking does not lock out another process that would like to do
819 I/O. A file lock only locks out others trying to get a lock, not pro‐
820 cesses trying to do I/O. Because locks are advisory, if one process
821 uses locking and another doesn't, all bets are off.
822
823 By default, the "flock" call will block until a lock is granted. A
824 request for a shared lock will be granted as soon as there is no exclu‐
825 sive locker. A request for an exclusive lock will be granted as soon
826 as there is no locker of any kind. Locks are on file descriptors, not
827 file names. You can't lock a file until you open it, and you can't
828 hold on to a lock once the file has been closed.
829
830 Here's how to get a blocking shared lock on a file, typically used for
831 reading:
832
833 use 5.004;
834 use Fcntl qw(:DEFAULT :flock);
835 open(FH, "< filename") or die "can't open filename: $!";
836 flock(FH, LOCK_SH) or die "can't lock filename: $!";
837 # now read from FH
838
839 You can get a non-blocking lock by using "LOCK_NB".
840
841 flock(FH, LOCK_SH ⎪ LOCK_NB)
842 or die "can't lock filename: $!";
843
844 This can be useful for producing more user-friendly behaviour by warn‐
845 ing if you're going to be blocking:
846
847 use 5.004;
848 use Fcntl qw(:DEFAULT :flock);
849 open(FH, "< filename") or die "can't open filename: $!";
850 unless (flock(FH, LOCK_SH ⎪ LOCK_NB)) {
851 $⎪ = 1;
852 print "Waiting for lock...";
853 flock(FH, LOCK_SH) or die "can't lock filename: $!";
854 print "got it.\n"
855 }
856 # now read from FH
857
858 To get an exclusive lock, typically used for writing, you have to be
859 careful. We "sysopen" the file so it can be locked before it gets emp‐
860 tied. You can get a nonblocking version using "LOCK_EX ⎪ LOCK_NB".
861
862 use 5.004;
863 use Fcntl qw(:DEFAULT :flock);
864 sysopen(FH, "filename", O_WRONLY ⎪ O_CREAT)
865 or die "can't open filename: $!";
866 flock(FH, LOCK_EX)
867 or die "can't lock filename: $!";
868 truncate(FH, 0)
869 or die "can't truncate filename: $!";
870 # now write to FH
871
872 Finally, due to the uncounted millions who cannot be dissuaded from
873 wasting cycles on useless vanity devices called hit counters, here's
874 how to increment a number in a file safely:
875
876 use Fcntl qw(:DEFAULT :flock);
877
878 sysopen(FH, "numfile", O_RDWR ⎪ O_CREAT)
879 or die "can't open numfile: $!";
880 # autoflush FH
881 $ofh = select(FH); $⎪ = 1; select ($ofh);
882 flock(FH, LOCK_EX)
883 or die "can't write-lock numfile: $!";
884
885 $num = <FH> ⎪⎪ 0;
886 seek(FH, 0, 0)
887 or die "can't rewind numfile : $!";
888 print FH $num+1, "\n"
889 or die "can't write numfile: $!";
890
891 truncate(FH, tell(FH))
892 or die "can't truncate numfile: $!";
893 close(FH)
894 or die "can't close numfile: $!";
895
896 IO Layers
897
898 In Perl 5.8.0 a new I/O framework called "PerlIO" was introduced. This
899 is a new "plumbing" for all the I/O happening in Perl; for the most
900 part everything will work just as it did, but PerlIO also brought in
901 some new features such as the ability to think of I/O as "layers". One
902 I/O layer may in addition to just moving the data also do transforma‐
903 tions on the data. Such transformations may include compression and
904 decompression, encryption and decryption, and transforming between var‐
905 ious character encodings.
906
907 Full discussion about the features of PerlIO is out of scope for this
908 tutorial, but here is how to recognize the layers being used:
909
910 · The three-(or more)-argument form of "open" is being used and the
911 second argument contains something else in addition to the usual
912 '<', '>', '>>', '⎪' and their variants, for example:
913
914 open(my $fh, "<:utf8", $fn);
915
916 · The two-argument form of "binmode" is being used, for example
917
918 binmode($fh, ":encoding(utf16)");
919
920 For more detailed discussion about PerlIO see PerlIO; for more detailed
921 discussion about Unicode and I/O see perluniintro.
922
924 The "open" and "sysopen" functions in perlfunc(1); the system open(2),
925 dup(2), fopen(3), and fdopen(3) manpages; the POSIX documentation.
926
928 Copyright 1998 Tom Christiansen.
929
930 This documentation is free; you can redistribute it and/or modify it
931 under the same terms as Perl itself.
932
933 Irrespective of its distribution, all code examples in these files are
934 hereby placed into the public domain. You are permitted and encouraged
935 to use this code in your own programs for fun or for profit as you see
936 fit. A simple comment in the code giving credit would be courteous but
937 is not required.
938
940 First release: Sat Jan 9 08:09:11 MST 1999
941
942
943
944perl v5.8.8 2006-01-07 PERLOPENTUT(1)