unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

LOCK(9)                  BSD Kernel Developer's Manual                 LOCK(9)

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

SYNOPSIS
     #include <&lt;sys/lock.h>&gt;

     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 pro-
             vided.  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 attempt-
                                      ing to acquire the lock.
                     LK_CANRECURSE    Processes can acquire the lock recur-
                                      sively.

     lockmgr(lock, flags, slock)
             Set, change or release a lock according to the parameters pro-
             vided.  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 dif-
                                 ferent thread.
                   LK_SHARED     Lock is locked for shared-access.  The cur-
                                 rent 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 progres-
     sively deprecated in favor of rwlock(9).

BSD                            January 11, 2015                            BSD