mingw/html/pod/perlfaq5.html

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