File: dlm_lock.3

package info (click to toggle)
dlm 4.0.7-1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 900 kB
  • ctags: 1,844
  • sloc: ansic: 13,442; makefile: 297; sh: 83
file content (239 lines) | stat: -rw-r--r-- 8,222 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
.TH DLM_LOCK 3 "July 5, 2007" "libdlm functions"
.SH NAME
dlm_lock \- acquire or convert a DLM lock
.SH SYNOPSIS
.nf
 #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);



.fi
.SH DESCRIPTION
dlm_lock and its variants acquire and convert locks in the DLM.
.PP
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. 
.B dlm_lock_wait()
will wait until the lock operation has completed and returns the final completion status.
.B dlm_ls_lock()
is the same as 
.B dlm_lock()
but takes a lockspace argument. This lockspace must have been previously opened by
.B dlm_lockspace_open() or
.B dlm_lockspace_create().
.PP
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.
.PP
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.
.PP
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.
.PP
.B mode
Lock mode to acquire or convert to.
.nf
  LKM_NLMODE	NULL Lock
  LKM_CRMODE	Concurrent read
  LKM_CWMODE	Concurrent write
  LKM_PRMODE	Protected read
  LKM_PWMODE	Protected write
  LKM_EXMODE	Exclusive
.fi
.PP
.B flags
Affect the operation of the lock call:
.nf
  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.

.fi
.PP
.B lksb
Lock Status block
.br
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.
.PP
.B name
.br
Name of the lock. Can be binary, max 64 bytes. Ignored for lock
conversions.  (Should be a string to work with debugging tools.)
.PP
.B namelen	
.br
Length of the above name. Ignored for lock conversions.
.PP
.B parent	
.br
ID of parent lock or NULL if this is a top-level lock. This is currently unused.
.PP
.B ast	
.br
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.
.PP		
.B astargs	
.br
Argument to pass to the AST routine (most people pass the lksb
in here but it can be anything you like.)
.PP
.B bast
.br
Blocking AST routine. address of a function to call if this 
lock is blocking another. The function will be called with
astargs. 
.PP
.B range
.br
This is unused.
.PP
.B xid
.br
Optional transaction ID for deadlock detection.
.PP
.B timeout
.br
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.
.PP
.SS Return values
0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following:
.PP
.nf
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)
.PP
If an error is returned in the AST, then lksb.sb_status is set to the one of the above values instead of zero.
.SS Structures
.nf
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 */
};

.fi
.SH EXAMPLE
.nf
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);

.fi

.SH SEE ALSO

.BR libdlm (3),
.BR dlm_unlock (3),
.BR dlm_open_lockspace (3),
.BR dlm_create_lockspace (3),
.BR dlm_close_lockspace (3),
.BR dlm_release_lockspace (3)