IO::AtomicFile(3)

💾 IO::AtomicFile — the Perl manual, bestie edition 🎀

okay so this is IO::AtomicFile(3), a User Contributed Perl Documentation page, and it's literally about writing files that update atomically. no cap. let me tell you everything 💅

---

🌸 NAME 🌸

IO::AtomicFile — write a file which is updated atomically ✨

like, the whole file. at once. no half-written chaos. periodt.

---

🦋 SYNOPSIS 🦋

use strict;
use warnings;
use feature 'say';
use IO::AtomicFile;

# Write a temp file, and have it install itself when closed:
my $fh = IO::AtomicFile->open("bar.dat", "w");
$fh->say("Hello!");
$fh->close || die "couldn't install atomic file: $!";

# Write a temp file, but delete it before it gets installed:
my $fh = IO::AtomicFile->open("bar.dat", "w");
$fh->say("Hello!");
$fh->delete;

# Write a temp file, but neither install it nor delete it:
my $fh = IO::AtomicFile->open("bar.dat", "w");
$fh->say("Hello!");
$fh->detach;

three whole vibes, three whole outcomes 💖 write-then-install, write-then-nuke, write-then-ghost. pick your main character moment.

---

🧚 DESCRIPTION 🧚

so this module is for people who need to update files reliably even when their program just... dies unexpectedly 😭 like, mid-run, bye.

for example — you generally do not want to be halfway through writing /etc/passwd and have your program terminate! not the vibe. not the vibe at all. and listen: even writing a single scalar to a filehandle is not atomic. not even one. 🙈

but this module gives you true atomic updates, via "rename". here's the tea 🍓: when you open a file /foo/bar.dat through this module, you're actually opening a temporary file /foo/bar.dat..TMP and writing all your output there. then, the act of closing this file — either explicitly via "close", or implicitly via the destruction of the object — will cause "rename" to be called...

so from the outside world's point of view? the file's contents are updated in a single time quantum ✨ iconic. literally a glow-up with zero in-between frames.

to make sure problems don't go undetected, the "close" method that the destructor runs will raise a fatal exception if the "rename" fails 🔥. the explicit "close" just returns "undef". different energy, on purpose.

you can also decide at any point to trash the file you've been building 💀 your build, your rules.

---

👑 METHODS 👑

IO::AtomicFile inherits all methods from IO::File and implements the following new ones. yes, all of them. nepotism but make it inheritance 🫶

🎀 close

$fh->close();

this one calls its parent "close" in IO::File and then renames its temporary file as the original file name. that's the whole slay. commit the temp file to the real filename 💅

💀 delete

$fh->delete();

this one calls its parent "close" in IO::File and then deletes the temporary file. so long, temp file, you were fun while you lasted 🙈

🌈 detach

$fh->detach();

this one calls its parent "close" in IO::File. and — unlike "delete" in IO::AtomicFile — it does not then delete the temporary file. it just... leaves it there. ghosting the temp file, honestly 🧚

---

⭐ AUTHOR ⭐

Eryq (eryq@zeegee.com). President, ZeeGee Software Inc (http://www.zeegee.com). founder energy fr fr 👑

---

💜 CONTRIBUTORS 💜

Dianne Skoll (dfs@roaringpenguin.com). we stan a contributor 🫶

---

🌸 COPYRIGHT & LICENSE 🌸

Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. yes bestie, same terms as Perl itself, that's the license, go read it and thrive 💖

---

ngl, if you're about to write something important — /etc/passwd-level important — please, please use the atomic path. your future self will thank you 😭🫶

---

✨ cute little sign-off ✨ — this page came from perl v5.42.0, dated 2020-06-04, and yes, it's IO::AtomicFile(3) in the User Contributed Perl Documentation section. that's a whole vibe check passed 💅🎀