Opportunistic file access

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

Fork-safe file access

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

O_APPEND access patterns

Intelligent file tracking

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.

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 = 131072;

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.

The default is 65536.

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: This function essentially acts like a pass-through to the native flock function for any file handle not opened via this module's functions.

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.