LOCK(9)

NAME
lock, lockinit, lockmgr, lockstatus - kernel lock functions

SYNOPSIS
#include <sys/lock.h>
void
lockinit(struct lock *lock, int prio, const char *wmesg, int timo, int flags);
int
lockmgr(struct lock *lock, u_int flags, struct simplelock *slock);
int
lockstatus(struct lock *lock);

DESCRIPTION
The lock functions provide synchronisation in the kernel by preventing multiple processes from simultaneously executing critical sections of code accessing shared data.

struct lock supports sleeping until the lock can be acquired. The lock manager supplies both exclusive-access and shared-access locks, with recursive exclusive-access locks within a single process. It also allows upgrading a shared-access lock to an exclusive-access lock, as well as downgrading an exclusive-access lock to a shared-access lock.

FUNCTIONS
The functions which operate on locks are:

lockinit(lock, prio, wmesg, timo, flags)
    The lock lock is initialised according to the parameters provided. Arguments are as follows:

    lock
        The lock.
    prio
        The process priority when it is woken up after sleeping on the lock.
    wmesg
        A sleep message used when a process goes to sleep waiting for the lock, so that the exact reason it is sleeping can easily be identified.
    timo
        The maximum sleep time. Used by tsleep(9).
    flags
        Flags to specify the lock behaviour permanently over the lifetime of the lock. Valid lock flags are:

        LK_NOWAIT
            Processes should not sleep when attempting to acquire the lock.
        LK_CANRECURSE
            Processes can acquire the lock recursively.

lockmgr(lock, flags, slock)
    Set, change or release a lock according to the parameters provided. Arguments are as follows:

    lock
        The lock.
    flags
        Flags to specify the lock request type. In addition to the flags specified above, the following flags are valid:

        LK_SHARED
            Get one of many possible shared-access locks. If a process holding an exclusive-access lock requests a shared-access lock, the exclusive-access lock is downgraded to a shared-access lock.

        LK_EXCLUSIVE
            Stop further shared-access locks, when they are cleared, grant a pending upgrade if it exists, then grant an exclusive-access lock. Only one exclusive-access lock may exist at a time, except that a process holding an exclusive-access lock may get additional exclusive-access locks if it explicitly sets the LK_CANRECURSE flag in the lock request, or if the LK_CANRECURSE flag was set when the lock was initialised.

        LK_RELEASE
            Release one instance of a lock.

        LK_DRAIN
            Wait for all activity on the lock to end, then mark it decommissioned. This feature is used before freeing a lock that is part of a piece of memory that is about to be freed.

        LK_RECURSEFAIL
            Attempt at recursive lock fails.

    slock
        This argument exists for legacy reasons, it is now ignored.

lockstatus(lock)
    Returns the current state of lock lock.

    LK_EXCLUSIVE
        Lock is locked for exclusive-access by the calling thread.
    LK_EXCLOTHER
        Lock is locked for exclusive-access by a different thread.
    LK_SHARED
        Lock is locked for shared-access. The current thread may be one of the threads that has it locked.
    0   Lock is not locked.

RETURN VALUES
Successfully acquired locks return 0. A failed lock attempt always returns a non-zero error value. No lock is held after an error return. Locks will always succeed unless one of the following is true:

[EBUSY]
    LK_NOWAIT is set and a sleep would be required.

[EINTR]
    PCATCH is set in lock priority and a signal arrives to interrupt a system call.

[ERESTART]
    PCATCH is set in lock priority and a signal arrives so that the system call is restarted.

[EWOULDBLOCK]
    Non-null lock timeout and timeout expires.

SEE ALSO
mutex(9), pmap(9), rwlock(9), spl(9), tsleep(9), uvm(9)

HISTORY
The kernel locking API first appeared in 4.4BSD lite2. It was progressively deprecated in favor of rwlock(9).