Man Linux: Main Page and Category List

NAME

       dlm_lock - acquire or convert a DLM lock

SYNOPSIS

        #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,         /* 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,         /* 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,         /* 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,         /* 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,         /* unused */
                 (*astaddr) (void *astarg),
                 void *astarg,
                 void (*bastaddr) (void *astarg),
                 uint64_t *xid,
                 uint64_t *timeout);

DESCRIPTION

       dlm_lock and its variants acquire and convert locks in the DLM.

       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.
       dlm_lock_wait() will wait until the lock operation  has  completed  and
       returns  the  final  completion  status.   dlm_ls_lock() is the same as
       dlm_lock() but takes a lockspace argument.  This  lockspace  must  have
       been      previously      opened     by     dlm_lockspace_open()     or
       dlm_lockspace_create().

       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.

       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.

       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.

       mode Lock mode to acquire or convert to.
         LKM_NLMODE   NULL Lock
         LKM_CRMODE   Concurrent read
         LKM_CWMODE   Concurrent write
         LKM_PRMODE   Protected read
         LKM_PWMODE   Protected write
         LKM_EXMODE   Exclusive

       flags Affect the operation of the lock call:
         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; 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
         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.

       lksb Lock Status block
       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.

       name
       Name of the lock. Can  be  binary,  max  64  bytes.  Ignored  for  lock
       conversions.  (Should be a string to work with debugging tools.)

       namelen
       Length of the above name. Ignored for lock conversions.

       parent
       ID  of  parent  lock  or  NULL  if  this  is  a top-level lock. This is
       currently unused.

       ast
       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.

       astargs
       Argument to pass to the AST routine (most people pass the lksb in  here
       but it can be anything you like.)

       bast
       Blocking  AST  routine.  address  of a function to call if this lock is
       blocking another. The function will be called with astargs.

       range
       This is unused.

       xid
       Optional transaction ID for deadlock detection.

       timeout
       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.  This is ignored without the LKF_TIMEOUT flag.

   Return values
       0  is  returned  if  the  call  completed  successfully.  If not, -1 is
       returned and errno is set to one of the following:

       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)

       If an error is returned in the AST, then lksb.sb_status is set to the one of the above values instead of zero.

   Structures
       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 */
       };

EXAMPLE

       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);

SEE ALSO

       libdlm(3),            dlm_unlock(3),             dlm_open_lockspace(3),
       dlm_create_lockspace(3),                        dlm_close_lockspace(3),
       dlm_release_lockspace(3)