[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Cluster-devel] cluster/dlm/man dlm_create_lockspace.3 dlm_loc ...



CVSROOT:	/cvs/cluster
Module name:	cluster
Changes by:	teigland 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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]