1dlmfs
  2==================
  3A minimal DLM userspace interface implemented via a virtual file
  4system.
  5
  6dlmfs is built with OCFS2 as it requires most of its infrastructure.
  7
  8Project web page:    http://ocfs2.wiki.kernel.org
  9Tools web page:      https://github.com/markfasheh/ocfs2-tools
 10OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/
 11
 12All code copyright 2005 Oracle except when otherwise noted.
 13
 14CREDITS
 15=======
 16
 17Some code taken from ramfs which is Copyright (C) 2000 Linus Torvalds
 18and Transmeta Corp.
 19
 20Mark Fasheh <mark.fasheh@oracle.com>
 21
 22Caveats
 23=======
 24- Right now it only works with the OCFS2 DLM, though support for other
 25  DLM implementations should not be a major issue.
 26
 27Mount options
 28=============
 29None
 30
 31Usage
 32=====
 33
 34If you're just interested in OCFS2, then please see ocfs2.txt. The
 35rest of this document will be geared towards those who want to use
 36dlmfs for easy to setup and easy to use clustered locking in
 37userspace.
 38
 39Setup
 40=====
 41
 42dlmfs requires that the OCFS2 cluster infrastructure be in
 43place. Please download ocfs2-tools from the above url and configure a
 44cluster.
 45
 46You'll want to start heartbeating on a volume which all the nodes in
 47your lockspace can access. The easiest way to do this is via
 48ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires
 49that an OCFS2 file system be in place so that it can automatically
 50find its heartbeat area, though it will eventually support heartbeat
 51against raw disks.
 52
 53Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed
 54with ocfs2-tools.
 55
 56Once you're heartbeating, DLM lock 'domains' can be easily created /
 57destroyed and locks within them accessed.
 58
 59Locking
 60=======
 61
 62Users may access dlmfs via standard file system calls, or they can use
 63'libo2dlm' (distributed with ocfs2-tools) which abstracts the file
 64system calls and presents a more traditional locking api.
 65
 66dlmfs handles lock caching automatically for the user, so a lock
 67request for an already acquired lock will not generate another DLM
 68call. Userspace programs are assumed to handle their own local
 69locking.
 70
 71Two levels of locks are supported - Shared Read, and Exclusive.
 72Also supported is a Trylock operation.
 73
 74For information on the libo2dlm interface, please see o2dlm.h,
 75distributed with ocfs2-tools.
 76
 77Lock value blocks can be read and written to a resource via read(2)
 78and write(2) against the fd obtained via your open(2) call. The
 79maximum currently supported LVB length is 64 bytes (though that is an
 80OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share
 81small amounts of data amongst their nodes.
 82
 83mkdir(2) signals dlmfs to join a domain (which will have the same name
 84as the resulting directory)
 85
 86rmdir(2) signals dlmfs to leave the domain
 87
 88Locks for a given domain are represented by regular inodes inside the
 89domain directory.  Locking against them is done via the open(2) system
 90call.
 91
 92The open(2) call will not return until your lock has been granted or
 93an error has occurred, unless it has been instructed to do a trylock
 94operation. If the lock succeeds, you'll get an fd.
 95
 96open(2) with O_CREAT to ensure the resource inode is created - dlmfs does
 97not automatically create inodes for existing lock resources.
 98
 99Open Flag     Lock Request Type
100---------     -----------------
101O_RDONLY      Shared Read
102O_RDWR        Exclusive
103
104Open Flag     Resulting Locking Behavior
105---------     --------------------------
106O_NONBLOCK    Trylock operation
107
108You must provide exactly one of O_RDONLY or O_RDWR.
109
110If O_NONBLOCK is also provided and the trylock operation was valid but
111could not lock the resource then open(2) will return ETXTBUSY.
112
113close(2) drops the lock associated with your fd.
114
115Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is
116supported locally as well. This means you can use them to restrict
117access to the resources via dlmfs on your local node only.
118
119The resource LVB may be read from the fd in either Shared Read or
120Exclusive modes via the read(2) system call. It can be written via
121write(2) only when open in Exclusive mode.
122
123Once written, an LVB will be visible to other nodes who obtain Read
124Only or higher level locks on the resource.
125
126See Also
127========
128http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf
129
130For more information on the VMS distributed locking API.