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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
LOCK(9)		       FreeBSD Kernel Developer's Manual	       LOCK(9)

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

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

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

     void
     lockdestroy(struct	lock *lkp);

     int
     lockcount(struct lock *lkp);

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

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

     void
     lockmgr_printinfo(struct lock *lkp);

DESCRIPTION
     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
	    sleep(9).

     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
			       panic(9).

	       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
			       exclusive 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
			       every lock there	must be	a release.

	       LK_INTERLOCK    Unlock the interlock (which should be locked
			       already).

     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.

RETURN VALUES
     The lockcount() function returns an integer greater than or equal to
     zero.

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

     LK_SHARED	   A shared lock is held.

     0		   The lock is not held	by anyone.

ERRORS
     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
			required.

     [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
			below.

     [ERESTART]		PCATCH was set in the lock priority, a signal was
			delivered during a sleep, and the system call is to be
			restarted.

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

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

     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.

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

AUTHORS
     This manual page was written by Chad David	<davidc@acns.ab.ca>.

FreeBSD	9.2			 June 20, 2006			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | LOCKS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=lock&sektion=9&manpath=FreeBSD+7.0-RELEASE>

home | help