pod/perlfaq5.pod

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