[Cluster-devel] cluster/dlm/man dlm_create_lockspace.3 dlm_loc ...
teigland at sourceware.org
teigland at sourceware.org
Mon Jul 9 16:53:08 UTC 2007
CVSROOT: /cvs/cluster
Module name: cluster
Changes by: teigland at sourceware.org 2007-07-09 16:53:08
Modified files:
dlm/man : dlm_create_lockspace.3 dlm_lock.3 dlm_unlock.3
Log message:
Various small changes and additions. Munging formatting to avoid
line wrapping on 80 columns.
Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_create_lockspace.3.diff?cvsroot=cluster&r1=1.2&r2=1.3
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_lock.3.diff?cvsroot=cluster&r1=1.2&r2=1.3
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_unlock.3.diff?cvsroot=cluster&r1=1.2&r2=1.3
--- cluster/dlm/man/dlm_create_lockspace.3 2007/07/09 09:29:57 1.2
+++ cluster/dlm/man/dlm_create_lockspace.3 2007/07/09 16:53:08 1.3
@@ -1,6 +1,6 @@
.TH DLM_CREATE_LOCKSPACE 3 "July 5, 2007" "libdlm functions"
.SH NAME
-dlm_create_lockspace, dlm_open_lockspace, dlm_close_lockspace, dlm_releas_lockspace \- manipulate DLM lockspaces
+dlm_create_lockspace, dlm_open_lockspace, dlm_close_lockspace, dlm_release_lockspace \- manipulate DLM lockspaces
.SH SYNOPSIS
.nf
#include <libdlm.h>
@@ -9,18 +9,18 @@
dlm_lshandle_t dlm_new_lockspace(const char *name, mode_t mode, uint32_t flags);
dlm_lshandle_t dlm_open_lockspace(const char *name);
int dlm_close_lockspace(dlm_lshandle_t lockspace);
-int dlm_release_lockspace(const char *name, dlm_lshandle_t lockspace, int force)
+int dlm_release_lockspace(const char *name, dlm_lshandle_t lockspace, int force);
.fi
.SH DESCRIPTION
The DLM allows locks to be partitioned into "lockspaces", and these can be manipulated by userspace calls. It is possible (though not recommended) for an application to have multiple lockspaces open at one time.
-Many of the DLM calls work on the "default" lockspace, which should be fine for most users. The calls with _ls_ in them allow you to isolate your application from all others running in the cluster. Remember, lockspaces are a cluster-wide resource, so if you create a lockspace called "myls" it will share locks with a lockspace called "myls" on all nodes. These calls allow users to create & remove lockspaces, and users to connecto to existing lockspace to store their locks there.
+Many of the DLM calls work on the "default" lockspace, which should be fine for most users. The calls with _ls_ in them allow you to isolate your application from all others running in the cluster. Remember, lockspaces are a cluster-wide resource, so if you create a lockspace called "myls" it will share locks with a lockspace called "myls" on all nodes. These calls allow users to create & remove lockspaces, and users to connect to existing lockspace to store their locks there.
.PP
.SS
dlm_lshandle_t dlm_create_lockspace(const char *name, mode_t mode);
.br
-This creates a lockspace called <name> and the mode of the file user to access it will be <mode> (subject to umask as usual). The lockspace must not already exist on this node, if it does -1 will be returned and errno will be set to EEXIST. If you really want to use this lockspace you can then user dlm_open_lockspace() below. The name is the name of a misc device that will be created in /dev/misc.
+This creates a lockspace called <name> and the mode of the file user to access it will be <mode> (subject to umask as usual). The lockspace must not already exist on this node, if it does -1 will be returned and errno will be set to EEXIST. If you really want to use this lockspace you can then use dlm_open_lockspace() below. The name is the name of a misc device that will be created in /dev/misc.
.br
On success a handle to the lockspace is returned, which can be used to pass into subsequent dlm_ls_lock/unlock calls. Make no assumptions as to the content of this handle as it's content may change in future.
.br
--- cluster/dlm/man/dlm_lock.3 2007/07/09 09:29:57 1.2
+++ cluster/dlm/man/dlm_lock.3 2007/07/09 16:53:08 1.3
@@ -6,61 +6,61 @@
#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,
- void (*astaddr) (void *astarg),
- void *astarg,
- void (*bastaddr) (void *astarg),
- struct dlm_range *range);
+ 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,
- void *bastarg,
- void (*bastaddr) (void *bastarg),
- void *range);
+ 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,
- void (*astaddr) (void *astarg),
- void *astarg,
- void (*bastaddr) (void *astarg),
- void *range);
+ 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,
- void *bastarg,
- void (*bastaddr) (void *bastarg),
- void *range);
+ 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,
- void (*astaddr) (void *astarg),
- void *astarg,
- void (*bastaddr) (void *astarg),
- uint64_t *xid,
- uint64_t *timeout);
+ 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);
@@ -98,18 +98,29 @@
.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_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.
- LKF_CONVDEADLK Enable conversion deadlock
- LKF_NODLCKWT Do not consider this lock when trying to detect deadlock conditions
- LKF_NODLCKBLK Do not consider this lock as blocking other locks when trying to detect deadlock conditions.
+ 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 when using range locks
+ 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
@@ -123,7 +134,7 @@
.B name
.br
Name of the lock. Can be binary, max 64 bytes. Ignored for lock
-conversions.
+conversions. (Should be a string to work with debugging tools.)
.PP
.B namelen
.br
@@ -152,18 +163,11 @@
.PP
.B range
.br
-an optional structure of two uint64_t that indicate the range
-of the lock. Locks with overlapping ranges will be granted only
-if the lock modes are compatible. locks with non-overlapping
-ranges (on the same resource) do not conflict. A lock with no
-range is assumed to have a range encompassing the largest
-possible range. ie. 0-0xFFFFFFFFFFFFFFFF. Note that is is more
-efficient to specify no range than to specify the full range
-above.
+This is unused.
.PP
.B xid
.br
-Don't know what this does...Dave!???
+Optional transaction ID for deadlock detection.
.PP
.B timeout
.br
@@ -171,18 +175,26 @@
(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.
+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)
+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
@@ -196,10 +208,6 @@
char sb_lvbptr; /* Optional pointer to lock value block */
};
-struct dlm_range {
- uint64_t ra_start;
- uint64_t ra_end;
-};
.fi
.SH EXAMPLE
.nf
--- cluster/dlm/man/dlm_unlock.3 2007/07/09 09:29:57 1.2
+++ cluster/dlm/man/dlm_unlock.3 2007/07/09 16:53:08 1.3
@@ -26,15 +26,16 @@
.B flags
flags affecting the unlock operation:
.nf
- LKF_CANCEL Cancel a pending lock or conversion.
- This returns the lock to it's
- previously granted mode (in case of a
- conversion) or unlocks it (in case of a waiting lock).
- LKF_IVVALBLK Invalidate value block
+ LKF_CANCEL Cancel a pending lock or conversion.
+ This returns the lock to it's previously
+ granted mode (in case of a conversion) or
+ unlocks it (in case of a waiting lock).
+ LKF_IVVALBLK Invalidate value block
+ LKF_FORCEUNLOCK Unlock the lock even if it's waiting.
.fi
.PP
.B lksb
-LKSB to return status and value block information.
+LKSB to return status and value block information.
.PP
.B astarg
New parameter to be passed to the completion AST.
@@ -50,13 +51,17 @@
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)
-EINPROGRESS The lock is already being unlocked
-EBUSY The lock is currently being locked or converted
-ENOTEMPTY An attempt to made to unlock a parent lock that still has child locks.
-ECANCEL A lock conversion was successfully cancelled
-EUNLOCK An unlock operation completed successfully (sb_status only)
-EFAULT The userland buffer could not be read/written by the kernel
+EINVAL An invalid parameter was passed to the call (eg bad
+ lock mode or flag)
+EINPROGRESS The lock is already being unlocked
+EBUSY The lock is currently being locked or converted
+ENOTEMPTY An attempt to made to unlock a parent lock that still has
+ child locks.
+ECANCEL A lock conversion was successfully cancelled
+EUNLOCK An unlock operation completed successfully
+ (sb_status only)
+EFAULT The userland buffer could not be read/written by the
+ kernel
.fi
If an error is returned in the AST, then lksb.sb_status is set to the one of the above numbers instead of zero.
.SH EXAMPLE
More information about the Cluster-devel
mailing list