[ Index ]

PHP Cross Reference of Unnamed Project




/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/pod/ -> perlopentut.pod (source)

   1  =head1 NAME
   3  perlopentut - tutorial on opening things in Perl
   5  =head1 DESCRIPTION
   7  Perl has two simple, built-in ways to open files: the shell way for
   8  convenience, and the C way for precision.  The shell way also has 2- and
   9  3-argument forms, which have different semantics for handling the filename.
  10  The choice is yours.
  12  =head1 Open E<agrave> la shell
  14  Perl's C<open> function was designed to mimic the way command-line
  15  redirection in the shell works.  Here are some basic examples
  16  from the shell:
  18      $ myprogram file1 file2 file3
  19      $ myprogram    <  inputfile
  20      $ myprogram    >  outputfile
  21      $ myprogram    >> outputfile
  22      $ myprogram    |  otherprogram 
  23      $ otherprogram |  myprogram
  25  And here are some more advanced examples:
  27      $ otherprogram      | myprogram f1 - f2
  28      $ otherprogram 2>&1 | myprogram -
  29      $ myprogram     <&3
  30      $ myprogram     >&4
  32  Programmers accustomed to constructs like those above can take comfort
  33  in learning that Perl directly supports these familiar constructs using
  34  virtually the same syntax as the shell.
  36  =head2 Simple Opens
  38  The C<open> function takes two arguments: the first is a filehandle,
  39  and the second is a single string comprising both what to open and how
  40  to open it.  C<open> returns true when it works, and when it fails,
  41  returns a false value and sets the special variable C<$!> to reflect
  42  the system error.  If the filehandle was previously opened, it will
  43  be implicitly closed first.
  45  For example:
  47      open(INFO,      "datafile") || die("can't open datafile: $!");
  48      open(INFO,   "<  datafile") || die("can't open datafile: $!");
  49      open(RESULTS,">  runstats") || die("can't open runstats: $!");
  50      open(LOG,    ">> logfile ") || die("can't open logfile:  $!");
  52  If you prefer the low-punctuation version, you could write that this way:
  54      open INFO,   "<  datafile"  or die "can't open datafile: $!";
  55      open RESULTS,">  runstats"  or die "can't open runstats: $!";
  56      open LOG,    ">> logfile "  or die "can't open logfile:  $!";
  58  A few things to notice.  First, the leading less-than is optional.
  59  If omitted, Perl assumes that you want to open the file for reading.
  61  Note also that the first example uses the C<||> logical operator, and the
  62  second uses C<or>, which has lower precedence.  Using C<||> in the latter
  63  examples would effectively mean
  65      open INFO, ( "<  datafile"  || die "can't open datafile: $!" );
  67  which is definitely not what you want.
  69  The other important thing to notice is that, just as in the shell,
  70  any whitespace before or after the filename is ignored.  This is good,
  71  because you wouldn't want these to do different things:
  73      open INFO,   "<datafile"   
  74      open INFO,   "< datafile" 
  75      open INFO,   "<  datafile"
  77  Ignoring surrounding whitespace also helps for when you read a filename
  78  in from a different file, and forget to trim it before opening:
  80      $filename = <INFO>;         # oops, \n still there
  81      open(EXTRA, "< $filename") || die "can't open $filename: $!";
  83  This is not a bug, but a feature.  Because C<open> mimics the shell in
  84  its style of using redirection arrows to specify how to open the file, it
  85  also does so with respect to extra whitespace around the filename itself
  86  as well.  For accessing files with naughty names, see 
  87  L<"Dispelling the Dweomer">.
  89  There is also a 3-argument version of C<open>, which lets you put the
  90  special redirection characters into their own argument:
  92      open( INFO, ">", $datafile ) || die "Can't create $datafile: $!";
  94  In this case, the filename to open is the actual string in C<$datafile>,
  95  so you don't have to worry about C<$datafile> containing characters
  96  that might influence the open mode, or whitespace at the beginning of
  97  the filename that would be absorbed in the 2-argument version.  Also,
  98  any reduction of unnecessary string interpolation is a good thing.
 100  =head2 Indirect Filehandles
 102  C<open>'s first argument can be a reference to a filehandle.  As of
 103  perl 5.6.0, if the argument is uninitialized, Perl will automatically
 104  create a filehandle and put a reference to it in the first argument,
 105  like so:
 107      open( my $in, $infile )   or die "Couldn't read $infile: $!";
 108      while ( <$in> ) {
 109      # do something with $_
 110      }
 111      close $in;
 113  Indirect filehandles make namespace management easier.  Since filehandles
 114  are global to the current package, two subroutines trying to open
 115  C<INFILE> will clash.  With two functions opening indirect filehandles
 116  like C<my $infile>, there's no clash and no need to worry about future
 117  conflicts.
 119  Another convenient behavior is that an indirect filehandle automatically
 120  closes when it goes out of scope or when you undefine it:
 122      sub firstline {
 123      open( my $in, shift ) && return scalar <$in>;
 124      # no close() required
 125      }
 127  =head2 Pipe Opens
 129  In C, when you want to open a file using the standard I/O library,
 130  you use the C<fopen> function, but when opening a pipe, you use the
 131  C<popen> function.  But in the shell, you just use a different redirection
 132  character.  That's also the case for Perl.  The C<open> call 
 133  remains the same--just its argument differs.  
 135  If the leading character is a pipe symbol, C<open> starts up a new
 136  command and opens a write-only filehandle leading into that command.
 137  This lets you write into that handle and have what you write show up on
 138  that command's standard input.  For example:
 140      open(PRINTER, "| lpr -Plp1")    || die "can't run lpr: $!";
 141      print PRINTER "stuff\n";
 142      close(PRINTER)                  || die "can't close lpr: $!";
 144  If the trailing character is a pipe, you start up a new command and open a
 145  read-only filehandle leading out of that command.  This lets whatever that
 146  command writes to its standard output show up on your handle for reading.
 147  For example:
 149      open(NET, "netstat -i -n |")    || die "can't fork netstat: $!";
 150      while (<NET>) { }               # do something with input
 151      close(NET)                      || die "can't close netstat: $!";
 153  What happens if you try to open a pipe to or from a non-existent
 154  command?  If possible, Perl will detect the failure and set C<$!> as
 155  usual.  But if the command contains special shell characters, such as
 156  C<E<gt>> or C<*>, called 'metacharacters', Perl does not execute the
 157  command directly.  Instead, Perl runs the shell, which then tries to
 158  run the command.  This means that it's the shell that gets the error
 159  indication.  In such a case, the C<open> call will only indicate
 160  failure if Perl can't even run the shell.  See L<perlfaq8/"How can I
 161  capture STDERR from an external command?"> to see how to cope with
 162  this.  There's also an explanation in L<perlipc>.
 164  If you would like to open a bidirectional pipe, the IPC::Open2
 165  library will handle this for you.  Check out 
 166  L<perlipc/"Bidirectional Communication with Another Process">
 168  =head2 The Minus File
 170  Again following the lead of the standard shell utilities, Perl's
 171  C<open> function treats a file whose name is a single minus, "-", in a
 172  special way.  If you open minus for reading, it really means to access
 173  the standard input.  If you open minus for writing, it really means to
 174  access the standard output.
 176  If minus can be used as the default input or default output, what happens
 177  if you open a pipe into or out of minus?  What's the default command it
 178  would run?  The same script as you're currently running!  This is actually
 179  a stealth C<fork> hidden inside an C<open> call.  See 
 180  L<perlipc/"Safe Pipe Opens"> for details.
 182  =head2 Mixing Reads and Writes
 184  It is possible to specify both read and write access.  All you do is
 185  add a "+" symbol in front of the redirection.  But as in the shell,
 186  using a less-than on a file never creates a new file; it only opens an
 187  existing one.  On the other hand, using a greater-than always clobbers
 188  (truncates to zero length) an existing file, or creates a brand-new one
 189  if there isn't an old one.  Adding a "+" for read-write doesn't affect
 190  whether it only works on existing files or always clobbers existing ones.
 192      open(WTMP, "+< /usr/adm/wtmp") 
 193          || die "can't open /usr/adm/wtmp: $!";
 195      open(SCREEN, "+> lkscreen")
 196          || die "can't open lkscreen: $!";
 198      open(LOGFILE, "+>> /var/log/applog")
 199          || die "can't open /var/log/applog: $!";
 201  The first one won't create a new file, and the second one will always
 202  clobber an old one.  The third one will create a new file if necessary
 203  and not clobber an old one, and it will allow you to read at any point
 204  in the file, but all writes will always go to the end.  In short,
 205  the first case is substantially more common than the second and third
 206  cases, which are almost always wrong.  (If you know C, the plus in
 207  Perl's C<open> is historically derived from the one in C's fopen(3S),
 208  which it ultimately calls.)
 210  In fact, when it comes to updating a file, unless you're working on
 211  a binary file as in the WTMP case above, you probably don't want to
 212  use this approach for updating.  Instead, Perl's B<-i> flag comes to
 213  the rescue.  The following command takes all the C, C++, or yacc source
 214  or header files and changes all their foo's to bar's, leaving
 215  the old version in the original filename with a ".orig" tacked
 216  on the end:
 218      $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]
 220  This is a short cut for some renaming games that are really
 221  the best way to update textfiles.  See the second question in 
 222  L<perlfaq5> for more details.
 224  =head2 Filters 
 226  One of the most common uses for C<open> is one you never
 227  even notice.  When you process the ARGV filehandle using
 228  C<< <ARGV> >>, Perl actually does an implicit open 
 229  on each file in @ARGV.  Thus a program called like this:
 231      $ myprogram file1 file2 file3
 233  can have all its files opened and processed one at a time
 234  using a construct no more complex than:
 236      while (<>) {
 237          # do something with $_
 238      } 
 240  If @ARGV is empty when the loop first begins, Perl pretends you've opened
 241  up minus, that is, the standard input.  In fact, $ARGV, the currently
 242  open file during C<< <ARGV> >> processing, is even set to "-"
 243  in these circumstances.
 245  You are welcome to pre-process your @ARGV before starting the loop to
 246  make sure it's to your liking.  One reason to do this might be to remove
 247  command options beginning with a minus.  While you can always roll the
 248  simple ones by hand, the Getopts modules are good for this:
 250      use Getopt::Std;
 252      # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
 253      getopts("vDo:");            
 255      # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
 256      getopts("vDo:", \%args);    
 258  Or the standard Getopt::Long module to permit named arguments:
 260      use Getopt::Long;
 261      GetOptions( "verbose"  => \$verbose,        # --verbose
 262                  "Debug"    => \$debug,          # --Debug
 263                  "output=s" => \$output );       
 264          # --output=somestring or --output somestring
 266  Another reason for preprocessing arguments is to make an empty
 267  argument list default to all files:
 269      @ARGV = glob("*") unless @ARGV;
 271  You could even filter out all but plain, text files.  This is a bit
 272  silent, of course, and you might prefer to mention them on the way.
 274      @ARGV = grep { -f && -T } @ARGV;
 276  If you're using the B<-n> or B<-p> command-line options, you
 277  should put changes to @ARGV in a C<BEGIN{}> block.
 279  Remember that a normal C<open> has special properties, in that it might
 280  call fopen(3S) or it might called popen(3S), depending on what its
 281  argument looks like; that's why it's sometimes called "magic open".
 282  Here's an example:
 284      $pwdinfo = `domainname` =~ /^(\(none\))?$/
 285                      ? '< /etc/passwd'
 286                      : 'ypcat passwd |';
 288      open(PWD, $pwdinfo)                 
 289                  or die "can't open $pwdinfo: $!";
 291  This sort of thing also comes into play in filter processing.  Because
 292  C<< <ARGV> >> processing employs the normal, shell-style Perl C<open>,
 293  it respects all the special things we've already seen:
 295      $ myprogram f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
 297  That program will read from the file F<f1>, the process F<cmd1>, standard
 298  input (F<tmpfile> in this case), the F<f2> file, the F<cmd2> command,
 299  and finally the F<f3> file.
 301  Yes, this also means that if you have files named "-" (and so on) in
 302  your directory, they won't be processed as literal files by C<open>.
 303  You'll need to pass them as "./-", much as you would for the I<rm> program,
 304  or you could use C<sysopen> as described below.
 306  One of the more interesting applications is to change files of a certain
 307  name into pipes.  For example, to autoprocess gzipped or compressed
 308  files by decompressing them with I<gzip>:
 310      @ARGV = map { /^\.(gz|Z)$/ ? "gzip -dc $_ |" : $_  } @ARGV;
 312  Or, if you have the I<GET> program installed from LWP,
 313  you can fetch URLs before processing them:
 315      @ARGV = map { m#^\w+://# ? "GET $_ |" : $_ } @ARGV;
 317  It's not for nothing that this is called magic C<< <ARGV> >>.
 318  Pretty nifty, eh?
 320  =head1 Open E<agrave> la C
 322  If you want the convenience of the shell, then Perl's C<open> is
 323  definitely the way to go.  On the other hand, if you want finer precision
 324  than C's simplistic fopen(3S) provides you should look to Perl's
 325  C<sysopen>, which is a direct hook into the open(2) system call.
 326  That does mean it's a bit more involved, but that's the price of 
 327  precision.
 329  C<sysopen> takes 3 (or 4) arguments.
 331      sysopen HANDLE, PATH, FLAGS, [MASK]
 333  The HANDLE argument is a filehandle just as with C<open>.  The PATH is
 334  a literal path, one that doesn't pay attention to any greater-thans or
 335  less-thans or pipes or minuses, nor ignore whitespace.  If it's there,
 336  it's part of the path.  The FLAGS argument contains one or more values
 337  derived from the Fcntl module that have been or'd together using the
 338  bitwise "|" operator.  The final argument, the MASK, is optional; if
 339  present, it is combined with the user's current umask for the creation
 340  mode of the file.  You should usually omit this.
 342  Although the traditional values of read-only, write-only, and read-write
 343  are 0, 1, and 2 respectively, this is known not to hold true on some
 344  systems.  Instead, it's best to load in the appropriate constants first
 345  from the Fcntl module, which supplies the following standard flags:
 347      O_RDONLY            Read only
 348      O_WRONLY            Write only
 349      O_RDWR              Read and write
 350      O_CREAT             Create the file if it doesn't exist
 351      O_EXCL              Fail if the file already exists
 352      O_APPEND            Append to the file
 353      O_TRUNC             Truncate the file
 354      O_NONBLOCK          Non-blocking access
 356  Less common flags that are sometimes available on some operating
 357  systems include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>,
 359  C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>.  Consult your open(2)
 360  manpage or its local equivalent for details.  (Note: starting from
 361  Perl release 5.6 the C<O_LARGEFILE> flag, if available, is automatically
 362  added to the sysopen() flags because large files are the default.)
 364  Here's how to use C<sysopen> to emulate the simple C<open> calls we had
 365  before.  We'll omit the C<|| die $!> checks for clarity, but make sure
 366  you always check the return values in real code.  These aren't quite
 367  the same, since C<open> will trim leading and trailing whitespace,
 368  but you'll get the idea.
 370  To open a file for reading:
 372      open(FH, "< $path");
 373      sysopen(FH, $path, O_RDONLY);
 375  To open a file for writing, creating a new file if needed or else truncating
 376  an old file:
 378      open(FH, "> $path");
 379      sysopen(FH, $path, O_WRONLY | O_TRUNC | O_CREAT);
 381  To open a file for appending, creating one if necessary:
 383      open(FH, ">> $path");
 384      sysopen(FH, $path, O_WRONLY | O_APPEND | O_CREAT);
 386  To open a file for update, where the file must already exist:
 388      open(FH, "+< $path");
 389      sysopen(FH, $path, O_RDWR);
 391  And here are things you can do with C<sysopen> that you cannot do with
 392  a regular C<open>.  As you'll see, it's just a matter of controlling the
 393  flags in the third argument.
 395  To open a file for writing, creating a new file which must not previously
 396  exist:
 398      sysopen(FH, $path, O_WRONLY | O_EXCL | O_CREAT);
 400  To open a file for appending, where that file must already exist:
 402      sysopen(FH, $path, O_WRONLY | O_APPEND);
 404  To open a file for update, creating a new file if necessary:
 406      sysopen(FH, $path, O_RDWR | O_CREAT);
 408  To open a file for update, where that file must not already exist:
 410      sysopen(FH, $path, O_RDWR | O_EXCL | O_CREAT);
 412  To open a file without blocking, creating one if necessary:
 414      sysopen(FH, $path, O_WRONLY | O_NONBLOCK | O_CREAT);
 416  =head2 Permissions E<agrave> la mode
 418  If you omit the MASK argument to C<sysopen>, Perl uses the octal value
 419  0666.  The normal MASK to use for executables and directories should
 420  be 0777, and for anything else, 0666.
 422  Why so permissive?  Well, it isn't really.  The MASK will be modified
 423  by your process's current C<umask>.  A umask is a number representing
 424  I<disabled> permissions bits; that is, bits that will not be turned on
 425  in the created files' permissions field.
 427  For example, if your C<umask> were 027, then the 020 part would
 428  disable the group from writing, and the 007 part would disable others
 429  from reading, writing, or executing.  Under these conditions, passing
 430  C<sysopen> 0666 would create a file with mode 0640, since C<0666 & ~027>
 431  is 0640.
 433  You should seldom use the MASK argument to C<sysopen()>.  That takes
 434  away the user's freedom to choose what permission new files will have.
 435  Denying choice is almost always a bad thing.  One exception would be for
 436  cases where sensitive or private data is being stored, such as with mail
 437  folders, cookie files, and internal temporary files.
 439  =head1 Obscure Open Tricks
 441  =head2 Re-Opening Files (dups)
 443  Sometimes you already have a filehandle open, and want to make another
 444  handle that's a duplicate of the first one.  In the shell, we place an
 445  ampersand in front of a file descriptor number when doing redirections.
 446  For example, C<< 2>&1 >> makes descriptor 2 (that's STDERR in Perl)
 447  be redirected into descriptor 1 (which is usually Perl's STDOUT).
 448  The same is essentially true in Perl: a filename that begins with an
 449  ampersand is treated instead as a file descriptor if a number, or as a
 450  filehandle if a string.
 452      open(SAVEOUT, ">&SAVEERR") || die "couldn't dup SAVEERR: $!";
 453      open(MHCONTEXT, "<&4")     || die "couldn't dup fd4: $!";
 455  That means that if a function is expecting a filename, but you don't
 456  want to give it a filename because you already have the file open, you
 457  can just pass the filehandle with a leading ampersand.  It's best to
 458  use a fully qualified handle though, just in case the function happens
 459  to be in a different package:
 461      somefunction("&main::LOGFILE");
 463  This way if somefunction() is planning on opening its argument, it can
 464  just use the already opened handle.  This differs from passing a handle,
 465  because with a handle, you don't open the file.  Here you have something
 466  you can pass to open.
 468  If you have one of those tricky, newfangled I/O objects that the C++
 469  folks are raving about, then this doesn't work because those aren't a
 470  proper filehandle in the native Perl sense.  You'll have to use fileno()
 471  to pull out the proper descriptor number, assuming you can:
 473      use IO::Socket;
 474      $handle = IO::Socket::INET->new("www.perl.com:80");
 475      $fd = $handle->fileno;
 476      somefunction("&$fd");  # not an indirect function call
 478  It can be easier (and certainly will be faster) just to use real
 479  filehandles though:
 481      use IO::Socket;
 482      local *REMOTE = IO::Socket::INET->new("www.perl.com:80");
 483      die "can't connect" unless defined(fileno(REMOTE));
 484      somefunction("&main::REMOTE");
 486  If the filehandle or descriptor number is preceded not just with a simple
 487  "&" but rather with a "&=" combination, then Perl will not create a
 488  completely new descriptor opened to the same place using the dup(2)
 489  system call.  Instead, it will just make something of an alias to the
 490  existing one using the fdopen(3S) library call.  This is slightly more
 491  parsimonious of systems resources, although this is less a concern
 492  these days.  Here's an example of that:
 494      $fd = $ENV{"MHCONTEXTFD"};
 495      open(MHCONTEXT, "<&=$fd")   or die "couldn't fdopen $fd: $!";
 497  If you're using magic C<< <ARGV> >>, you could even pass in as a
 498  command line argument in @ARGV something like C<"<&=$MHCONTEXTFD">,
 499  but we've never seen anyone actually do this.
 501  =head2 Dispelling the Dweomer
 503  Perl is more of a DWIMmer language than something like Java--where DWIM
 504  is an acronym for "do what I mean".  But this principle sometimes leads
 505  to more hidden magic than one knows what to do with.  In this way, Perl
 506  is also filled with I<dweomer>, an obscure word meaning an enchantment.
 507  Sometimes, Perl's DWIMmer is just too much like dweomer for comfort.
 509  If magic C<open> is a bit too magical for you, you don't have to turn
 510  to C<sysopen>.  To open a file with arbitrary weird characters in
 511  it, it's necessary to protect any leading and trailing whitespace.
 512  Leading whitespace is protected by inserting a C<"./"> in front of a
 513  filename that starts with whitespace.  Trailing whitespace is protected
 514  by appending an ASCII NUL byte (C<"\0">) at the end of the string.
 516      $file =~ s#^(\s)#./$1#;
 517      open(FH, "< $file\0")   || die "can't open $file: $!";
 519  This assumes, of course, that your system considers dot the current
 520  working directory, slash the directory separator, and disallows ASCII
 521  NULs within a valid filename.  Most systems follow these conventions,
 522  including all POSIX systems as well as proprietary Microsoft systems.
 523  The only vaguely popular system that doesn't work this way is the
 524  "Classic" Macintosh system, which uses a colon where the rest of us
 525  use a slash.  Maybe C<sysopen> isn't such a bad idea after all.
 527  If you want to use C<< <ARGV> >> processing in a totally boring
 528  and non-magical way, you could do this first:
 530      #   "Sam sat on the ground and put his head in his hands.  
 531      #   'I wish I had never come here, and I don't want to see 
 532      #   no more magic,' he said, and fell silent."
 533      for (@ARGV) { 
 534          s#^([^./])#./$1#;
 535          $_ .= "\0";
 536      } 
 537      while (<>) {  
 538          # now process $_
 539      } 
 541  But be warned that users will not appreciate being unable to use "-"
 542  to mean standard input, per the standard convention.
 544  =head2 Paths as Opens
 546  You've probably noticed how Perl's C<warn> and C<die> functions can
 547  produce messages like:
 549      Some warning at scriptname line 29, <FH> line 7.
 551  That's because you opened a filehandle FH, and had read in seven records
 552  from it.  But what was the name of the file, rather than the handle?
 554  If you aren't running with C<strict refs>, or if you've turned them off
 555  temporarily, then all you have to do is this:
 557      open($path, "< $path") || die "can't open $path: $!";
 558      while (<$path>) {
 559          # whatever
 560      } 
 562  Since you're using the pathname of the file as its handle,
 563  you'll get warnings more like
 565      Some warning at scriptname line 29, </etc/motd> line 7.
 567  =head2 Single Argument Open
 569  Remember how we said that Perl's open took two arguments?  That was a
 570  passive prevarication.  You see, it can also take just one argument.
 571  If and only if the variable is a global variable, not a lexical, you
 572  can pass C<open> just one argument, the filehandle, and it will 
 573  get the path from the global scalar variable of the same name.
 575      $FILE = "/etc/motd";
 576      open FILE or die "can't open $FILE: $!";
 577      while (<FILE>) {
 578          # whatever
 579      } 
 581  Why is this here?  Someone has to cater to the hysterical porpoises.
 582  It's something that's been in Perl since the very beginning, if not
 583  before.
 585  =head2 Playing with STDIN and STDOUT
 587  One clever move with STDOUT is to explicitly close it when you're done
 588  with the program.
 590      END { close(STDOUT) || die "can't close stdout: $!" }
 592  If you don't do this, and your program fills up the disk partition due
 593  to a command line redirection, it won't report the error exit with a
 594  failure status.
 596  You don't have to accept the STDIN and STDOUT you were given.  You are
 597  welcome to reopen them if you'd like.
 599      open(STDIN, "< datafile")
 600      || die "can't open datafile: $!";
 602      open(STDOUT, "> output")
 603      || die "can't open output: $!";
 605  And then these can be accessed directly or passed on to subprocesses.
 606  This makes it look as though the program were initially invoked
 607  with those redirections from the command line.
 609  It's probably more interesting to connect these to pipes.  For example:
 611      $pager = $ENV{PAGER} || "(less || more)";
 612      open(STDOUT, "| $pager")
 613      || die "can't fork a pager: $!";
 615  This makes it appear as though your program were called with its stdout
 616  already piped into your pager.  You can also use this kind of thing
 617  in conjunction with an implicit fork to yourself.  You might do this
 618  if you would rather handle the post processing in your own program,
 619  just in a different process:
 621      head(100);
 622      while (<>) {
 623          print;
 624      } 
 626      sub head {
 627          my $lines = shift || 20;
 628          return if $pid = open(STDOUT, "|-");       # return if parent
 629          die "cannot fork: $!" unless defined $pid;
 630          while (<STDIN>) {
 631              last if --$lines < 0;
 632              print;
 633          } 
 634          exit;
 635      } 
 637  This technique can be applied to repeatedly push as many filters on your
 638  output stream as you wish.
 640  =head1 Other I/O Issues
 642  These topics aren't really arguments related to C<open> or C<sysopen>,
 643  but they do affect what you do with your open files.
 645  =head2 Opening Non-File Files
 647  When is a file not a file?  Well, you could say when it exists but
 648  isn't a plain file.   We'll check whether it's a symbolic link first,
 649  just in case.
 651      if (-l $file || ! -f _) {
 652          print "$file is not a plain file\n";
 653      } 
 655  What other kinds of files are there than, well, files?  Directories,
 656  symbolic links, named pipes, Unix-domain sockets, and block and character
 657  devices.  Those are all files, too--just not I<plain> files.  This isn't
 658  the same issue as being a text file. Not all text files are plain files.
 659  Not all plain files are text files.  That's why there are separate C<-f>
 660  and C<-T> file tests.
 662  To open a directory, you should use the C<opendir> function, then
 663  process it with C<readdir>, carefully restoring the directory 
 664  name if necessary:
 666      opendir(DIR, $dirname) or die "can't opendir $dirname: $!";
 667      while (defined($file = readdir(DIR))) {
 668          # do something with "$dirname/$file"
 669      }
 670      closedir(DIR);
 672  If you want to process directories recursively, it's better to use the
 673  File::Find module.  For example, this prints out all files recursively
 674  and adds a slash to their names if the file is a directory.
 676      @ARGV = qw(.) unless @ARGV;
 677      use File::Find;
 678      find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;
 680  This finds all bogus symbolic links beneath a particular directory:
 682      find sub { print "$File::Find::name\n" if -l && !-e }, $dir;
 684  As you see, with symbolic links, you can just pretend that it is
 685  what it points to.  Or, if you want to know I<what> it points to, then
 686  C<readlink> is called for:
 688      if (-l $file) {
 689          if (defined($whither = readlink($file))) {
 690              print "$file points to $whither\n";
 691          } else {
 692              print "$file points nowhere: $!\n";
 693          } 
 694      } 
 696  =head2 Opening Named Pipes
 698  Named pipes are a different matter.  You pretend they're regular files,
 699  but their opens will normally block until there is both a reader and
 700  a writer.  You can read more about them in L<perlipc/"Named Pipes">.
 701  Unix-domain sockets are rather different beasts as well; they're
 702  described in L<perlipc/"Unix-Domain TCP Clients and Servers">.
 704  When it comes to opening devices, it can be easy and it can be tricky.
 705  We'll assume that if you're opening up a block device, you know what
 706  you're doing.  The character devices are more interesting.  These are
 707  typically used for modems, mice, and some kinds of printers.  This is
 708  described in L<perlfaq8/"How do I read and write the serial port?">
 709  It's often enough to open them carefully:
 711      sysopen(TTYIN, "/dev/ttyS1", O_RDWR | O_NDELAY | O_NOCTTY)
 712          # (O_NOCTTY no longer needed on POSIX systems)
 713          or die "can't open /dev/ttyS1: $!";
 714      open(TTYOUT, "+>&TTYIN")
 715          or die "can't dup TTYIN: $!";
 717      $ofh = select(TTYOUT); $| = 1; select($ofh);
 719      print TTYOUT "+++at\015";
 720      $answer = <TTYIN>;
 722  With descriptors that you haven't opened using C<sysopen>, such as
 723  sockets, you can set them to be non-blocking using C<fcntl>:
 725      use Fcntl;
 726      my $old_flags = fcntl($handle, F_GETFL, 0) 
 727          or die "can't get flags: $!";
 728      fcntl($handle, F_SETFL, $old_flags | O_NONBLOCK) 
 729          or die "can't set non blocking: $!";
 731  Rather than losing yourself in a morass of twisting, turning C<ioctl>s,
 732  all dissimilar, if you're going to manipulate ttys, it's best to
 733  make calls out to the stty(1) program if you have it, or else use the
 734  portable POSIX interface.  To figure this all out, you'll need to read the
 735  termios(3) manpage, which describes the POSIX interface to tty devices,
 736  and then L<POSIX>, which describes Perl's interface to POSIX.  There are
 737  also some high-level modules on CPAN that can help you with these games.
 738  Check out Term::ReadKey and Term::ReadLine.
 740  =head2 Opening Sockets
 742  What else can you open?  To open a connection using sockets, you won't use
 743  one of Perl's two open functions.  See 
 744  L<perlipc/"Sockets: Client/Server Communication"> for that.  Here's an 
 745  example.  Once you have it, you can use FH as a bidirectional filehandle.
 747      use IO::Socket;
 748      local *FH = IO::Socket::INET->new("www.perl.com:80");
 750  For opening up a URL, the LWP modules from CPAN are just what
 751  the doctor ordered.  There's no filehandle interface, but
 752  it's still easy to get the contents of a document:
 754      use LWP::Simple;
 755      $doc = get('http://www.linpro.no/lwp/');
 757  =head2 Binary Files
 759  On certain legacy systems with what could charitably be called terminally
 760  convoluted (some would say broken) I/O models, a file isn't a file--at
 761  least, not with respect to the C standard I/O library.  On these old
 762  systems whose libraries (but not kernels) distinguish between text and
 763  binary streams, to get files to behave properly you'll have to bend over
 764  backwards to avoid nasty problems.  On such infelicitous systems, sockets
 765  and pipes are already opened in binary mode, and there is currently no
 766  way to turn that off.  With files, you have more options.
 768  Another option is to use the C<binmode> function on the appropriate
 769  handles before doing regular I/O on them:
 771      binmode(STDIN);
 772      binmode(STDOUT);
 773      while (<STDIN>) { print } 
 775  Passing C<sysopen> a non-standard flag option will also open the file in
 776  binary mode on those systems that support it.  This is the equivalent of
 777  opening the file normally, then calling C<binmode> on the handle.
 779      sysopen(BINDAT, "records.data", O_RDWR | O_BINARY)
 780          || die "can't open records.data: $!";
 782  Now you can use C<read> and C<print> on that handle without worrying
 783  about the non-standard system I/O library breaking your data.  It's not
 784  a pretty picture, but then, legacy systems seldom are.  CP/M will be
 785  with us until the end of days, and after.
 787  On systems with exotic I/O systems, it turns out that, astonishingly
 788  enough, even unbuffered I/O using C<sysread> and C<syswrite> might do
 789  sneaky data mutilation behind your back.
 791      while (sysread(WHENCE, $buf, 1024)) {
 792          syswrite(WHITHER, $buf, length($buf));
 793      } 
 795  Depending on the vicissitudes of your runtime system, even these calls
 796  may need C<binmode> or C<O_BINARY> first.  Systems known to be free of
 797  such difficulties include Unix, the Mac OS, Plan 9, and Inferno.
 799  =head2 File Locking
 801  In a multitasking environment, you may need to be careful not to collide
 802  with other processes who want to do I/O on the same files as you
 803  are working on.  You'll often need shared or exclusive locks
 804  on files for reading and writing respectively.  You might just
 805  pretend that only exclusive locks exist.
 807  Never use the existence of a file C<-e $file> as a locking indication,
 808  because there is a race condition between the test for the existence of
 809  the file and its creation.  It's possible for another process to create
 810  a file in the slice of time between your existence check and your attempt
 811  to create the file.  Atomicity is critical.
 813  Perl's most portable locking interface is via the C<flock> function,
 814  whose simplicity is emulated on systems that don't directly support it
 815  such as SysV or Windows.  The underlying semantics may affect how
 816  it all works, so you should learn how C<flock> is implemented on your
 817  system's port of Perl.
 819  File locking I<does not> lock out another process that would like to
 820  do I/O.  A file lock only locks out others trying to get a lock, not
 821  processes trying to do I/O.  Because locks are advisory, if one process
 822  uses locking and another doesn't, all bets are off.
 824  By default, the C<flock> call will block until a lock is granted.
 825  A request for a shared lock will be granted as soon as there is no
 826  exclusive locker.  A request for an exclusive lock will be granted as
 827  soon as there is no locker of any kind.  Locks are on file descriptors,
 828  not file names.  You can't lock a file until you open it, and you can't
 829  hold on to a lock once the file has been closed.
 831  Here's how to get a blocking shared lock on a file, typically used
 832  for reading:
 834      use 5.004;
 835      use Fcntl qw(:DEFAULT :flock);
 836      open(FH, "< filename")  or die "can't open filename: $!";
 837      flock(FH, LOCK_SH)         or die "can't lock filename: $!";
 838      # now read from FH
 840  You can get a non-blocking lock by using C<LOCK_NB>.
 842      flock(FH, LOCK_SH | LOCK_NB)
 843          or die "can't lock filename: $!";
 845  This can be useful for producing more user-friendly behaviour by warning
 846  if you're going to be blocking:
 848      use 5.004;
 849      use Fcntl qw(:DEFAULT :flock);
 850      open(FH, "< filename")  or die "can't open filename: $!";
 851      unless (flock(FH, LOCK_SH | LOCK_NB)) {
 852      $| = 1;
 853      print "Waiting for lock...";
 854      flock(FH, LOCK_SH)  or die "can't lock filename: $!";
 855      print "got it.\n"
 856      } 
 857      # now read from FH
 859  To get an exclusive lock, typically used for writing, you have to be
 860  careful.  We C<sysopen> the file so it can be locked before it gets
 861  emptied.  You can get a nonblocking version using C<LOCK_EX | LOCK_NB>.
 863      use 5.004;
 864      use Fcntl qw(:DEFAULT :flock);
 865      sysopen(FH, "filename", O_WRONLY | O_CREAT)
 866          or die "can't open filename: $!";
 867      flock(FH, LOCK_EX)
 868          or die "can't lock filename: $!";
 869      truncate(FH, 0)
 870          or die "can't truncate filename: $!";
 871      # now write to FH
 873  Finally, due to the uncounted millions who cannot be dissuaded from
 874  wasting cycles on useless vanity devices called hit counters, here's
 875  how to increment a number in a file safely:
 877      use Fcntl qw(:DEFAULT :flock);
 879      sysopen(FH, "numfile", O_RDWR | O_CREAT)
 880          or die "can't open numfile: $!";
 881      # autoflush FH
 882      $ofh = select(FH); $| = 1; select ($ofh);
 883      flock(FH, LOCK_EX)
 884          or die "can't write-lock numfile: $!";
 886      $num = <FH> || 0;
 887      seek(FH, 0, 0)
 888          or die "can't rewind numfile : $!";
 889      print FH $num+1, "\n"
 890          or die "can't write numfile: $!";
 892      truncate(FH, tell(FH))
 893          or die "can't truncate numfile: $!";
 894      close(FH)
 895          or die "can't close numfile: $!";
 897  =head2 IO Layers
 899  In Perl 5.8.0 a new I/O framework called "PerlIO" was introduced.
 900  This is a new "plumbing" for all the I/O happening in Perl; for the
 901  most part everything will work just as it did, but PerlIO also brought
 902  in some new features such as the ability to think of I/O as "layers".
 903  One I/O layer may in addition to just moving the data also do
 904  transformations on the data.  Such transformations may include
 905  compression and decompression, encryption and decryption, and transforming
 906  between various character encodings.
 908  Full discussion about the features of PerlIO is out of scope for this
 909  tutorial, but here is how to recognize the layers being used:
 911  =over 4
 913  =item *
 915  The three-(or more)-argument form of C<open> is being used and the
 916  second argument contains something else in addition to the usual
 917  C<< '<' >>, C<< '>' >>, C<< '>>' >>, C<< '|' >> and their variants,
 918  for example:
 920      open(my $fh, "<:crlf", $fn);
 922  =item *
 924  The two-argument form of C<binmode> is being used, for example
 926      binmode($fh, ":encoding(utf16)");
 928  =back
 930  For more detailed discussion about PerlIO see L<PerlIO>;
 931  for more detailed discussion about Unicode and I/O see L<perluniintro>.
 933  =head1 SEE ALSO 
 935  The C<open> and C<sysopen> functions in perlfunc(1);
 936  the system open(2), dup(2), fopen(3), and fdopen(3) manpages;
 937  the POSIX documentation.
 939  =head1 AUTHOR and COPYRIGHT
 941  Copyright 1998 Tom Christiansen.  
 943  This documentation is free; you can redistribute it and/or modify it
 944  under the same terms as Perl itself.
 946  Irrespective of its distribution, all code examples in these files are
 947  hereby placed into the public domain.  You are permitted and
 948  encouraged to use this code in your own programs for fun or for profit
 949  as you see fit.  A simple comment in the code giving credit would be
 950  courteous but is not required.
 952  =head1 HISTORY
 954  First release: Sat Jan  9 08:09:11 MST 1999

Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1