[Cluster-devel] cluster/dlm/man Makefile dlm_cleanup.3 dlm_clo ...
pcaulfield at sourceware.org
pcaulfield at sourceware.org
Fri Aug 3 10:27:57 UTC 2007
CVSROOT: /cvs/cluster
Module name: cluster
Branch: RHEL5
Changes by: pcaulfield at sourceware.org 2007-08-03 10:27:54
Added files:
dlm/man : Makefile dlm_cleanup.3 dlm_close_lockspace.3
dlm_create_lockspace.3 dlm_dispatch.3
dlm_get_fd.3 dlm_lock.3 dlm_lock_wait.3
dlm_ls_lock.3 dlm_ls_lock_wait.3 dlm_ls_lockx.3
dlm_ls_pthread_init.3 dlm_ls_unlock.3
dlm_ls_unlock_wait.3 dlm_new_lockspace.3
dlm_open_lockspace.3 dlm_pthread_init.3
dlm_release_lockspace.3 dlm_unlock.3
dlm_unlock_wait.3 libdlm.3
Log message:
Add man pages for libdlm calls.
Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/Makefile.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.3.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_cleanup.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_close_lockspace.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_create_lockspace.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.3.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_dispatch.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_get_fd.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_lock.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.3.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_lock_wait.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_lock.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_lock_wait.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_lockx.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.1.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_pthread_init.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_unlock.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_ls_unlock_wait.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_new_lockspace.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.1.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_open_lockspace.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_pthread_init.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_release_lockspace.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_unlock.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.3.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_unlock_wait.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/libdlm.3.diff?cvsroot=cluster&only_with_tag=RHEL5&r1=NONE&r2=1.2.2.1
/cvs/cluster/cluster/dlm/man/Makefile,v --> standard output
revision 1.3.2.1
--- cluster/dlm/man/Makefile
+++ - 2007-08-03 10:27:55.311547000 +0000
@@ -0,0 +1,30 @@
+###############################################################################
+###############################################################################
+##
+## Copyright (C) 2007 Red Hat, Inc. All rights reserved.
+##
+## This copyrighted material is made available to anyone wishing to use,
+## modify, copy, or redistribute it subject to the terms and conditions
+## of the GNU General Public License v.2.
+##
+###############################################################################
+###############################################################################
+
+include ../make/defines.mk
+
+TARGETS = dlm_cleanup.3 dlm_lock_wait.3 dlm_open_lockspace.3 \
+ dlm_close_lockspace.3 dlm_ls_lock.3 dlm_pthread_init.3 \
+ dlm_create_lockspace.3 dlm_ls_lock_wait.3 dlm_release_lockspace.3 \
+ dlm_dispatch.3 dlm_ls_pthread_init.3 dlm_unlock.3 \
+ dlm_get_fd.3 dlm_ls_unlock.3 dlm_unlock_wait.3 \
+ dlm_lock.3 dlm_ls_unlock_wait.3 libdlm.3
+
+
+all:
+
+install:
+ install -d ${mandir}/man3
+ install ${TARGETS} ${mandir}/man3
+
+uninstall:
+ ${UNINSTALL} ${TARGETS} ${mandir}/man3
/cvs/cluster/cluster/dlm/man/dlm_cleanup.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_cleanup.3
+++ - 2007-08-03 10:27:55.440459000 +0000
@@ -0,0 +1 @@
+.so man3/libdlm.3
/cvs/cluster/cluster/dlm/man/dlm_close_lockspace.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_close_lockspace.3
+++ - 2007-08-03 10:27:55.544057000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_create_lockspace.3
/cvs/cluster/cluster/dlm/man/dlm_create_lockspace.3,v --> standard output
revision 1.3.2.1
--- cluster/dlm/man/dlm_create_lockspace.3
+++ - 2007-08-03 10:27:55.635099000 +0000
@@ -0,0 +1,92 @@
+.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
+.SH SYNOPSIS
+.nf
+ #include <libdlm.h>
+
+dlm_lshandle_t dlm_create_lockspace(const char *name, mode_t mode);
+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)
+
+.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.
+.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.
+.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
+The caller must have CAP_SYSADMIN privileges to do this operation.
+.PP
+Return codes:
+0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following:
+.nf
+EINVAL An invalid parameter was passed to the call
+ENOMEM A (kernel) memory allocation failed
+EEXIST The lockspace already exists
+EPERM Process does not have capability to create lockspaces
+ENOSYS A fatal error occurred initialising the DLM
+Any error returned by the open() system call
+.fi
+.SS
+int dlm_new_lockspace(const char *name, mode_t mode, uint32_t flags);
+.PP
+Performs the same function as
+.B dlm_create_lockspace()
+above, but passes some creation flags to the call that affect the lockspace being created. Currently supported flags are:
+.nf
+DLM_LSFL_NODIR
+DLM_LSFL_TIMEWARN
+.fi
+.SS
+int dlm_release_lockspace(const char *name, dlm_lshandle_t lockspace, int force)
+.PP
+Deletes a lockspace. If the lockspace still has active locks then -1 will be returned and errno set to EBUSY. Both the lockspace handle /and/ the name must be specified. This call also closes the lockspace and stops the thread associated with the lockspace, if any.
+.br
+Note that other nodes in the cluster may still have locks open on this lockspace. This call only removes the lockspace from the current node. If the force flag is set then the lockspace will be removed even if another user on this node has active locks in it. Existing users will NOT be notified if you do this, so be careful.
+.br
+The caller must have CAP_SYSADMIN privileges to do this operation.
+.PP
+Return codes:
+0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following:
+.nf
+EINVAL An invalid parameter was passed to the call
+EPERM Process does not have capability to release lockspaces
+EBUSY The lockspace could not be freed because it still contains locks
+ and force was not set.
+.fi
+
+.SS
+dlm_lshandle_t dlm_open_lockspace(const char *name)
+.PP
+Opens an already existing lockspace and returns a handle to it.
+.br
+Return codes:
+.br
+0 is returned if the call completed successfully. If not, -1 is returned and errno is set to an error returned by the open() system call
+.SS
+int dlm_close_lockspace(dlm_lshandle_t lockspace)
+.br
+Close the lockspace. Any locks held by this process will be freed. If a thread is associated with this lockspace then it will be stopped.
+.PP
+Return codes:
+.br
+0 is returned if the call completed successfully. If not, -1 is returned and errno is set to one of the following:
+.nf
+EINVAL lockspace was not a valid lockspace handle
+.fi
+
+
+.SH SEE ALSO
+
+.BR libdlm (3),
+.BR dlm_unlock (3),
+.BR dlm_lock (3),
/cvs/cluster/cluster/dlm/man/dlm_dispatch.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_dispatch.3
+++ - 2007-08-03 10:27:55.716697000 +0000
@@ -0,0 +1 @@
+.so man3/libdlm.3
/cvs/cluster/cluster/dlm/man/dlm_get_fd.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_get_fd.3
+++ - 2007-08-03 10:27:55.811006000 +0000
@@ -0,0 +1 @@
+.so man3/libdlm.3
/cvs/cluster/cluster/dlm/man/dlm_lock.3,v --> standard output
revision 1.3.2.1
--- cluster/dlm/man/dlm_lock.3
+++ - 2007-08-03 10:27:55.895973000 +0000
@@ -0,0 +1,231 @@
+.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,
+ void (*astaddr) (void *astarg),
+ void *astarg,
+ void (*bastaddr) (void *astarg),
+ struct dlm_range *range);
+
+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);
+
+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);
+
+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);
+
+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);
+
+
+
+.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.
+ 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_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
+
+.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.
+.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
+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.
+.PP
+.B xid
+.br
+Don't know what this does...Dave!???
+.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.
+.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 */
+};
+
+struct dlm_range {
+ uint64_t ra_start;
+ uint64_t ra_end;
+};
+.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)
/cvs/cluster/cluster/dlm/man/dlm_lock_wait.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_lock_wait.3
+++ - 2007-08-03 10:27:55.990509000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_lock.3
/cvs/cluster/cluster/dlm/man/dlm_ls_lock.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_ls_lock.3
+++ - 2007-08-03 10:27:56.080853000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_lock.3
/cvs/cluster/cluster/dlm/man/dlm_ls_lock_wait.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_ls_lock_wait.3
+++ - 2007-08-03 10:27:56.172186000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_lock.3
/cvs/cluster/cluster/dlm/man/dlm_ls_lockx.3,v --> standard output
revision 1.1.2.1
--- cluster/dlm/man/dlm_ls_lockx.3
+++ - 2007-08-03 10:27:56.253553000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_lock.3
/cvs/cluster/cluster/dlm/man/dlm_ls_pthread_init.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_ls_pthread_init.3
+++ - 2007-08-03 10:27:56.332957000 +0000
@@ -0,0 +1 @@
+.so man3/libdlm.3
/cvs/cluster/cluster/dlm/man/dlm_ls_unlock.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_ls_unlock.3
+++ - 2007-08-03 10:27:56.412427000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_unlock.3
/cvs/cluster/cluster/dlm/man/dlm_ls_unlock_wait.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_ls_unlock_wait.3
+++ - 2007-08-03 10:27:56.503752000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_unlock.3
/cvs/cluster/cluster/dlm/man/dlm_new_lockspace.3,v --> standard output
revision 1.1.2.1
--- cluster/dlm/man/dlm_new_lockspace.3
+++ - 2007-08-03 10:27:56.584253000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_create_lockspace.3
/cvs/cluster/cluster/dlm/man/dlm_open_lockspace.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_open_lockspace.3
+++ - 2007-08-03 10:27:56.664268000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_create_lockspace.3
/cvs/cluster/cluster/dlm/man/dlm_pthread_init.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_pthread_init.3
+++ - 2007-08-03 10:27:56.741112000 +0000
@@ -0,0 +1 @@
+.so man3/libdlm.3
/cvs/cluster/cluster/dlm/man/dlm_release_lockspace.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_release_lockspace.3
+++ - 2007-08-03 10:27:56.817940000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_create_lockspace.3
/cvs/cluster/cluster/dlm/man/dlm_unlock.3,v --> standard output
revision 1.3.2.1
--- cluster/dlm/man/dlm_unlock.3
+++ - 2007-08-03 10:27:56.898703000 +0000
@@ -0,0 +1,89 @@
+.TH DLM_UNLOCK 3 "July 5, 2007" "libdlm functions"
+.SH NAME
+dlm_unlock \- unlock a DLM lock
+.SH SYNOPSIS
+.nf
+#include <libdlm.h>
+
+int dlm_unlock(uint32_t lkid,
+ uint32_t flags, struct dlm_lksb *lksb, void *astarg);
+
+int dlm_unlock_wait(uint32_t lkid,
+ uint32_t flags, struct dlm_lksb *lksb);
+
+.fi
+.SH DESCRIPTION
+.B dlm_unlock()
+unlocks a lock previously acquired by dlm_lock and its variants.
+.PP
+Unless
+.B dlm_unlock_wait()
+is used unlocks are also asynchronous. The AST routine is called when the resource is successfully unlocked (see below).
+.PP
+.B lkid
+Lock ID as returned in the lksb
+.PP
+.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
+.fi
+.PP
+.B lksb
+LKSB to return status and value block information.
+.PP
+.B astarg
+New parameter to be passed to the completion AST.
+The completion AST routine is the
+last completion AST routine specified in a dlm_lock call.
+If dlm_lock_wait() was the last routine to issue a lock,
+dlm_unlock_wait() must be used to release the lock. If dlm_lock()
+was the last routine to issue a lock then either dlm_unlock()
+or dlm_unlock_wait() may be called.
+.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)
+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
+.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_lock (3),
+.BR dlm_open_lockspace (3),
+.BR dlm_create_lockspace (3),
+.BR dlm_close_lockspace (3),
+.BR dlm_release_lockspace (3)
/cvs/cluster/cluster/dlm/man/dlm_unlock_wait.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/dlm_unlock_wait.3
+++ - 2007-08-03 10:27:56.977295000 +0000
@@ -0,0 +1 @@
+.so man3/dlm_unlock.3
/cvs/cluster/cluster/dlm/man/libdlm.3,v --> standard output
revision 1.2.2.1
--- cluster/dlm/man/libdlm.3
+++ - 2007-08-03 10:27:57.058378000 +0000
@@ -0,0 +1,101 @@
+.TH LIBDLM 3 "July 5, 2007" "libdlm functions"
+.SH NAME
+libdlm, dlm_get_fd, dlm_dispatch, dlm_pthread_init, dlm_ls_pthread_init, dlm_cleanup
+.SH SYNOPSIS
+.nf
+#include <libdlm.h>
+.nf
+int dlm_pthread_init();
+int dlm_ls_pthread_init(dlm_lshandle_t lockspace);
+int dlm_pthread_cleanup();
+int dlm_get_fd(void);
+int dlm_dispatch(int fd);
+
+link with -ldlm
+.fi
+.SH DESCRIPTION
+libdlm provides the programmatic userspace interface to the Distributed Lock manager. It provides all the calls you need to maniupulate locks & lockspaces
+.br
+libdlm can be used in pthread or non-pthread applications. For pthread applications simply call the following function before doing any lock operations. If you're using pthreads, remember to define _REENTRANT at the top of the program or using -D_REENTRANT on the compile line.
+.br
+pthreads is the normal way of using the DLM. This way you simply initialise the DLM's thread and all the AST routines will be delivered in that thread. You just call the dlm_lock() etc routines in the main line of your program.
+.br
+If you don't want to use pthreads or you want to handle the dlm callback ASTs yourself then you can get an FD handle to the DLM device and call
+.B dlm_dispatch() on it whenever it becomes active. That was ASTs will be delivered in the context of the thread/process that called
+.B dlm_dispatch().
+
+
+.SS int dlm_pthread_init()
+.br
+Creates a thread to receive all lock ASTs. The AST callback function for lock operations will be called in the context of this thread. If there is a potential for local resource access conflicts you must provide your own pthread-based locking in the AST routine.
+.PP
+.SS int dlm_ls_pthread_init(dlm_lshandle_t lockspace)
+.br
+As dlm_pthread_init but initialises a thread for the specified lockspace.
+.PP
+.SS int dlm_pthread_cleanup()
+.br
+Cleans up the default lockspace threads after use. Normally you don't need to call this, but if the locking code is in a dynamically loadable shared library this will probably be necessary.
+.br
+For non-pthread based applications the DLM provides a file descriptor that the program can feed into poll/select. If activity is detected on that FD then a dispatch function should be called:
+.PP
+.SS int dlm_get_fd()
+Returns a file-descriptor for the DLM suitable for passing in to poll() or select().
+.PP
+.SS int dlm_dispatch(int fd)
+.br
+Reads from the DLM and calls any AST routines that may be needed. This routine runs in the context of the caller so no extra locking is needed to protect local resources.
+.PP
+
+
+.SH EXAMPLES
+
+Create a lockspace and start a thread to deliver its callbacks:
+.nf
+dlm_lshandle_t ls;
+
+ls = dlm_create_lockspace("myLS", 0660);
+dlm_ls_pthread_init(ls);
+
+...
+
+status = dlm_ls_lock(ls,
+ ... );
+
+
+.fi
+.PP
+ Using poll(2) to wait for and dispatch ASTs
+.nf
+
+
+static int poll_for_ast(dlm_lshandle_t ls)
+{
+ struct pollfd pfd;
+
+ pfd.fd = dlm_ls_get_fd(ls);
+ pfd.events = POLLIN;
+ while (!ast_called)
+ {
+ if (poll(&pfd, 1, 0) < 0)
+ {
+ perror("poll");
+ return -1;
+ }
+ dlm_dispatch(dlm_ls_get_fd(ls));
+ }
+ ast_called = 0;
+ return 0;
+}
+.fi
+
+
+.SH SEE ALSO
+
+.BR libdlm (3),
+.BR dlm_lock (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)
More information about the Cluster-devel
mailing list