1perlfaq5(3)           User Contributed Perl Documentation          perlfaq5(3)
2
3
4

NAME

6       perlfaq5 - Files and Formats
7

VERSION

9       version 5.20230812
10

DESCRIPTION

12       This section deals with I/O and the "f" issues: filehandles, flushing,
13       formats, and footers.
14
15   How do I flush/unbuffer an output filehandle? Why must I do this?
16       (contributed by brian d foy)
17
18       You might like to read Mark Jason Dominus's "Suffering From Buffering"
19       at <http://perl.plover.com/FAQs/Buffering.html> .
20
21       Perl normally buffers output so it doesn't make a system call for every
22       bit of output. By saving up output, it makes fewer expensive system
23       calls.  For instance, in this little bit of code, you want to print a
24       dot to the screen for every line you process to watch the progress of
25       your program.  Instead of seeing a dot for every line, Perl buffers the
26       output and you have a long wait before you see a row of 50 dots all at
27       once:
28
29           # long wait, then row of dots all at once
30           while( <> ) {
31               print ".";
32               print "\n" unless ++$count % 50;
33
34               #... expensive line processing operations
35           }
36
37       To get around this, you have to unbuffer the output filehandle, in this
38       case, "STDOUT". You can set the special variable $| to a true value
39       (mnemonic: making your filehandles "piping hot"):
40
41           $|++;
42
43           # dot shown immediately
44           while( <> ) {
45               print ".";
46               print "\n" unless ++$count % 50;
47
48               #... expensive line processing operations
49           }
50
51       The $| is one of the per-filehandle special variables, so each
52       filehandle has its own copy of its value. If you want to merge standard
53       output and standard error for instance, you have to unbuffer each
54       (although STDERR might be unbuffered by default):
55
56           {
57               my $previous_default = select(STDOUT);  # save previous default
58               $|++;                                   # autoflush STDOUT
59               select(STDERR);
60               $|++;                                   # autoflush STDERR, to be sure
61               select($previous_default);              # restore previous default
62           }
63
64           # now should alternate . and +
65           while( 1 ) {
66               sleep 1;
67               print STDOUT ".";
68               print STDERR "+";
69               print STDOUT "\n" unless ++$count % 25;
70           }
71
72       Besides the $| special variable, you can use "binmode" to give your
73       filehandle a ":unix" layer, which is unbuffered:
74
75           binmode( STDOUT, ":unix" );
76
77           while( 1 ) {
78               sleep 1;
79               print ".";
80               print "\n" unless ++$count % 50;
81           }
82
83       For more information on output layers, see the entries for "binmode"
84       and open in perlfunc, and the PerlIO module documentation.
85
86       If you are using IO::Handle or one of its subclasses, you can call the
87       "autoflush" method to change the settings of the filehandle:
88
89           use IO::Handle;
90           open my( $io_fh ), ">", "output.txt";
91           $io_fh->autoflush(1);
92
93       The IO::Handle objects also have a "flush" method. You can flush the
94       buffer any time you want without auto-buffering
95
96           $io_fh->flush;
97
98   How do I change, delete, or insert a line in a file, or append to the
99       beginning of a file?
100       (contributed by brian d foy)
101
102       The basic idea of inserting, changing, or deleting a line from a text
103       file involves reading and printing the file to the point you want to
104       make the change, making the change, then reading and printing the rest
105       of the file. Perl doesn't provide random access to lines (especially
106       since the record input separator, $/, is mutable), although modules
107       such as Tie::File can fake it.
108
109       A Perl program to do these tasks takes the basic form of opening a
110       file, printing its lines, then closing the file:
111
112           open my $in,  '<',  $file      or die "Can't read old file: $!";
113           open my $out, '>', "$file.new" or die "Can't write new file: $!";
114
115           while( <$in> ) {
116                   print $out $_;
117           }
118
119           close $out;
120
121       Within that basic form, add the parts that you need to insert, change,
122       or delete lines.
123
124       To prepend lines to the beginning, print those lines before you enter
125       the loop that prints the existing lines.
126
127           open my $in,  '<',  $file      or die "Can't read old file: $!";
128           open my $out, '>', "$file.new" or die "Can't write new file: $!";
129
130           print $out "# Add this line to the top\n"; # <--- HERE'S THE MAGIC
131
132           while( <$in> ) {
133                   print $out $_;
134           }
135
136           close $out;
137
138       To change existing lines, insert the code to modify the lines inside
139       the "while" loop. In this case, the code finds all lowercased versions
140       of "perl" and uppercases them. The happens for every line, so be sure
141       that you're supposed to do that on every line!
142
143           open my $in,  '<',  $file      or die "Can't read old file: $!";
144           open my $out, '>', "$file.new" or die "Can't write new file: $!";
145
146           print $out "# Add this line to the top\n";
147
148           while( <$in> ) {
149               s/\b(perl)\b/Perl/g;
150               print $out $_;
151           }
152
153           close $out;
154
155       To change only a particular line, the input line number, $., is useful.
156       First read and print the lines up to the one you  want to change. Next,
157       read the single line you want to change, change it, and print it. After
158       that, read the rest of the lines and print those:
159
160           while( <$in> ) { # print the lines before the change
161               print $out $_;
162               last if $. == 4; # line number before change
163           }
164
165           my $line = <$in>;
166           $line =~ s/\b(perl)\b/Perl/g;
167           print $out $line;
168
169           while( <$in> ) { # print the rest of the lines
170               print $out $_;
171           }
172
173       To skip lines, use the looping controls. The "next" in this example
174       skips comment lines, and the "last" stops all processing once it
175       encounters either "__END__" or "__DATA__".
176
177           while( <$in> ) {
178               next if /^\s+#/;             # skip comment lines
179               last if /^__(END|DATA)__$/;  # stop at end of code marker
180               print $out $_;
181           }
182
183       Do the same sort of thing to delete a particular line by using "next"
184       to skip the lines you don't want to show up in the output. This example
185       skips every fifth line:
186
187           while( <$in> ) {
188               next unless $. % 5;
189               print $out $_;
190           }
191
192       If, for some odd reason, you really want to see the whole file at once
193       rather than processing line-by-line, you can slurp it in (as long as
194       you can fit the whole thing in memory!):
195
196           open my $in,  '<',  $file      or die "Can't read old file: $!"
197           open my $out, '>', "$file.new" or die "Can't write new file: $!";
198
199           my $content = do { local $/; <$in> }; # slurp!
200
201               # do your magic here
202
203           print $out $content;
204
205       Modules such as Path::Tiny and Tie::File can help with that too. If you
206       can, however, avoid reading the entire file at once. Perl won't give
207       that memory back to the operating system until the process finishes.
208
209       You can also use Perl one-liners to modify a file in-place. The
210       following changes all 'Fred' to 'Barney' in inFile.txt, overwriting the
211       file with the new contents. With the "-p" switch, Perl wraps a "while"
212       loop around the code you specify with "-e", and "-i" turns on in-place
213       editing. The current line is in $_. With "-p", Perl automatically
214       prints the value of $_ at the end of the loop. See perlrun for more
215       details.
216
217           perl -pi -e 's/Fred/Barney/' inFile.txt
218
219       To make a backup of "inFile.txt", give "-i" a file extension to add:
220
221           perl -pi.bak -e 's/Fred/Barney/' inFile.txt
222
223       To change only the fifth line, you can add a test checking $., the
224       input line number, then only perform the operation when the test
225       passes:
226
227           perl -pi -e 's/Fred/Barney/ if $. == 5' inFile.txt
228
229       To add lines before a certain line, you can add a line (or lines!)
230       before Perl prints $_:
231
232           perl -pi -e 'print "Put before third line\n" if $. == 3' inFile.txt
233
234       You can even add a line to the beginning of a file, since the current
235       line prints at the end of the loop:
236
237           perl -pi -e 'print "Put before first line\n" if $. == 1' inFile.txt
238
239       To insert a line after one already in the file, use the "-n" switch.
240       It's just like "-p" except that it doesn't print $_ at the end of the
241       loop, so you have to do that yourself. In this case, print $_ first,
242       then print the line that you want to add.
243
244           perl -ni -e 'print; print "Put after fifth line\n" if $. == 5' inFile.txt
245
246       To delete lines, only print the ones that you want.
247
248           perl -ni -e 'print if /d/' inFile.txt
249
250   How do I count the number of lines in a file?
251       (contributed by brian d foy)
252
253       Conceptually, the easiest way to count the lines in a file is to simply
254       read them and count them:
255
256           my $count = 0;
257           while( <$fh> ) { $count++; }
258
259       You don't really have to count them yourself, though, since Perl
260       already does that with the $. variable, which is the current line
261       number from the last filehandle read:
262
263           1 while( <$fh> );
264           my $count = $.;
265
266       If you want to use $., you can reduce it to a simple one-liner, like
267       one of these:
268
269           % perl -lne '} print $.; {'    file
270
271           % perl -lne 'END { print $. }' file
272
273       Those can be rather inefficient though. If they aren't fast enough for
274       you, you might just read chunks of data and count the number of
275       newlines:
276
277           my $lines = 0;
278           open my($fh), '<:raw', $filename or die "Can't open $filename: $!";
279           while( sysread $fh, $buffer, 4096 ) {
280               $lines += ( $buffer =~ tr/\n// );
281           }
282           close $fh;
283
284       However, that doesn't work if the line ending isn't a newline. You
285       might change that "tr///" to a "s///" so you can count the number of
286       times the input record separator, $/, shows up:
287
288           my $lines = 0;
289           open my($fh), '<:raw', $filename or die "Can't open $filename: $!";
290           while( sysread $fh, $buffer, 4096 ) {
291               $lines += ( $buffer =~ s|$/||g; );
292           }
293           close $fh;
294
295       If you don't mind shelling out, the "wc" command is usually the
296       fastest, even with the extra interprocess overhead. Ensure that you
297       have an untainted filename though:
298
299           #!perl -T
300
301           $ENV{PATH} = undef;
302
303           my $lines;
304           if( $filename =~ /^([0-9a-z_.]+)\z/ ) {
305               $lines = `/usr/bin/wc -l $1`
306               chomp $lines;
307           }
308
309   How do I delete the last N lines from a file?
310       (contributed by brian d foy)
311
312       The easiest conceptual solution is to count the lines in the file then
313       start at the beginning and print the number of lines (minus the last N)
314       to a new file.
315
316       Most often, the real question is how you can delete the last N lines
317       without making more than one pass over the file, or how to do it
318       without a lot of copying. The easy concept is the hard reality when you
319       might have millions of lines in your file.
320
321       One trick is to use File::ReadBackwards, which starts at the end of the
322       file. That module provides an object that wraps the real filehandle to
323       make it easy for you to move around the file. Once you get to the spot
324       you need, you can get the actual filehandle and work with it as normal.
325       In this case, you get the file position at the end of the last line you
326       want to keep and truncate the file to that point:
327
328           use File::ReadBackwards;
329
330           my $filename = 'test.txt';
331           my $Lines_to_truncate = 2;
332
333           my $bw = File::ReadBackwards->new( $filename )
334               or die "Could not read backwards in [$filename]: $!";
335
336           my $lines_from_end = 0;
337           until( $bw->eof or $lines_from_end == $Lines_to_truncate ) {
338               print "Got: ", $bw->readline;
339               $lines_from_end++;
340           }
341
342           truncate( $filename, $bw->tell );
343
344       The File::ReadBackwards module also has the advantage of setting the
345       input record separator to a regular expression.
346
347       You can also use the Tie::File module which lets you access the lines
348       through a tied array. You can use normal array operations to modify
349       your file, including setting the last index and using "splice".
350
351   How can I use Perl's "-i" option from within a program?
352       "-i" sets the value of Perl's $^I variable, which in turn affects the
353       behavior of "<>"; see perlrun for more details. By modifying the
354       appropriate variables directly, you can get the same behavior within a
355       larger program. For example:
356
357           # ...
358           {
359               local($^I, @ARGV) = ('.orig', glob("*.c"));
360               while (<>) {
361                   if ($. == 1) {
362                       print "This line should appear at the top of each file\n";
363                   }
364                   s/\b(p)earl\b/${1}erl/i;        # Correct typos, preserving case
365                   print;
366                   close ARGV if eof;              # Reset $.
367               }
368           }
369           # $^I and @ARGV return to their old values here
370
371       This block modifies all the ".c" files in the current directory,
372       leaving a backup of the original data from each file in a new ".c.orig"
373       file.
374
375   How can I copy a file?
376       (contributed by brian d foy)
377
378       Use the File::Copy module. It comes with Perl and can do a true copy
379       across file systems, and it does its magic in a portable fashion.
380
381           use File::Copy;
382
383           copy( $original, $new_copy ) or die "Copy failed: $!";
384
385       If you can't use File::Copy, you'll have to do the work yourself: open
386       the original file, open the destination file, then print to the
387       destination file as you read the original. You also have to remember to
388       copy the permissions, owner, and group to the new file.
389
390   How do I make a temporary file name?
391       If you don't need to know the name of the file, you can use open() with
392       "undef" in place of the file name. In Perl 5.8 or later, the open()
393       function creates an anonymous temporary file:
394
395           open my $tmp, '+>', undef or die $!;
396
397       Otherwise, you can use the File::Temp module.
398
399           use File::Temp qw/ tempfile tempdir /;
400
401           my $dir = tempdir( CLEANUP => 1 );
402           ($fh, $filename) = tempfile( DIR => $dir );
403
404           # or if you don't need to know the filename
405
406           my $fh = tempfile( DIR => $dir );
407
408       The File::Temp has been a standard module since Perl 5.6.1. If you
409       don't have a modern enough Perl installed, use the "new_tmpfile" class
410       method from the IO::File module to get a filehandle opened for reading
411       and writing. Use it if you don't need to know the file's name:
412
413           use IO::File;
414           my $fh = IO::File->new_tmpfile()
415               or die "Unable to make new temporary file: $!";
416
417       If you're committed to creating a temporary file by hand, use the
418       process ID and/or the current time-value. If you need to have many
419       temporary files in one process, use a counter:
420
421           BEGIN {
422               use Fcntl;
423               use File::Spec;
424               my $temp_dir  = File::Spec->tmpdir();
425               my $file_base = sprintf "%d-%d-0000", $$, time;
426               my $base_name = File::Spec->catfile($temp_dir, $file_base);
427
428               sub temp_file {
429                   my $fh;
430                   my $count = 0;
431                   until( defined(fileno($fh)) || $count++ > 100 ) {
432                       $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
433                       # O_EXCL is required for security reasons.
434                       sysopen $fh, $base_name, O_WRONLY|O_EXCL|O_CREAT;
435                   }
436
437                   if( defined fileno($fh) ) {
438                       return ($fh, $base_name);
439                   }
440                   else {
441                       return ();
442                   }
443               }
444           }
445
446   How can I manipulate fixed-record-length files?
447       The most efficient way is using pack() and unpack(). This is faster
448       than using substr() when taking many, many strings. It is slower for
449       just a few.
450
451       Here is a sample chunk of code to break up and put back together again
452       some fixed-format input lines, in this case from the output of a
453       normal, Berkeley-style ps:
454
455           # sample input line:
456           #   15158 p5  T      0:00 perl /home/tchrist/scripts/now-what
457           my $PS_T = 'A6 A4 A7 A5 A*';
458           open my $ps, '-|', 'ps';
459           print scalar <$ps>;
460           my @fields = qw( pid tt stat time command );
461           while (<$ps>) {
462               my %process;
463               @process{@fields} = unpack($PS_T, $_);
464               for my $field ( @fields ) {
465                   print "$field: <$process{$field}>\n";
466               }
467               print 'line=', pack($PS_T, @process{@fields} ), "\n";
468           }
469
470       We've used a hash slice in order to easily handle the fields of each
471       row.  Storing the keys in an array makes it easy to operate on them as
472       a group or loop over them with "for". It also avoids polluting the
473       program with global variables and using symbolic references.
474
475   How can I make a filehandle local to a subroutine? How do I pass
476       filehandles between subroutines? How do I make an array of filehandles?
477       As of perl5.6, open() autovivifies file and directory handles as
478       references if you pass it an uninitialized scalar variable.  You can
479       then pass these references just like any other scalar, and use them in
480       the place of named handles.
481
482           open my    $fh, $file_name;
483
484           open local $fh, $file_name;
485
486           print $fh "Hello World!\n";
487
488           process_file( $fh );
489
490       If you like, you can store these filehandles in an array or a hash.  If
491       you access them directly, they aren't simple scalars and you need to
492       give "print" a little help by placing the filehandle reference in
493       braces. Perl can only figure it out on its own when the filehandle
494       reference is a simple scalar.
495
496           my @fhs = ( $fh1, $fh2, $fh3 );
497
498           for( $i = 0; $i <= $#fhs; $i++ ) {
499               print {$fhs[$i]} "just another Perl answer, \n";
500           }
501
502       Before perl5.6, you had to deal with various typeglob idioms which you
503       may see in older code.
504
505           open FILE, "> $filename";
506           process_typeglob(   *FILE );
507           process_reference( \*FILE );
508
509           sub process_typeglob  { local *FH = shift; print FH  "Typeglob!" }
510           sub process_reference { local $fh = shift; print $fh "Reference!" }
511
512       If you want to create many anonymous handles, you should check out the
513       Symbol or IO::Handle modules.
514
515   How can I use a filehandle indirectly?
516       An indirect filehandle is the use of something other than a symbol in a
517       place that a filehandle is expected. Here are ways to get indirect
518       filehandles:
519
520           $fh =   SOME_FH;       # bareword is strict-subs hostile
521           $fh =  "SOME_FH";      # strict-refs hostile; same package only
522           $fh =  *SOME_FH;       # typeglob
523           $fh = \*SOME_FH;       # ref to typeglob (bless-able)
524           $fh =  *SOME_FH{IO};   # blessed IO::Handle from *SOME_FH typeglob
525
526       Or, you can use the "new" method from one of the IO::* modules to
527       create an anonymous filehandle and store that in a scalar variable.
528
529           use IO::Handle;                     # 5.004 or higher
530           my $fh = IO::Handle->new();
531
532       Then use any of those as you would a normal filehandle. Anywhere that
533       Perl is expecting a filehandle, an indirect filehandle may be used
534       instead. An indirect filehandle is just a scalar variable that contains
535       a filehandle. Functions like "print", "open", "seek", or the "<FH>"
536       diamond operator will accept either a named filehandle or a scalar
537       variable containing one:
538
539           ($ifh, $ofh, $efh) = (*STDIN, *STDOUT, *STDERR);
540           print $ofh "Type it: ";
541           my $got = <$ifh>
542           print $efh "What was that: $got";
543
544       If you're passing a filehandle to a function, you can write the
545       function in two ways:
546
547           sub accept_fh {
548               my $fh = shift;
549               print $fh "Sending to indirect filehandle\n";
550           }
551
552       Or it can localize a typeglob and use the filehandle directly:
553
554           sub accept_fh {
555               local *FH = shift;
556               print  FH "Sending to localized filehandle\n";
557           }
558
559       Both styles work with either objects or typeglobs of real filehandles.
560       (They might also work with strings under some circumstances, but this
561       is risky.)
562
563           accept_fh(*STDOUT);
564           accept_fh($handle);
565
566       In the examples above, we assigned the filehandle to a scalar variable
567       before using it. That is because only simple scalar variables, not
568       expressions or subscripts of hashes or arrays, can be used with built-
569       ins like "print", "printf", or the diamond operator. Using something
570       other than a simple scalar variable as a filehandle is illegal and
571       won't even compile:
572
573           my @fd = (*STDIN, *STDOUT, *STDERR);
574           print $fd[1] "Type it: ";                           # WRONG
575           my $got = <$fd[0]>                                  # WRONG
576           print $fd[2] "What was that: $got";                 # WRONG
577
578       With "print" and "printf", you get around this by using a block and an
579       expression where you would place the filehandle:
580
581           print  { $fd[1] } "funny stuff\n";
582           printf { $fd[1] } "Pity the poor %x.\n", 3_735_928_559;
583           # Pity the poor deadbeef.
584
585       That block is a proper block like any other, so you can put more
586       complicated code there. This sends the message out to one of two
587       places:
588
589           my $ok = -x "/bin/cat";
590           print { $ok ? $fd[1] : $fd[2] } "cat stat $ok\n";
591           print { $fd[ 1+ ($ok || 0) ]  } "cat stat $ok\n";
592
593       This approach of treating "print" and "printf" like object methods
594       calls doesn't work for the diamond operator. That's because it's a real
595       operator, not just a function with a comma-less argument. Assuming
596       you've been storing typeglobs in your structure as we did above, you
597       can use the built-in function named "readline" to read a record just as
598       "<>" does. Given the initialization shown above for @fd, this would
599       work, but only because readline() requires a typeglob. It doesn't work
600       with objects or strings, which might be a bug we haven't fixed yet.
601
602           $got = readline($fd[0]);
603
604       Let it be noted that the flakiness of indirect filehandles is not
605       related to whether they're strings, typeglobs, objects, or anything
606       else.  It's the syntax of the fundamental operators. Playing the object
607       game doesn't help you at all here.
608
609   How can I open a filehandle to a string?
610       (contributed by Peter J. Holzer, hjp-usenet2@hjp.at)
611
612       Since Perl 5.8.0 a file handle referring to a string can be created by
613       calling open with a reference to that string instead of the filename.
614       This file handle can then be used to read from or write to the string:
615
616           open(my $fh, '>', \$string) or die "Could not open string for writing";
617           print $fh "foo\n";
618           print $fh "bar\n";    # $string now contains "foo\nbar\n"
619
620           open(my $fh, '<', \$string) or die "Could not open string for reading";
621           my $x = <$fh>;    # $x now contains "foo\n"
622
623       With older versions of Perl, the IO::String module provides similar
624       functionality.
625
626   How can I set up a footer format to be used with write()?
627       There's no builtin way to do this, but perlform has a couple of
628       techniques to make it possible for the intrepid hacker.
629
630   How can I write() into a string?
631       (contributed by brian d foy)
632
633       If you want to "write" into a string, you just have to <open> a
634       filehandle to a string, which Perl has been able to do since Perl 5.6:
635
636           open FH, '>', \my $string;
637           write( FH );
638
639       Since you want to be a good programmer, you probably want to use a
640       lexical filehandle, even though formats are designed to work with
641       bareword filehandles since the default format names take the filehandle
642       name. However, you can control this with some Perl special per-
643       filehandle variables: $^, which names the top-of-page format, and $~
644       which shows the line format. You have to change the default filehandle
645       to set these variables:
646
647           open my($fh), '>', \my $string;
648
649           { # set per-filehandle variables
650               my $old_fh = select( $fh );
651               $~ = 'ANIMAL';
652               $^ = 'ANIMAL_TOP';
653               select( $old_fh );
654           }
655
656           format ANIMAL_TOP =
657            ID  Type    Name
658           .
659
660           format ANIMAL =
661           @##   @<<<    @<<<<<<<<<<<<<<
662           $id,  $type,  $name
663           .
664
665       Although write can work with lexical or package variables, whatever
666       variables you use have to scope in the format. That most likely means
667       you'll want to localize some package variables:
668
669           {
670               local( $id, $type, $name ) = qw( 12 cat Buster );
671               write( $fh );
672           }
673
674           print $string;
675
676       There are also some tricks that you can play with "formline" and the
677       accumulator variable $^A, but you lose a lot of the value of formats
678       since "formline" won't handle paging and so on. You end up
679       reimplementing formats when you use them.
680
681   How can I output my numbers with commas added?
682       (contributed by brian d foy and Benjamin Goldberg)
683
684       You can use Number::Format to separate places in a number.  It handles
685       locale information for those of you who want to insert full stops
686       instead (or anything else that they want to use, really).
687
688       This subroutine will add commas to your number:
689
690           sub commify {
691               local $_  = shift;
692               1 while s/^([-+]?\d+)(\d{3})/$1,$2/;
693               return $_;
694           }
695
696       This regex from Benjamin Goldberg will add commas to numbers:
697
698           s/(^[-+]?\d+?(?=(?>(?:\d{3})+)(?!\d))|\G\d{3}(?=\d))/$1,/g;
699
700       It is easier to see with comments:
701
702           s/(
703               ^[-+]?             # beginning of number.
704               \d+?               # first digits before first comma
705               (?=                # followed by, (but not included in the match) :
706                   (?>(?:\d{3})+) # some positive multiple of three digits.
707                   (?!\d)         # an *exact* multiple, not x * 3 + 1 or whatever.
708               )
709               |                  # or:
710               \G\d{3}            # after the last group, get three digits
711               (?=\d)             # but they have to have more digits after them.
712           )/$1,/xg;
713
714   How can I translate tildes (~) in a filename?
715       Use the <> (glob()) operator, documented in perlfunc.  Versions of Perl
716       older than 5.6 require that you have a shell installed that groks
717       tildes. Later versions of Perl have this feature built in. The
718       File::KGlob module (available from CPAN) gives more portable glob
719       functionality.
720
721       Within Perl, you may use this directly:
722
723           $filename =~ s{
724             ^ ~             # find a leading tilde
725             (               # save this in $1
726                 [^/]        # a non-slash character
727                       *     # repeated 0 or more times (0 means me)
728             )
729           }{
730             $1
731                 ? (getpwnam($1))[7]
732                 : ( $ENV{HOME} || $ENV{LOGDIR} )
733           }ex;
734
735   How come when I open a file read-write it wipes it out?
736       Because you're using something like this, which truncates the file then
737       gives you read-write access:
738
739           open my $fh, '+>', '/path/name'; # WRONG (almost always)
740
741       Whoops. You should instead use this, which will fail if the file
742       doesn't exist:
743
744           open my $fh, '+<', '/path/name'; # open for update
745
746       Using ">" always clobbers or creates. Using "<" never does either. The
747       "+" doesn't change this.
748
749       Here are examples of many kinds of file opens. Those using "sysopen"
750       all assume that you've pulled in the constants from Fcntl:
751
752           use Fcntl;
753
754       To open file for reading:
755
756           open my $fh, '<', $path                               or die $!;
757           sysopen my $fh, $path, O_RDONLY                       or die $!;
758
759       To open file for writing, create new file if needed or else truncate
760       old file:
761
762           open my $fh, '>', $path                               or die $!;
763           sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT       or die $!;
764           sysopen my $fh, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666 or die $!;
765
766       To open file for writing, create new file, file must not exist:
767
768           sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT        or die $!;
769           sysopen my $fh, $path, O_WRONLY|O_EXCL|O_CREAT, 0666  or die $!;
770
771       To open file for appending, create if necessary:
772
773           open my $fh, '>>', $path                              or die $!;
774           sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT      or die $!;
775           sysopen my $fh, $path, O_WRONLY|O_APPEND|O_CREAT, 0666 or die $!;
776
777       To open file for appending, file must exist:
778
779           sysopen my $fh, $path, O_WRONLY|O_APPEND              or die $!;
780
781       To open file for update, file must exist:
782
783           open my $fh, '+<', $path                              or die $!;
784           sysopen my $fh, $path, O_RDWR                         or die $!;
785
786       To open file for update, create file if necessary:
787
788           sysopen my $fh, $path, O_RDWR|O_CREAT                 or die $!;
789           sysopen my $fh, $path, O_RDWR|O_CREAT, 0666           or die $!;
790
791       To open file for update, file must not exist:
792
793           sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT          or die $!;
794           sysopen my $fh, $path, O_RDWR|O_EXCL|O_CREAT, 0666    or die $!;
795
796       To open a file without blocking, creating if necessary:
797
798           sysopen my $fh, '/foo/somefile', O_WRONLY|O_NDELAY|O_CREAT
799               or die "can't open /foo/somefile: $!":
800
801       Be warned that neither creation nor deletion of files is guaranteed to
802       be an atomic operation over NFS. That is, two processes might both
803       successfully create or unlink the same file! Therefore O_EXCL isn't as
804       exclusive as you might wish.
805
806       See also perlopentut.
807
808   Why do I sometimes get an "Argument list too long" when I use <*>?
809       The "<>" operator performs a globbing operation (see above).  In Perl
810       versions earlier than v5.6.0, the internal glob() operator forks csh(1)
811       to do the actual glob expansion, but csh can't handle more than 127
812       items and so gives the error message "Argument list too long". People
813       who installed tcsh as csh won't have this problem, but their users may
814       be surprised by it.
815
816       To get around this, either upgrade to Perl v5.6.0 or later, do the glob
817       yourself with readdir() and patterns, or use a module like File::Glob,
818       one that doesn't use the shell to do globbing.
819
820   How can I open a file named with a leading ">" or trailing blanks?
821       (contributed by Brian McCauley)
822
823       The special two-argument form of Perl's open() function ignores
824       trailing blanks in filenames and infers the mode from certain leading
825       characters (or a trailing "|"). In older versions of Perl this was the
826       only version of open() and so it is prevalent in old code and books.
827
828       Unless you have a particular reason to use the two-argument form you
829       should use the three-argument form of open() which does not treat any
830       characters in the filename as special.
831
832           open my $fh, "<", "  file  ";  # filename is "   file   "
833           open my $fh, ">", ">file";     # filename is ">file"
834
835   How can I reliably rename a file?
836       If your operating system supports a proper mv(1) utility or its
837       functional equivalent, this works:
838
839           rename($old, $new) or system("mv", $old, $new);
840
841       It may be more portable to use the File::Copy module instead.  You just
842       copy to the new file to the new name (checking return values), then
843       delete the old one. This isn't really the same semantically as a
844       rename(), which preserves meta-information like permissions,
845       timestamps, inode info, etc.
846
847   How can I lock a file?
848       Perl's builtin flock() function (see perlfunc for details) will call
849       flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004
850       and later), and lockf(3) if neither of the two previous system calls
851       exists.  On some systems, it may even use a different form of native
852       locking.  Here are some gotchas with Perl's flock():
853
854       1.  Produces a fatal error if none of the three system calls (or their
855           close equivalent) exists.
856
857       2.  lockf(3) does not provide shared locking, and requires that the
858           filehandle be open for writing (or appending, or read/writing).
859
860       3.  Some versions of flock() can't lock files over a network (e.g. on
861           NFS file systems), so you'd need to force the use of fcntl(2) when
862           you build Perl.  But even this is dubious at best. See the flock
863           entry of perlfunc and the INSTALL file in the source distribution
864           for information on building Perl to do this.
865
866           Two potentially non-obvious but traditional flock semantics are
867           that it waits indefinitely until the lock is granted, and that its
868           locks are merely advisory. Such discretionary locks are more
869           flexible, but offer fewer guarantees. This means that files locked
870           with flock() may be modified by programs that do not also use
871           flock(). Cars that stop for red lights get on well with each other,
872           but not with cars that don't stop for red lights. See the perlport
873           manpage, your port's specific documentation, or your system-
874           specific local manpages for details. It's best to assume
875           traditional behavior if you're writing portable programs.  (If
876           you're not, you should as always feel perfectly free to write for
877           your own system's idiosyncrasies (sometimes called "features").
878           Slavish adherence to portability concerns shouldn't get in the way
879           of your getting your job done.)
880
881           For more information on file locking, see also "File Locking" in
882           perlopentut if you have it (new for 5.6).
883
884   Why can't I just open(FH, ">file.lock")?
885       A common bit of code NOT TO USE is this:
886
887           sleep(3) while -e 'file.lock';    # PLEASE DO NOT USE
888           open my $lock, '>', 'file.lock'; # THIS BROKEN CODE
889
890       This is a classic race condition: you take two steps to do something
891       which must be done in one. That's why computer hardware provides an
892       atomic test-and-set instruction. In theory, this "ought" to work:
893
894           sysopen my $fh, "file.lock", O_WRONLY|O_EXCL|O_CREAT
895               or die "can't open  file.lock: $!";
896
897       except that lamentably, file creation (and deletion) is not atomic over
898       NFS, so this won't work (at least, not every time) over the net.
899       Various schemes involving link() have been suggested, but these tend to
900       involve busy-wait, which is also less than desirable.
901
902   I still don't get locking. I just want to increment the number in the file.
903       How can I do this?
904       Didn't anyone ever tell you web-page hit counters were useless?  They
905       don't count number of hits, they're a waste of time, and they serve
906       only to stroke the writer's vanity. It's better to pick a random
907       number; they're more realistic.
908
909       Anyway, this is what you can do if you can't help yourself.
910
911           use Fcntl qw(:DEFAULT :flock);
912           sysopen my $fh, "numfile", O_RDWR|O_CREAT or die "can't open numfile: $!";
913           flock $fh, LOCK_EX                        or die "can't flock numfile: $!";
914           my $num = <$fh> || 0;
915           seek $fh, 0, 0                            or die "can't rewind numfile: $!";
916           truncate $fh, 0                           or die "can't truncate numfile: $!";
917           (print $fh $num+1, "\n")                  or die "can't write numfile: $!";
918           close $fh                                 or die "can't close numfile: $!";
919
920       Here's a much better web-page hit counter:
921
922           $hits = int( (time() - 850_000_000) / rand(1_000) );
923
924       If the count doesn't impress your friends, then the code might. :-)
925
926   All I want to do is append a small amount of text to the end of a file. Do
927       I still have to use locking?
928       If you are on a system that correctly implements "flock" and you use
929       the example appending code from "perldoc -f flock" everything will be
930       OK even if the OS you are on doesn't implement append mode correctly
931       (if such a system exists). So if you are happy to restrict yourself to
932       OSs that implement "flock" (and that's not really much of a
933       restriction) then that is what you should do.
934
935       If you know you are only going to use a system that does correctly
936       implement appending (i.e. not Win32) then you can omit the "seek" from
937       the code in the previous answer.
938
939       If you know you are only writing code to run on an OS and filesystem
940       that does implement append mode correctly (a local filesystem on a
941       modern Unix for example), and you keep the file in block-buffered mode
942       and you write less than one buffer-full of output between each manual
943       flushing of the buffer then each bufferload is almost guaranteed to be
944       written to the end of the file in one chunk without getting
945       intermingled with anyone else's output. You can also use the "syswrite"
946       function which is simply a wrapper around your system's write(2) system
947       call.
948
949       There is still a small theoretical chance that a signal will interrupt
950       the system-level write() operation before completion. There is also a
951       possibility that some STDIO implementations may call multiple system
952       level write()s even if the buffer was empty to start. There may be some
953       systems where this probability is reduced to zero, and this is not a
954       concern when using ":perlio" instead of your system's STDIO.
955
956   How do I randomly update a binary file?
957       If you're just trying to patch a binary, in many cases something as
958       simple as this works:
959
960           perl -i -pe 's{window manager}{window mangler}g' /usr/bin/emacs
961
962       However, if you have fixed sized records, then you might do something
963       more like this:
964
965           my $RECSIZE = 220; # size of record, in bytes
966           my $recno   = 37;  # which record to update
967           open my $fh, '+<', 'somewhere' or die "can't update somewhere: $!";
968           seek $fh, $recno * $RECSIZE, 0;
969           read $fh, $record, $RECSIZE == $RECSIZE or die "can't read record $recno: $!";
970           # munge the record
971           seek $fh, -$RECSIZE, 1;
972           print $fh $record;
973           close $fh;
974
975       Locking and error checking are left as an exercise for the reader.
976       Don't forget them or you'll be quite sorry.
977
978   How do I get a file's timestamp in perl?
979       If you want to retrieve the time at which the file was last read,
980       written, or had its meta-data (owner, etc) changed, you use the -A, -M,
981       or -C file test operations as documented in perlfunc.  These retrieve
982       the age of the file (measured against the start-time of your program)
983       in days as a floating point number. Some platforms may not have all of
984       these times. See perlport for details. To retrieve the "raw" time in
985       seconds since the epoch, you would call the stat function, then use
986       localtime(), gmtime(), or POSIX::strftime() to convert this into human-
987       readable form.
988
989       Here's an example:
990
991           my $write_secs = (stat($file))[9];
992           printf "file %s updated at %s\n", $file,
993               scalar localtime($write_secs);
994
995       If you prefer something more legible, use the File::stat module (part
996       of the standard distribution in version 5.004 and later):
997
998           # error checking left as an exercise for reader.
999           use File::stat;
1000           use Time::localtime;
1001           my $date_string = ctime(stat($file)->mtime);
1002           print "file $file updated at $date_string\n";
1003
1004       The POSIX::strftime() approach has the benefit of being, in theory,
1005       independent of the current locale. See perllocale for details.
1006
1007   How do I set a file's timestamp in perl?
1008       You use the utime() function documented in "utime" in perlfunc.  By way
1009       of example, here's a little program that copies the read and write
1010       times from its first argument to all the rest of them.
1011
1012           if (@ARGV < 2) {
1013               die "usage: cptimes timestamp_file other_files ...\n";
1014           }
1015           my $timestamp = shift;
1016           my($atime, $mtime) = (stat($timestamp))[8,9];
1017           utime $atime, $mtime, @ARGV;
1018
1019       Error checking is, as usual, left as an exercise for the reader.
1020
1021       The perldoc for utime also has an example that has the same effect as
1022       touch(1) on files that already exist.
1023
1024       Certain file systems have a limited ability to store the times on a
1025       file at the expected level of precision. For example, the FAT and HPFS
1026       filesystem are unable to create dates on files with a finer granularity
1027       than two seconds. This is a limitation of the filesystems, not of
1028       utime().
1029
1030   How do I print to more than one file at once?
1031       To connect one filehandle to several output filehandles, you can use
1032       the IO::Tee or Tie::FileHandle::Multiplex modules.
1033
1034       If you only have to do this once, you can print individually to each
1035       filehandle.
1036
1037           for my $fh ($fh1, $fh2, $fh3) { print $fh "whatever\n" }
1038
1039   How can I read in an entire file all at once?
1040       The customary Perl approach for processing all the lines in a file is
1041       to do so one line at a time:
1042
1043           open my $input, '<', $file or die "can't open $file: $!";
1044           while (<$input>) {
1045               chomp;
1046               # do something with $_
1047           }
1048           close $input or die "can't close $file: $!";
1049
1050       This is tremendously more efficient than reading the entire file into
1051       memory as an array of lines and then processing it one element at a
1052       time, which is often--if not almost always--the wrong approach.
1053       Whenever you see someone do this:
1054
1055           my @lines = <INPUT>;
1056
1057       You should think long and hard about why you need everything loaded at
1058       once. It's just not a scalable solution.
1059
1060       If you "mmap" the file with the File::Map module from CPAN, you can
1061       virtually load the entire file into a string without actually storing
1062       it in memory:
1063
1064           use File::Map qw(map_file);
1065
1066           map_file my $string, $filename;
1067
1068       Once mapped, you can treat $string as you would any other string.
1069       Since you don't necessarily have to load the data, mmap-ing can be very
1070       fast and may not increase your memory footprint.
1071
1072       You might also find it more fun to use the standard Tie::File module,
1073       or the DB_File module's $DB_RECNO bindings, which allow you to tie an
1074       array to a file so that accessing an element of the array actually
1075       accesses the corresponding line in the file.
1076
1077       If you want to load the entire file, you can use the Path::Tiny module
1078       to do it in one simple and efficient step:
1079
1080           use Path::Tiny;
1081
1082           my $all_of_it = path($filename)->slurp; # entire file in scalar
1083           my @all_lines = path($filename)->lines; # one line per element
1084
1085       Or you can read the entire file contents into a scalar like this:
1086
1087           my $var;
1088           {
1089               local $/;
1090               open my $fh, '<', $file or die "can't open $file: $!";
1091               $var = <$fh>;
1092           }
1093
1094       That temporarily undefs your record separator, and will automatically
1095       close the file at block exit. If the file is already open, just use
1096       this:
1097
1098           my $var = do { local $/; <$fh> };
1099
1100       You can also use a localized @ARGV to eliminate the "open":
1101
1102           my $var = do { local( @ARGV, $/ ) = $file; <> };
1103
1104   How can I read in a file by paragraphs?
1105       Use the $/ variable (see perlvar for details). You can either set it to
1106       "" to eliminate empty paragraphs ("abc\n\n\n\ndef", for instance, gets
1107       treated as two paragraphs and not three), or "\n\n" to accept empty
1108       paragraphs.
1109
1110       Note that a blank line must have no blanks in it. Thus
1111       "fred\n \nstuff\n\n" is one paragraph, but "fred\n\nstuff\n\n" is two.
1112
1113   How can I read a single character from a file? From the keyboard?
1114       You can use the builtin getc() function for most filehandles, but it
1115       won't (easily) work on a terminal device. For STDIN, either use the
1116       Term::ReadKey module from CPAN or use the sample code in "getc" in
1117       perlfunc.
1118
1119       If your system supports the portable operating system programming
1120       interface (POSIX), you can use the following code, which you'll note
1121       turns off echo processing as well.
1122
1123           #!/usr/bin/perl -w
1124           use strict;
1125           $| = 1;
1126           for (1..4) {
1127               print "gimme: ";
1128               my $got = getone();
1129               print "--> $got\n";
1130           }
1131           exit;
1132
1133           BEGIN {
1134               use POSIX qw(:termios_h);
1135
1136               my ($term, $oterm, $echo, $noecho, $fd_stdin);
1137
1138               my $fd_stdin = fileno(STDIN);
1139
1140               $term     = POSIX::Termios->new();
1141               $term->getattr($fd_stdin);
1142               $oterm     = $term->getlflag();
1143
1144               $echo     = ECHO | ECHOK | ICANON;
1145               $noecho   = $oterm & ~$echo;
1146
1147               sub cbreak {
1148                   $term->setlflag($noecho);
1149                   $term->setcc(VTIME, 1);
1150                   $term->setattr($fd_stdin, TCSANOW);
1151               }
1152
1153               sub cooked {
1154                   $term->setlflag($oterm);
1155                   $term->setcc(VTIME, 0);
1156                   $term->setattr($fd_stdin, TCSANOW);
1157               }
1158
1159               sub getone {
1160                   my $key = '';
1161                   cbreak();
1162                   sysread(STDIN, $key, 1);
1163                   cooked();
1164                   return $key;
1165               }
1166           }
1167
1168           END { cooked() }
1169
1170       The Term::ReadKey module from CPAN may be easier to use. Recent
1171       versions include also support for non-portable systems as well.
1172
1173           use Term::ReadKey;
1174           open my $tty, '<', '/dev/tty';
1175           print "Gimme a char: ";
1176           ReadMode "raw";
1177           my $key = ReadKey 0, $tty;
1178           ReadMode "normal";
1179           printf "\nYou said %s, char number %03d\n",
1180               $key, ord $key;
1181
1182   How can I tell whether there's a character waiting on a filehandle?
1183       The very first thing you should do is look into getting the
1184       Term::ReadKey extension from CPAN. As we mentioned earlier, it now even
1185       has limited support for non-portable (read: not open systems, closed,
1186       proprietary, not POSIX, not Unix, etc.) systems.
1187
1188       You should also check out the Frequently Asked Questions list in
1189       comp.unix.* for things like this: the answer is essentially the same.
1190       It's very system-dependent. Here's one solution that works on BSD
1191       systems:
1192
1193           sub key_ready {
1194               my($rin, $nfd);
1195               vec($rin, fileno(STDIN), 1) = 1;
1196               return $nfd = select($rin,undef,undef,0);
1197           }
1198
1199       If you want to find out how many characters are waiting, there's also
1200       the FIONREAD ioctl call to be looked at. The h2ph tool that comes with
1201       Perl tries to convert C include files to Perl code, which can be
1202       "require"d. FIONREAD ends up defined as a function in the sys/ioctl.ph
1203       file:
1204
1205           require './sys/ioctl.ph';
1206
1207           $size = pack("L", 0);
1208           ioctl(FH, FIONREAD(), $size)    or die "Couldn't call ioctl: $!\n";
1209           $size = unpack("L", $size);
1210
1211       If h2ph wasn't installed or doesn't work for you, you can grep the
1212       include files by hand:
1213
1214           % grep FIONREAD /usr/include/*/*
1215           /usr/include/asm/ioctls.h:#define FIONREAD      0x541B
1216
1217       Or write a small C program using the editor of champions:
1218
1219           % cat > fionread.c
1220           #include <sys/ioctl.h>
1221           main() {
1222               printf("%#08x\n", FIONREAD);
1223           }
1224           ^D
1225           % cc -o fionread fionread.c
1226           % ./fionread
1227           0x4004667f
1228
1229       And then hard-code it, leaving porting as an exercise to your
1230       successor.
1231
1232           $FIONREAD = 0x4004667f;         # XXX: opsys dependent
1233
1234           $size = pack("L", 0);
1235           ioctl(FH, $FIONREAD, $size)     or die "Couldn't call ioctl: $!\n";
1236           $size = unpack("L", $size);
1237
1238       FIONREAD requires a filehandle connected to a stream, meaning that
1239       sockets, pipes, and tty devices work, but not files.
1240
1241   How do I do a "tail -f" in perl?
1242       First try
1243
1244           seek($gw_fh, 0, 1);
1245
1246       The statement "seek($gw_fh, 0, 1)" doesn't change the current position,
1247       but it does clear the end-of-file condition on the handle, so that the
1248       next "<$gw_fh>" makes Perl try again to read something.
1249
1250       If that doesn't work (it relies on features of your stdio
1251       implementation), then you need something more like this:
1252
1253           for (;;) {
1254             for ($curpos = tell($gw_fh); <$gw_fh>; $curpos =tell($gw_fh)) {
1255               # search for some stuff and put it into files
1256             }
1257             # sleep for a while
1258             seek($gw_fh, $curpos, 0);  # seek to where we had been
1259           }
1260
1261       If this still doesn't work, look into the "clearerr" method from
1262       IO::Handle, which resets the error and end-of-file states on the
1263       handle.
1264
1265       There's also a File::Tail module from CPAN.
1266
1267   How do I dup() a filehandle in Perl?
1268       If you check "open" in perlfunc, you'll see that several of the ways to
1269       call open() should do the trick. For example:
1270
1271           open my $log, '>>', '/foo/logfile';
1272           open STDERR, '>&', $log;
1273
1274       Or even with a literal numeric descriptor:
1275
1276           my $fd = $ENV{MHCONTEXTFD};
1277           open $mhcontext, "<&=$fd";  # like fdopen(3S)
1278
1279       Note that "<&STDIN" makes a copy, but "<&=STDIN" makes an alias. That
1280       means if you close an aliased handle, all aliases become inaccessible.
1281       This is not true with a copied one.
1282
1283       Error checking, as always, has been left as an exercise for the reader.
1284
1285   How do I close a file descriptor by number?
1286       If, for some reason, you have a file descriptor instead of a filehandle
1287       (perhaps you used "POSIX::open"), you can use the close() function from
1288       the POSIX module:
1289
1290           use POSIX ();
1291
1292           POSIX::close( $fd );
1293
1294       This should rarely be necessary, as the Perl close() function is to be
1295       used for things that Perl opened itself, even if it was a dup of a
1296       numeric descriptor as with "MHCONTEXT" above. But if you really have
1297       to, you may be able to do this:
1298
1299           require './sys/syscall.ph';
1300           my $rc = syscall(SYS_close(), $fd + 0);  # must force numeric
1301           die "can't sysclose $fd: $!" unless $rc == -1;
1302
1303       Or, just use the fdopen(3S) feature of open():
1304
1305           {
1306               open my $fh, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
1307               close $fh;
1308           }
1309
1310   Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe`
1311       work?
1312       Whoops!  You just put a tab and a formfeed into that filename!
1313       Remember that within double quoted strings ("like\this"), the backslash
1314       is an escape character. The full list of these is in "Quote and Quote-
1315       like Operators" in perlop. Unsurprisingly, you don't have a file called
1316       "c:(tab)emp(formfeed)oo" or "c:(tab)emp(formfeed)oo.exe" on your legacy
1317       DOS filesystem.
1318
1319       Either single-quote your strings, or (preferably) use forward slashes.
1320       Since all DOS and Windows versions since something like MS-DOS 2.0 or
1321       so have treated "/" and "\" the same in a path, you might as well use
1322       the one that doesn't clash with Perl--or the POSIX shell, ANSI C and
1323       C++, awk, Tcl, Java, or Python, just to mention a few. POSIX paths are
1324       more portable, too.
1325
1326   Why doesn't glob("*.*") get all the files?
1327       Because even on non-Unix ports, Perl's glob function follows standard
1328       Unix globbing semantics. You'll need glob("*") to get all (non-hidden)
1329       files. This makes glob() portable even to legacy systems. Your port may
1330       include proprietary globbing functions as well. Check its documentation
1331       for details.
1332
1333   Why does Perl let me delete read-only files? Why does "-i" clobber
1334       protected files? Isn't this a bug in Perl?
1335       This is elaborately and painstakingly described in the file-dir-perms
1336       article in the "Far More Than You Ever Wanted To Know" collection in
1337       <http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> .
1338
1339       The executive summary: learn how your filesystem works. The permissions
1340       on a file say what can happen to the data in that file.  The
1341       permissions on a directory say what can happen to the list of files in
1342       that directory. If you delete a file, you're removing its name from the
1343       directory (so the operation depends on the permissions of the
1344       directory, not of the file). If you try to write to the file, the
1345       permissions of the file govern whether you're allowed to.
1346
1347   How do I select a random line from a file?
1348       Short of loading the file into a database or pre-indexing the lines in
1349       the file, there are a couple of things that you can do.
1350
1351       Here's a reservoir-sampling algorithm from the Camel Book:
1352
1353           srand;
1354           rand($.) < 1 && ($line = $_) while <>;
1355
1356       This has a significant advantage in space over reading the whole file
1357       in. You can find a proof of this method in The Art of Computer
1358       Programming, Volume 2, Section 3.4.2, by Donald E. Knuth.
1359
1360       You can use the File::Random module which provides a function for that
1361       algorithm:
1362
1363           use File::Random qw/random_line/;
1364           my $line = random_line($filename);
1365
1366       Another way is to use the Tie::File module, which treats the entire
1367       file as an array. Simply access a random array element.
1368
1369   Why do I get weird spaces when I print an array of lines?
1370       (contributed by brian d foy)
1371
1372       If you are seeing spaces between the elements of your array when you
1373       print the array, you are probably interpolating the array in double
1374       quotes:
1375
1376           my @animals = qw(camel llama alpaca vicuna);
1377           print "animals are: @animals\n";
1378
1379       It's the double quotes, not the "print", doing this. Whenever you
1380       interpolate an array in a double quote context, Perl joins the elements
1381       with spaces (or whatever is in $", which is a space by default):
1382
1383           animals are: camel llama alpaca vicuna
1384
1385       This is different than printing the array without the interpolation:
1386
1387           my @animals = qw(camel llama alpaca vicuna);
1388           print "animals are: ", @animals, "\n";
1389
1390       Now the output doesn't have the spaces between the elements because the
1391       elements of @animals simply become part of the list to "print":
1392
1393           animals are: camelllamaalpacavicuna
1394
1395       You might notice this when each of the elements of @array end with a
1396       newline. You expect to print one element per line, but notice that
1397       every line after the first is indented:
1398
1399           this is a line
1400            this is another line
1401            this is the third line
1402
1403       That extra space comes from the interpolation of the array. If you
1404       don't want to put anything between your array elements, don't use the
1405       array in double quotes. You can send it to print without them:
1406
1407           print @lines;
1408
1409   How do I traverse a directory tree?
1410       (contributed by brian d foy)
1411
1412       The File::Find module, which comes with Perl, does all of the hard work
1413       to traverse a directory structure. It comes with Perl. You simply call
1414       the "find" subroutine with a callback subroutine and the directories
1415       you want to traverse:
1416
1417           use File::Find;
1418
1419           find( \&wanted, @directories );
1420
1421           sub wanted {
1422               # full path in $File::Find::name
1423               # just filename in $_
1424               ... do whatever you want to do ...
1425           }
1426
1427       The File::Find::Closures, which you can download from CPAN, provides
1428       many ready-to-use subroutines that you can use with File::Find.
1429
1430       The File::Finder, which you can download from CPAN, can help you create
1431       the callback subroutine using something closer to the syntax of the
1432       "find" command-line utility:
1433
1434           use File::Find;
1435           use File::Finder;
1436
1437           my $deep_dirs = File::Finder->depth->type('d')->ls->exec('rmdir','{}');
1438
1439           find( $deep_dirs->as_options, @places );
1440
1441       The File::Find::Rule module, which you can download from CPAN, has a
1442       similar interface, but does the traversal for you too:
1443
1444           use File::Find::Rule;
1445
1446           my @files = File::Find::Rule->file()
1447                                    ->name( '*.pm' )
1448                                    ->in( @INC );
1449
1450   How do I delete a directory tree?
1451       (contributed by brian d foy)
1452
1453       If you have an empty directory, you can use Perl's built-in "rmdir".
1454       If the directory is not empty (so, with files or subdirectories), you
1455       either have to empty it yourself (a lot of work) or use a module to
1456       help you.
1457
1458       The File::Path module, which comes with Perl, has a "remove_tree" which
1459       can take care of all of the hard work for you:
1460
1461           use File::Path qw(remove_tree);
1462
1463           remove_tree( @directories );
1464
1465       The File::Path module also has a legacy interface to the older "rmtree"
1466       subroutine.
1467
1468   How do I copy an entire directory?
1469       (contributed by Shlomi Fish)
1470
1471       To do the equivalent of "cp -R" (i.e. copy an entire directory tree
1472       recursively) in portable Perl, you'll either need to write something
1473       yourself or find a good CPAN module such as  File::Copy::Recursive.
1474
1476       Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and other
1477       authors as noted. All rights reserved.
1478
1479       This documentation is free; you can redistribute it and/or modify it
1480       under the same terms as Perl itself.
1481
1482       Irrespective of its distribution, all code examples here are in the
1483       public domain. You are permitted and encouraged to use this code and
1484       any derivatives thereof in your own programs for fun or for profit as
1485       you see fit. A simple comment in the code giving credit to the FAQ
1486       would be courteous but is not required.
1487
1488
1489
1490perl v5.38.0                      2023-08-24                       perlfaq5(3)
Impressum