LIBDLM(3)

🦋 LIBDLM(3) — the libdlm girlies' guide 🦋

okay bestie, so you know that libdlm section of the manual? yeah. this is it. Library Functions Manual, third section, we're doing this. pull up a chair, grab a boba 🧋, and let's get into it.

---

✨ NAME ✨

libdlm — aka these lil guys right here:

• dlm_get_fd
• dlm_dispatch
• dlm_pthread_init
• dlm_ls_pthread_init
• dlm_cleanup

---

🌸 SYNOPSIS 🌸

#include <libdlm.h>
int dlm_pthread_init();
int dlm_ls_pthread_init(dlm_lshandle_t lockspace);
int dlm_pthread_cleanup();
int dlm_get_fd(void);
int dlm_dispatch(int fd);

and then you gotta link with -ldlm or it's giving nothing. literally nothing. 🙈

---

💖 DESCRIPTION 💖

so libdlm is the programmatic userspace interface to the Distributed Lock manager. it hands you all the calls you need to manipulate locks & lockspaces. all of them. she's generous like that. 💅

libdlm can be used in pthread or non-pthread applications — both are valid, both are welcome, no gatekeeping here.

for pthread applications, you simply call the following function before doing any lock operations. and listen, if you're using pthreads, remember to define _REENTRANT at the top of the program or use -D_REENTRANT on the compile line. do not skip this. it's not a vibe, it's a requirement. 🫶

pthreads is the normal way of using the DLM. this way you simply initialize the DLM's thread and all the AST routines will be delivered in that thread. you just call the dlm_lock() etc routines in the main line of your program. easy. effortless. main character energy. 👑

if you don't want to use pthreads, or you want to handle the dlm callback ASTs yourself, then you can get an FD handle to the DLM device and call dlm_dispatch() on it whenever it becomes active. that way ASTs will be delivered in the context of the thread/process that called dlm_dispatch(). your context, your rules. ✨

🎀 int dlm_pthread_init()

creates a thread to receive all lock ASTs. the AST callback function for lock operations will be called in the context of this thread. and heads up bestie — if there is a potential for local resource access conflicts, you must provide your own pthread-based locking in the AST routine. no cap. that one's on you.

🎀 int dlm_ls_pthread_init(dlm_lshandle_t lockspace)

same energy as dlm_pthread_init but it initializes a thread for the specified lockspace. that's it. that's the whole thing. iconic.

🎀 int dlm_pthread_cleanup()

cleans up the default lockspace threads after use. normally you don't need to call this, but if the locking code is in a dynamically loadable shared library, this will probably be necessary. so like, know your context. 😌

for non-pthread based applications, the DLM provides a file descriptor that the program can feed into poll/select. if activity is detected on that FD, then a dispatch function should be called:

🎀 int dlm_get_fd()

returns a file-descriptor for the DLM suitable for passing in to poll() or select(). give her to the poller. she's ready. 🌈

🎀 int dlm_dispatch(int fd)

reads from the DLM and calls any AST routines that may be needed. this routine runs in the context of the caller, so no extra locking is needed to protect local resources. chef's kiss. 🤌

---

🧚 libdlm_lt 🧚

there also exists a "light" version of the libdlm library called libdlm_lt. this is provided for those applications that do not want to use pthread functions.

⚠️ if you use this library it is important that your application is NOT compiled with -D_REENTRANT or linked with libpthread. not even a little. this is the one rule. 🚨

---

🌟 EXAMPLES 🌟

create a lockspace and start a thread to deliver its callbacks:

dlm_lshandle_t ls;

ls = dlm_create_lockspace("myLS", 0660);
dlm_ls_pthread_init(ls);

 ...

status = dlm_ls_lock(ls,
                     ... );

using poll(2) to wait for and dispatch ASTs:

static int poll_for_ast(dlm_lshandle_t ls)
{
    struct pollfd pfd;

    pfd.fd = dlm_ls_get_fd(ls);
    pfd.events = POLLIN;
    while (!ast_called)
    {
        if (poll(&pfd, 1, 0) < 0)
        {
            perror("poll");
            return -1;
        }
        dlm_dispatch(dlm_ls_get_fd(ls));
    }
    ast_called = 0;
    return 0;
}

---

👑 SEE ALSO 👑

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

---

aaaand that's the whole page, bestie. this was the libdlm functions page, dated July 5, 2007 — yes it's vintage, yes it still eats. 💜 go forth and lock responsibly. mwah. 💋🎀🦋