DLM_UNLOCK(3)

💅 DLM_UNLOCK(3) — the libdlm manual, but make it make sense ✨

okay bestie, welcome to DLM_UNLOCK(3) from the Library Functions Manual — yes it's a section 3 library function page and yes we're gonna make unlocking a DLM lock feel like a group chat glow-up 🫶

🌸 NAME 🌸

dlm_unlock — unlock a DLM lock. that's it. that's the whole vibe. you had a lock, now you're giving it back 💖

✨ SYNOPSIS ✨

#include <libdlm.h>

int dlm_unlock(uint32_t lkid,
               uint32_t flags, struct dlm_lksb *lksb, void *astarg);

int dlm_unlock_wait(uint32_t lkid,
                    uint32_t flags, struct dlm_lksb *lksb);

two functions, one mission: releasing the lock. one of them waits around like a loyal bestie, the other just sends it and dips 😌

💜 DESCRIPTION 💜

dlm_unlock() unlocks a lock that was previously acquired by dlm_lock and its variants. like, you don't just take locks and ghost them, that's rude 🚫

Unless you're using dlm_unlock_wait(), unlocks are also asynchronous. The AST routine gets called when the resource is successfully unlocked (details below, keep reading 📖).

• lkid — the Lock ID, exactly as it came back to you in the lksb. your lock's little name tag 🏷️
• flags — the flags that change up how the unlock behaves:
  • LKF_CANCEL — cancel a pending lock or conversion. This returns the lock to it's previously granted mode (in case of a conversion) or unlocks it (in case of a waiting lock). ngl this is the "never mind, take it back" option 🙈
  • LKF_IVVALBLK — invalidate value block. bye bye value block 💀
  • LKF_FORCEUNLOCK — unlock the lock even if it's waiting. no queue, no patience, just out 👑
• lksb — the LKSB, which returns status and value block information back to you 📬
• astarg — the new parameter that gets passed to the completion AST. The completion AST routine is the last completion AST routine specified in a dlm_lock call. so like, whichever AST you most recently handed over in a dlm_lock, that's the one that gets this.

⚠️ lowkey important rule, do not skip this: If dlm_lock_wait() was the last routine to issue a lock, dlm_unlock_wait() must be used to release the lock. If dlm_lock() was the last routine to issue a lock, then either dlm_unlock() or dlm_unlock_wait() may be called. match the energy of your lock, basically ✨

🎀 Return values 🎀

0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following besties:

• EINVAL — An invalid parameter was passed to the call (eg bad lock mode or flag). something you handed over was simply not it 🚩
• EINPROGRESS — The lock is already being unlocked. girl it's already happening, be patient 😭
• EBUSY — The lock is currently being locked or converted. it's busy, it has plans 💅
• ENOTEMPTY — An attempt to made to unlock a parent lock that still has child locks. you can't leave while the kids are still here 🧚
• ECANCEL — A lock conversion was successfully cancelled. cancelled, but make it a success 💀
• EUNLOCK — An unlock operation completed successfully (sb_status only). note that little caveat, it's sb_status only, okay? okay 🫶
• EFAULT — The userland buffer could not be read/written by the kernel. kernel said "can't read that" 📵

If an error is returned in the AST, then lksb.sb_status is set to the one of the above numbers instead of zero. so check your status field, bestie, it's doing the talking 🔥

🌈 EXAMPLE 🌈

here's the whole thing in action, copy-paste energy:

int status;
struct dlm_lksb lksb;

status = dlm_lock_wait(LKM_EXMODE,
                       &lksb,
                       LKF_NOQUEUE,
                       "MyLock",
                       strlen("MyLock"),
                       0,     // Parent,
                       NULL,  // bast arg
                       NULL,  // bast routine,
                       NULL); // Range

if (status == 0)
     dlm_unlock_wait(lksb.sb_lkid, 0, &lksb);

lock it, check it went fine, unlock it. the whole arc, start to finish 🦋

👑 SEE ALSO 👑

go read these next, they're the rest of the lore:

• libdlm(3)
• dlm_lock(3)
• dlm_open_lockspace(3)
• dlm_create_lockspace(3)
• dlm_close_lockspace(3)
• dlm_release_lockspace(3)

and that's the page, periodt 💖 this one's brought to you by the libdlm functions, dated July 5, 2007 — vintage, iconic, still slaying. mwah 💅✨