Paranoid::IO(3pm)

📦

version 2.10 · 3 versions

2.10 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
2.09 · ubuntu jammy
2.10 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Paranoid::IO — the manual, but make it make sense ✨

okay bestie, welcome to Paranoid::IO(3pm), aka the Perl module that is so careful with your files it's basically the friend who double-checks that the door is locked. twice. and then texts you about it. 🫶

🌸 NAME 🌸

Paranoid::IO — support for IO that is, and I cannot stress this enough, paranoid 💅

🎀 VERSION 🎀

$Id: lib/Paranoid/IO.pm, 2.10 2022/03/08 00:01:04 acorliss $

yeah that's the version string, exactly as it lives in the file, don't touch it, it's iconic ✨

🦋 SYNOPSIS 🦋

here's the whole vibe, code and all, no edits, no notes, just the goods 🍓

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

# 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;

# Enable flock lock stack
PIOLOCKSTACK = 1;

# Explicit open with explicit locking
$fh = popen($filename, O_RDWR | O_CREAT | O_TRUNC, 0600);
$rv = pseek($filename, 0, SEEK_END);
$rv = pflock($filename, LOCK_EX);
if ($rv > 0) {
  pseek($filename, 0, SEEK_SET) && ptruncate($filename);
}
$rv = pwrite($filename, $text)
$rv = ptell($filename);
$rv = plockstat($filename);

# Calls that ignore file locks
$rv = pnlwrite($filename, $text)
$rv = pnlappend($filename, $text)
$rv = pnlread($filename, $text)

# After fork
$rv = preopen();

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

okay quick tour because there's a lot going on here and I want you to be obsessed with it like I am 😭

use Fcntl qw(:DEFAULT :flock :mode :seek); pulls in the constant families you'll want — the default set, plus flock, mode and seek stuff. it's giving "I came prepared" 💅
use Paranoid::IO qw(:all); imports absolutely everything. all of it. the whole squad. 🔥
then we do the implicit open thing with pread("./foo.log", $in, 2048), where the open just… happens. sneaky. elegant.
implicit write/append is next: pwrite("./bar.log", $out) and pappend("./bar.log", $out) — same energy, no open call in sight ✨
wanna change how big your read blocks are? that's PIOBLKSIZE = 8192; — boom, adjusted 🎀
wanna cap how big a file can be before file scans say "no ma'am"? PIOMAXFSIZE = 65536; 💖
flock lock stack? enable it with PIOLOCKSTACK = 1; 👑
and if you like doing things explicitly, there's the whole popen / pseek / pflock / ptruncate / pwrite / ptell / plockstat pipeline, including an if ($rv > 0) guard that does pseek($filename, 0, SEEK_SET) && ptruncate($filename); 🌈
some calls ignore file locks entirely: pnlwrite($filename, $text), pnlappend($filename, $text), pnlread($filename, $text). the pnl is your lil hint. iykyk 💀
after a <purple>fork</purple>? preopen(); gets you sorted 🧚
and cleanup is pclose($filename) for one, pcloseAll() for literally all of them 💜

heads up bestie: that # Implcit write/append comment in there is spelled exactly like that in the original. I am not fixing it. I am not copying it wrong either. it stays. 🙈

💖 DESCRIPTION 💖

okay so Paranoid::IO is here to make your basic file I/O so much easier while still keeping every single paranoid-programming tenet intact, bestie. most of these calls are basically little wrappers around the plain system calls (the ones exposed as sysopen, syswrite, etc.) — but with extra logic sprinkled on top so you don't have to hand-code every single step of normal safe access rules, like file locking. and in the most basic usage patterns? you don't even have to open files explicitly at all. ✨

for the most part, the system calls wrapped in here act identically to the underlying calls — same arguments they take, same values they return. the one notable glow-up difference, though, is the popen function itself. a glob variable isn't passed for assignation, because this module stores those references internally along with some meta data, so popen returns file handles directly. 💅

and that semantic is exactly what gives the rest of the functions the flexibility to accept either a file name or a file handle to work on. with file names, some of these functions can open files automatically, and the rest of the features get granted automatically too. 🦋

with file handles, though — heads up — 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 this module serves up 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
🧚 Optional flock lock stack for transactional I/O patterns

the following sections will explain each feature in more depth:

🌈 Opportunistic file access

opportunistic file access means not needing the explicit I/O handling for what can be implied. for instance, to read content from a file you can just use the pread function without having to open and apply a shared file lock first. same energy with writing or appending to a file. files get opened automatically (with the file mode intuited from the type of call) as needed. only where you've got more complicated access patterns (like read/write file handles) should an explicit popen call be needed.

but the opportunism is limited to where it actually makes sense, okay? files are not opportunistically opened if the first I/O call is to pseek or ptell. the intent of the file I/O (as in, read/write file modes) is literally impossible to tell within those calls. sorry bestie, them's the rules. 🙈

