DLM_CREATE_LOCKSPACE(3)

💅 DLM_CREATE_LOCKSPACE — bestie edition 💅

okay so this is a page from the Library Functions Manual, and it's all about the DLM (that's the Distributed Lock Manager, iykyk) and how us userspace girlies get to play with lockspaces. Buckle up, this one's a whole vibe ✨

---

🌸 NAME 🌸

dlm_create_lockspace, dlm_open_lockspace, dlm_close_lockspace, dlm_release_lockspace — the squad that manipulates DLM lockspaces 🫶

---

✨ SYNOPSIS ✨

#include <libdlm.h>

dlm_lshandle_t dlm_create_lockspace(const char *name, mode_t mode);
dlm_lshandle_t dlm_new_lockspace(const char *name, mode_t mode,
                                 uint32_t flags);
dlm_lshandle_t dlm_open_lockspace(const char *name);
int dlm_close_lockspace(dlm_lshandle_t ls);
int dlm_release_lockspace(const char *name, dlm_lshandle_t ls,
                          int force);

---

🦋 DESCRIPTION 🦋

so the DLM lets locks get partitioned into what we call "lockspaces", and bestie, these can be manipulated by userspace calls. It is possible — though not recommended 🙈 — for an application to have multiple lockspaces open at one time. like, you can, but why would you.

Many of the DLM calls work on the "default" lockspace, which should be fine for most users. The calls with _ls_ in them let you isolate your application from all others running in the cluster. Remember, lockspaces are a cluster-wide resource, so if you create a lockspace called "myls" it will share locks with a lockspace called "myls" on all nodes. no cap, it's giving hive mind 🐝. These calls let users create & remove lockspaces, and let users connect to an existing lockspace to store their locks there.

---

💖 dlm_lshandle_t dlm_create_lockspace(const char *name, mode_t mode); 💖

This creates a lockspace called <name> and the mode of the file used to access it will be <mode> (subject to umask as usual, you know how it is). The lockspace must not already exist on this node — if it does, -1 will be returned and errno will be set to EEXIST. If you really want to use this lockspace you can then use dlm_open_lockspace() below. The name is the name of a misc device that will be created in /dev/misc. 🎀

On success a handle to the lockspace is returned, which can be used to pass into subsequent dlm_ls_lock/unlock calls. Make no assumptions as to the content of this handle, as its content may change in future. it's mysterious like that 💅

The caller must have CAP_SYSADMIN privileges to do this operation. sorry babe, them's the rules 👑

Return codes: 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
• ENOMEM — A (kernel) memory allocation failed 😭
• EEXIST — The lockspace already exists
• EPERM — Process does not have capability to create lockspaces
• ENOSYS — A fatal error occurred initializing the DLM 💀
• Any error returned by the open() system call

---

🌈 int dlm_new_lockspace(const char *name, mode_t mode, uint32_t flags) 🌈

Performs the same function as dlm_create_lockspace() above, but passes some creation flags to the call that affect the lockspace being created. same energy, extra options ✨

---

🎀 int dlm_release_lockspace(const char *name, dlm_lshandle_t ls, int force) 🎀

Deletes a lockspace. If the lockspace still has active locks then -1 will be returned and errno set to EBUSY. Both the lockspace handle /and/ the name must be specified — yeah, both, no shortcuts. This call also closes the lockspace and stops the thread associated with the lockspace, if any. she's thorough 💅

Note that other nodes in the cluster may still have locks open on this lockspace. This call only removes the lockspace from the current node. so like, it's not a global delete, bestie, don't be fooled.

If the force flag is set then the lockspace will be removed even if another user on this node has active locks in it. Existing users will NOT be notified if you do this, so be careful. 😱 this is the "chaotic main character" move, please use responsibly.

The caller must have CAP_SYSADMIN privileges to do this operation.

Return codes: 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
• EPERM — Process does not have capability to release lockspaces
• EBUSY — The lockspace could not be freed because it still contains locks and force was not set.

---

🧚 dlm_lshandle_t dlm_open_lockspace(const char *name) 🧚

Opens an already existing lockspace and returns a handle to it. that's it, that's the whole thing 🫶

Return codes: 0 is returned if the call completed successfully. If not, -1 is returned and errno is set to an error returned by the open() system call.

---

🍓 int dlm_close_lockspace(dlm_lshandle_t ls) 🍓

Close the lockspace. Any locks held by this process will be freed. If a thread is associated with this lockspace then it will be stopped. bye bestie, you're done here 👋

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

• EINVAL — lockspace was not a valid lockspace handle

---

👑 SEE ALSO 👑

libdlm(3), dlm_unlock(3), dlm_lock(3),

---

and that's the whole page, bestie — slay 💖

this gorgeous lil doc is part of the libdlm functions and it's dated July 5, 2007. iconic since day one, no notes. ✨🦋🌸