1DLM_LOCK(3)                Library Functions Manual                DLM_LOCK(3)
2
3
4

NAME

6       dlm_lock - acquire or convert a DLM lock
7

SYNOPSIS

9        #include <libdlm.h>
10
11       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
22       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
32       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
44       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
55       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
68
69
70

DESCRIPTION

72       dlm_lock and its variants acquire and convert locks in the DLM.
73
74       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
85       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
88       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
97       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
101       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
109       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
134
135       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
140       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
144       namelen
145       Length of the above name. Ignored for lock conversions.
146
147       parent
148       ID  of  parent  lock  or NULL if this is a top-level lock. This is cur‐
149       rently unused.
150
151       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
156       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
160       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
164       range
165       This is unused.
166
167       xid
168       Optional transaction ID for deadlock detection.
169
170       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
178   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
182       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
196       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
198   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
208

EXAMPLE

210       int status;
211       struct dlm_lksb lksb;
212
213       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
223       if (status == 0)
224            dlm_unlock_wait(lksb.sb_lkid, 0, &lksb);
225
226
227

SEE ALSO

229       libdlm(3),     dlm_unlock(3),      dlm_open_lockspace(3),      dlm_cre‐
230       ate_lockspace(3), dlm_close_lockspace(3), dlm_release_lockspace(3)
231
232
233
234libdlm functions                 July 5, 2007                      DLM_LOCK(3)
Impressum