💜 File handle caching

this module gives you a replacement for Perl's internal sysopen, and you should use it even where read/write file access is necessary. one key benefit: it provides internal file handle caching based on the file name. all the additional functions this module provides use it internally to retrieve that cached file handle, which avoids the overhead of repetitive opening and closing of files. iconic, honestly. ✨

🎀 Fork-safe file access

a greater benefit of popen, though, is its fork-safe behavior. every call checks to see if the file handle it has was inherited from its parent, and if so, it's 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. no cap, that's the main character energy right there. 👑

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, which alleviates the need for the developer to do so explicitly. locks are applied and removed as quickly as possible to facilitate concurrent access.

if you're managing flocks directly, though, all of the read/write functions in this module not only support an option boolean argument to disable internal flocking, but also have pnl* wrapper functions that set that argument for you. 💅

🌸 O_APPEND access patterns

pappend lets you 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. anticipating this, popen also tracks the real path (as resolved by the realpath system call) and file name. that 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 are cautioned to avoid using relative paths with popen. 💀

🧚 Optional flock lock stack for transactional I/O patterns

complex I/O patterns on file I/O can sometimes involve extensive nested function calls that each manipulate flocks independently. those nested calls can come into conflict when one call degrades a needed lock applied by a previous call. 😭

for instance, picture a pattern where a new block needs to be allocated to an opened file, but an index of blocks must be maintained within the same file. one might have a function which retrieves the list of block addresses from the index, and that function rationally applies a shared flock before reading, and removes it afterwards. one might try to get an exclusive lock on the file, then retrieve the index using the existing function. that function, however, would end up replacing your exclusive lock with the shared lock, potentially making it impossible to reacquire that exclusive lock depending on other processes and their I/O. ugh, the drama.

the lock stack attempts to solve those kinds of problems by maintaining a stack of flocks, and making sure that no new locks degrade the previous locks. in the previous example, it would notice that the stack was opened with an exclusive lock, and when the index retrieval function attempts to apply the shared lock, it would simply upgrade that lock to preserve the exclusive lock. since a stack tracks each call to pflock(), once that function attempts to release the shared lock, the lock stack would simply pop off its upgraded call from the stack, and make sure the preceding lock stays in place. slay. 💅

another way to describe this in psuedo code:

# Enable the lock stack
PIOLOCKSTACK = 1;

sub readIdx {
    pflock($file, LOCK_SH);
    # ... read data
    pflock($file, LOCK_UN);
    # ... return data
}

sub writeIdx {
    pflock($file, LOCK_EX);
    # ... write data
    pflock($file, LOCK_UN);
}

sub writeData {
    pflock($file, LOCK_EX);
    # ... write data
    pflock($file, LOCK_UN);
}

sub writeTx {
    pflock($file, LOCK_EX);
    readIdx();
    writeData();
    writeIdx();
    pflock($file, LOCK_UN);
}

# Execute the transaction
writeTx();

without the lock stack, executing the transaction function would cause the following to happen:

writeTx:
    # apply LOCK_EX
    # readIdx:
        # apply LOCK_SH
        # read data
        # release all locks w/LOCK_UN
    # writeData:
        # apply LOCK_EX
        # ERROR: any write decisions at this point based on the previous
        # ERROR: index read may cause file corruption because the index
        # ERROR: may have changed while this process was waiting to
        # ERROR: reacquire the exclusive lock!

with the lock stack in place, however, it goes like this:

writeTx:
    # apply LOCK_EX
        # lock stack: (LOCK_EX)
    # readIdx:
        # asks for LOCK_SH, but maintains LOCK_EX
            # lock stack: (LOCK_EX, LOCK_EX)
        # read data
        # deletes its lock from the stack, but preserves the previous lock
            # lock stack: (LOCK_EX)
    # writeData:
        # asks for LOCK_EX
            # lock stack: (LOCK_EX, LOCK_EX)
        # writes data
        # deletes its lock from the stack, but preserves the previous lock
            # lock stack: (LOCK_EX)
    # writeIdx:
        # asks for LOCK_EX
            # lock stack: (LOCK_EX, LOCK_EX)
        # writes data
        # deletes its lock from the stack, but preserves the previous lock
            # lock stack: (LOCK_EX)
    # release lock
        # lock stack: ()

at no point was the advisory lock lost, and hence, transactional integrity was preserved for all compliant processes. 🔥

the lock stack is off by default to allow the developer complete control over locking and I/O patterns, but it's there to make functions easier to write without having to worry about any locks applied outside of their code scope.

one downside of the lock stack is that it affects all I/O performed via the Paranoid::IO framework — it is not locallized to specific file handles. for that reason, one must be confident that flocks are applied as atomically as possible throughout the code space leveraging it. ⚠️

