Provided by: libparanoid-perl_2.05-2_all bug

NAME

       Paranoid::IO - Paranoid IO support

VERSION

       $Id: lib/Paranoid/IO.pm, 2.05 2017/02/06 01:48:57 acorliss Exp $

SYNOPSIS

         use Fcntl qw(:DEFAULT :flock :mode :seek);
         use Paranoid::IO;

         # Implicit open
         $chars = pread("./foo.log", $in, 2048);

         # Implcit write/append
         $chars = pwrite("./bar.log", $out);
         $chars = pappend("./bar.log", $out);

         # Adjust block read size
         PIOBLKSIZE = 8192;

         # Adjust max file size for file scans
         PIOMAXFSIZE = 65536;

         # Explicit open
         $fh = popen($filename, O_RDWR | O_CREAT | O_TRUNC, 0600);
         $rv = pseek($filename, 0, SEEK_END);
         if ($rv > 0) {
           pseek($filename, 0, SEEK_SET) && ptruncate($filename);
         }
         $rv = pwrite($fileanme, $text) && pclose($filename);

         $rv = pclose($filename);

DESCRIPTION

       Paranoid::IO is intended to make basic file I/O access easier while keeping with the
       tenets of paranoid programming.  Most of these calls are essentially wrappers for the
       basic system calls (exposed as sysopen, syswrite, etc.) with some additional logic to
       reduce the need to explicitly code every step of normal safe access rules, such as file
       locking.  In the most basic of usage patterns, even explicitly opening files isn't
       necessary.

       For the most part the system calls that are wrapped here act identically as the underlying
       calls, both in the arguments they take and the values they return.  The one notable
       difference, however, is the popen function itself.  A glob variable isn't passed for
       assignation since this module stores those references internally along with some meta
       data, so popen returns file handles directly.

       That semantic, however, is what gives the rest of the functions the flexibility of
       accepting either a file name or a file handle to work on.  In the case of file names some
       of these functions can open files automatically, and the rest of the features are granted
       automatically.

       In the case of passing file handles the full feature set of this module is only available
       if the file handle was originally opened with popen.  The calls will still work even if it
       wasn't, but some of the safety features, like being fork-safe, won't have the meta data to
       work properly.

       The features provided by this module are:

       •   Opportunistic file access

       •   File handle caching

       •   Fork-safe file access

       •   Inherent file locking

       •   O_APPEND access patterns where needed even for files not opened with O_APPEND

       •   Intelligent file tracking

       The following sections will explain each feature in more depth:

   Opportunistic file access
       Opportunistic file access is defined here as not needing the explicit I/O handling for
       what can be implied.  For instance, to read content from a file one can simply use the
       pread function without having to open and apply a shared file lock.  In a similar manner
       one should be able to write or append to a file.  Files are automatically opened (with the
       file mode being intuited by the type of call) as needed.  Only where more complicated
       access patterns (such as read/write file handles) should an explicit popen call be needed.

       Opportunism is limited to where it makes sense, however.  Files are not opportunistically
       opened if the first I/O call is to pseek, ptell, or pflock.  The intent of the file I/O
       (in regards to read/write file modes) is impossible to tell within those calls.

   File handle caching
       This module provides a replacement for Perl's internal sysopen, which should be used even
       where read/write file access is necessary.  One key benefit for doing so is that it
       provides internal file handle caching based on the file name.  All the additional
       functions provided by this module use it internally to retrieve that cached file handle to
       avoid the overhead of repetitive opening and closing of files.

   Fork-safe file access
       A greater benefit of popen, however, is in it's fork-safe behavior.  Every call checks to
       see if the file handle it has was inherited from its parent, and if so, transparently
       closed and reopened so I/O can continue without both processes conflicting over cursor
       positions and buffers.  After files are reopened read cursors are placed at the same
       location they were prior to the first I/O access in the child.

       File modes are preserved without the obvious conflicts of intent as well.  Files opened in
       the parent with O_TRUNC are reopened without that flag to prevent content from being
       clobbered.

   Inherent file locking
       Except where explicitly ignored (like for pnlread) all read, write, and append operations
       use locking internally, alleviating the need for the developer to do so explicitly.  Locks
       are applied and removed as quickly as possible to facilitate concurrent access.

   O_APPEND access patterns
       pappend allows you to mimic O_APPEND access patterns even for files that weren't
       explicitly opened with O_APPEND.  If you open a file with O_RDWR you can still call
       pappend and the content will be appended to the end of the file, without moving the file's
       cursor position for regular reads and writes.

   Intelligent file tracking
       popen caches file handles by file name.  If files are opened with relative paths this has
       the potential to cause some confusion if the process or children are changing their
       working directories.  In anticipation of this popen also tracks the real path (as resolved
       by the realpath system call) and file name.  This way you can still access the same file
       regardless of the process or its children's movements on the file system.

       This could be, however, a double-edged sword if your program intends to open identically
       named files in multiple locations.  If that is your intent you would be cautioned to avoid
       using relative paths with popen.

