Linux Certif

Toute la documentation sur la certification Linux LPI

FileHandle::Deluxe.3pm

NAME

FileHandle::Deluxe - file handle with a lot of extra features

SYNOPSIS

         use FileHandle::Deluxe;
 
 

         # Open for read: Don't bother checking for open success, 
         # that's done automatically.  Don't bother locking either,
         # that's also done automatically.
         $fh = FileHandle::Deluxe->new($path);
 
 

         # Handle stringifies to the path being read
         print 'reading from ', $fh, "\n";
 
 

         # Loop through the file handle as usual
         # the handle is lazy: the file isn't actually
         # opened until the first read.
         while (<$fh>) {
                 ...
         }
 
 

         # the handle automatically closes when the
         # the last line is read
 
 

INSTALLATION

FileHandle::Deluxe can be installed with the usual routine:

         perl Makefile.PL
         make
         make test
         make install
 
 

You can also just copy Deluxe.pm into the FileHandle/ directory of one of your library trees.

DESCRIPTION

FileHandle::Deluxe works like a regular FileHandle object, with the addition of doing the routine file handle chores for you. FileHandle::Deluxe (FD) is targeted at beginning Perl users who usually find those tasks intimidating and often elect to skip them rather than learn how to do them. FileHandle::Deluxe defaults to a set of best practices for working with file handles.

The following sections describe the practices and features implemented by FD.

Security

FileHandles are the most notorious source of Perl application security holes. FD implements a strict set of security rules. Rather than allowing users ``enough rope to hang themselves'', FD forces the user to either program more securely or explicitly acknowlege that their program uses insecure techniques. Hopefully most FD users will choose the first option.

For beginners, FD refuses to run unless either Perl is in taint mode or the developer gives explicit permission for FD to run while not in taint mode. See the documentation on the allow_insecure_code option below for more details.

FD also dispenses with the traditional notation for indicating if a file should be opened for reading, writing, etc. For example, the argument ``> mydata.txt'' would be prohibited. Instead, to indicate opening a file for writing, the command for a new file handle would use the "write" option:

  $fh = FileHandle::Deluxe->new($path, write=>1);
 
 

FD refuses to open any file using a tainted path. (Regular file handles will open files for read using tainted paths.) Users, however, frequently find the task of properly untainting paths more than they want to deal with, so FD helps out. The user may indicate that certain files, directories, or entire directory trees are ``safe''. Tainted data paths may be used to open files within safe locations. See the sections for safe_files, safe_dirs, and safe_trees below for more details.

FD also addresses security issues with executable files. When an FD file handle is opened for piping to and from an executable, FD automatically uses the more secure exec method for opening the file handles. The exec method opens the executables directly, instead of spawning an intermediate shell, thereby bypassing shell hacks. See the sections for pipe_to and pipe_from below for more details.

File Locking

File locking is a file handle housekeeping nuisance that even experienced Perl programmers often overlook. FD takes care of file locking chores for you. Files that are opened as read only get a shared lock. Files that are opened as writable get an exclusive lock. See the section on file locks below for more details.

Resource Conservation

FD file handles are ``lazy''... they do not open the files until they are actually used. Furthermore, for read-only files, the file handles are closed once the last line of the file is read. By using these conservation features, a function can return a large number of FD objects (perhaps representing all the files in a directory) without using up limited system file handles. See the section on the lazy and auto_close options below for more details.

Convenience

FD simplifies many tasks associated with working with files. For beginners, FD objects stringify to the file paths, so a function can return a series of FD objects that can be easily used to output file names. FD handles also provide the ability to quickly slurp in the entire contents of a file either as an array of pre-chomped lines or as a single string. See the lines and contents methods below, and also the non-OO functions file_lines and file_contents.

Speaking of chomping, FD handles can also be set to automatically chomp lines as you pull them from the file. See the auto_chomp option for more details.

METHODS

FileHandle->new($path);

The "new" method creates a new FileHandle::Deluxe object. The first and only required argument is a file path:

  $fh = FileHandle::Deluxe->new($path);
 
 

If there are no further arguments, the file is opened for reading, the file gets a shared lock, and the entire program croaks if the file cannot be opened. The path may not be tainted unless the safe_files, safe_dirs, and/or safe_trees options are used (see option list below for more details).

The following optional arguments may be passed to "new". None of these arguments may be tainted.

append

Open the file for appending... that is, add to the file without deleting what is already there. The file does not need to already exist. If this option is set, then the "write" option is also assumed to be true.

Example:

  $fh = FileHandle::Deluxe->new('data.txt', append=>1);
 
 

allow_insecure_code

This option must be set to true if you want to use FileHandle::Deluxe while not running in taint mode. It is highly recommended that you always run Perl in taint mode until you are clear on when it is ok not to use tainting. In particular, you should always use taint mode for web applications, regardless of how safe you think your script is. If you are making the mistake of developing a web application without using tainting, consider the words of Randal L. Schwartz, one of the world's foremost experts on Perl: ``*All* of my Web scripts run with taintchecks on. Cuz I make mistakes sometimes. Fancy that. :-)''

