af_lock(3)

📦 version 1.4pl6, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 af_lock — bestie, it's the AtFS lock situation 💖

okay so this is af_lock(3) from the Attribute Filesystem (AtFS) manual, and we're about to talk about reserving update rights, which is lowkey the most main-character thing you can do in a filesystem. sit down, grab a strawberry 🍓, let's go.

✨ NAME ✨

af_lock, af_unlock, af_testlock — the whole mechanism for reserving update rights in AtFS, no cap 💅

🌈 SYNOPSIS 🌈

#include <atfs.h>

Af_user *af_lock (Af_key *aso, Af_user *locker)

Af_user *af_unlock (Af_key *aso)

Af_user *af_testlock (Af_key *aso)

like look at these signatures. they're giving elegant. 🎀

🦋 DESCRIPTION 🦋

This page is your full tour of the AtFS locking interface, bestie. Locks exist so that two people don't both go "hehe let me update this" at the same time and cause conflicting updates to one object history. that would be chaos, and not the fun kind. 💀

Once a user has reserved the update rights, no other user may add new versions to the reserved history. periodt. and the way you reserve those update rights is by locking the most recent version of the history.

Here's the cute part: AtFS lets you add new versions to each generation in a history, so each generation can be locked separately. 🧚 if you wanna reserve update rights for an old generation (one whose generation number is smaller than the newest generation), you do it by locking the most recent version of that corresponding generation. yes queen, per-generation locking.

Also also — and this is important — removing an ASO (af_rm, see the manual page af_files(3)) and changing an ASO's version number (af_svnum, see the manual page af_version(3)) also require a lock on the corresponding ASO. so no sneaky deleting or renumbering without the lock. nope. 🙈

🔥 the three functions, one by one 🔥

  • af_lock — reserves the update permission for the user identified by locker. on successful completion you get back a buffer identical to locker, and otherwise you get a NULL pointer. that's it, that's the vibe.
  • af_unlock — cancels a formerly established reservation of update rights. only the owner or the locker of an ASO are allowed to do this, and the locker is identified by the Af_user structure that was given to the corresponding call of af_lock. on successful completion, af_unlock returns a buffer containing the identification of the former locker. this may be empty if the ASO was not locked. upon error, a NULL pointer is returned. 😭
  • af_testlock — returns a buffer containing an identification of the current locker of the specified ASO. it returns an empty buffer if no lock is set. so basically it's the gossip function, it tells you who's holding the lock rn. 👑

💜 SEE ALSO 💜

go read those too, bestie, they're connected, iykyk.

💅 DIAGNOSTICS 💅

af_lock and af_unlock return -1 on error, and af_errno is set to indicate the error number. so if something's wrong, check af_errno — it's literally telling you what happened. 🔍

not me being emotionally invested in a C library from 1993 but here we are, obsessed. 🫶

and that's the whole page, bestie! this was AtFS-1.71, dated Fri Jun 25 14:33:11 1993 — iconic vintage behavior, we love her, mwah 💖✨🌸

📦 where this page comes from