1PERLOPENTUT(1) Perl Programmers Reference Guide PERLOPENTUT(1)
2
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 $ myprogram file1 file2 file3
20 $ myprogram < inputfile
21 $ myprogram > outputfile
22 $ myprogram >> outputfile
23 $ myprogram ⎪ otherprogram
24 $ otherprogram ⎪ myprogram
25 And here are some more advanced examples:
27 $ otherprogram ⎪ myprogram f1 - f2
29 $ otherprogram 2>&1 ⎪ myprogram -
30 $ myprogram <&3
31 $ myprogram >&4
32 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 Simple Opens
38 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 For example:
47 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 If you prefer the low-punctuation version, you could write that this
54 way:
55 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 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 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 open INFO, ( "< datafile" ⎪⎪ die "can't open datafile: $!" );
68 which is definitely not what you want.
70 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 open INFO, "<datafile"
76 open INFO, "< datafile"
77 open INFO, "< datafile"
78 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 $filename = <INFO>; # oops, \n still there
83 open(EXTRA, "< $filename") ⎪⎪ die "can't open $filename: $!";
84 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 There is also a 3-argument version of "open", which lets you put the
92 special redirection characters into their own argument:
93 open( INFO, ">", $datafile ) ⎪⎪ die "Can't create $datafile: $!";
95 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 Indirect Filehandles
103 "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 open( my $in, $infile ) or die "Couldn't read $infile: $!";
109 while ( <$in> ) {
110 # do something with $_
111 }
112 close $in;
113 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 Another convenient behavior is that an indirect filehandle automati‐
121 cally closes when it goes out of scope or when you undefine it:
122 sub firstline {
124 open( my $in, shift ) && return scalar <$in>;
125 # no close() required
126 }
127 Pipe Opens
129 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 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 open(PRINTER, "⎪ lpr -Plp1") ⎪⎪ die "can't run lpr: $!";
142 print PRINTER "stuff\n";
143 close(PRINTER) ⎪⎪ die "can't close lpr: $!";
144 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 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 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 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 The Minus File
170 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 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 Mixing Reads and Writes
184 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 open(WTMP, "+< /usr/adm/wtmp")
195 ⎪⎪ die "can't open /usr/adm/wtmp: $!";
196 open(SCREEN, "+> lkscreen")
198 ⎪⎪ die "can't open lkscreen: $!";
199 open(LOGFILE, "+>> /var/log/applog"
201 ⎪⎪ die "can't open /var/log/applog: $!";
202 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 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 $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]
220 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 Filters
226 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 $ myprogram file1 file2 file3
233 Can have all its files opened and processed one at a time using a con‐
235 struct no more complex than:
236 while (<>) {
238 # do something with $_
239 }
240 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 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 use Getopt::Std;
252 # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
254 getopts("vDo:");
255 # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
257 getopts("vDo:", \%args);
258 Or the standard Getopt::Long module to permit named arguments:
260 use Getopt::Long;
262 GetOptions( "verbose" => \$verbose, # --verbose
263 "Debug" => \$debug, # --Debug
264 "output=s" => \$output );
265 # --output=somestring or --output somestring
266 Another reason for preprocessing arguments is to make an empty argument
268 list default to all files:
269 @ARGV = glob("*") unless @ARGV;
271 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 @ARGV = grep { -f && -T } @ARGV;
276 If you're using the -n or -p command-line options, you should put
278 changes to @ARGV in a "BEGIN{}" block.
279 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 $pwdinfo = `domainname` =~ /^(\(none\))?$/
286 ? '< /etc/passwd'
287 : 'ypcat passwd ⎪';
288 open(PWD, $pwdinfo)
290 or die "can't open $pwdinfo: $!";
291 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 $ myprogram f1 "cmd1⎪" - f2 "cmd2⎪" f3 < tmpfile
297 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 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 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 @ARGV = map { /^\.(gz⎪Z)$/ ? "gzip -dc $_ ⎪" : $_ } @ARGV;
312 Or, if you have the GET program installed from LWP, you can fetch URLs
314 before processing them:
315 @ARGV = map { m#^\w+://# ? "GET $_ ⎪" : $_ } @ARGV;
317 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 "sysopen" takes 3 (or 4) arguments.
329 sysopen HANDLE, PATH, FLAGS, [MASK]
331 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 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 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 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 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 To open a file for reading:
371 open(FH, "< $path");
373 sysopen(FH, $path, O_RDONLY);
374 To open a file for writing, creating a new file if needed or else trun‐
376 cating an old file:
377 open(FH, "> $path");
379 sysopen(FH, $path, O_WRONLY ⎪ O_TRUNC ⎪ O_CREAT);
380 To open a file for appending, creating one if necessary:
382 open(FH, ">> $path");
384 sysopen(FH, $path, O_WRONLY ⎪ O_APPEND ⎪ O_CREAT);
385 To open a file for update, where the file must already exist:
387 open(FH, "+< $path");
389 sysopen(FH, $path, O_RDWR);
390 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 To open a file for writing, creating a new file which must not previ‐
396 ously exist:
397 sysopen(FH, $path, O_WRONLY ⎪ O_EXCL ⎪ O_CREAT);
399 To open a file for appending, where that file must already exist:
401 sysopen(FH, $path, O_WRONLY ⎪ O_APPEND);
403 To open a file for update, creating a new file if necessary:
405 sysopen(FH, $path, O_RDWR ⎪ O_CREAT);
407 To open a file for update, where that file must not already exist:
409 sysopen(FH, $path, O_RDWR ⎪ O_EXCL ⎪ O_CREAT);
411 To open a file without blocking, creating one if necessary:
413 sysopen(FH, $path, O_WRONLY ⎪ O_NONBLOCK ⎪ O_CREAT);
415 Permissions A la mode
417 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 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 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 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 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 open(SAVEOUT, ">&SAVEERR") ⎪⎪ die "couldn't dup SAVEERR: $!";
452 open(MHCONTEXT, "<&4") ⎪⎪ die "couldn't dup fd4: $!";
453 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 somefunction("&main::LOGFILE");
461 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 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 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 It can be easier (and certainly will be faster) just to use real file‐
478 handles though:
479 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 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 $fd = $ENV{"MHCONTEXTFD"};
494 open(MHCONTEXT, "<&=$fd") or die "couldn't fdopen $fd: $!";
495 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 Dispelling the Dweomer
501 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 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 $file =~ s#^(\s)#./$1#;
516 open(FH, "< $file\0") ⎪⎪ die "can't open $file: $!";
517 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 If you want to use "<ARGV>" processing in a totally boring and non-mag‐
527 ical way, you could do this first:
528 # "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 But be warned that users will not appreciate being unable to use "-" to
541 mean standard input, per the standard convention.
542 Paths as Opens
544 You've probably noticed how Perl's "warn" and "die" functions can pro‐
546 duce messages like:
547 Some warning at scriptname line 29, <FH> line 7.
549 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 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 open($path, "< $path") ⎪⎪ die "can't open $path: $!";
558 while (<$path>) {
559 # whatever
560 }
561 Since you're using the pathname of the file as its handle, you'll get
563 warnings more like
564 Some warning at scriptname line 29, </etc/motd> line 7.
566 Single Argument Open
568 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 $FILE = "/etc/motd";
576 open FILE or die "can't open $FILE: $!";
577 while (<FILE>) {
578 # whatever
579 }
580 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 Playing with STDIN and STDOUT
586 One clever move with STDOUT is to explicitly close it when you're done
588 with the program.
589 END { close(STDOUT) ⎪⎪ die "can't close stdout: $!" }
591 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 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 open(STDIN, "< datafile")
600 ⎪⎪ die "can't open datafile: $!";
601 open(STDOUT, "> output")
603 ⎪⎪ die "can't open output: $!";
604 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 It's probably more interesting to connect these to pipes. For example:
610 $pager = $ENV{PAGER} ⎪⎪ "(less ⎪⎪ more)";
612 open(STDOUT, "⎪ $pager")
613 ⎪⎪ die "can't fork a pager: $!";
614 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 head(100);
622 while (<>) {
623 print;
624 }
625 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 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 Opening Non-File Files
645 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 if (-l $file ⎪⎪ ! -f _) {
651 print "$file is not a plain file\n";
652 }
653 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 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 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 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 @ARGV = qw(.) unless @ARGV;
676 use File::Find;
677 find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;
678 This finds all bogus symbolic links beneath a particular directory:
680 find sub { print "$File::Find::name\n" if -l && !-e }, $dir;
682 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 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 Opening Named Pipes
696 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 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 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 $ofh = select(TTYOUT); $⎪ = 1; select($ofh);
717 print TTYOUT "+++at\015";
719 $answer = <TTYIN>;
720 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 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 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 Opening Sockets
740 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 use IO::Socket;
747 local *FH = IO::Socket::INET->new("www.perl.com:80");
748 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 use LWP::Simple;
754 $doc = get('http://www.linpro.no/lwp/');
755 Binary Files
757 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 Another option is to use the "binmode" function on the appropriate han‐
768 dles before doing regular I/O on them:
769 binmode(STDIN);
771 binmode(STDOUT);
772 while (<STDIN>) { print }
773 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 sysopen(BINDAT, "records.data", O_RDWR ⎪ O_BINARY)
779 ⎪⎪ die "can't open records.data: $!";
780 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 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 while (sysread(WHENCE, $buf, 1024)) {
791 syswrite(WHITHER, $buf, length($buf));
792 }
793 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 File Locking
799 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 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 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 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 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 Here's how to get a blocking shared lock on a file, typically used for
831 reading:
832 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 You can get a non-blocking lock by using "LOCK_NB".
840 flock(FH, LOCK_SH ⎪ LOCK_NB)
842 or die "can't lock filename: $!";
843 This can be useful for producing more user-friendly behaviour by warn‐
845 ing if you're going to be blocking:
846 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 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 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 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 use Fcntl qw(:DEFAULT :flock);
877 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 $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 truncate(FH, tell(FH))
892 or die "can't truncate numfile: $!";
893 close(FH)
894 or die "can't close numfile: $!";
895 IO Layers
897 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 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 · 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 open(my $fh, "<:utf8", $fn);
915 · The two-argument form of "binmode" is being used, for example
917 binmode($fh, ":encoding(utf16)");
919 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 This documentation is free; you can redistribute it and/or modify it
931 under the same terms as Perl itself.
932 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
941perl v5.8.8 2006-01-07 PERLOPENTUT(1)