[Cluster-devel] cluster/dlm/man dlm_query.3

[pcaulfield at sourceware.org]

CVSROOT:	/cvs/cluster
Module name:	cluster
Branch: 	RHEL4
Changes by:	pcaulfield at sourceware.org	2007-07-11 13:22:30

Modified files:
	dlm/man        : dlm_query.3 

Log message:
	A little more spiel.

Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/cluster/dlm/man/dlm_query.3.diff?cvsroot=cluster&only_with_tag=RHEL4&r1=1.1.2.1&r2=1.1.2.2

--- cluster/dlm/man/Attic/dlm_query.3	2007/07/11 13:11:36	1.1.2.1
+++ cluster/dlm/man/Attic/dlm_query.3	2007/07/11 13:22:29	1.1.2.2
@@ -29,6 +29,16 @@
                       struct dlm_queryinfo *qinfo)
 
 .fi
+.br
+.SS DESCRIPTION
+The dlm query API is a method of getting information about other locks that are held (or pending) on a resource that you already hold a lock for.If you don't have a lock on a known resource then a getting a NL lock on it will allow you to query it without affecting ether locking operations (much).
+.br
+It is not a method of getting a list of resources in a lockspace, use dlm_tool or similar for that purpose.
+.br
+Once you have a lock ID, you can use these calls to find out (eg) which locks are waiting to be granted, or which locks are blocking your lock, including which cluster node and PID of the process (if relevant). You can also get general information about the lock such as the resource name (if you've forgotten it!), LVB state and value and the node where it is mastered.
+.br
+The main structure passed into dlm_query() is the dlm_queryinfo struct (see below). The main constituents of this are two pointers, one to a gdlm_resinfo structure which will be filled in with information about the resource, and an array of gdlm_lockinfo structures which contains information about all the locks that match the requested criteria; or, at least, as many as will fit int the allocated space.
+.PP
 .B dlm_query()
 is asynchronous, the ultimate status and data will be returned into the dlm_query_info structure which should be checked when the ast_routine is called. The lksb must contain a valid lock ID in sb_lkid which is used to identify the resource to be queried, status will be returned in sb_status; As with the locking calls an AST routine will be called when the query completes if the call itself returns 0. See below for full details of the query call.
 .PP