DLM_LOCK(3)

💖 DLM_LOCK(3) 💖

okay bestie, welcome to the libdlm manual section 3 page for dlm_lock — yes it's a whole page about ONE function family and yes it's giving main character energy 🔥

---

✨ NAME ✨

dlm_lock — acquire or convert a DLM lock 🎀

---

🌸 SYNOPSIS 🌸

#include <libdlm.h>

int dlm_lock(uint32_t mode,
          struct dlm_lksb *lksb,
          uint32_t flags,
          const void *name,
          unsigned int namelen,
          uint32_t parent,         /* unused */
          void (*astaddr) (void *astarg),
          void *astarg,
          void (*bastaddr) (void *astarg),
          void *range);            /* unused */

int dlm_lock_wait(uint32_t mode,
          struct dlm_lksb *lksb,
          uint32_t flags,
          const void *name,
          unsigned int namelen,
          uint32_t parent,         /* unused */
          void *bastarg,
          void (*bastaddr) (void *bastarg),
          void *range);            /* unused */

int dlm_ls_lock(dlm_lshandle_t lockspace,
          uint32_t mode,
          struct dlm_lksb *lksb,
          uint32_t flags,
          const void *name,
          unsigned int namelen,
          uint32_t parent,         /* unused */
          void (*astaddr) (void *astarg),
          void *astarg,
          void (*bastaddr) (void *astarg),
          void *range);            /* unused */

int dlm_ls_lock_wait(dlm_lshandle_t lockspace,
          uint32_t mode,
          struct dlm_lksb *lksb,
          uint32_t flags,
          const void *name,
          unsigned int namelen,
          uint32_t parent,         /* unusued */
          void *bastarg,
          void (*bastaddr) (void *bastarg),
          void *range);            /* unused */

int dlm_ls_lockx(dlm_lshandle_t lockspace,
          uint32_t mode,
          struct dlm_lksb *lksb,
          uint32_t flags,
          const void *name,
          unsigned int namelen,
          uint32_t parent,         /* unused */
          (*astaddr) (void *astarg),
          void *astarg,
          void (*bastaddr) (void *astarg),
          uint64_t *xid,
          uint64_t *timeout);

(yes the typo in /* unusued */ is canon, we keep it, do not touch it 💅)

---

🦋 DESCRIPTION 🦋

dlm_lock and all its little siblings acquire and convert locks in the DLM. that's the whole vibe.

dlm_lock() operations are asynchronous. so here's the tea: if your call to dlm_lock returns an error, the operation failed and the AST routine is NOT getting called, periodt. but if dlm_lock returns 0? bestie, it's still possible the lock operation will fail 😭. the AST routine gets called when the locking is complete or has failed, and the status comes back in the lksb.

dlm_lock_wait() will just sit there and wait until the lock operation has completed, then hands you the final completion status. no AST chaos, just patience ✨

dlm_ls_lock() is the same as dlm_lock() but it takes a lockspace argument. that lockspace has to have been previously opened by dlm_lockspace_open() or dlm_lockspace_create() — no opening, no locking, iykyk 🫶

For conversion operations the name and namelen are ignored, and the lock ID in the LKSB is what identifies the lock you're converting.

If a lock value block is specified then, in general, a grant or a conversion to an equal-level or higher-level lock mode reads the lock value from the resource into the caller's lock value block. when a lock conversion from EX or PW to an equal-level or lower-level lock mode happens, the contents of the caller's lock value block get written into the resource. If the LVB is invalidated, the lksb.sb_flags member will be set to DLM_SBF_VALNOTVALID. Lock value blocks are always 32 bytes long, no cap, that's just the size 💅

If the AST routines or parameter get passed to a conversion operation, they will overwrite those values that were passed to a previous dlm_lock call. so yeah, they're replacing the old ones, not stacking.

mode — the lock mode to acquire or convert to 👑

• LKM_NLMODE — NULL Lock
• LKM_CRMODE — Concurrent read
• LKM_CWMODE — Concurrent write
• LKM_PRMODE — Protected read
• LKM_PWMODE — Protected write
• LKM_EXMODE — Exclusive

flags — these affect how the lock call operates 🎀

