1DLM_LOCK(3) Library Functions Manual DLM_LOCK(3)
2
6 dlm_lock - acquire or convert a DLM lock
7
9 #include <libdlm.h>
10 int dlm_lock(uint32_t mode,
12 struct dlm_lksb *lksb,
13 uint32_t flags,
14 const void *name,
15 unsigned int namelen,
16 uint32_t parent, /* unused */
17 void (*astaddr) (void *astarg),
18 void *astarg,
19 void (*bastaddr) (void *astarg),
20 void *range); /* unused */
21 int dlm_lock_wait(uint32_t mode,
23 struct dlm_lksb *lksb,
24 uint32_t flags,
25 const void *name,
26 unsigned int namelen,
27 uint32_t parent, /* unused */
28 void *bastarg,
29 void (*bastaddr) (void *bastarg),
30 void *range); /* unused */
31 int dlm_ls_lock(dlm_lshandle_t lockspace,
33 uint32_t mode,
34 struct dlm_lksb *lksb,
35 uint32_t flags,
36 const void *name,
37 unsigned int namelen,
38 uint32_t parent, /* unused */
39 void (*astaddr) (void *astarg),
40 void *astarg,
41 void (*bastaddr) (void *astarg),
42 void *range); /* unused */
43 int dlm_ls_lock_wait(dlm_lshandle_t lockspace,
45 uint32_t mode,
46 struct dlm_lksb *lksb,
47 uint32_t flags,
48 const void *name,
49 unsigned int namelen,
50 uint32_t parent, /* unusued */
51 void *bastarg,
52 void (*bastaddr) (void *bastarg),
53 void *range); /* unused */
54 int dlm_ls_lockx(dlm_lshandle_t lockspace,
56 uint32_t mode,
57 struct dlm_lksb *lksb,
58 uint32_t flags,
59 const void *name,
60 unsigned int namelen,
61 uint32_t parent, /* unused */
62 (*astaddr) (void *astarg),
63 void *astarg,
64 void (*bastaddr) (void *astarg),
65 uint64_t *xid,
66 uint64_t *timeout);
67
72 dlm_lock and its variants acquire and convert locks in the DLM.
73 dlm_lock() operations are asynchronous. If the call to dlm_lock returns
75 an error then the operation has failed and the AST routine will not be
76 called. If dlm_lock returns 0 it is still possible that the lock opera‐
77 tion will fail. The AST routine will be called when the locking is com‐
78 plete or has failed and the status is returned in the lksb.
79 dlm_lock_wait() will wait until the lock operation has completed and
80 returns the final completion status. dlm_ls_lock() is the same as
81 dlm_lock() but takes a lockspace argument. This lockspace must have
82 been previously opened by dlm_lockspace_open() or dlm_lockspace_cre‐
83 ate().
84 For conversion operations the name and namelen are ignored and the lock
86 ID in the LKSB is used to identify the lock to be converted.
87 If a lock value block is specified then in general, a grant or a con‐
89 version to an equal-level or higher-level lock mode reads the lock
90 value from the resource into the caller's lock value block. When a lock
91 conversion from EX or PW to an equal-level or lower-level lock mode
92 occurs, the contents of the caller's lock value block are written into
93 the resource. If the LVB is invalidated the lksb.sb_flags member will
94 be set to DLM_SBF_VALNOTVALID. Lock values blocks are always 32 bytes
95 long.
96 If the AST routines or parameter are passed to a conversion operation
98 then they will overwrite those values that were passed to a previous
99 dlm_lock call.
100 mode Lock mode to acquire or convert to.
102 LKM_NLMODE NULL Lock
103 LKM_CRMODE Concurrent read
104 LKM_CWMODE Concurrent write
105 LKM_PRMODE Protected read
106 LKM_PWMODE Protected write
107 LKM_EXMODE Exclusive
108 flags Affect the operation of the lock call:
110 LKF_NOQUEUE Don't queue the lock. If it cannot be granted return
111 -EAGAIN
112 LKF_CONVERT Convert an existing lock
113 LKF_VALBLK Lock has a value block
114 LKF_QUECVT Put conversion to the back of the queue
115 LKF_EXPEDITE Grant a NL lock immediately regardless of other locks
116 on the conversion queue
117 LKF_PERSISTENT Specifies a lock that will not be unlocked when the
118 process exits; it will become an orphan lock.
119 LKF_CONVDEADLK Enable internal conversion deadlock resolution where
120 the lock's granted mode may be set to NL and
121 DLM_SBF_DEMOTED is returned in lksb.sb_flags.
122 LKF_NODLCKWT Do not consider this lock when trying to detect
123 deadlock conditions.
124 LKF_NODLCKBLK Not implemented
125 LKF_NOQUEUEBAST Send blocking ASTs even for NOQUEUE operations
126 LKF_HEADQUE Add locks to the head of the convert or waiting queue
127 LKF_NOORDER Avoid the VMS rules on grant order
128 LKF_ALTPR If the requested mode can't be granted (generally CW),
129 try to grant in PR and return DLM_SBF_ALTMODE.
130 LKF_ALTCW If the requested mode can't be granted (generally PR),
131 try to grant in CW and return DLM_SBF_ALTMODE.
132 LKF_TIMEOUT The lock will time out per the timeout arg.
133 lksb Lock Status block
136 This structure contains the returned lock ID, the actual status of the
137 lock operation (all lock ops are asynchronous) and the value block if
138 LKF_VALBLK is set.
139 name
141 Name of the lock. Can be binary, max 64 bytes. Ignored for lock conver‐
142 sions. (Should be a string to work with debugging tools.)
143 namelen
145 Length of the above name. Ignored for lock conversions.
146 parent
148 ID of parent lock or NULL if this is a top-level lock. This is cur‐
149 rently unused.
150 ast
152 Address of AST routine to be called when the lock operation completes.
153 The final completion status of the lock will be in the lksb. the AST
154 routine must not be NULL.
155 astargs
157 Argument to pass to the AST routine (most people pass the lksb in here
158 but it can be anything you like.)
159 bast
161 Blocking AST routine. address of a function to call if this lock is
162 blocking another. The function will be called with astargs.
163 range
165 This is unused.
166 xid
168 Optional transaction ID for deadlock detection.
169 timeout
171 Timeout in centiseconds. If it takes longer than this to acquire the
172 lock (usually because it is already blocked by another lock), then the
173 AST will trigger with ETIMEDOUT as the status. If the lock operation is
174 a conversion then the lock will remain at its current status. If this
175 is a new lock then the lock will not exist and any LKB in the lksb will
176 be invalid. This is ignored without the LKF_TIMEOUT flag.
177 Return values
179 0 is returned if the call completed successfully. If not, -1 is
180 returned and errno is set to one of the following:
181 EINVAL An invalid parameter was passed to the call (eg bad lock
183 mode or flag)
184 ENOMEM A (kernel) memory allocation failed
185 EAGAIN LKF_NOQUEUE was requested and the lock could not be
186 granted
187 EBUSY The lock is currently being locked or converted
188 EFAULT The userland buffer could not be read/written by the
189 kernel (this indicates a library problem)
190 EDEADLOCK The lock operation is causing a deadlock and has been
191 cancelled. If this was a conversion then the lock is
192 reverted to its previously granted state. If it was a
193 new lock then it has not been granted. (NB Only
194 conversion deadlocks are currently detected)
195 If an error is returned in the AST, then lksb.sb_status is set to the one of the above values instead of zero.
197 Structures
199 struct dlm_lksb {
200 int sb_status; /* Final status of lock operation */
201 uint32_t sb_lkid; /* ID of lock. Returned from dlm_lock()
202 on first use. Used as input to
203 dlm_lock() for a conversion operation */
204 char sb_flags; /* Completion flags, see above */
205 char sb_lvbptr; /* Optional pointer to lock value block */
206 };
207
210 int status;
211 struct dlm_lksb lksb;
212 status = dlm_lock_wait(LKM_EXMODE,
214 &lksb,
215 LKF_NOQUEUE,
216 "MyLock",
217 strlen("MyLock"),
218 0, // Parent,
219 NULL, // bast arg
220 NULL, // bast routine,
221 NULL); // Range
222 if (status == 0)
224 dlm_unlock_wait(lksb.sb_lkid, 0, &lksb);
225
229 libdlm(3), dlm_unlock(3), dlm_open_lockspace(3), dlm_cre‐
230 ate_lockspace(3), dlm_close_lockspace(3), dlm_release_lockspace(3)
231libdlm functions July 5, 2007 DLM_LOCK(3)