3 perlopentut - tutorial on opening things in Perl
7 Perl has two simple, built-in ways to open files: the shell way for
8 convenience, and the C way for precision. The shell way also has 2- and
9 3-argument forms, which have different semantics for handling the filename.
12 =head1 Open E<agrave> la shell
14 Perl's C<open> function was designed to mimic the way command-line
15 redirection in the shell works. Here are some basic examples
18 $ myprogram file1 file2 file3
19 $ myprogram < inputfile
20 $ myprogram > outputfile
21 $ myprogram >> outputfile
22 $ myprogram | otherprogram
23 $ otherprogram | myprogram
25 And here are some more advanced examples:
27 $ otherprogram | myprogram f1 - f2
28 $ otherprogram 2>&1 | myprogram -
32 Programmers accustomed to constructs like those above can take comfort
33 in learning that Perl directly supports these familiar constructs using
34 virtually the same syntax as the shell.
38 The C<open> function takes two arguments: the first is a filehandle,
39 and the second is a single string comprising both what to open and how
40 to open it. C<open> returns true when it works, and when it fails,
41 returns a false value and sets the special variable C<$!> to reflect
42 the system error. If the filehandle was previously opened, it will
43 be implicitly closed first.
47 open(INFO, "datafile") || die("can't open datafile: $!");
48 open(INFO, "< datafile") || die("can't open datafile: $!");
49 open(RESULTS,"> runstats") || die("can't open runstats: $!");
50 open(LOG, ">> logfile ") || die("can't open logfile: $!");
52 If you prefer the low-punctuation version, you could write that this way:
54 open INFO, "< datafile" or die "can't open datafile: $!";
55 open RESULTS,"> runstats" or die "can't open runstats: $!";
56 open LOG, ">> logfile " or die "can't open logfile: $!";
58 A few things to notice. First, the leading C<< < >> is optional.
59 If omitted, Perl assumes that you want to open the file for reading.
61 Note also that the first example uses the C<||> logical operator, and the
62 second uses C<or>, which has lower precedence. Using C<||> in the latter
63 examples would effectively mean
65 open INFO, ( "< datafile" || die "can't open datafile: $!" );
67 which is definitely not what you want.
69 The other important thing to notice is that, just as in the shell,
70 any whitespace before or after the filename is ignored. This is good,
71 because you wouldn't want these to do different things:
73 open INFO, "<datafile"
74 open INFO, "< datafile"
75 open INFO, "< datafile"
77 Ignoring surrounding whitespace also helps for when you read a filename
78 in from a different file, and forget to trim it before opening:
80 $filename = <INFO>; # oops, \n still there
81 open(EXTRA, "< $filename") || die "can't open $filename: $!";
83 This is not a bug, but a feature. Because C<open> mimics the shell in
84 its style of using redirection arrows to specify how to open the file, it
85 also does so with respect to extra whitespace around the filename itself
86 as well. For accessing files with naughty names, see
87 L<"Dispelling the Dweomer">.
89 There is also a 3-argument version of C<open>, which lets you put the
90 special redirection characters into their own argument:
92 open( INFO, ">", $datafile ) || die "Can't create $datafile: $!";
94 In this case, the filename to open is the actual string in C<$datafile>,
95 so you don't have to worry about C<$datafile> containing characters
96 that might influence the open mode, or whitespace at the beginning of
97 the filename that would be absorbed in the 2-argument version. Also,
98 any reduction of unnecessary string interpolation is a good thing.
100 =head2 Indirect Filehandles
102 C<open>'s first argument can be a reference to a filehandle. As of
103 perl 5.6.0, if the argument is uninitialized, Perl will automatically
104 create a filehandle and put a reference to it in the first argument,
107 open( my $in, $infile ) or die "Couldn't read $infile: $!";
109 # do something with $_
113 Indirect filehandles make namespace management easier. Since filehandles
114 are global to the current package, two subroutines trying to open
115 C<INFILE> will clash. With two functions opening indirect filehandles
116 like C<my $infile>, there's no clash and no need to worry about future
119 Another convenient behavior is that an indirect filehandle automatically
120 closes when there are no more references to it:
123 open( my $in, shift ) && return scalar <$in>;
124 # no close() required
127 Indirect filehandles also make it easy to pass filehandles to and return
128 filehandles from subroutines:
130 for my $file ( qw(this.conf that.conf) ) {
131 my $fin = open_or_throw('<', $file);
132 process_conf( $fin );
138 my ($mode, $filename) = @_;
139 open my $h, $mode, $filename
140 or croak "Could not open '$filename': $!";
146 In C, when you want to open a file using the standard I/O library,
147 you use the C<fopen> function, but when opening a pipe, you use the
148 C<popen> function. But in the shell, you just use a different redirection
149 character. That's also the case for Perl. The C<open> call
150 remains the same--just its argument differs.
152 If the leading character is a pipe symbol, C<open> starts up a new
153 command and opens a write-only filehandle leading into that command.
154 This lets you write into that handle and have what you write show up on
155 that command's standard input. For example:
157 open(PRINTER, "| lpr -Plp1") || die "can't run lpr: $!";
158 print PRINTER "stuff\n";
159 close(PRINTER) || die "can't close lpr: $!";
161 If the trailing character is a pipe, you start up a new command and open a
162 read-only filehandle leading out of that command. This lets whatever that
163 command writes to its standard output show up on your handle for reading.
166 open(NET, "netstat -i -n |") || die "can't fork netstat: $!";
167 while (<NET>) { } # do something with input
168 close(NET) || die "can't close netstat: $!";
170 What happens if you try to open a pipe to or from a non-existent
171 command? If possible, Perl will detect the failure and set C<$!> as
172 usual. But if the command contains special shell characters, such as
173 C<E<gt>> or C<*>, called 'metacharacters', Perl does not execute the
174 command directly. Instead, Perl runs the shell, which then tries to
175 run the command. This means that it's the shell that gets the error
176 indication. In such a case, the C<open> call will only indicate
177 failure if Perl can't even run the shell. See L<perlfaq8/"How can I
178 capture STDERR from an external command?"> to see how to cope with
179 this. There's also an explanation in L<perlipc>.
181 If you would like to open a bidirectional pipe, the IPC::Open2
182 library will handle this for you. Check out
183 L<perlipc/"Bidirectional Communication with Another Process">
185 perl-5.6.x introduced a version of piped open that executes a process
186 based on its command line arguments without relying on the shell. (Similar
187 to the C<system(@LIST)> notation.) This is safer and faster than executing
188 a single argument pipe-command, but does not allow special shell
189 constructs. (It is also not supported on Microsoft Windows, Mac OS Classic
192 Here's an example of C<open '-|'>, which prints a random Unix
193 fortune cookie as uppercase:
195 my $collection = shift(@ARGV);
196 open my $fortune, '-|', 'fortune', $collection
197 or die "Could not find fortune - $!";
204 And this C<open '|-'> pipes into lpr:
206 open my $printer, '|-', 'lpr', '-Plp1'
207 or die "can't run lpr: $!";
208 print {$printer} "stuff\n";
210 or die "can't close lpr: $!";
212 =head2 The Minus File
214 Again following the lead of the standard shell utilities, Perl's
215 C<open> function treats a file whose name is a single minus, "-", in a
216 special way. If you open minus for reading, it really means to access
217 the standard input. If you open minus for writing, it really means to
218 access the standard output.
220 If minus can be used as the default input or default output, what happens
221 if you open a pipe into or out of minus? What's the default command it
222 would run? The same script as you're currently running! This is actually
223 a stealth C<fork> hidden inside an C<open> call. See
224 L<perlipc/"Safe Pipe Opens"> for details.
226 =head2 Mixing Reads and Writes
228 It is possible to specify both read and write access. All you do is
229 add a "+" symbol in front of the redirection. But as in the shell,
230 using a less-than on a file never creates a new file; it only opens an
231 existing one. On the other hand, using a greater-than always clobbers
232 (truncates to zero length) an existing file, or creates a brand-new one
233 if there isn't an old one. Adding a "+" for read-write doesn't affect
234 whether it only works on existing files or always clobbers existing ones.
236 open(WTMP, "+< /usr/adm/wtmp")
237 || die "can't open /usr/adm/wtmp: $!";
239 open(SCREEN, "+> lkscreen")
240 || die "can't open lkscreen: $!";
242 open(LOGFILE, "+>> /var/log/applog")
243 || die "can't open /var/log/applog: $!";
245 The first one won't create a new file, and the second one will always
246 clobber an old one. The third one will create a new file if necessary
247 and not clobber an old one, and it will allow you to read at any point
248 in the file, but all writes will always go to the end. In short,
249 the first case is substantially more common than the second and third
250 cases, which are almost always wrong. (If you know C, the plus in
251 Perl's C<open> is historically derived from the one in C's fopen(3S),
252 which it ultimately calls.)
254 In fact, when it comes to updating a file, unless you're working on
255 a binary file as in the WTMP case above, you probably don't want to
256 use this approach for updating. Instead, Perl's B<-i> flag comes to
257 the rescue. The following command takes all the C, C++, or yacc source
258 or header files and changes all their foo's to bar's, leaving
259 the old version in the original filename with a ".orig" tacked
262 $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]
264 This is a short cut for some renaming games that are really
265 the best way to update textfiles. See the second question in
266 L<perlfaq5> for more details.
270 One of the most common uses for C<open> is one you never
271 even notice. When you process the ARGV filehandle using
272 C<< <ARGV> >>, Perl actually does an implicit open
273 on each file in @ARGV. Thus a program called like this:
275 $ myprogram file1 file2 file3
277 can have all its files opened and processed one at a time
278 using a construct no more complex than:
281 # do something with $_
284 If @ARGV is empty when the loop first begins, Perl pretends you've opened
285 up minus, that is, the standard input. In fact, $ARGV, the currently
286 open file during C<< <ARGV> >> processing, is even set to "-"
287 in these circumstances.
289 You are welcome to pre-process your @ARGV before starting the loop to
290 make sure it's to your liking. One reason to do this might be to remove
291 command options beginning with a minus. While you can always roll the
292 simple ones by hand, the Getopts modules are good for this:
296 # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
299 # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
300 getopts("vDo:", \%args);
302 Or the standard Getopt::Long module to permit named arguments:
305 GetOptions( "verbose" => \$verbose, # --verbose
306 "Debug" => \$debug, # --Debug
307 "output=s" => \$output );
308 # --output=somestring or --output somestring
310 Another reason for preprocessing arguments is to make an empty
311 argument list default to all files:
313 @ARGV = glob("*") unless @ARGV;
315 You could even filter out all but plain, text files. This is a bit
316 silent, of course, and you might prefer to mention them on the way.
318 @ARGV = grep { -f && -T } @ARGV;
320 If you're using the B<-n> or B<-p> command-line options, you
321 should put changes to @ARGV in a C<BEGIN{}> block.
323 Remember that a normal C<open> has special properties, in that it might
324 call fopen(3S) or it might called popen(3S), depending on what its
325 argument looks like; that's why it's sometimes called "magic open".
328 $pwdinfo = `domainname` =~ /^(\(none\))?$/
333 or die "can't open $pwdinfo: $!";
335 This sort of thing also comes into play in filter processing. Because
336 C<< <ARGV> >> processing employs the normal, shell-style Perl C<open>,
337 it respects all the special things we've already seen:
339 $ myprogram f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
341 That program will read from the file F<f1>, the process F<cmd1>, standard
342 input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command,
343 and finally the F<f3> file.
345 Yes, this also means that if you have files named "-" (and so on) in
346 your directory, they won't be processed as literal files by C<open>.
347 You'll need to pass them as "./-", much as you would for the I<rm> program,
348 or you could use C<sysopen> as described below.
350 One of the more interesting applications is to change files of a certain
351 name into pipes. For example, to autoprocess gzipped or compressed
352 files by decompressing them with I<gzip>:
354 @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc $_ |" : $_ } @ARGV;
356 Or, if you have the I<GET> program installed from LWP,
357 you can fetch URLs before processing them:
359 @ARGV = map { m#^\w+://# ? "GET $_ |" : $_ } @ARGV;
361 It's not for nothing that this is called magic C<< <ARGV> >>.
364 =head1 Open E<agrave> la C
366 If you want the convenience of the shell, then Perl's C<open> is
367 definitely the way to go. On the other hand, if you want finer precision
368 than C's simplistic fopen(3S) provides you should look to Perl's
369 C<sysopen>, which is a direct hook into the open(2) system call.
370 That does mean it's a bit more involved, but that's the price of
373 C<sysopen> takes 3 (or 4) arguments.
375 sysopen HANDLE, PATH, FLAGS, [MASK]
377 The HANDLE argument is a filehandle just as with C<open>. The PATH is
378 a literal path, one that doesn't pay attention to any greater-thans or
379 less-thans or pipes or minuses, nor ignore whitespace. If it's there,
380 it's part of the path. The FLAGS argument contains one or more values
381 derived from the Fcntl module that have been or'd together using the
382 bitwise "|" operator. The final argument, the MASK, is optional; if
383 present, it is combined with the user's current umask for the creation
384 mode of the file. You should usually omit this.
386 Although the traditional values of read-only, write-only, and read-write
387 are 0, 1, and 2 respectively, this is known not to hold true on some
388 systems. Instead, it's best to load in the appropriate constants first
389 from the Fcntl module, which supplies the following standard flags:
393 O_RDWR Read and write
394 O_CREAT Create the file if it doesn't exist
395 O_EXCL Fail if the file already exists
396 O_APPEND Append to the file
397 O_TRUNC Truncate the file
398 O_NONBLOCK Non-blocking access
400 Less common flags that are sometimes available on some operating
401 systems include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>,
402 C<O_DEFER>, C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>,
403 C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>. Consult your open(2)
404 manpage or its local equivalent for details. (Note: starting from
405 Perl release 5.6 the C<O_LARGEFILE> flag, if available, is automatically
406 added to the sysopen() flags because large files are the default.)
408 Here's how to use C<sysopen> to emulate the simple C<open> calls we had
409 before. We'll omit the C<|| die $!> checks for clarity, but make sure
410 you always check the return values in real code. These aren't quite
411 the same, since C<open> will trim leading and trailing whitespace,
412 but you'll get the idea.
414 To open a file for reading:
417 sysopen(FH, $path, O_RDONLY);
419 To open a file for writing, creating a new file if needed or else truncating
423 sysopen(FH, $path, O_WRONLY | O_TRUNC | O_CREAT);
425 To open a file for appending, creating one if necessary:
427 open(FH, ">> $path");
428 sysopen(FH, $path, O_WRONLY | O_APPEND | O_CREAT);
430 To open a file for update, where the file must already exist:
432 open(FH, "+< $path");
433 sysopen(FH, $path, O_RDWR);
435 And here are things you can do with C<sysopen> that you cannot do with
436 a regular C<open>. As you'll see, it's just a matter of controlling the
437 flags in the third argument.
439 To open a file for writing, creating a new file which must not previously
442 sysopen(FH, $path, O_WRONLY | O_EXCL | O_CREAT);
444 To open a file for appending, where that file must already exist:
446 sysopen(FH, $path, O_WRONLY | O_APPEND);
448 To open a file for update, creating a new file if necessary:
450 sysopen(FH, $path, O_RDWR | O_CREAT);
452 To open a file for update, where that file must not already exist:
454 sysopen(FH, $path, O_RDWR | O_EXCL | O_CREAT);
456 To open a file without blocking, creating one if necessary:
458 sysopen(FH, $path, O_WRONLY | O_NONBLOCK | O_CREAT);
460 =head2 Permissions E<agrave> la mode
462 If you omit the MASK argument to C<sysopen>, Perl uses the octal value
463 0666. The normal MASK to use for executables and directories should
464 be 0777, and for anything else, 0666.
466 Why so permissive? Well, it isn't really. The MASK will be modified
467 by your process's current C<umask>. A umask is a number representing
468 I<disabled> permissions bits; that is, bits that will not be turned on
469 in the created file's permissions field.
471 For example, if your C<umask> were 027, then the 020 part would
472 disable the group from writing, and the 007 part would disable others
473 from reading, writing, or executing. Under these conditions, passing
474 C<sysopen> 0666 would create a file with mode 0640, since C<0666 & ~027>
477 You should seldom use the MASK argument to C<sysopen()>. That takes
478 away the user's freedom to choose what permission new files will have.
479 Denying choice is almost always a bad thing. One exception would be for
480 cases where sensitive or private data is being stored, such as with mail
481 folders, cookie files, and internal temporary files.
483 =head1 Obscure Open Tricks
485 =head2 Re-Opening Files (dups)
487 Sometimes you already have a filehandle open, and want to make another
488 handle that's a duplicate of the first one. In the shell, we place an
489 ampersand in front of a file descriptor number when doing redirections.
490 For example, C<< 2>&1 >> makes descriptor 2 (that's STDERR in Perl)
491 be redirected into descriptor 1 (which is usually Perl's STDOUT).
492 The same is essentially true in Perl: a filename that begins with an
493 ampersand is treated instead as a file descriptor if a number, or as a
494 filehandle if a string.
496 open(SAVEOUT, ">&SAVEERR") || die "couldn't dup SAVEERR: $!";
497 open(MHCONTEXT, "<&4") || die "couldn't dup fd4: $!";
499 That means that if a function is expecting a filename, but you don't
500 want to give it a filename because you already have the file open, you
501 can just pass the filehandle with a leading ampersand. It's best to
502 use a fully qualified handle though, just in case the function happens
503 to be in a different package:
505 somefunction("&main::LOGFILE");
507 This way if somefunction() is planning on opening its argument, it can
508 just use the already opened handle. This differs from passing a handle,
509 because with a handle, you don't open the file. Here you have something
510 you can pass to open.
512 If you have one of those tricky, newfangled I/O objects that the C++
513 folks are raving about, then this doesn't work because those aren't a
514 proper filehandle in the native Perl sense. You'll have to use fileno()
515 to pull out the proper descriptor number, assuming you can:
518 $handle = IO::Socket::INET->new("www.perl.com:80");
519 $fd = $handle->fileno;
520 somefunction("&$fd"); # not an indirect function call
522 It can be easier (and certainly will be faster) just to use real
526 local *REMOTE = IO::Socket::INET->new("www.perl.com:80");
527 die "can't connect" unless defined(fileno(REMOTE));
528 somefunction("&main::REMOTE");
530 If the filehandle or descriptor number is preceded not just with a simple
531 "&" but rather with a "&=" combination, then Perl will not create a
532 completely new descriptor opened to the same place using the dup(2)
533 system call. Instead, it will just make something of an alias to the
534 existing one using the fdopen(3S) library call. This is slightly more
535 parsimonious of systems resources, although this is less a concern
536 these days. Here's an example of that:
538 $fd = $ENV{"MHCONTEXTFD"};
539 open(MHCONTEXT, "<&=$fd") or die "couldn't fdopen $fd: $!";
541 If you're using magic C<< <ARGV> >>, you could even pass in as a
542 command line argument in @ARGV something like C<"<&=$MHCONTEXTFD">,
543 but we've never seen anyone actually do this.
545 =head2 Dispelling the Dweomer
547 Perl is more of a DWIMmer language than something like Java--where DWIM
548 is an acronym for "do what I mean". But this principle sometimes leads
549 to more hidden magic than one knows what to do with. In this way, Perl
550 is also filled with I<dweomer>, an obscure word meaning an enchantment.
551 Sometimes, Perl's DWIMmer is just too much like dweomer for comfort.
553 If magic C<open> is a bit too magical for you, you don't have to turn
554 to C<sysopen>. To open a file with arbitrary weird characters in
555 it, it's necessary to protect any leading and trailing whitespace.
556 Leading whitespace is protected by inserting a C<"./"> in front of a
557 filename that starts with whitespace. Trailing whitespace is protected
558 by appending an ASCII NUL byte (C<"\0">) at the end of the string.
560 $file =~ s#^(\s)#./$1#;
561 open(FH, "< $file\0") || die "can't open $file: $!";
563 This assumes, of course, that your system considers dot the current
564 working directory, slash the directory separator, and disallows ASCII
565 NULs within a valid filename. Most systems follow these conventions,
566 including all POSIX systems as well as proprietary Microsoft systems.
567 The only vaguely popular system that doesn't work this way is the
568 "Classic" Macintosh system, which uses a colon where the rest of us
569 use a slash. Maybe C<sysopen> isn't such a bad idea after all.
571 If you want to use C<< <ARGV> >> processing in a totally boring
572 and non-magical way, you could do this first:
574 # "Sam sat on the ground and put his head in his hands.
575 # 'I wish I had never come here, and I don't want to see
576 # no more magic,' he said, and fell silent."
585 But be warned that users will not appreciate being unable to use "-"
586 to mean standard input, per the standard convention.
588 =head2 Paths as Opens
590 You've probably noticed how Perl's C<warn> and C<die> functions can
591 produce messages like:
593 Some warning at scriptname line 29, <FH> line 7.
595 That's because you opened a filehandle FH, and had read in seven records
596 from it. But what was the name of the file, rather than the handle?
598 If you aren't running with C<strict refs>, or if you've turned them off
599 temporarily, then all you have to do is this:
601 open($path, "< $path") || die "can't open $path: $!";
606 Since you're using the pathname of the file as its handle,
607 you'll get warnings more like
609 Some warning at scriptname line 29, </etc/motd> line 7.
611 =head2 Single Argument Open
613 Remember how we said that Perl's open took two arguments? That was a
614 passive prevarication. You see, it can also take just one argument.
615 If and only if the variable is a global variable, not a lexical, you
616 can pass C<open> just one argument, the filehandle, and it will
617 get the path from the global scalar variable of the same name.
620 open FILE or die "can't open $FILE: $!";
625 Why is this here? Someone has to cater to the hysterical porpoises.
626 It's something that's been in Perl since the very beginning, if not
629 =head2 Playing with STDIN and STDOUT
631 One clever move with STDOUT is to explicitly close it when you're done
634 END { close(STDOUT) || die "can't close stdout: $!" }
636 If you don't do this, and your program fills up the disk partition due
637 to a command line redirection, it won't report the error exit with a
640 You don't have to accept the STDIN and STDOUT you were given. You are
641 welcome to reopen them if you'd like.
643 open(STDIN, "< datafile")
644 || die "can't open datafile: $!";
646 open(STDOUT, "> output")
647 || die "can't open output: $!";
649 And then these can be accessed directly or passed on to subprocesses.
650 This makes it look as though the program were initially invoked
651 with those redirections from the command line.
653 It's probably more interesting to connect these to pipes. For example:
655 $pager = $ENV{PAGER} || "(less || more)";
656 open(STDOUT, "| $pager")
657 || die "can't fork a pager: $!";
659 This makes it appear as though your program were called with its stdout
660 already piped into your pager. You can also use this kind of thing
661 in conjunction with an implicit fork to yourself. You might do this
662 if you would rather handle the post processing in your own program,
663 just in a different process:
671 my $lines = shift || 20;
672 return if $pid = open(STDOUT, "|-"); # return if parent
673 die "cannot fork: $!" unless defined $pid;
675 last if --$lines < 0;
681 This technique can be applied to repeatedly push as many filters on your
682 output stream as you wish.
684 =head1 Other I/O Issues
686 These topics aren't really arguments related to C<open> or C<sysopen>,
687 but they do affect what you do with your open files.
689 =head2 Opening Non-File Files
691 When is a file not a file? Well, you could say when it exists but
692 isn't a plain file. We'll check whether it's a symbolic link first,
695 if (-l $file || ! -f _) {
696 print "$file is not a plain file\n";
699 What other kinds of files are there than, well, files? Directories,
700 symbolic links, named pipes, Unix-domain sockets, and block and character
701 devices. Those are all files, too--just not I<plain> files. This isn't
702 the same issue as being a text file. Not all text files are plain files.
703 Not all plain files are text files. That's why there are separate C<-f>
704 and C<-T> file tests.
706 To open a directory, you should use the C<opendir> function, then
707 process it with C<readdir>, carefully restoring the directory
710 opendir(DIR, $dirname) or die "can't opendir $dirname: $!";
711 while (defined($file = readdir(DIR))) {
712 # do something with "$dirname/$file"
716 If you want to process directories recursively, it's better to use the
717 File::Find module. For example, this prints out all files recursively
718 and adds a slash to their names if the file is a directory.
720 @ARGV = qw(.) unless @ARGV;
722 find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;
724 This finds all bogus symbolic links beneath a particular directory:
726 find sub { print "$File::Find::name\n" if -l && !-e }, $dir;
728 As you see, with symbolic links, you can just pretend that it is
729 what it points to. Or, if you want to know I<what> it points to, then
730 C<readlink> is called for:
733 if (defined($whither = readlink($file))) {
734 print "$file points to $whither\n";
736 print "$file points nowhere: $!\n";
740 =head2 Opening Named Pipes
742 Named pipes are a different matter. You pretend they're regular files,
743 but their opens will normally block until there is both a reader and
744 a writer. You can read more about them in L<perlipc/"Named Pipes">.
745 Unix-domain sockets are rather different beasts as well; they're
746 described in L<perlipc/"Unix-Domain TCP Clients and Servers">.
748 When it comes to opening devices, it can be easy and it can be tricky.
749 We'll assume that if you're opening up a block device, you know what
750 you're doing. The character devices are more interesting. These are
751 typically used for modems, mice, and some kinds of printers. This is
752 described in L<perlfaq8/"How do I read and write the serial port?">
753 It's often enough to open them carefully:
755 sysopen(TTYIN, "/dev/ttyS1", O_RDWR | O_NDELAY | O_NOCTTY)
756 # (O_NOCTTY no longer needed on POSIX systems)
757 or die "can't open /dev/ttyS1: $!";
758 open(TTYOUT, "+>&TTYIN")
759 or die "can't dup TTYIN: $!";
761 $ofh = select(TTYOUT); $| = 1; select($ofh);
763 print TTYOUT "+++at\015";
766 With descriptors that you haven't opened using C<sysopen>, such as
767 sockets, you can set them to be non-blocking using C<fcntl>:
770 my $old_flags = fcntl($handle, F_GETFL, 0)
771 or die "can't get flags: $!";
772 fcntl($handle, F_SETFL, $old_flags | O_NONBLOCK)
773 or die "can't set non blocking: $!";
775 Rather than losing yourself in a morass of twisting, turning C<ioctl>s,
776 all dissimilar, if you're going to manipulate ttys, it's best to
777 make calls out to the stty(1) program if you have it, or else use the
778 portable POSIX interface. To figure this all out, you'll need to read the
779 termios(3) manpage, which describes the POSIX interface to tty devices,
780 and then L<POSIX>, which describes Perl's interface to POSIX. There are
781 also some high-level modules on CPAN that can help you with these games.
782 Check out Term::ReadKey and Term::ReadLine.
784 =head2 Opening Sockets
786 What else can you open? To open a connection using sockets, you won't use
787 one of Perl's two open functions. See
788 L<perlipc/"Sockets: Client/Server Communication"> for that. Here's an
789 example. Once you have it, you can use FH as a bidirectional filehandle.
792 local *FH = IO::Socket::INET->new("www.perl.com:80");
794 For opening up a URL, the LWP modules from CPAN are just what
795 the doctor ordered. There's no filehandle interface, but
796 it's still easy to get the contents of a document:
799 $doc = get('http://www.cpan.org/');
803 On certain legacy systems with what could charitably be called terminally
804 convoluted (some would say broken) I/O models, a file isn't a file--at
805 least, not with respect to the C standard I/O library. On these old
806 systems whose libraries (but not kernels) distinguish between text and
807 binary streams, to get files to behave properly you'll have to bend over
808 backwards to avoid nasty problems. On such infelicitous systems, sockets
809 and pipes are already opened in binary mode, and there is currently no
810 way to turn that off. With files, you have more options.
812 Another option is to use the C<binmode> function on the appropriate
813 handles before doing regular I/O on them:
817 while (<STDIN>) { print }
819 Passing C<sysopen> a non-standard flag option will also open the file in
820 binary mode on those systems that support it. This is the equivalent of
821 opening the file normally, then calling C<binmode> on the handle.
823 sysopen(BINDAT, "records.data", O_RDWR | O_BINARY)
824 || die "can't open records.data: $!";
826 Now you can use C<read> and C<print> on that handle without worrying
827 about the non-standard system I/O library breaking your data. It's not
828 a pretty picture, but then, legacy systems seldom are. CP/M will be
829 with us until the end of days, and after.
831 On systems with exotic I/O systems, it turns out that, astonishingly
832 enough, even unbuffered I/O using C<sysread> and C<syswrite> might do
833 sneaky data mutilation behind your back.
835 while (sysread(WHENCE, $buf, 1024)) {
836 syswrite(WHITHER, $buf, length($buf));
839 Depending on the vicissitudes of your runtime system, even these calls
840 may need C<binmode> or C<O_BINARY> first. Systems known to be free of
841 such difficulties include Unix, the Mac OS, Plan 9, and Inferno.
845 In a multitasking environment, you may need to be careful not to collide
846 with other processes who want to do I/O on the same files as you
847 are working on. You'll often need shared or exclusive locks
848 on files for reading and writing respectively. You might just
849 pretend that only exclusive locks exist.
851 Never use the existence of a file C<-e $file> as a locking indication,
852 because there is a race condition between the test for the existence of
853 the file and its creation. It's possible for another process to create
854 a file in the slice of time between your existence check and your attempt
855 to create the file. Atomicity is critical.
857 Perl's most portable locking interface is via the C<flock> function,
858 whose simplicity is emulated on systems that don't directly support it
859 such as SysV or Windows. The underlying semantics may affect how
860 it all works, so you should learn how C<flock> is implemented on your
861 system's port of Perl.
863 File locking I<does not> lock out another process that would like to
864 do I/O. A file lock only locks out others trying to get a lock, not
865 processes trying to do I/O. Because locks are advisory, if one process
866 uses locking and another doesn't, all bets are off.
868 By default, the C<flock> call will block until a lock is granted.
869 A request for a shared lock will be granted as soon as there is no
870 exclusive locker. A request for an exclusive lock will be granted as
871 soon as there is no locker of any kind. Locks are on file descriptors,
872 not file names. You can't lock a file until you open it, and you can't
873 hold on to a lock once the file has been closed.
875 Here's how to get a blocking shared lock on a file, typically used
879 use Fcntl qw(:DEFAULT :flock);
880 open(FH, "< filename") or die "can't open filename: $!";
881 flock(FH, LOCK_SH) or die "can't lock filename: $!";
884 You can get a non-blocking lock by using C<LOCK_NB>.
886 flock(FH, LOCK_SH | LOCK_NB)
887 or die "can't lock filename: $!";
889 This can be useful for producing more user-friendly behaviour by warning
890 if you're going to be blocking:
893 use Fcntl qw(:DEFAULT :flock);
894 open(FH, "< filename") or die "can't open filename: $!";
895 unless (flock(FH, LOCK_SH | LOCK_NB)) {
897 print "Waiting for lock...";
898 flock(FH, LOCK_SH) or die "can't lock filename: $!";
903 To get an exclusive lock, typically used for writing, you have to be
904 careful. We C<sysopen> the file so it can be locked before it gets
905 emptied. You can get a nonblocking version using C<LOCK_EX | LOCK_NB>.
908 use Fcntl qw(:DEFAULT :flock);
909 sysopen(FH, "filename", O_WRONLY | O_CREAT)
910 or die "can't open filename: $!";
912 or die "can't lock filename: $!";
914 or die "can't truncate filename: $!";
917 Finally, due to the uncounted millions who cannot be dissuaded from
918 wasting cycles on useless vanity devices called hit counters, here's
919 how to increment a number in a file safely:
921 use Fcntl qw(:DEFAULT :flock);
923 sysopen(FH, "numfile", O_RDWR | O_CREAT)
924 or die "can't open numfile: $!";
926 $ofh = select(FH); $| = 1; select ($ofh);
928 or die "can't write-lock numfile: $!";
932 or die "can't rewind numfile : $!";
933 print FH $num+1, "\n"
934 or die "can't write numfile: $!";
936 truncate(FH, tell(FH))
937 or die "can't truncate numfile: $!";
939 or die "can't close numfile: $!";
943 In Perl 5.8.0 a new I/O framework called "PerlIO" was introduced.
944 This is a new "plumbing" for all the I/O happening in Perl; for the
945 most part everything will work just as it did, but PerlIO also brought
946 in some new features such as the ability to think of I/O as "layers".
947 One I/O layer may in addition to just moving the data also do
948 transformations on the data. Such transformations may include
949 compression and decompression, encryption and decryption, and transforming
950 between various character encodings.
952 Full discussion about the features of PerlIO is out of scope for this
953 tutorial, but here is how to recognize the layers being used:
959 The three-(or more)-argument form of C<open> is being used and the
960 second argument contains something else in addition to the usual
961 C<< '<' >>, C<< '>' >>, C<< '>>' >>, C<< '|' >> and their variants,
964 open(my $fh, "<:crlf", $fn);
968 The two-argument form of C<binmode> is being used, for example
970 binmode($fh, ":encoding(utf16)");
974 For more detailed discussion about PerlIO see L<PerlIO>;
975 for more detailed discussion about Unicode and I/O see L<perluniintro>.
979 The C<open> and C<sysopen> functions in perlfunc(1);
980 the system open(2), dup(2), fopen(3), and fdopen(3) manpages;
981 the POSIX documentation.
983 =head1 AUTHOR and COPYRIGHT
985 Copyright 1998 Tom Christiansen.
987 This documentation is free; you can redistribute it and/or modify it
988 under the same terms as Perl itself.
990 Irrespective of its distribution, all code examples in these files are
991 hereby placed into the public domain. You are permitted and
992 encouraged to use this code in your own programs for fun or for profit
993 as you see fit. A simple comment in the code giving credit would be
994 courteous but is not required.
998 First release: Sat Jan 9 08:09:11 MST 1999