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