LockedFile(3pm)

💖 LockedFile(3pm) — the IO::LockedFile glow-up ✨

okay bestie, buckle up, because this is the Perl doc for IO::LockedFile, and it's literally the file-locking module. It's IO::File but with ✨commitment issues solved✨ — every file you touch gets locked with flock. Manual name is LockedFile(3pm), so like, you're in the right place, no notes. 💅

---

🎀 NAME 🎀

IO::LockedFile — supply object methods for locking files. fr fr that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

use IO::LockedFile;

# create new locked file object. $file will hold a file handle.
# if the file is already locked, the method will not return until the
# file is unlocked
my $file = new IO::LockedFile(">locked1.txt");

# when we close the file - it become unlocked.
$file->close();

# suppose we did not have the line above, we can also delete the
# object, and the file is automatically unlocked and closed.
$file = undef;

see how clean that is?? closing it unlocks it. dropping the object unlocks it too. it's giving ✨responsible✨ 💜

---

👑 DESCRIPTION 👑

In its simplest, most low-effort-glam use, the IO::LockedFile class gives us the exact same interface as the IO::File class — with one ✨iconic✨ difference: the files we deal with are locked using the Flock mechanism (that's the "flock" function, iykyk).

And here's the part that ate: if the process crashes mid-run, the file gets automatically unlocked. no cap. Actually — if the IO::LockedFile object just goes out of scope, the file is automatically closed and unlocked. it cleans up after itself, main character energy for real. 💅

So if all you want is locked files with "flock", you can skip most of the documentation below. go off, you don't need the rest. 🫶

If, on the other hand, you're interested in locking files with other schemes than Flock, or you wanna control the locking behavior (like, having a non-blocking lock, for example), read on bestie. 📖

---

🦋 the abstract class tea 🦋

Actually the class IO::LockedFile is kind of an abstract class.

Why abstract? Because the methods of this class call the methods "lock" and "unlock". But those methods are not really implemented in this class. They're supposed to be implemented in the derived classes of IO::LockedFile. 🧚

Why "kind" of abstract? Because the constructor of this class will return an object! 😭

How can an abstract class create objects? Simple — the constructor returns an object that is actually an object of one of the derived classes of IO::LockedFile.

So by default, the constructor of IO::LockedFile returns an object of IO::LockedFile::Flock. For example, this:

use IO::LockedFile;
$lock = new IO::LockedFile(">bla");
print ref($lock);

Will give you:

IO::LockedFile::Flock

---

⭐ so what are the conclusions here? ⭐

First of all — do not be surprised to get an object of a derived class from the constructor of IO::LockedFile. that's just how she operates. 🙈

Secondly — by changing the default behavior of the constructor of IO::LockedFile, we can get an object of another class, which means we have a locked file that's locked with a different scheme. versatility queen. 👑

The default behavior of the constructor is determined by the global options.

We can access these global options — or the options per object — using the method "set_option" and "get_option".

We can set the global options in the use line:

use IO::LockedFile 'Flock'; # set the default scheme to be Flock

use IO::LockedFile ( scheme => Flock );

We can also set the options of a new object by passing the options to the constructor, as we'll see below. And we can change the options of an existing object by using the "set_option" method. 🎀

---

🌈 which options are available? 🌈

• scheme — The scheme lets us define which derived class we use for the object we create. See below for which derived classes are available. The default scheme is 'Flock'. 🦋
• block — The block option can be 1 or 0 (true or false). If it's 1, a call to the "open" method or to the constructor will be blocked if the file we try to open is already locked. Which means those methods will not return till the file is unlocked. If the value of the block option is 0, the "open" and the constructor will return immediately in any case. If the file is locked, those methods will return undef. The default value of the block option is 1. ⏳
• lock — The lock option can be 1 or 0 (true or false). It defines if the file we open when we create the object will be opened locked. Sometimes we want a file that can be locked, yet we do not want to open it locked from the beginning. For example, if we want to print into a log file, usually we want to lock that file only when we print into it. Yet it might be that when we open the file in the beginning, we don't print into it immediately. In that case we'd prefer to open the file as unlocked, and later lock it when needed. The default value of the lock option is 1. 🔐

There might be extra options used by one of the derived classes. So according to the scheme you choose to use, please look in the manual page of the class that implements that scheme. iykyk. 📚

Finally, some information connected to a certain scheme will be found in the classes that are derived from this class. For example, compatibility issues will be discussed in each derived class.

The classes that currently implement the interface that IO::LockedFile defines are:

• IO::LockedFile::Flock 🐑 (yes, just the one, she's the moment)

---

✨ CONSTRUCTOR ✨

• new ( FILENAME [,MODE [,PERMS]] ) — Creates an object that belongs to one of the derived classes of "IO::LockedFile". If it receives any parameters, they're passed to the method "open". If the "open" fails, the object is destroyed. Otherwise, it's returned to the caller. The object will be the file handle of that opened file. 🫶
• new ( OPTIONS, FILENAME [,MODE [,PERMS]] ) — This version of the constructor is the same as above, except we send as the first parameter a reference to a hash — OPTIONS. This hash lets us change, for this object only, the options from the default options. So for example, if we want to change the lock option from its default, we can do it as follows:

$file = new IO::LockedFile( { lock => 0 },
                            ">locked_later.txt" );

---

💅 METHODS 💅

• open ( FILENAME [,MODE [,PERMS]] ) — This method lets us open the file FILENAME. By default, the file will be opened as a locked file, and if the file that's opened is already locked, the method will not return until the file is unlocked. Of course this default behavior can be controlled by setting other options. The object will be the file handle of that opened file. The parameters that should be provided to this method are the same as the parameters that the method "open" of IO::File accepts (like ">file.txt", for example). Note that the open method checks if the file is opened for reading or for writing, and only then calls the lock method of the derived class that's being used. This way, for example, when using the Flock scheme, the lock will be a shared lock for a file that's being read, and an exclusive lock for a file that's opened to be written. 📖✍️
• close ( ) — The file will be closed and unlocked. The method returns the same as the close method of IO::File. bye bestie 👋
• lock ( ) — Practically this method does nothing, and returns 1 (true). This method will be overridden by the derived class that implements the scheme we use. When it's overridden, the method is supposed to lock the file according to the scheme we use. If the file is already locked, and the block option is 1 (true), the method will not return until the file is unlocked, and locked again by the method. If the block option is 0 (false), the method will return 0 immediately. Besides, the lock method is aware if the file was opened for reading or for writing. Thus, for example, when using the Flock scheme, the method will create a shared lock for a file that's being read, and an exclusive lock for a file that's opened to be written. 🔒
• unlock ( ) — Practically this method does nothing, and returns 1 (true). This method will be overridden by the derived class that implements the scheme we use. When it's overridden, the method is supposed to unlock the file according to the scheme we use, and return 1 (true) on success and 0 (false) on failure. 🔓
• have_lock ( ) — Will return 1 (true) if the file is already locked by this object. Will return 0 (false) otherwise. Note that this will not tell us anything about the situation of the file itself — so we should not use this method in order to check if the file is locked by someone else. 👀 careful bestie, it's about you, not about them.
• print ( ) — This method is exactly like the "print" method of IO::Handle, with the difference that when using this method, if the file is unlocked, then before printing to it, it will be locked and afterward it will be unlocked. 🖨️
• truncate ( ) — This method is exactly like the "truncate" method of IO::Handle, with the difference that when using this method, if the file is unlocked, then before truncating it, it will be locked and afterward it will be unlocked. ✂️
• is_writable ( ) — This method will return 1 (true) if the file was opened to write. Will return 0 (false) otherwise.
• should_block ( ) — This method will return 1 (true) if the block option is set to 1. Will return 0 (false) otherwise.
• should_lock ( ) — This method will return 1 (true) if the lock option is set to 1. Will return 0 (false) otherwise.
• get_scheme ( ) — This method will return the name of the scheme that is currently used. 💖

---

🌟 AUTHORS 🌟

Rani Pinchuk, rani@cpan.org 💜

Rob Napier, rnapier@employees.org 💙

---

🍓 COPYRIGHT 🍓

Copyright (c) 2001-2002 Ockham Technology N.V. & Rani Pinchuk. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

---

🔥 SEE ALSO 🔥

IO::File(3), IO::LockedFile::Flock(3)

---

and that's the whole page bestie, you ate it 💅 this doc is from perl v5.36.0, dated 2022-11-19 — so go lock some files, stay iconic, and remember: the file unlocks itself when the object dips. periodt. ✨🌈🎀