1
.TH DLM_LOCK 3 "July 5, 2007" "libdlm functions"
3
dlm_lock \- acquire or convert a DLM lock
8
int dlm_lock(uint32_t mode,
13
uint32_t parent, /* unused */
14
void (*astaddr) (void *astarg),
16
void (*bastaddr) (void *astarg),
17
void *range); /* unused */
19
int dlm_lock_wait(uint32_t mode,
20
struct dlm_lksb *lksb,
24
uint32_t parent, /* unused */
26
void (*bastaddr) (void *bastarg),
27
void *range); /* unused */
29
int dlm_ls_lock(dlm_lshandle_t lockspace,
31
struct dlm_lksb *lksb,
35
uint32_t parent, /* unused */
36
void (*astaddr) (void *astarg),
38
void (*bastaddr) (void *astarg),
39
void *range); /* unused */
41
int dlm_ls_lock_wait(dlm_lshandle_t lockspace,
43
struct dlm_lksb *lksb,
47
uint32_t parent, /* unusued */
49
void (*bastaddr) (void *bastarg),
50
void *range); /* unused */
52
int dlm_ls_lockx(dlm_lshandle_t lockspace,
54
struct dlm_lksb *lksb,
58
uint32_t parent, /* unused */
59
(*astaddr) (void *astarg),
61
void (*bastaddr) (void *astarg),
69
dlm_lock and its variants acquire and convert locks in the DLM.
71
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.
73
will wait until the lock operation has completed and returns the final completion status.
77
but takes a lockspace argument. This lockspace must have been previously opened by
78
.B dlm_lockspace_open() or
79
.B dlm_lockspace_create().
81
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.
83
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.
85
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.
88
Lock mode to acquire or convert to.
91
LKM_CRMODE Concurrent read
92
LKM_CWMODE Concurrent write
93
LKM_PRMODE Protected read
94
LKM_PWMODE Protected write
99
Affect the operation of the lock call:
101
LKF_NOQUEUE Don't queue the lock. If it cannot be granted return
103
LKF_CONVERT Convert an existing lock
104
LKF_VALBLK Lock has a value block
105
LKF_QUECVT Put conversion to the back of the queue
106
LKF_EXPEDITE Grant a NL lock immediately regardless of other locks
107
on the conversion queue
108
LKF_PERSISTENT Specifies a lock that will not be unlocked when the
109
process exits; it will become an orphan lock.
110
LKF_CONVDEADLK Enable internal conversion deadlock resolution where
111
the lock's granted mode may be set to NL and
112
DLM_SBF_DEMOTED is returned in lksb.sb_flags.
113
LKF_NODLCKWT Do not consider this lock when trying to detect
115
LKF_NODLCKBLK Not implemented
116
LKF_NOQUEUEBAST Send blocking ASTs even for NOQUEUE operations
117
LKF_HEADQUE Add locks to the head of the convert or waiting queue
118
LKF_NOORDER Avoid the VMS rules on grant order
119
LKF_ALTPR If the requested mode can't be granted (generally CW),
120
try to grant in PR and return DLM_SBF_ALTMODE.
121
LKF_ALTCW If the requested mode can't be granted (generally PR),
122
try to grant in CW and return DLM_SBF_ALTMODE.
123
LKF_TIMEOUT The lock will time out per the timeout arg.
130
This structure contains the returned lock ID, the actual
131
status of the lock operation (all lock ops are asynchronous)
132
and the value block if LKF_VALBLK is set.
136
Name of the lock. Can be binary, max 64 bytes. Ignored for lock
137
conversions. (Should be a string to work with debugging tools.)
141
Length of the above name. Ignored for lock conversions.
145
ID of parent lock or NULL if this is a top-level lock. This is currently unused.
149
Address of AST routine to be called when the lock operation
150
completes. The final completion status of the lock will be
151
in the lksb. the AST routine must not be NULL.
155
Argument to pass to the AST routine (most people pass the lksb
156
in here but it can be anything you like.)
160
Blocking AST routine. address of a function to call if this
161
lock is blocking another. The function will be called with
170
Optional transaction ID for deadlock detection.
174
Timeout in centiseconds. If it takes longer than this to acquire the lock
175
(usually because it is already blocked by another lock), then the AST
176
will trigger with ETIMEDOUT as the status. If the lock operation is a conversion
177
then the lock will remain at its current status. If this is a new lock then
178
the lock will not exist and any LKB in the lksb will be invalid. This is
179
ignored without the LKF_TIMEOUT flag.
182
0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following:
185
EINVAL An invalid parameter was passed to the call (eg bad lock
187
ENOMEM A (kernel) memory allocation failed
188
EAGAIN LKF_NOQUEUE was requested and the lock could not be
190
EBUSY The lock is currently being locked or converted
191
EFAULT The userland buffer could not be read/written by the
192
kernel (this indicates a library problem)
193
EDEADLOCK The lock operation is causing a deadlock and has been
194
cancelled. If this was a conversion then the lock is
195
reverted to its previously granted state. If it was a
196
new lock then it has not been granted. (NB Only
197
conversion deadlocks are currently detected)
199
If an error is returned in the AST, then lksb.sb_status is set to the one of the above values instead of zero.
203
int sb_status; /* Final status of lock operation */
204
uint32_t sb_lkid; /* ID of lock. Returned from dlm_lock()
205
on first use. Used as input to
206
dlm_lock() for a conversion operation */
207
char sb_flags; /* Completion flags, see above */
208
char sb_lvbptr; /* Optional pointer to lock value block */
215
struct dlm_lksb lksb;
217
status = dlm_lock_wait(LKM_EXMODE,
224
NULL, // bast routine,
228
dlm_unlock_wait(lksb.sb_lkid, 0, &lksb);
236
.BR dlm_open_lockspace (3),
237
.BR dlm_create_lockspace (3),
238
.BR dlm_close_lockspace (3),
239
.BR dlm_release_lockspace (3)
added
removed
libdlm/man/dlm_lock.3
