FileCache(3perl)

💖 FileCache(3perl) 💖

okay bestie, welcome to the Perl Programmers Reference Guide ✨ this one's called FileCache and no cap it does exactly one iconic thing:

🌸 NAME 🌸

FileCache — keep more files open than the system permits 💅

like. the system said "no more filehandles for u" and FileCache said "bet." 🫶

---

✨ SYNOPSIS ✨

no strict 'refs';

use FileCache;
# or
use FileCache maxopen => 16;

cacheout $mode, $path;
# or
cacheout $path;
print $path @data;

$fh = cacheout $mode, $path;
# or
$fh = cacheout $path;
print $fh @data;

---

🦋 DESCRIPTION 🦋

So the cacheout function makes sure there's a filehandle open for reading or writing, available under the pathname you hand it. And the way it does that?? It automatically closes and re-opens files the moment you'd go over your system's maximum number of file descriptors, or over the suggested maximum maxopen. Careful, casual, unbothered. main character energy fr fr 😌

🌷 cacheout EXPR

The 1-argument form of cacheout opens a file for writing ('>') on its first use, and then appending ('>>') after that. First time it's like "hi let's write", every time after it's like "k we're just adding to the end bestie."

It returns EXPR on success, purely for convenience. And honestly? You may completely neglect that return value and just manipulate EXPR as the filehandle directly if that's more your vibe. do whatever slays 💅

🌈 cacheout MODE, EXPR

The 2-argument form uses whatever mode you supplied for the initial opening and all the subsequent ones. It supports most valid modes for 3-argument open, namely:

• '>'
• '+>'
• '<'
• '<+'
• '>>'
• '|-'
• '-|'

If you wanna pass supplemental arguments to a program opened with '|-' or '-|', just append them to the command string exactly the way you would with system EXPR. periodt.

It returns EXPR on success for convenience. You may neglect the return value and manipulate EXPR as the filehandle directly if you prefer. (Same deal as above, no cap. 🎀)

---

💀 CAVEATS 💀

ngl this is the part where we get serious, bestie. read it. 🫶

• It IS permissible to close a FileCache managed file… BUT do not do it if you're calling FileCache::cacheout from a package other than the one it was imported into, or with another module that overrides close. If you absolutely must, use FileCache::cacheout_close. That's the safe word. use it.
• FileCache can be used with piped opens ('-|' or '|-'), but doing that is strongly discouraged. Why? Because if FileCache decides it needs to close and then reopen a pipe, the command at the far end of the pipe gets reexecuted 😭 and the results of performing IO on FileCache'd pipes are, quote, unlikely to be what you expect. The ability to use FileCache on pipes may be removed in a future release, so like… don't build ur whole life on it. 🙈
• FileCache does not store the current file offset if it finds it necessary to close a file. When the file gets reopened, the offset will be whatever the original open file mode specifies. And yes, the manpage itself says this could be construed to be a bug. iconic honestly. it said "this might be a bug" and left 💀
• The module's functionality relies on symbolic references, so things will break under use strict unless you also specify no strict "refs". That's literally why it's the very first line of the synopsis. it's giving necessary chaos. 🌸

---

🐛 BUGS 🐛

sys/param.h straight up lies with its "NOFILE" define on some systems 😭 so you might have to set maxopen yourself. no notes, just vibes and manual configuration.

---

okay that's the whole page, bestie!! go forth and cache ur files 💖✨🎀🦋🌸💅🫶🔥👑🌈⭐🍓🧚💜

This lovely little page came out of perl v5.44.0, dated 2026-10-17 — talk to u never, FileCache(3perl) 💕