SUBROUTINES/METHODS

   PIOBLKSIZE
           PIOBLKSIZE = 65536;

       This lvalue function is not exported by default.  It is used to determine the default
       block size to read when a size is not explicitly passed.  Depending on hardware and file
       system parameters there might be performance gains to be had when doing default-sized
       reads.  The default is 4096, which is generally a safe size for most applications.

   PIOMAXFSIZE
           PIOMAXFSIZE = 65536;

       This lvalue function is not exported by default.  It is used to determine the maximum file
       size that will be read.  This is not used in this module, but provided for use in
       dependent modules that may want to impose file size limits, such as Paranoid::IO::Line and
       others.

   popen
           $fh = popen($filename);
           $fh = popen($filename, $mode);
           $fh = popen($filename, $mode, $perms);
           $fh = popen($fh);

       Returns a file handle if the file could be opened.  If the mode is omitted the default is
       O_CREAT | O_RDWR.  File permissions (for newly created files) default to 0666 ^ UMASK.

       Failures to open a file will result in an undef return value, with a text description of
       the fault stored in Paranoid::ERROR.

       If a file handle is passed to popen it will attempt to match it to a tracked file handle
       and, if identified, take the appropriate action.  If it doesn't match any tracked file
       handles it will just return that file handle back to the caller.

   pclose
           $rv = pclose($filename);
           $rv = pclose($fh);

       Returns the value from close.  Attempts to close a file that's already closed is
       considered a success, and true value is returned.  Handing it a stale file handle,
       however, will be handed to the internal close, with all the expected results.

   preopen
           $rv = preopen();
           $rv = preopen(@filenames);
           $rv = preopen(@filehandles);

       This checks each tracked file handle (i.e., file handles that were opened by popen) and
       reopens them if necessary.  This is typically only useful after a fork.  It is also not
       striclty necessary since every call to a function in this module does that with every
       invocation, but if you have several file handles that you may not access immediately you
       run the risk of the parent moving the current file position before the child gets back to
       those files.  You may or may not care.  If you do, use this function immediately after a
       fork.

       Called with a list of file names means that only those files are examined and reopened.
       Any failure to reopen any single file handle will result in a false return value.  That
       said, any failures will not interrupt the function from trying every file in the list.

   pcloseAll
           $rv = pcloseAll();
           $rv = pcloseAll(@filenames);
           $rv = pcloseAll(@filehandles);

       This function returns a boolean value denoting any errors while trying to close every
       tracked file handle.  This function is also not strictly necessary for all the normal Perl
       I/O reasons, but it's here for those that want to be explicit.

   ptell
           $pos = ptell($filename);
           $pos = ptell($fh);

       Returns the current position of the file cursor.  Returns the results of sysseek, which
       means that any successful seek is true, even if the cursor is at the beginning of the
       file.  In that instance it returns "0 but true" which is boolean true while converting to
       an integer appropriately.

       Any failures are returned as false or undef.

   pseek
           $rv = pseek($filename, $pos, $whence);
           $rv = pseek($fh, $pos, $whence);

       This returns the return value from sysseek.  The appropriate whence values sould be one of
       the SEEK_* constants as exported by Fcntl.

   pflock
           $rv = pflock($filename, $locktype);
           $rv = pflock($fh, $locktype);

       This returns the return value from flock.  The appropriate lock type values should be one
       of the LOCK_* constants as exported by Fcntl.

       NOTE:  If you wish to control file locking yourself you can do so with this function.  Any
       existing locks explicitly applied are tracked and will cause read/write functions to
       refrain from attempting to apply (and remove) locks automatically.

   pread
           $bytes = pread($filename, $text, $length);
           $bytes = pread($filename, $text, $length, $offset);
           $bytes = pread($fh, $text, $length);
           $bytes = pread($fh, $text, $length, $offset);

       This returns the number of bytes read, or undef on errors.  If this is called prior to an
       explicit popen it will default to a mode of O_RDONLY.  Length defaults to PIOBLKSIZE.

   pnlread
           $bytes = pnlread($filename, $text, $length);
           $bytes = pnlread($filename, $text, $length, $offset);
           $bytes = pnlread($fh, $text, $length);
           $bytes = pnlread($fh, $text, $length, $offset);

       File locks are inherent on all reads and writes.  There are plenty of legitimate scenarios
       where a read needs to be done ignoring any file locks.  It is for those situations that
       this function exists.  It acts identically in every way to pread with the lone exception
       that it does not perform file locking.

   pwrite
           $bytes = pwrite($filename, $text);
           $bytes = pwrite($filename, $text, $length);
           $bytes = pwrite($filename, $text, $length, $offset);
           $bytes = pwrite($fh, $text);
           $bytes = pwrite($fj, $text, $length);
           $bytes = pwrite($fh, $text, $length, $offset);

       This returns the number of bytes written, or undef for any critical failures.  If this is
       called prior to an explicit popen it uses a default mode of O_WRONLY | O_CREAT | O_TRUNC.

   pappend
           $bytes = pappend($filename, $text);
           $bytes = pappend($filename, $text, $length);
           $bytes = pappend($filename, $text, $length, $offset);
           $bytes = pappend($fh, $text);
           $bytes = pappend($fh, $text, $length);
           $bytes = pappend($fh, $text, $length, $offset);

       This behaves identically to pwrite with the sole exception that this preserves the file
       position after explicitly seeking and writing to the end of the file.  The default mode
       here, however, would be O_WRONLY | O_CREAT | O_APPEND for those files not explicitly
       opened.

   ptruncate
           $rv = ptruncate($filename);
           $rv = ptruncate($filename, $pos);
           $rv = ptruncate($fh);
           $rv = ptruncate($fh, $pos);

       This returns the result of the internal truncate call.  If called without an explicit
       popen it will open the named file with the default mode of O_RDWR | O_CREAT.  Omitting the
       position to truncate from will result in the file being truncated at the beginning of the
       file.

DEPENDENCIES

       o   Cwd

       o   Fcntl

       o   IO::Handle

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::Input

BUGS AND LIMITATIONS

       It may not always be benficial to cache file handles.  You must explicitly pclose file
       handles to avoid that.  That said, with straight Perl you'd have to either explicitly
       close the file handles or use lexical scoping, anyway.  From that perspective I don't find
       it onerous to do so, especially with all of the other code-saving features this module
       provides.

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is licensed under the same terms as Perl, itself.  Please see
       http://dev.perl.org/licenses/ for more information.

       (c) 2005 - 2017, Arthur Corliss (corliss@digitalmages.com)