📦 IMPORT LISTS 📦

this module exports the following symbols by default:

pclose pcloseAll popen preopen ptell pseek pflock
plockstat pread pnlread pwrite pappend ptruncate

the following specialized import lists also exist:

List        Members
---------------------------------------------------------
all         @defaults PIOBLKSIZE PIOMAXFSIZE PIOLOCKSTACK

✨ SUBROUTINES/METHODS ✨

okay bestie, this is the whole toolkit — every function and every lil lvalue, no skips, no “we’ll come back to it later.” 💅

💖 PIOBLKSIZE 💖

PIOBLKSIZE = 65536;

This lvalue function is not exported by default. It sets the default block size to read when you don’t explicitly pass a size. Depending on your hardware and file system parameters, default-sized reads might give you performance gains. 👑

The default is 4096, which is generally a safe size for most applications.

The code snippet shows PIOBLKSIZE = 65536;, but the stated default is 4096.

💖 PIOMAXFSIZE 💖

PIOMAXFSIZE = 131072;

Not exported by default. Used to determine the maximum file size that will be read. It’s not used in this module, but it’s provided for dependent modules that may want to impose file size limits — like Paranoid::IO::Line and others.

Default is 65536.

💖 PIOLOCKSTACK 💖

PIOLOCKSTACK = 1

Not exported by default. Used to enable the flock lock stack functionality so transactional I/O patterns can happen. It is disabled by default.

🫶 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.

If opening fails, you get an undef return value, and a text description of the fault is stored in Paranoid::ERROR.

If you pass a file handle to popen, it tries to match it to a tracked file handle. If identified, it takes the appropriate action. If it doesn’t match any tracked file handles, it just returns that file handle back to you. No drama. 🦋

🫶 pclose

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

Returns the value from close. Trying to close a file that’s already closed counts as success, so you get a true value. Handing it a stale file handle, though, sends it 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 opened by popen) and reopens them if necessary. Typically only useful after a fork. It’s also not strictly necessary, because every call to a function in this module does that with every invocation. But if you have several file handles 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 care, use this function immediately after a fork.

Called with a list of file names, only those files are examined and reopened. Any failure to reopen any single file handle results 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);

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 who 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 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);

Returns the return value from sysseek. The appropriate $whence values should be one of the SEEK_* constants as exported by Fcntl.

🫶 pflock

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

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.

🫶 plockstat

$lock = plockstat($filename);

Returns the last flock applied via pflock.

🫶 pread

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

Returns the number of bytes read, or undef on errors. If this is called prior to an explicit popen, it defaults 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);

This is a wrapper function for pread that calls it with inherent file locking disabled. It is assumed that the dev is either managing flocks directly, or they’re not needed for this application.

🫶 pwrite

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

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.

The optional boolean fifth argument (nolock) will bypass automatic flocks since it assumes you’re managing the lock directly.

🫶 pnlwrite

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

This is a wrapper function for pwrite that calls it with inherent file locking disabled. It is assumed that the dev is either managing flocks directly, or they’re not needed for this application.

🫶 pappend

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

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.

The optional boolean fifth argument (nolock) will bypass automatic flocks since it assumes you’re managing the lock directly.

🫶 pnlappend

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

This is a wrapper function for pappend that calls it with inherent file locking disabled. It is assumed that the dev is either managing flocks directly, or they’re not needed for this application.

🫶 ptruncate

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

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.

The optional boolean third argument (nolock) will bypass automatic flocks since it assumes you’re managing the lock directly.

🫶 pnltruncate

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

This is a wrapper function for pnltruncate that calls it with inherent file locking disabled. It is assumed that the dev is either managing flocks directly, or they’re not needed for this application.

🧚 DEPENDENCIES 🧚

Cwd
Fcntl
IO::Handle
Paranoid
Paranoid::Debug
Paranoid::Input

💀 BUGS AND LIMITATIONS 💀

It may not always be beneficial 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 free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either:

the GNU General Public License (https://www.gnu.org/licenses/gpl-1.0.html) as published by the Free Software Foundation (http://www.fsf.org/); either version 1 (https://www.gnu.org/licenses/gpl-1.0.html), or any later version (https://www.gnu.org/licenses/license-list.html#GNUGPL), or
the Artistic License 2.0 (https://opensource.org/licenses/Artistic-2.0),

subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark.

and that’s the whole page, bestie. this one was made with perl v5.38.2 on 2024-03-07, for Paranoid::IO(3pm). go be paranoid, but make it cute. 💖✨

📦 where this page comes from

debian trixie: libparanoid-perl 2.10-2 · other
ubuntu resolute: libparanoid-perl 2.10-2 · other
ubuntu stonking: libparanoid-perl 2.10-2 · other
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms