.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
  LKF_FORCEUNLOCK  Unlock the lock even if it's waiting.
.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)