This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
5061f6960c512c549915545e58a208f160b71584
[perl5.git] / pod / perlfaq5.pod
1 =head1 NAME
2
3 perlfaq5 - Files and Formats ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $)
4
5 =head1 DESCRIPTION
6
7 This section deals with I/O and the "f" issues: filehandles, flushing,
8 formats, and footers.
9
10 =head2 How do I flush/unbuffer an output filehandle?  Why must I do this?
11
12 The C standard I/O library (stdio) normally buffers characters sent to
13 devices.  This is done for efficiency reasons so that there isn't a
14 system call for each byte.  Any time you use print() or write() in
15 Perl, you go though this buffering.  syswrite() circumvents stdio and
16 buffering.
17
18 In most stdio implementations, the type of output buffering and the size of
19 the buffer varies according to the type of device.  Disk files are block
20 buffered, often with a buffer size of more than 2k.  Pipes and sockets
21 are often buffered with a buffer size between 1/2 and 2k.  Serial devices
22 (e.g. modems, terminals) are normally line-buffered, and stdio sends
23 the entire line when it gets the newline.
24
25 Perl does not support truly unbuffered output (except insofar as you can
26 C<syswrite(OUT, $char, 1)>).  What it does instead support is "command
27 buffering", in which a physical write is performed after every output
28 command.  This isn't as hard on your system as unbuffering, but does
29 get the output where you want it when you want it.
30
31 If you expect characters to get to your device when you print them there,
32 you'll want to autoflush its handle.
33 Use select() and the C<$|> variable to control autoflushing
34 (see L<perlvar/$|> and L<perlfunc/select>):
35
36     $old_fh = select(OUTPUT_HANDLE);
37     $| = 1;
38     select($old_fh);
39
40 Or using the traditional idiom:
41
42     select((select(OUTPUT_HANDLE), $| = 1)[0]);
43
44 Or if don't mind slowly loading several thousand lines of module code
45 just because you're afraid of the C<$|> variable:
46
47     use FileHandle;
48     open(DEV, "+</dev/tty");      # ceci n'est pas une pipe
49     DEV->autoflush(1);
50
51 or the newer IO::* modules:
52
53     use IO::Handle;
54     open(DEV, ">/dev/printer");   # but is this?
55     DEV->autoflush(1);
56
57 or even this:
58
59     use IO::Socket;               # this one is kinda a pipe?
60     $sock = IO::Socket::INET->new(PeerAddr => 'www.perl.com',
61                                   PeerPort => 'http(80)',
62                                   Proto    => 'tcp');
63     die "$!" unless $sock;
64
65     $sock->autoflush();
66     print $sock "GET / HTTP/1.0" . "\015\012" x 2;
67     $document = join('', <$sock>);
68     print "DOC IS: $document\n";
69
70 Note the bizarrely hardcoded carriage return and newline in their octal
71 equivalents.  This is the ONLY way (currently) to assure a proper flush
72 on all platforms, including Macintosh.  That's the way things work in
73 network programming: you really should specify the exact bit pattern
74 on the network line terminator.  In practice, C<"\n\n"> often works,
75 but this is not portable.
76
77 See L<perlfaq9> for other examples of fetching URLs over the web.
78
79 =head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
80
81 Those are operations of a text editor.  Perl is not a text editor.
82 Perl is a programming language.  You have to decompose the problem into
83 low-level calls to read, write, open, close, and seek.
84
85 Although humans have an easy time thinking of a text file as being a
86 sequence of lines that operates much like a stack of playing cards--or
87 punch cards--computers usually see the text file as a sequence of bytes.
88 In general, there's no direct way for Perl to seek to a particular line
89 of a file, insert text into a file, or remove text from a file.
90
91 (There are exceptions in special circumstances.  You can add or remove
92 data at the very end of the file.  A sequence of bytes can be replaced
93 with another sequence of the same length.  The C<$DB_RECNO> array
94 bindings as documented in L<DB_File> also provide a direct way of
95 modifying a file.  Files where all lines are the same length are also
96 easy to alter.)
97
98 The general solution is to create a temporary copy of the text file with
99 the changes you want, then copy that over the original.  This assumes
100 no locking.
101
102     $old = $file;
103     $new = "$file.tmp.$$";
104     $bak = "$file.orig";
105
106     open(OLD, "< $old")         or die "can't open $old: $!";
107     open(NEW, "> $new")         or die "can't open $new: $!";
108
109     # Correct typos, preserving case
110     while (<OLD>) {
111         s/\b(p)earl\b/${1}erl/i;
112         (print NEW $_)          or die "can't write to $new: $!";
113     }
114
115     close(OLD)                  or die "can't close $old: $!";
116     close(NEW)                  or die "can't close $new: $!";
117
118     rename($old, $bak)          or die "can't rename $old to $bak: $!";
119     rename($new, $old)          or die "can't rename $new to $old: $!";
120
121 Perl can do this sort of thing for you automatically with the C<-i>
122 command-line switch or the closely-related C<$^I> variable (see
123 L<perlrun> for more details).  Note that
124 C<-i> may require a suffix on some non-Unix systems; see the
125 platform-specific documentation that came with your port.
126
127     # Renumber a series of tests from the command line
128     perl -pi -e 's/(^\s+test\s+)\d+/ $1 . ++$count /e' t/op/taint.t
129
130     # form a script
131     local($^I, @ARGV) = ('.orig', glob("*.c"));
132     while (<>) {
133         if ($. == 1) {
134             print "This line should appear at the top of each file\n";
135         }
136         s/\b(p)earl\b/${1}erl/i;        # Correct typos, preserving case
137         print;
138         close ARGV if eof;              # Reset $.
139     }
140
141 If you need to seek to an arbitrary line of a file that changes
142 infrequently, you could build up an index of byte positions of where
143 the line ends are in the file.  If the file is large, an index of
144 every tenth or hundredth line end would allow you to seek and read
145 fairly efficiently.  If the file is sorted, try the look.pl library
146 (part of the standard perl distribution).
147
148 In the unique case of deleting lines at the end of a file, you
149 can use tell() and truncate().  The following code snippet deletes
150 the last line of a file without making a copy or reading the
151 whole file into memory:
152
153         open (FH, "+< $file");
154         while ( <FH> ) { $addr = tell(FH) unless eof(FH) }
155         truncate(FH, $addr);
156
157 Error checking is left as an exercise for the reader.
158
159 =head2 How do I count the number of lines in a file?
160
161 One fairly efficient way is to count newlines in the file. The
162 following program uses a feature of tr///, as documented in L<perlop>.
163 If your text file doesn't end with a newline, then it's not really a
164 proper text file, so this may report one fewer line than you expect.
165
166     $lines = 0;
167     open(FILE, $filename) or die "Can't open `$filename': $!";
168     while (sysread FILE, $buffer, 4096) {
169         $lines += ($buffer =~ tr/\n//);
170     }
171     close FILE;
172
173 This assumes no funny games with newline translations.
174
175 =head2 How do I make a temporary file name?
176
177 Use the C<new_tmpfile> class method from the IO::File module to get a
178 filehandle opened for reading and writing.  Use it if you don't
179 need to know the file's name:
180
181     use IO::File;
182     $fh = IO::File->new_tmpfile()
183         or die "Unable to make new temporary file: $!";
184
185 If you do need to know the file's name, you can use the C<tmpnam>
186 function from the POSIX module to get a filename that you then open
187 yourself:
188
189
190     use Fcntl;
191     use POSIX qw(tmpnam);
192
193     # try new temporary filenames until we get one that didn't already
194     # exist;  the check should be unnecessary, but you can't be too careful
195     do { $name = tmpnam() }
196         until sysopen(FH, $name, O_RDWR|O_CREAT|O_EXCL);
197
198     # install atexit-style handler so that when we exit or die,
199     # we automatically delete this temporary file
200     END { unlink($name) or die "Couldn't unlink $name : $!" }
201
202     # now go on to use the file ...
203
204 If you're committed to creating a temporary file by hand, use the
205 process ID and/or the current time-value.  If you need to have many
206 temporary files in one process, use a counter:
207
208     BEGIN {
209         use Fcntl;
210         my $temp_dir = -d '/tmp' ? '/tmp' : $ENV{TMP} || $ENV{TEMP};
211         my $base_name = sprintf("%s/%d-%d-0000", $temp_dir, $$, time());
212         sub temp_file {
213             local *FH;
214             my $count = 0;
215             until (defined(fileno(FH)) || $count++ > 100) {
216                 $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
217                 sysopen(FH, $base_name, O_WRONLY|O_EXCL|O_CREAT);
218             }
219             if (defined(fileno(FH))
220                 return (*FH, $base_name);
221             } else {
222                 return ();
223             }
224         }
225     }
226
227 =head2 How can I manipulate fixed-record-length files?
228
229 The most efficient way is using pack() and unpack().  This is faster than
230 using substr() when taking many, many strings.  It is slower for just a few.
231
232 Here is a sample chunk of code to break up and put back together again
233 some fixed-format input lines, in this case from the output of a normal,
234 Berkeley-style ps:
235
236     # sample input line:
237     #   15158 p5  T      0:00 perl /home/tchrist/scripts/now-what
238     $PS_T = 'A6 A4 A7 A5 A*';
239     open(PS, "ps|");
240     print scalar <PS>; 
241     while (<PS>) {
242         ($pid, $tt, $stat, $time, $command) = unpack($PS_T, $_);
243         for $var (qw!pid tt stat time command!) {
244             print "$var: <$$var>\n";
245         }
246         print 'line=', pack($PS_T, $pid, $tt, $stat, $time, $command),
247                 "\n";
248     }
249
250 We've used C<$$var> in a way that forbidden by C<use strict 'refs'>.
251 That is, we've promoted a string to a scalar variable reference using
252 symbolic references.  This is ok in small programs, but doesn't scale
253 well.   It also only works on global variables, not lexicals.
254
255 =head2 How can I make a filehandle local to a subroutine?  How do I pass filehandles between subroutines?  How do I make an array of filehandles?
256
257 The fastest, simplest, and most direct way is to localize the typeglob
258 of the filehandle in question:
259
260     local *TmpHandle;
261
262 Typeglobs are fast (especially compared with the alternatives) and
263 reasonably easy to use, but they also have one subtle drawback.  If you
264 had, for example, a function named TmpHandle(), or a variable named
265 %TmpHandle, you just hid it from yourself.
266
267     sub findme {
268         local *HostFile;
269         open(HostFile, "</etc/hosts") or die "no /etc/hosts: $!";
270         local $_;               # <- VERY IMPORTANT
271         while (<HostFile>) {
272             print if /\b127\.(0\.0\.)?1\b/;
273         }
274         # *HostFile automatically closes/disappears here
275     }
276
277 Here's how to use typeglobs in a loop to open and store a bunch of
278 filehandles.  We'll use as values of the hash an ordered
279 pair to make it easy to sort the hash in insertion order.
280
281     @names = qw(motd termcap passwd hosts);
282     my $i = 0;
283     foreach $filename (@names) {
284         local *FH;
285         open(FH, "/etc/$filename") || die "$filename: $!";
286         $file{$filename} = [ $i++, *FH ];
287     }
288
289     # Using the filehandles in the array
290     foreach $name (sort { $file{$a}[0] <=> $file{$b}[0] } keys %file) {
291         my $fh = $file{$name}[1];
292         my $line = <$fh>;
293         print "$name $. $line";
294     }
295
296 For passing filehandles to functions, the easiest way is to 
297 preface them with a star, as in func(*STDIN).  
298 See L<perlfaq7/"Passing Filehandles"> for details.
299
300 If you want to create many anonymous handles, you should check out the
301 Symbol, FileHandle, or IO::Handle (etc.) modules.  Here's the equivalent
302 code with Symbol::gensym, which is reasonably light-weight:
303
304     foreach $filename (@names) {
305         use Symbol;
306         my $fh = gensym();
307         open($fh, "/etc/$filename") || die "open /etc/$filename: $!";
308         $file{$filename} = [ $i++, $fh ];
309     }
310
311 Here's using the semi-object-oriented FileHandle module, which certainly
312 isn't light-weight:
313
314     use FileHandle;
315
316     foreach $filename (@names) {
317         my $fh = FileHandle->new("/etc/$filename") or die "$filename: $!";
318         $file{$filename} = [ $i++, $fh ];
319     }
320
321 Please understand that whether the filehandle happens to be a (probably
322 localized) typeglob or an anonymous handle from one of the modules
323 in no way affects the bizarre rules for managing indirect handles.
324 See the next question.
325
326 =head2 How can I use a filehandle indirectly?
327
328 An indirect filehandle is using something other than a symbol
329 in a place that a filehandle is expected.  Here are ways
330 to get indirect filehandles:
331
332     $fh =   SOME_FH;       # bareword is strict-subs hostile
333     $fh =  "SOME_FH";      # strict-refs hostile; same package only
334     $fh =  *SOME_FH;       # typeglob
335     $fh = \*SOME_FH;       # ref to typeglob (bless-able)
336     $fh =  *SOME_FH{IO};   # blessed IO::Handle from *SOME_FH typeglob
337
338 Or, you can use the C<new> method from the FileHandle or IO modules to
339 create an anonymous filehandle, store that in a scalar variable,
340 and use it as though it were a normal filehandle.
341
342     use FileHandle;
343     $fh = FileHandle->new();
344
345     use IO::Handle;                     # 5.004 or higher
346     $fh = IO::Handle->new();
347
348 Then use any of those as you would a normal filehandle.  Anywhere that
349 Perl is expecting a filehandle, an indirect filehandle may be used
350 instead. An indirect filehandle is just a scalar variable that contains
351 a filehandle.  Functions like C<print>, C<open>, C<seek>, or
352 the C<< <FH> >> diamond operator will accept either a read filehandle
353 or a scalar variable containing one:
354
355     ($ifh, $ofh, $efh) = (*STDIN, *STDOUT, *STDERR);
356     print $ofh "Type it: ";
357     $got = <$ifh>
358     print $efh "What was that: $got";
359
360 If you're passing a filehandle to a function, you can write
361 the function in two ways:
362
363     sub accept_fh {
364         my $fh = shift;
365         print $fh "Sending to indirect filehandle\n";
366     }
367
368 Or it can localize a typeglob and use the filehandle directly:
369
370     sub accept_fh {
371         local *FH = shift;
372         print  FH "Sending to localized filehandle\n";
373     }
374
375 Both styles work with either objects or typeglobs of real filehandles.
376 (They might also work with strings under some circumstances, but this
377 is risky.)
378
379     accept_fh(*STDOUT);
380     accept_fh($handle);
381
382 In the examples above, we assigned the filehandle to a scalar variable
383 before using it.  That is because only simple scalar variables, not
384 expressions or subscripts of hashes or arrays, can be used with
385 built-ins like C<print>, C<printf>, or the diamond operator.  Using
386 something other than a simple scalar varaible as a filehandle is
387 illegal and won't even compile:
388
389     @fd = (*STDIN, *STDOUT, *STDERR);
390     print $fd[1] "Type it: ";                           # WRONG
391     $got = <$fd[0]>                                     # WRONG
392     print $fd[2] "What was that: $got";                 # WRONG
393
394 With C<print> and C<printf>, you get around this by using a block and
395 an expression where you would place the filehandle:
396
397     print  { $fd[1] } "funny stuff\n";
398     printf { $fd[1] } "Pity the poor %x.\n", 3_735_928_559;
399     # Pity the poor deadbeef.
400
401 That block is a proper block like any other, so you can put more
402 complicated code there.  This sends the message out to one of two places:
403
404     $ok = -x "/bin/cat";                
405     print { $ok ? $fd[1] : $fd[2] } "cat stat $ok\n";
406     print { $fd[ 1+ ($ok || 0) ]  } "cat stat $ok\n";           
407
408 This approach of treating C<print> and C<printf> like object methods
409 calls doesn't work for the diamond operator.  That's because it's a
410 real operator, not just a function with a comma-less argument.  Assuming
411 you've been storing typeglobs in your structure as we did above, you
412 can use the built-in function named C<readline> to reads a record just
413 as C<< <> >> does.  Given the initialization shown above for @fd, this
414 would work, but only because readline() require a typeglob.  It doesn't
415 work with objects or strings, which might be a bug we haven't fixed yet.
416
417     $got = readline($fd[0]);
418
419 Let it be noted that the flakiness of indirect filehandles is not
420 related to whether they're strings, typeglobs, objects, or anything else.
421 It's the syntax of the fundamental operators.  Playing the object
422 game doesn't help you at all here.
423
424 =head2 How can I set up a footer format to be used with write()?
425
426 There's no builtin way to do this, but L<perlform> has a couple of
427 techniques to make it possible for the intrepid hacker.
428
429 =head2 How can I write() into a string?
430
431 See L<perlform/"Accessing Formatting Internals"> for an swrite() function.
432
433 =head2 How can I output my numbers with commas added?
434
435 This one will do it for you:
436
437     sub commify {
438         local $_  = shift;
439         1 while s/^([-+]?\d+)(\d{3})/$1,$2/;
440         return $_;
441     }
442
443     $n = 23659019423.2331;
444     print "GOT: ", commify($n), "\n";
445
446     GOT: 23,659,019,423.2331
447
448 You can't just:
449
450     s/^([-+]?\d+)(\d{3})/$1,$2/g;
451
452 because you have to put the comma in and then recalculate your
453 position.
454
455 Alternatively, this code commifies all numbers in a line regardless of
456 whether they have decimal portions, are preceded by + or -, or
457 whatever:
458
459     # from Andrew Johnson <ajohnson@gpu.srv.ualberta.ca>
460     sub commify {
461        my $input = shift;
462         $input = reverse $input;
463         $input =~ s<(\d\d\d)(?=\d)(?!\d*\.)><$1,>g;
464         return scalar reverse $input;
465     }
466
467 =head2 How can I translate tildes (~) in a filename?
468
469 Use the <> (glob()) operator, documented in L<perlfunc>.  Older
470 versions of Perl require that you have a shell installed that groks
471 tildes.  Recent perl versions have this feature built in. The
472 File::KGlob module (available from CPAN) gives more portable glob
473 functionality.
474
475 Within Perl, you may use this directly:
476
477         $filename =~ s{
478           ^ ~             # find a leading tilde
479           (               # save this in $1
480               [^/]        # a non-slash character
481                     *     # repeated 0 or more times (0 means me)
482           )
483         }{
484           $1
485               ? (getpwnam($1))[7]
486               : ( $ENV{HOME} || $ENV{LOGDIR} )
487         }ex;
488
489 =head2 How come when I open a file read-write it wipes it out?
490
491 Because you're using something like this, which truncates the file and
492 I<then> gives you read-write access:
493
494     open(FH, "+> /path/name");          # WRONG (almost always)
495
496 Whoops.  You should instead use this, which will fail if the file
497 doesn't exist.  
498
499     open(FH, "+< /path/name");          # open for update
500
501 Using ">" always clobbers or creates.  Using "<" never does
502 either.  The "+" doesn't change this.
503
504 Here are examples of many kinds of file opens.  Those using sysopen()
505 all assume
506
507     use Fcntl;
508
509 To open file for reading:
510
511     open(FH, "< $path")                                 || die $!;
512     sysopen(FH, $path, O_RDONLY)                        || die $!;
513
514 To open file for writing, create new file if needed or else truncate old file:
515
516     open(FH, "> $path") || die $!;
517     sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT)        || die $!;
518     sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666)  || die $!;
519
520 To open file for writing, create new file, file must not exist:
521
522     sysopen(FH, $path, O_WRONLY|O_EXCL|O_CREAT)         || die $!;
523     sysopen(FH, $path, O_WRONLY|O_EXCL|O_CREAT, 0666)   || die $!;
524
525 To open file for appending, create if necessary:
526
527     open(FH, ">> $path") || die $!;
528     sysopen(FH, $path, O_WRONLY|O_APPEND|O_CREAT)       || die $!;
529     sysopen(FH, $path, O_WRONLY|O_APPEND|O_CREAT, 0666) || die $!;
530
531 To open file for appending, file must exist:
532
533     sysopen(FH, $path, O_WRONLY|O_APPEND)               || die $!;
534
535 To open file for update, file must exist:
536
537     open(FH, "+< $path")                                || die $!;
538     sysopen(FH, $path, O_RDWR)                          || die $!;
539
540 To open file for update, create file if necessary:
541
542     sysopen(FH, $path, O_RDWR|O_CREAT)                  || die $!;
543     sysopen(FH, $path, O_RDWR|O_CREAT, 0666)            || die $!;
544
545 To open file for update, file must not exist:
546
547     sysopen(FH, $path, O_RDWR|O_EXCL|O_CREAT)           || die $!;
548     sysopen(FH, $path, O_RDWR|O_EXCL|O_CREAT, 0666)     || die $!;
549
550 To open a file without blocking, creating if necessary:
551
552     sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT)
553             or die "can't open /tmp/somefile: $!":
554
555 Be warned that neither creation nor deletion of files is guaranteed to
556 be an atomic operation over NFS.  That is, two processes might both
557 successfully create or unlink the same file!  Therefore O_EXCL
558 isn't as exclusive as you might wish.
559
560 See also the new L<perlopentut> if you have it (new for 5.6).
561
562 =head2 Why do I sometimes get an "Argument list too long" when I use <*>?
563
564 The C<< <> >> operator performs a globbing operation (see above).
565 In Perl versions earlier than v5.6.0, the internal glob() operator forks
566 csh(1) to do the actual glob expansion, but
567 csh can't handle more than 127 items and so gives the error message
568 C<Argument list too long>.  People who installed tcsh as csh won't
569 have this problem, but their users may be surprised by it.
570
571 To get around this, either upgrade to Perl v5.6.0 or later, do the glob
572 yourself with readdir() and patterns, or use a module like File::KGlob,
573 one that doesn't use the shell to do globbing.
574
575 =head2 Is there a leak/bug in glob()?
576
577 Due to the current implementation on some operating systems, when you
578 use the glob() function or its angle-bracket alias in a scalar
579 context, you may cause a memory leak and/or unpredictable behavior.  It's
580 best therefore to use glob() only in list context.
581
582 =head2 How can I open a file with a leading ">" or trailing blanks?
583
584 Normally perl ignores trailing blanks in filenames, and interprets
585 certain leading characters (or a trailing "|") to mean something
586 special.  To avoid this, you might want to use a routine like the one below.
587 It turns incomplete pathnames into explicit relative ones, and tacks a
588 trailing null byte on the name to make perl leave it alone:
589
590     sub safe_filename {
591         local $_  = shift;
592         s#^([^./])#./$1#;
593         $_ .= "\0";
594         return $_;
595     }
596
597     $badpath = "<<<something really wicked   ";
598     $fn = safe_filename($badpath");
599     open(FH, "> $fn") or "couldn't open $badpath: $!";
600
601 This assumes that you are using POSIX (portable operating systems
602 interface) paths.  If you are on a closed, non-portable, proprietary
603 system, you may have to adjust the C<"./"> above.
604
605 It would be a lot clearer to use sysopen(), though:
606
607     use Fcntl;
608     $badpath = "<<<something really wicked   ";
609     sysopen (FH, $badpath, O_WRONLY | O_CREAT | O_TRUNC)
610         or die "can't open $badpath: $!";
611
612 For more information, see also the new L<perlopentut> if you have it
613 (new for 5.6).
614
615 =head2 How can I reliably rename a file?
616
617 Well, usually you just use Perl's rename() function.  That may not
618 work everywhere, though, particularly when renaming files across file systems.
619 Some sub-Unix systems have broken ports that corrupt the semantics of
620 rename()--for example, WinNT does this right, but Win95 and Win98
621 are broken.  (The last two parts are not surprising, but the first is. :-)
622
623 If your operating system supports a proper mv(1) program or its moral
624 equivalent, this works:
625
626     rename($old, $new) or system("mv", $old, $new);
627
628 It may be more compelling to use the File::Copy module instead.  You
629 just copy to the new file to the new name (checking return values),
630 then delete the old one.  This isn't really the same semantically as a
631 real rename(), though, which preserves metainformation like
632 permissions, timestamps, inode info, etc.
633
634 Newer versions of File::Copy exports a move() function.
635
636 =head2 How can I lock a file?
637
638 Perl's builtin flock() function (see L<perlfunc> for details) will call
639 flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and
640 later), and lockf(3) if neither of the two previous system calls exists.
641 On some systems, it may even use a different form of native locking.
642 Here are some gotchas with Perl's flock():
643
644 =over 4
645
646 =item 1
647
648 Produces a fatal error if none of the three system calls (or their
649 close equivalent) exists.
650
651 =item 2
652
653 lockf(3) does not provide shared locking, and requires that the
654 filehandle be open for writing (or appending, or read/writing).
655
656 =item 3
657
658 Some versions of flock() can't lock files over a network (e.g. on NFS file
659 systems), so you'd need to force the use of fcntl(2) when you build Perl.
660 But even this is dubious at best.  See the flock entry of L<perlfunc>
661 and the F<INSTALL> file in the source distribution for information on
662 building Perl to do this.
663
664 Two potentially non-obvious but traditional flock semantics are that
665 it waits indefinitely until the lock is granted, and that its locks are
666 I<merely advisory>.  Such discretionary locks are more flexible, but
667 offer fewer guarantees.  This means that files locked with flock() may
668 be modified by programs that do not also use flock().  Cars that stop
669 for red lights get on well with each other, but not with cars that don't
670 stop for red lights.  See the perlport manpage, your port's specific
671 documentation, or your system-specific local manpages for details.  It's
672 best to assume traditional behavior if you're writing portable programs.
673 (If you're not, you should as always feel perfectly free to write
674 for your own system's idiosyncrasies (sometimes called "features").
675 Slavish adherence to portability concerns shouldn't get in the way of
676 your getting your job done.)
677
678 For more information on file locking, see also 
679 L<perlopentut/"File Locking"> if you have it (new for 5.6).
680
681 =back
682
683 =head2 Why can't I just open(FH, ">file.lock")?
684
685 A common bit of code B<NOT TO USE> is this:
686
687     sleep(3) while -e "file.lock";      # PLEASE DO NOT USE
688     open(LCK, "> file.lock");           # THIS BROKEN CODE
689
690 This is a classic race condition: you take two steps to do something
691 which must be done in one.  That's why computer hardware provides an
692 atomic test-and-set instruction.   In theory, this "ought" to work:
693
694     sysopen(FH, "file.lock", O_WRONLY|O_EXCL|O_CREAT)
695                 or die "can't open  file.lock: $!":
696
697 except that lamentably, file creation (and deletion) is not atomic
698 over NFS, so this won't work (at least, not every time) over the net.
699 Various schemes involving link() have been suggested, but
700 these tend to involve busy-wait, which is also subdesirable.
701
702 =head2 I still don't get locking.  I just want to increment the number in the file.  How can I do this?
703
704 Didn't anyone ever tell you web-page hit counters were useless?
705 They don't count number of hits, they're a waste of time, and they serve
706 only to stroke the writer's vanity.  It's better to pick a random number;
707 they're more realistic.
708
709 Anyway, this is what you can do if you can't help yourself.
710
711     use Fcntl qw(:DEFAULT :flock);
712     sysopen(FH, "numfile", O_RDWR|O_CREAT)       or die "can't open numfile: $!";
713     flock(FH, LOCK_EX)                           or die "can't flock numfile: $!";
714     $num = <FH> || 0;
715     seek(FH, 0, 0)                               or die "can't rewind numfile: $!";
716     truncate(FH, 0)                              or die "can't truncate numfile: $!";
717     (print FH $num+1, "\n")                      or die "can't write numfile: $!";
718     close FH                                     or die "can't close numfile: $!";
719
720 Here's a much better web-page hit counter:
721
722     $hits = int( (time() - 850_000_000) / rand(1_000) );
723
724 If the count doesn't impress your friends, then the code might.  :-)
725
726 =head2 All I want to do is append a small amount of text to the end of a file.  Do I still have to use locking?
727
728 If you are on a system that correctly implements flock() and you use the
729 example appending code from "perldoc -f flock" everything will be OK
730 even if the OS you are on doesn't implement append mode correctly (if
731 such a system exists.) So if you are happy to restrict yourself to OSs
732 that implement flock() (and that's not really much of a restriction)
733 then that is what you should do.
734
735 If you know you are only going to use a system that does correctly
736 implement appending (i.e. not Win32) then you can omit the seek() from
737 the above code.
738
739 If you know you are only writing code to run on an OS and filesystem that
740 does implement append mode correctly (a local filesystem on a modern
741 Unix for example), and you keep the file in block-buffered mode and you
742 write less than one buffer-full of output between each manual flushing
743 of the buffer then each bufferload is almost garanteed to be written to
744 the end of the file in one chunk without getting intermingled with
745 anyone else's output. You can also use the syswrite() function which is
746 simply a wrapper around your systems write(2) system call.
747
748 There is still a small theoretical chance that a signal will interrupt
749 the system level write() operation before completion.  There is also a
750 possibility that some STDIO implementations may call multiple system
751 level write()s even if the buffer was empty to start.  There may be some
752 systems where this probability is reduced to zero.
753
754 =head2 How do I randomly update a binary file?
755
756 If you're just trying to patch a binary, in many cases something as
757 simple as this works:
758
759     perl -i -pe 's{window manager}{window mangler}g' /usr/bin/emacs
760
761 However, if you have fixed sized records, then you might do something more
762 like this:
763
764     $RECSIZE = 220; # size of record, in bytes
765     $recno   = 37;  # which record to update
766     open(FH, "+<somewhere") || die "can't update somewhere: $!";
767     seek(FH, $recno * $RECSIZE, 0);
768     read(FH, $record, $RECSIZE) == $RECSIZE || die "can't read record $recno: $!";
769     # munge the record
770     seek(FH, -$RECSIZE, 1);
771     print FH $record;
772     close FH;
773
774 Locking and error checking are left as an exercise for the reader.
775 Don't forget them or you'll be quite sorry.
776
777 =head2 How do I get a file's timestamp in perl?
778
779 If you want to retrieve the time at which the file was last read,
780 written, or had its meta-data (owner, etc) changed, you use the B<-M>,
781 B<-A>, or B<-C> filetest operations as documented in L<perlfunc>.  These
782 retrieve the age of the file (measured against the start-time of your
783 program) in days as a floating point number.  To retrieve the "raw"
784 time in seconds since the epoch, you would call the stat function,
785 then use localtime(), gmtime(), or POSIX::strftime() to convert this
786 into human-readable form.
787
788 Here's an example:
789
790     $write_secs = (stat($file))[9];
791     printf "file %s updated at %s\n", $file,
792         scalar localtime($write_secs);
793
794 If you prefer something more legible, use the File::stat module
795 (part of the standard distribution in version 5.004 and later):
796
797     # error checking left as an exercise for reader.
798     use File::stat;
799     use Time::localtime;
800     $date_string = ctime(stat($file)->mtime);
801     print "file $file updated at $date_string\n";
802
803 The POSIX::strftime() approach has the benefit of being,
804 in theory, independent of the current locale.  See L<perllocale>
805 for details.
806
807 =head2 How do I set a file's timestamp in perl?
808
809 You use the utime() function documented in L<perlfunc/utime>.
810 By way of example, here's a little program that copies the
811 read and write times from its first argument to all the rest
812 of them.
813
814     if (@ARGV < 2) {
815         die "usage: cptimes timestamp_file other_files ...\n";
816     }
817     $timestamp = shift;
818     ($atime, $mtime) = (stat($timestamp))[8,9];
819     utime $atime, $mtime, @ARGV;
820
821 Error checking is, as usual, left as an exercise for the reader.
822
823 Note that utime() currently doesn't work correctly with Win95/NT
824 ports.  A bug has been reported.  Check it carefully before using
825 utime() on those platforms.
826
827 =head2 How do I print to more than one file at once?
828
829 If you only have to do this once, you can do this:
830
831     for $fh (FH1, FH2, FH3) { print $fh "whatever\n" }
832
833 To connect up to one filehandle to several output filehandles, it's
834 easiest to use the tee(1) program if you have it, and let it take care
835 of the multiplexing:
836
837     open (FH, "| tee file1 file2 file3");
838
839 Or even:
840
841     # make STDOUT go to three files, plus original STDOUT
842     open (STDOUT, "| tee file1 file2 file3") or die "Teeing off: $!\n";
843     print "whatever\n"                       or die "Writing: $!\n";
844     close(STDOUT)                            or die "Closing: $!\n";
845
846 Otherwise you'll have to write your own multiplexing print
847 function--or your own tee program--or use Tom Christiansen's,
848 at http://www.perl.com/CPAN/authors/id/TOMC/scripts/tct.gz , which is
849 written in Perl and offers much greater functionality
850 than the stock version.
851
852 =head2 How can I read in an entire file all at once?
853
854 The customary Perl approach for processing all the lines in a file is to
855 do so one line at a time:
856
857     open (INPUT, $file)         || die "can't open $file: $!";
858     while (<INPUT>) {
859         chomp;
860         # do something with $_
861     } 
862     close(INPUT)                || die "can't close $file: $!";
863
864 This is tremendously more efficient than reading the entire file into
865 memory as an array of lines and then processing it one element at a time,
866 which is often--if not almost always--the wrong approach.  Whenever
867 you see someone do this:
868
869     @lines = <INPUT>;
870
871 you should think long and hard about why you need everything loaded
872 at once.  It's just not a scalable solution.  You might also find it
873 more fun to use the standard DB_File module's $DB_RECNO bindings,
874 which allow you to tie an array to a file so that accessing an element
875 the array actually accesses the corresponding line in the file.
876
877 On very rare occasion, you may have an algorithm that demands that
878 the entire file be in memory at once as one scalar.  The simplest solution
879 to that is
880
881     $var = `cat $file`;
882
883 Being in scalar context, you get the whole thing.  In list context,
884 you'd get a list of all the lines:
885
886     @lines = `cat $file`;
887
888 This tiny but expedient solution is neat, clean, and portable to
889 all systems on which decent tools have been installed.  For those
890 who prefer not to use the toolbox, you can of course read the file
891 manually, although this makes for more complicated code.
892
893     {
894         local(*INPUT, $/);
895         open (INPUT, $file)     || die "can't open $file: $!";
896         $var = <INPUT>;
897     }
898
899 That temporarily undefs your record separator, and will automatically 
900 close the file at block exit.  If the file is already open, just use this:
901
902     $var = do { local $/; <INPUT> };
903
904 =head2 How can I read in a file by paragraphs?
905
906 Use the C<$/> variable (see L<perlvar> for details).  You can either
907 set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">,
908 for instance, gets treated as two paragraphs and not three), or
909 C<"\n\n"> to accept empty paragraphs.
910
911 Note that a blank line must have no blanks in it.  Thus C<"fred\n
912 \nstuff\n\n"> is one paragraph, but C<"fred\n\nstuff\n\n"> is two.
913
914 =head2 How can I read a single character from a file?  From the keyboard?
915
916 You can use the builtin C<getc()> function for most filehandles, but
917 it won't (easily) work on a terminal device.  For STDIN, either use
918 the Term::ReadKey module from CPAN or use the sample code in
919 L<perlfunc/getc>.
920
921 If your system supports the portable operating system programming
922 interface (POSIX), you can use the following code, which you'll note
923 turns off echo processing as well.
924
925     #!/usr/bin/perl -w
926     use strict;
927     $| = 1;
928     for (1..4) {
929         my $got;
930         print "gimme: ";
931         $got = getone();
932         print "--> $got\n";
933     }
934     exit;
935
936     BEGIN {
937         use POSIX qw(:termios_h);
938
939         my ($term, $oterm, $echo, $noecho, $fd_stdin);
940
941         $fd_stdin = fileno(STDIN);
942
943         $term     = POSIX::Termios->new();
944         $term->getattr($fd_stdin);
945         $oterm     = $term->getlflag();
946
947         $echo     = ECHO | ECHOK | ICANON;
948         $noecho   = $oterm & ~$echo;
949
950         sub cbreak {
951             $term->setlflag($noecho);
952             $term->setcc(VTIME, 1);
953             $term->setattr($fd_stdin, TCSANOW);
954         }
955
956         sub cooked {
957             $term->setlflag($oterm);
958             $term->setcc(VTIME, 0);
959             $term->setattr($fd_stdin, TCSANOW);
960         }
961
962         sub getone {
963             my $key = '';
964             cbreak();
965             sysread(STDIN, $key, 1);
966             cooked();
967             return $key;
968         }
969
970     }
971
972     END { cooked() }
973
974 The Term::ReadKey module from CPAN may be easier to use.  Recent versions
975 include also support for non-portable systems as well.
976
977     use Term::ReadKey;
978     open(TTY, "</dev/tty");
979     print "Gimme a char: ";
980     ReadMode "raw";
981     $key = ReadKey 0, *TTY;
982     ReadMode "normal";
983     printf "\nYou said %s, char number %03d\n",
984         $key, ord $key;
985
986 =head2 How can I tell whether there's a character waiting on a filehandle?
987
988 The very first thing you should do is look into getting the Term::ReadKey
989 extension from CPAN.  As we mentioned earlier, it now even has limited
990 support for non-portable (read: not open systems, closed, proprietary,
991 not POSIX, not Unix, etc) systems.
992
993 You should also check out the Frequently Asked Questions list in
994 comp.unix.* for things like this: the answer is essentially the same.
995 It's very system dependent.  Here's one solution that works on BSD
996 systems:
997
998     sub key_ready {
999         my($rin, $nfd);
1000         vec($rin, fileno(STDIN), 1) = 1;
1001         return $nfd = select($rin,undef,undef,0);
1002     }
1003
1004 If you want to find out how many characters are waiting, there's
1005 also the FIONREAD ioctl call to be looked at.  The I<h2ph> tool that
1006 comes with Perl tries to convert C include files to Perl code, which
1007 can be C<require>d.  FIONREAD ends up defined as a function in the
1008 I<sys/ioctl.ph> file:
1009
1010     require 'sys/ioctl.ph';
1011
1012     $size = pack("L", 0);
1013     ioctl(FH, FIONREAD(), $size)    or die "Couldn't call ioctl: $!\n";
1014     $size = unpack("L", $size);
1015
1016 If I<h2ph> wasn't installed or doesn't work for you, you can
1017 I<grep> the include files by hand:
1018
1019     % grep FIONREAD /usr/include/*/*
1020     /usr/include/asm/ioctls.h:#define FIONREAD      0x541B
1021
1022 Or write a small C program using the editor of champions:
1023
1024     % cat > fionread.c
1025     #include <sys/ioctl.h>
1026     main() {
1027         printf("%#08x\n", FIONREAD);
1028     }
1029     ^D
1030     % cc -o fionread fionread.c
1031     % ./fionread
1032     0x4004667f
1033
1034 And then hard-code it, leaving porting as an exercise to your successor.
1035
1036     $FIONREAD = 0x4004667f;         # XXX: opsys dependent
1037
1038     $size = pack("L", 0);
1039     ioctl(FH, $FIONREAD, $size)     or die "Couldn't call ioctl: $!\n";
1040     $size = unpack("L", $size);
1041
1042 FIONREAD requires a filehandle connected to a stream, meaning that sockets,
1043 pipes, and tty devices work, but I<not> files.
1044
1045 =head2 How do I do a C<tail -f> in perl?
1046
1047 First try
1048
1049     seek(GWFILE, 0, 1);
1050
1051 The statement C<seek(GWFILE, 0, 1)> doesn't change the current position,
1052 but it does clear the end-of-file condition on the handle, so that the
1053 next <GWFILE> makes Perl try again to read something.
1054
1055 If that doesn't work (it relies on features of your stdio implementation),
1056 then you need something more like this:
1057
1058         for (;;) {
1059           for ($curpos = tell(GWFILE); <GWFILE>; $curpos = tell(GWFILE)) {
1060             # search for some stuff and put it into files
1061           }
1062           # sleep for a while
1063           seek(GWFILE, $curpos, 0);  # seek to where we had been
1064         }
1065
1066 If this still doesn't work, look into the POSIX module.  POSIX defines
1067 the clearerr() method, which can remove the end of file condition on a
1068 filehandle.  The method: read until end of file, clearerr(), read some
1069 more.  Lather, rinse, repeat.
1070
1071 There's also a File::Tail module from CPAN.
1072
1073 =head2 How do I dup() a filehandle in Perl?
1074
1075 If you check L<perlfunc/open>, you'll see that several of the ways
1076 to call open() should do the trick.  For example:
1077
1078     open(LOG, ">>/tmp/logfile");
1079     open(STDERR, ">&LOG");
1080
1081 Or even with a literal numeric descriptor:
1082
1083    $fd = $ENV{MHCONTEXTFD};
1084    open(MHCONTEXT, "<&=$fd");   # like fdopen(3S)
1085
1086 Note that "<&STDIN" makes a copy, but "<&=STDIN" make
1087 an alias.  That means if you close an aliased handle, all
1088 aliases become inaccessible.  This is not true with 
1089 a copied one.
1090
1091 Error checking, as always, has been left as an exercise for the reader.
1092
1093 =head2 How do I close a file descriptor by number?
1094
1095 This should rarely be necessary, as the Perl close() function is to be
1096 used for things that Perl opened itself, even if it was a dup of a
1097 numeric descriptor as with MHCONTEXT above.  But if you really have
1098 to, you may be able to do this:
1099
1100     require 'sys/syscall.ph';
1101     $rc = syscall(&SYS_close, $fd + 0);  # must force numeric
1102     die "can't sysclose $fd: $!" unless $rc == -1;
1103
1104 Or, just use the fdopen(3S) feature of open():
1105
1106     { 
1107         local *F; 
1108         open F, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
1109         close F;
1110     }
1111
1112 =head2 Why can't I use "C:\temp\foo" in DOS paths?  What doesn't `C:\temp\foo.exe` work?
1113
1114 Whoops!  You just put a tab and a formfeed into that filename!
1115 Remember that within double quoted strings ("like\this"), the
1116 backslash is an escape character.  The full list of these is in
1117 L<perlop/Quote and Quote-like Operators>.  Unsurprisingly, you don't
1118 have a file called "c:(tab)emp(formfeed)oo" or
1119 "c:(tab)emp(formfeed)oo.exe" on your legacy DOS filesystem.
1120
1121 Either single-quote your strings, or (preferably) use forward slashes.
1122 Since all DOS and Windows versions since something like MS-DOS 2.0 or so
1123 have treated C</> and C<\> the same in a path, you might as well use the
1124 one that doesn't clash with Perl--or the POSIX shell, ANSI C and C++,
1125 awk, Tcl, Java, or Python, just to mention a few.  POSIX paths
1126 are more portable, too.
1127
1128 =head2 Why doesn't glob("*.*") get all the files?
1129
1130 Because even on non-Unix ports, Perl's glob function follows standard
1131 Unix globbing semantics.  You'll need C<glob("*")> to get all (non-hidden)
1132 files.  This makes glob() portable even to legacy systems.  Your
1133 port may include proprietary globbing functions as well.  Check its
1134 documentation for details.
1135
1136 =head2 Why does Perl let me delete read-only files?  Why does C<-i> clobber protected files?  Isn't this a bug in Perl?
1137
1138 This is elaborately and painstakingly described in the "Far More Than
1139 You Ever Wanted To Know" in
1140 http://www.perl.com/CPAN/doc/FMTEYEWTK/file-dir-perms .
1141
1142 The executive summary: learn how your filesystem works.  The
1143 permissions on a file say what can happen to the data in that file.
1144 The permissions on a directory say what can happen to the list of
1145 files in that directory.  If you delete a file, you're removing its
1146 name from the directory (so the operation depends on the permissions
1147 of the directory, not of the file).  If you try to write to the file,
1148 the permissions of the file govern whether you're allowed to.
1149
1150 =head2 How do I select a random line from a file?
1151
1152 Here's an algorithm from the Camel Book:
1153
1154     srand;
1155     rand($.) < 1 && ($line = $_) while <>;
1156
1157 This has a significant advantage in space over reading the whole
1158 file in.  A simple proof by induction is available upon 
1159 request if you doubt the algorithm's correctness.
1160
1161 =head2 Why do I get weird spaces when I print an array of lines?
1162
1163 Saying
1164
1165     print "@lines\n";
1166
1167 joins together the elements of C<@lines> with a space between them.
1168 If C<@lines> were C<("little", "fluffy", "clouds")> then the above
1169 statement would print
1170
1171     little fluffy clouds
1172
1173 but if each element of C<@lines> was a line of text, ending a newline
1174 character C<("little\n", "fluffy\n", "clouds\n")> then it would print:
1175
1176     little
1177      fluffy
1178      clouds
1179
1180 If your array contains lines, just print them:
1181
1182     print @lines;
1183
1184 =head1 AUTHOR AND COPYRIGHT
1185
1186 Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington.
1187 All rights reserved.
1188
1189 When included as an integrated part of the Standard Distribution
1190 of Perl or of its documentation (printed or otherwise), this works is
1191 covered under Perl's Artistic License.  For separate distributions of
1192 all or part of this FAQ outside of that, see L<perlfaq>.
1193
1194 Irrespective of its distribution, all code examples here are in the public
1195 domain.  You are permitted and encouraged to use this code and any
1196 derivatives thereof in your own programs for fun or for profit as you
1197 see fit.  A simple comment in the code giving credit to the FAQ would
1198 be courteous but is not required.