Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
LOCK(9)			 BSD Kernel Developer's	Manual		       LOCK(9)

     lockinit, lockdestroy, lockcount, lockmgr,	lockstatus, lockmgr_printinfo
     --	lockmgr	family of functions

     #include <sys/types.h>
     #include <sys/lock.h>
     #include <sys/lockmgr.h>

     lockinit(struct lock *lkp,	int prio, const	char *wmesg, int timo,
	 int flags);

     lockdestroy(struct	lock *lkp);

     lockcount(struct lock *lkp);

     lockmgr(struct lock *lkp, u_int flags, struct mtx *interlkp,
	 struct	thread *td);

     lockstatus(struct lock *lkp, struct thread	*td);

     lockmgr_printinfo(struct lock *lkp);

     The lockinit() function is	used to	initialize a lock.  It must be called
     before any	operation can be performed on a	lock.  Its arguments are:

     lkp    A pointer to the lock to initialize.

     prio   The	priority passed	to sleep(9).

     wmesg  The	lock message.  This is used for	both debugging output and

     timo   The	timeout	value passed to	sleep(9).

     flags  The	flags the lock is to be	initialized with.

	    LK_NOWAIT	   Do not sleep	while acquiring	the lock.

	    LK_SLEEPFAIL   Fail	after a	sleep.

	    LK_CANRECURSE  Allow recursive exclusive locks.

	    LK_NOSHARE	   Allow exclusive locks only.

	    LK_TIMELOCK	   Use timo during a sleep; otherwise, 0 is used.

     The lockdestroy() function	is used	to destroy a lock, and while it	is
     called in a number	of places in the kernel, it currently does nothing.

     The lockcount() function returns a	count of the number of exclusive locks
     and shared	locks held against the lock lkp.

     The lockmgr() function handles general locking functionality within the
     kernel, including support for shared and exclusive	locks, and recursion.
     lockmgr() is also able to upgrade and downgrade locks.

     Its arguments are:

     lkp       A pointer to the	lock to	manipulate.

     flags     Flags indicating	what action is to be taken.

	       LK_SHARED       Acquire a shared	lock.  If an exclusive lock is
			       currently held, it will be downgraded.

	       LK_EXCLUSIVE    Acquire an exclusive lock.  If an exclusive
			       lock is already held, and LK_CANRECURSE is not
			       set, the	system will panic(9).

	       LK_DOWNGRADE    Downgrade exclusive lock	to a shared lock.
			       Downgrading a shared lock is not	permitted.  If
			       an exclusive lock has been recursed, all	refer-
			       ences will be downgraded.

	       LK_EXCLUPGRADE  Upgrade a shared	lock to	an exclusive lock.
			       Fails with EBUSY	if there is someone ahead of
			       you in line waiting for an upgrade.  If this
			       call fails, the shared lock is lost.  Attempts
			       to upgrade an exclusive lock will cause a

	       LK_UPGRADE      Upgrade a shared	lock to	an exclusive lock.  If
			       this call fails,	the shared lock	is lost.  Dur-
			       ing the upgrade,	the shared lock	could be tem-
			       porarily	dropped.  Attempts to upgrade an ex-
			       clusive lock will cause a panic(9).

	       LK_RELEASE      Release the lock.  Releasing a lock that	is not
			       held can	cause a	panic(9).

	       LK_DRAIN	       Wait for	all activity on	the lock to end, then
			       mark it decommissioned.	This is	used before
			       freeing a lock that is part of a	piece of mem-
			       ory that	is about to be freed.  (As documented
			       in <sys/lockmgr.h>.)

	       LK_SLEEPFAIL    Fail if operation has slept.

	       LK_NOWAIT       Do not allow the	call to	sleep.	This can be
			       used to test the	lock.

	       LK_CANRECURSE   Allow recursion on an exclusive lock.  For ev-
			       ery lock	there must be a	release.

	       LK_INTERLOCK    Unlock the interlock (which should be locked

     interlkp  An interlock mutex for controlling group	access to the lock.
	       If LK_INTERLOCK is specified, lockmgr() assumes interlkp	is
	       currently owned and not recursed, and will return it unlocked.
	       See mtx_assert(9).

     td	       A thread	responsible for	this call.  NULL becomes LK_KERNPROC.

     The lockstatus() function returns the status of the lock in relation to
     the thread	passed to it.  Note that if td is NULL and an exclusive	lock
     is	held, LK_EXCLUSIVE will	be returned.

     The lockmgr_printinfo() function prints debugging information about the
     lock.  It is used primarily by VOP_PRINT(9) functions.

     The lockcount() function returns an integer greater than or equal to

     The lockmgr() function returns 0 on success and non-zero on failure.

     The lockstatus() function returns:

     LK_EXCLUSIVE  An exclusive	lock is	held by	the thread td.

     LK_EXCLOTHER  An exclusive	lock is	held by	someone	other than the thread

     LK_SHARED	   A shared lock is held.

     0		   The lock is not held	by anyone.

     lockmgr() fails if:

     [EBUSY]		LK_FORCEUPGRADE	was requested and another thread had
			already	requested a lock upgrade.

     [EBUSY]		LK_NOWAIT was set, and a sleep would have been re-

     [ENOLCK]		LK_SLEEPFAIL was set and lockmgr() did sleep.

     [EINTR]		PCATCH was set in the lock priority, and a signal was
			delivered during a sleep.  Note	the ERESTART error be-

     [ERESTART]		PCATCH was set in the lock priority, a signal was de-
			livered	during a sleep,	and the	system call is to be

     [EWOULDBLOCK]	a non-zero timeout was given, and the timeout expired.

     If	LK_INTERLOCK is	passed in the flags argument to	lockmgr(), the
     interlkp must be held prior to calling lockmgr(), and will	be returned

     Upgrade attempts that fail	result in the loss of the lock that is cur-
     rently held.  Also, it is invalid to upgrade an exclusive lock, and a
     panic(9) will be the result of trying.

     condvar(9), locking(9), mutex(9), rwlock(9), sleep(9), sx(9),
     mtx_assert(9), panic(9), VOP_PRINT(9)

     This manual page was written by Chad David	<>.

BSD				 June 20, 2006				   BSD


Want to link to this manual page? Use this URL:

home | help