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);
DESCRIPTION
dlm_lock and its variants acquire and convert locks in the DLM.
dlm_lock() operations are asynchronous. If the call to dlm_lock returns
an error then the operation has failed and the AST routine will not be
called. If dlm_lock returns 0 it is still possible that the lock
operation will fail. The AST routine will be called when the locking is
complete or has failed and the status is returned in the lksb.
dlm_lock_wait() will wait until the lock operation has completed and
returns the final completion status. dlm_ls_lock() is the same as
dlm_lock() but takes a lockspace argument. This lockspace must have
been previously opened by dlm_lockspace_open() or
dlm_lockspace_create().
For conversion operations the name and namelen are ignored and the lock
ID in the LKSB is used to identify the lock to be converted.
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
occurs, the contents of the caller’s lock value block are written into
the resource. If the LVB is invalidated the lksb.sb_flags member will
be set to DLM_SBF_VALNOTVALID. Lock values blocks are always 32 bytes
long.
If the AST routines or parameter are passed to a conversion operation
then they will overwrite those values that were passed to a previous
dlm_lock call.
mode 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 Affect the operation of the lock call:
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) 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)