• LKF_NOQUEUE — Don't queue the lock. If it cannot be granted return -EAGAIN
• LKF_CONVERT — Convert an existing lock
• LKF_VALBLK — Lock has a value block
• LKF_QUECVT — Put conversion to the back of the queue
• LKF_EXPEDITE — Grant a NL lock immediately regardless of other locks on the conversion queue
• LKF_PERSISTENT — Specifies a lock that will not be unlocked when the process exits; it will become an orphan lock.
• LKF_CONVDEADLK — Enable internal conversion deadlock resolution where the lock's granted mode may be set to NL and DLM_SBF_DEMOTED is returned in lksb.sb_flags.
• LKF_NODLCKWT — Do not consider this lock when trying to detect deadlock conditions.
• LKF_NODLCKBLK — Not implemented
• LKF_NOQUEUEBAST — Send blocking ASTs even for NOQUEUE operations
• LKF_HEADQUE — Add locks to the head of the convert or waiting queue
• LKF_NOORDER — Avoid the VMS rules on grant order
• LKF_ALTPR — If the requested mode can't be granted (generally CW), try to grant in PR and return DLM_SBF_ALTMODE.
• LKF_ALTCW — If the requested mode can't be granted (generally PR), try to grant in CW and return DLM_SBF_ALTMODE.
• LKF_TIMEOUT — The lock will time out per the timeout arg.

lksb — Lock Status block 💜

This structure contains the returned lock ID, the actual status of the lock operation (all lock ops are asynchronous, remember bestie) and the value block if LKF_VALBLK is set.

name

Name of the lock. Can be binary, max 64 bytes. Ignored for lock conversions. (Should be a string to work with debugging tools.) 🧚

namelen

Length of the above name. Ignored for lock conversions.

parent

ID of parent lock or NULL if this is a top-level lock. This is currently unused.

ast

Address of AST routine to be called when the lock operation completes. The final completion status of the lock will be in the lksb. the AST routine must not be NULL.

astargs

Argument to pass to the AST routine (most people pass the lksb in here but it can be anything you like.) 🍓

bast

Blocking AST routine. address of a function to call if this lock is blocking another. The function will be called with astargs.

range

This is unused.

xid

Optional transaction ID for deadlock detection.

timeout

Timeout in centiseconds. If it takes longer than this to acquire the lock (usually because it is already blocked by another lock), then the AST will trigger with ETIMEDOUT as the status. If the lock operation is a conversion then the lock will remain at its current status. If this is a new lock then the lock will not exist and any LKB in the lksb will be invalid. This is ignored without the LKF_TIMEOUT flag.

💫 Return values 💫

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

• EINVAL — An invalid parameter was passed to the call (eg bad lock mode or flag)
• ENOMEM — A (kernel) memory allocation failed
• EAGAIN — LKF_NOQUEUE was requested and the lock could not be granted
• EBUSY — The lock is currently being locked or converted
• EFAULT — The userland buffer could not be read/written by the kernel (this indicates a library problem)
• EDEADLOCK — The lock operation is causing a deadlock and has been cancelled. If this was a conversion then the lock is reverted to its previously granted state. If it was a new lock then it has not been granted. (NB Only conversion deadlocks are currently detected)

If an error is returned in the AST, then lksb.sb_status is set to the one of the above values instead of zero.

🌈 Structures 🌈

struct dlm_lksb {
  int      sb_status; /* Final status of lock operation */
  uint32_t sb_lkid;   /* ID of lock. Returned from dlm_lock()
                         on first use. Used as input to
                         dlm_lock() for a conversion operation */
  char     sb_flags;  /* Completion flags, see above */
  char     sb_lvbptr; /* Optional pointer to lock value block */
};

---

⭐ EXAMPLE ⭐

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);

---

🎀 SEE ALSO 🎀

libdlm(3), dlm_unlock(3), dlm_open_lockspace(3), dlm_create_lockspace(3), dlm_close_lockspace(3), dlm_release_lockspace(3)

---

and that's the page bestie!! this whole thing lives in the libdlm functions corner of the manual, and it's dated July 5, 2007 — old but iconic, like a limited edition lip gloss from 2007 that still hits 💖✨ go forth and lock responsibly 🫶💅