.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Paranoid::IO 3pm"
.TH Paranoid::IO 3pm "2018-11-09" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Paranoid::IO \- Paranoid IO support
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR lib/Paranoid/IO.pm, 2.06 2018/08/05 01:21:48 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBParanoid::IO\fR 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.
.PP
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 \fIpopen\fR function itself.
A glob variable isn't passed for assignation since this module stores those
references internally along with some meta data, so \fIpopen\fR returns file
handles directly.
.PP
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.
.PP
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 \fIpopen\fR.  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.
.PP
The features provided by this module are:
.IP "\(bu" 4
Opportunistic file access
.IP "\(bu" 4
File handle caching
.IP "\(bu" 4
Fork-safe file access
.IP "\(bu" 4
Inherent file locking
.IP "\(bu" 4
O_APPEND access patterns where needed even for files not opened with
O_APPEND
.IP "\(bu" 4
Intelligent file tracking
.PP
The following sections will explain each feature in more depth:
.SS "Opportunistic file access"
.IX Subsection "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 \fIpread\fR 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 \fIpopen\fR call be needed.
.PP
Opportunism is limited to where it makes sense, however.  Files are not
opportunistically opened if the first I/O call is to \fIpseek\fR, \fIptell\fR, or
\&\fIpflock\fR.  The intent of the file I/O (in regards to read/write file modes)
is impossible to tell within those calls.
.SS "File handle caching"
.IX Subsection "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.
.SS "Fork-safe file access"
.IX Subsection "Fork-safe file access"
A greater benefit of \fIpopen\fR, 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.
.PP
File modes are preserved without the obvious conflicts of intent as well.  
Files opened in the parent with \fBO_TRUNC\fR are reopened without that flag 
to prevent content from being clobbered.
.SS "Inherent file locking"
.IX Subsection "Inherent file locking"
Except where explicitly ignored (like for \fIpnlread\fR) 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.
.SS "O_APPEND access patterns"
.IX Subsection "O_APPEND access patterns"
\&\fIpappend\fR allows you to mimic \fBO_APPEND\fR access patterns even for files that
weren't explicitly opened with \fBO_APPEND\fR.  If you open a file with \fBO_RDWR\fR
you can still call \fIpappend\fR and the content will be appended to the end of
the file, without moving the file's cursor position for regular reads and
writes.
.SS "Intelligent file tracking"
.IX Subsection "Intelligent file tracking"
\&\fIpopen\fR 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
\&\fIpopen\fR 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.
.PP
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 \fIpopen\fR.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "\s-1PIOBLKSIZE\s0"
.IX Subsection "PIOBLKSIZE"
.Vb 1
\&    PIOBLKSIZE = 65536;
.Ve
.PP
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.
.SS "\s-1PIOMAXFSIZE\s0"
.IX Subsection "PIOMAXFSIZE"
.Vb 1
\&    PIOMAXFSIZE = 65536;
.Ve
.PP
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.
.SS "popen"
.IX Subsection "popen"
.Vb 4
\&    $fh = popen($filename);
\&    $fh = popen($filename, $mode);
\&    $fh = popen($filename, $mode, $perms);
\&    $fh = popen($fh);
.Ve
.PP
Returns a file handle if the file could be opened.  If the mode is omitted the
default is \fBO_CREAT | O_RDWR\fR.  File permissions (for newly created files)
default to \fB0666 ^ \s-1UMASK\s0\fR.
.PP
Failures to open a file will result in an undef return value, with a text
description of the fault stored in \fBParanoid::ERROR\fR.
.PP
If a file handle is passed to \fIpopen\fR 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.
.SS "pclose"
.IX Subsection "pclose"
.Vb 2
\&    $rv = pclose($filename);
\&    $rv = pclose($fh);
.Ve
.PP
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 \fBclose\fR, with all
the expected results.
.SS "preopen"
.IX Subsection "preopen"
.Vb 3
\&    $rv = preopen();
\&    $rv = preopen(@filenames);
\&    $rv = preopen(@filehandles);
.Ve
.PP
This checks each tracked file handle (i.e., file handles that were opened by
\&\fIpopen\fR) 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.
.PP
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.
.SS "pcloseAll"
.IX Subsection "pcloseAll"
.Vb 3
\&    $rv = pcloseAll();
\&    $rv = pcloseAll(@filenames);
\&    $rv = pcloseAll(@filehandles);
.Ve
.PP
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.
.SS "ptell"
.IX Subsection "ptell"
.Vb 2
\&    $pos = ptell($filename);
\&    $pos = ptell($fh);
.Ve
.PP
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 \*(L"0 but true\*(R"
which is boolean true while converting to an integer appropriately.
.PP
Any failures are returned as false or undef.
.SS "pseek"
.IX Subsection "pseek"
.Vb 2
\&    $rv = pseek($filename, $pos, $whence);
\&    $rv = pseek($fh, $pos, $whence);
.Ve
.PP
This returns the return value from sysseek.  The appropriate whence values
sould be one of the \fBSEEK_*\fR constants as exported by Fcntl.
.SS "pflock"
.IX Subsection "pflock"
.Vb 2
\&    $rv = pflock($filename, $locktype);
\&    $rv = pflock($fh, $locktype);
.Ve
.PP
This returns the return value from flock.  The appropriate lock type values
should be one of the \fBLOCK_*\fR constants as exported by Fcntl.
.PP
\&\fB\s-1NOTE:\s0\fR This function essentially acts like a pass-through to the native
flock function for any file handle not opened via this module's functions.
.SS "pread"
.IX Subsection "pread"
.Vb 4
\&    $bytes = pread($filename, $text, $length);
\&    $bytes = pread($filename, $text, $length, $offset);
\&    $bytes = pread($fh, $text, $length);
\&    $bytes = pread($fh, $text, $length, $offset);
.Ve
.PP
This returns the number of bytes read, or undef on errors.  If this is called
prior to an explicit \fIpopen\fR it will default to a mode of \fBO_RDONLY\fR.  Length
defaults to \fB\s-1PIOBLKSIZE\s0\fR.
.SS "pnlread"
.IX Subsection "pnlread"
.Vb 4
\&    $bytes = pnlread($filename, $text, $length);
\&    $bytes = pnlread($filename, $text, $length, $offset);
\&    $bytes = pnlread($fh, $text, $length);
\&    $bytes = pnlread($fh, $text, $length, $offset);
.Ve
.PP
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 \fIpread\fR with the lone exception that it does not perform file
locking.
.SS "pwrite"
.IX Subsection "pwrite"
.Vb 6
\&    $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);
.Ve
.PP
This returns the number of bytes written, or undef for any critical failures.
If this is called prior to an explicit \fIpopen\fR it uses a default mode of
\&\fBO_WRONLY | O_CREAT | O_TRUNC\fR.
.SS "pappend"
.IX Subsection "pappend"
.Vb 6
\&    $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);
.Ve
.PP
This behaves identically to \fIpwrite\fR 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 \fBO_WRONLY | O_CREAT |
O_APPEND\fR for those files not explicitly opened.
.SS "ptruncate"
.IX Subsection "ptruncate"
.Vb 4
\&    $rv = ptruncate($filename);
\&    $rv = ptruncate($filename, $pos);
\&    $rv = ptruncate($fh);
\&    $rv = ptruncate($fh, $pos);
.Ve
.PP
This returns the result of the internal truncate call.  If called without
an explicit \fIpopen\fR it will open the named file with the default mode of
\&\fBO_RDWR | O_CREAT\fR.  Omitting the position to truncate from will result in
the file being truncated at the beginning of the file.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Cwd
.IP "o" 4
.IX Item "o"
Fcntl
.IP "o" 4
.IX Item "o"
IO::Handle
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.IP "o" 4
.IX Item "o"
Paranoid::Input
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
It may not always be benficial to cache file handles.  You must explicitly
\&\fIpclose\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005 \- 2017, Arthur Corliss (corliss@digitalmages.com)