Sympa::LockedFile(3Sympa)

💖 Sympa::LockedFile 💖

okay bestie, welcome to Sympa::LockedFile — the Filehandle with locking situation, straight out of sympa 6.2.80. it's giving ✨ main character filehandle ✨ and honestly? we're obsessed. 🫶

---

✨ SYNOPSIS ✨

use Sympa::LockedFile;

# Create filehandle acquiring lock.
my $fh = Sympa::LockedFile->new('/path/to/file', 20, '+<') or die;
# or,
my $fh = Sympa::LockedFile->new();
$fh->open('/path/to/file', 20, '+<') or die;

# Operations...
while (<$fh>) { ... }
seek $fh, 0, 0;
truncate $fh, 0;
print $fh "blah blah\n";
# et cetera.

# Close filehandle releasing lock.
$fh->close;

like look at that. create → lock acquired. read/write/seek/truncate → do literally whatever. $fh->close → lock released, we're done, periodt. 💅

---

🌸 DESCRIPTION 🌸

This class implements a filehandle with locking. that's the whole vibe: a filehandle that knows how to lock itself so your processes don't fight over the same file like it's the last slice of birthday cake. 🎂

---

🎀 Class Methods 🎀

• new ( [ $file, [ $blocking_timeout, [ $mode ] ] ] ) — creates a new object. and if you pass in any of those optional parameters? it also opens a file and acquires the lock for you. two birds, one adorable stone. 🪨✨

Parameters:

See open().

Returns:

A brand new object, or a false value if something went wrong. 😭

• last_error ( ) — get a string describing the most recent error. it's the receipts, bestie. 🧾

Parameters:

None.

Returns:

A string — or, if the recent operation was a success, undef. slay.

---

🦋 Instance Methods 🦋

Instances of Sympa::LockedFile support the methods provided by IO::File. yes, all of them. we're a whole IO::File with extra ✨lock✨ energy, iykyk.

• open ( $file, [ $blocking_timeout, [ $mode ] ] ) — opens the file specified by $file and acquires a lock on it. the moment. 👑

Parameters:

• $file — the path of the file to be locked and opened. that's your target, bestie. 🎯
• $blocking_timeout — programs will block up to this many seconds before returning undef (meaning: could not get a lock, so sad 😭). but if you hand it a negative value, programs will not block — they'll fail immediately instead, a.k.a. "LOCK_NB".

Default is 30.

⚠️ however!! if an existing lock is older than 1200 seconds (that's 20 minutes, fr fr), the lock will be stolen. yes, stolen. not even sorry. 💀

• $mode — the mode to open the file with. if it implies any writing operations ('>', '>>', '+<', ...), it tries to acquire an exclusive lock ("LOCK_EX"); otherwise it goes with a shared lock ("LOCK_SH").

Default is '<'.

plus there's a special little mode: '+' will acquire an exclusive lock without opening the file. in that case the file doesn't even have to exist. iconic behavior honestly. 🎀

the numeric modes used for sysopen() (e.g. "O_CREAT") are not supported. nope. don't try it. 🙈

Returns:

A new filehandle. if acquiring the lock failed, it won't open the file. if opening the file failed, it releases the acquired lock. either way? false value. 💔

• close ( ) — closes the filehandle and releases the lock on it.

ngl, even just destroying the instance will safely close the filehandle and release the lock. so you're covered either way. 🫶

Parameters:

None.

Returns:

If close succeeded, true value — otherwise false value.

⚠️ if the filehandle had not been locked by the current process, this method will safely close it and then die. dramatic? maybe. necessary? absolutely. 💀

---

🧚 Following methods are specific to this module. 🧚

• basename ( [ $level ] ) — gets the base name of the locked file. cute little name reveal. 🌸
• extend ( ) — extends the stale lock timeout. the lock will never be stolen in 1200 seconds again. take that, thief. 🔥

Parameters:

None.

Returns:

If the extension succeeded, true value — otherwise false value.

⚠️ if the filehandle had not been locked by the current process, this method will die doing nothing. just. die. 😭

• rename ( $destfile ) — renames the file, closes the filehandle and releases the lock on it. the filehandle must have acquired an exclusive lock. no shared-lock girlies allowed on this one. 👑

Parameter:

• $destfile — the destination path of the renaming. where we're headed, bestie. 🚀

Returns:

If renaming succeeded, true value. otherwise false value and it does not release the lock. in both cases, the filehandle is closed anyway. so like, closed either way — noted. 📝

⚠️ if the filehandle had not been locked by the current process, this method will die doing nothing. 💀

• unlink ( ) — deletes the file and releases the lock on it. gone. deleted. no cap. 🗑️

Parameters:

None.

Returns:

If unlink succeeded, true value. otherwise false value and it does not release the lock.

⚠️ if the filehandle had not been locked by the current process, this method will die without deleting the file. the file stays. the method does not. 😭

---

⭐ SEE ALSO ⭐

"Functions for filehandles, files or directories" in perlfunc, "I/O Operators" in perlop, IO::File, File::NFSLock. go read those too, bestie, they're the moment. 📚💖

---

🌈 HISTORY 🌈

• The Lock module was written by Olivier Salaün and appeared on Sympa 5.3. 🎀
• Support for NFS was added by Kazuo Moriwaka. 🦋
• The rewritten Sympa::LockedFile module was initially written by IKEDA Soji for Sympa 6.2. 👑

---

💜 and that's the whole lore, bestie. filehandle, locked. vibe check: passed. periodt. 💅✨

sympa 6.2.80 — dated 2026-10-19 — Sympa::LockedFile(3Sympa) 🫶🌸💖