To run Perl in taint mode, add a capital T to your bang path:

  #!/usr/local/bin/perl -wT
 
 

You'll probably also want to set $ENV{'PATH'} to an empty string at the top of your script:

  $ENV{'PATH'} = '';
 
 

If you are sure that you want to run Perl without tainting, you can use FileHandle::Deluxe by adding the allow_insecure_code option to your call to new:

  $fh = FileHandle::Deluxe->new($path, allow_insecure_code=>1);
 
 

allow_insecure_program_arguments

FileHandle::Deluxe uses the piped exec method for opening executables. That means that, among things, tainted arguments can be passed to the executable. Passing tainted arguments to an external program won't cause any security problems in your Perl script itself, but it might cause security holes in the external program itself, so FileHandle::Deluxe does not allow it by default.

If you are sure you want to allow tainted arguments to be passed, set allow_insecure_program_arguments to true:

  $fh = FileHandle::Deluxe->new(
      $path, 
      pipe_to=>1,
      args=>[@arguments],
      allow_insecure_program_arguments=>1,
      );
 
 

If FileHandle::Deluxe uses the shell method for opening an executable (see allow_shell_execute below), and if tainting is on, then allow_insecure_program_arguments makes no difference, the arguments may not be tainted.

allow_shell_execute

FileHandle::Deluxe uses the piped exec method for opening executables (which is much more secure) if the operating system appears to support it. (The current test for supporting piped exec is if $^O contains the string ``Win'' ... i.e. it's a Windows machine... which is perhaps not the most robust test. Suggestions are welcome.) If it appears that the OS does NOT support piped execs, then it will open the executable using a shell, but only if the allow_shell_execute option is set to true, like this:

  $fh = FileHandle::Deluxe->new(
      $path, 
      pipe_to=>1,
      args=>[@arguments],
      allow_shell_execute=>1,
      );
 
 

If FileHandle::Deluxe uses the shell method for opening an executable, and if tainting is on, then program arguments may not be tainted.

args

Arguments to pass to an external executable. For example, the following code sends four arguments to sendmail:

  $fh = FileHandle::Deluxe->new(
      $sendmail, 
      pipe_to=>1,
      args=>['-t', '-f', 'error@idocs.com', 'miko@idocs.com'],
      );
 
 

auto_close

By default, FileHandle::Deluxe closes read-only files when the last line is read. This conserves system file handles and frees up locks for other objects that may be using the same file. If you want the handle to keep the file open after the last line is read, set "auto_close" to false:

  $fh = FileHandle::Deluxe->new($path, auto_close=>0);
 
 

auto_chomp

The "auto_chomp" option (which is not on by default) tells the file handle to remove trailing end-of-line characters each time a line is read from the file. So, for example, the following code reads all the lines from the file, removing end-of-line characters form each line:

  $fh = FileHandle::Deluxe->new($path, auto_chomp=>1);
 
 

  while (<$fh>) {
    if ($_ eq 'Fred'){...}
    elsif ($_ eq 'Barney'){...}
  }
 
 

Contrary to what you might expect, empty lines and lines consisting of the zero character (``0''), do not fail the initial test in the while loop. That's because in "auto_chomp" mode, the returned ``line'' is really an object that boolifies to true the first time it is tested. All subsequent boolean tests are based on the content of the line. The object always stringifies to the text of the line in the file, so use it like a regular string.

auto_croak

By default, FileHandle::Deluxe croaks if it is unable to open the file. If you would prefer to do your own croaking, set "auto_croak" to false.

  $fh = FileHandle::Deluxe->new($path, auto_croak=>0);
 
 

If "auto_croak" is set to false then "lazy_open" defaults to false as well, meaning that the open attempt occurs when the FileHandle::Deluxe object is created.

lazy_open

By default, FileHandle::Deluxe does not open the file until a read or write call is made to the file handle. If you want the file to open when "new" is called, set "lazy_open" to false:

  $fh = FileHandle::Deluxe->new($path, lazy_open=>1);
 
 

"lazy_open" defaults to false if you set "auto_croak" to false.

lock

By default, FileHandle::Deluxe gets a shared lock for read-only file handles and an exclusive lock for write or read/write handles. If you want to get a different type of lock, or no lock at all, set the "lock" option. For no lock, set "lock" to 0:

  $fh = FileHandle::Deluxe->new($path, lock=>0);
 
 

For any other lock, use LOCK_SH (shared lock), LOCK_EX (exclusive lock), and LOCK_NB (do not wait for lock). To use these constants, you must add the ':all' option to your use FileHandle::Deluxe call, like this:

  use FileHandle::Deluxe ':all';
 
 

pipe_from, pipe_to

"pipe_from" and "pipe_to" indicate to pipe to or from an executable file. For example, the following command indicates to open a handle for piping to Sendmail (where $sendmail is the path to the Sendmail executable):

  $fh = FileHandle::Deluxe->new($sendmail, pipe_to=>1);
 
 

Any arguments you want passed to the executable should be sent with the "args" option as an array reference:

  $fh = FileHandle::Deluxe->new(
      $sendmail, 
      pipe_to=>1,
      args=>['-t', '-f', 'error@idocs.com', 'miko@idocs.com'],
      );
 
 

plain_path

"plain_path", which is true by default, indicates that if the given file is tainted, it may only consist of a ``plain'' file path characters, that is, single dots, alphanumerics, spaces, underscores, and slashes. Doubles dots, ampersands, pipes, and other fancy characters are prohibited.

"plain_path" is the single best security layer FileHandle::Deluxe gives you. It is highly recommended that you do not disable "plain_path".

read

Indicates that the file should be open for reading. If none of "write", "append", "pipe_to", or "pipe_from" are sent than "read" defaults to true.

safe_files, safe_dirs, safe_trees

These options indicate ``safe'' locations for the file. The file path must be within one of the locations for each of these options that is sent, or it will not be opened. If the file path is tainted, but is within one of these locations, then it will be opened.

"safe_files" gives a list of complete file paths. The path for opening must be one of the given paths. For example, the following command indicates that FileHandle::Deluxe may open data.txt, names.txt, or adds.txt:

  $fh = FileHandle::Deluxe->new(
      $path, 
      safe_files=>['data.txt', 'names.txt', 'adds.txt'],
      );
 
 

"safe_dirs" gives a list of directories, one of which the file must be in. The file must be directly within the directory, not nested deeper in the directory tree (see "safe_trees" below for that). For example, the following command indicates that the file must be directly within ./data/, ./names/, or ./adds/:

  $fh = FileHandle::Deluxe->new(
      $path, 
      safe_dirs=>['./data/', './names/', './adds/'],
      );
 
 

"safe_trees" also gives a list of directories, but the file may be anywhere nested within one of the directories, not necessarily directly within it. So, for example, if one of the given directories was ./adds/:

  $fh = FileHandle::Deluxe->new(
      $path, 
      safe_trees=>['./data/', './names/', './adds/'],
      );
 
 

then ./adds/joined/data.txt, ./adds/joined/quit/data.txt, as well as ./adds/data.txt would all be accepted.

traditional_open_notation

"traditional_open_notation", which is false by default, indicates that FileHandle::Deluxe should open the file using traditional Perl file handle opening notation. For example, traditionally a handle for writing to a file would be opened like this (notice the > at the beginning of the path string):

  $fh = FileHandle->new('> data.txt') or die $!;
 
 

The problem with that technique is that it makes it easier for careless programming to open security holes. If the file path is carelessly untainted then unintended commands can be run through the shell. FileHandle::Deluxe prohibits shell meta-characters unless you explictly choose to use them with "traditional_open_notation":

  $fh = FileHandle->new('> data.txt', traditional_open_notation=>1);
 
 

Avoid using "traditional_open_notation". Use the "read", "write", "append", "pipe_to", and "pipe_from" options instead. "traditional_open_notation" also negates the "plain_path" option, another important security layer.

write

"write" indicates that the file should be opened for writing:

  $fh = FileHandle->new('data.txt', write=>1);
 
 

contents

The "contents" method returns the entire contents of the file. In array context it returns each line as an individual array element. In scalar context it returns the file as a single string. So, for example, the following command outputs the entire file:

  print $fh->contents;
 
 

lines

The "contents" method returns the entire contents of the file as an array. Each line is an individual element in the array. All lines are chomped. For example, the following code assigns the lines to an array:

  @names = $fh->lines;
 
 

file_contents, file_lines

"file_contents" and "file_lines" are static (i.e. no object required) equivalents for slurping in the entire contents of a file. These commands can be imported by adding the ':all' option to your use FileHandle::Deluxe call, like this:

  use FileHandle::Deluxe ':all';
 
 

Each of these commands takes the file path as the first argument:

  print file_contents('data.txt');
  @arr file_lines('data.txt');
 
 

MISC INTERESTING STUFF

FileHandle::Deluxe objects stringify to the path for the file they open. That means you can use the object as a string if you want to know the path:

         print 'reading from ', $fh, "\n";
 
 

TERMS AND CONDITIONS

Copyright (c) 2001-2002 by Miko O'Sullivan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with NO WARRANTY of any kind.

AUTHOR

Miko O'Sullivan miko@idocs.com

VERSION

Version 0.90 Aug 19, 2002

Initial release

Version 0.91 Aug 21, 2002

Bug fixes

Version 0.92 Aug 23, 2002

Bug fixes