*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> lockinit (9)              



NAME    [Toc]    [Back]

     lock,   simple_lock_init,   simple_lock,    simple_lock_try,
     lockinit,  lockmgr,  lockstatus, lockmgr_printinfo, - kernel
lock functions

SYNOPSIS    [Toc]    [Back]

     #include <sys/lock.h>

     simple_lock_init(struct simplelock *slock);

     simple_lock(struct simplelock *slock);

     simple_lock_try(struct simplelock *slock);

     simple_unlock(struct simplelock *slock);

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

     lockmgr(struct  lock  *lock,  u_int flags, struct simplelock
             struct proc *p);

     lockstatus(struct lock *lock);

     lockmgr_printinfo(struct lock *lock);

DESCRIPTION    [Toc]    [Back]

     The lock functions provide synchronisation in the kernel  by
     multiple  processes  from  simultaneously executing critical
sections of
     code accessing shared data.  A number of different locks are

     struct simplelock
              Provides a simple spinning mutex.  A processor will
              while trying to acquire a simplelock.  The  simplelock operations
              are   implemented  with  machine-dependent  locking

              Simplelocks are usually used only by the high-level
lock manager
              and  to  protect  short, critical sections of code.
              are the only locks that can be used inside  an  interrupt handler.
              For  a  simplelock  to be used in an interrupt handler, care must
              be taken to  disable  the  interrupt,  acquire  the
lock, do any processing,
  release  the simplelock and re-enable the
              This procedure is necessary to avoid  deadlock  between the interrupt
  handler  and other processes executing on the
same processor.

     struct lock
              Provides  a  high-level  lock   supporting   sleeping/spinning until
              the  lock  can  be acquired.  The lock manager supplies both exclusive-access
 and shared-access locks, with recursive
  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 sharedaccess lock.

     If the kernel option LOCKDEBUG is enabled, additional facilities are provided
  to record additional lock information.  These facilities are provided
 to assist in determining deadlock occurrences.

FUNCTIONS    [Toc]    [Back]

     The functions which operate on simplelocks are:

              The simplelock slock is initialised to the unlocked
state.  A
              statically  allocated  simplelock  also can be initialised with the
              macro SIMPLELOCK_INITIALIZER.  The  effect  is  the
same as the dynamic
 initialisation by a call to simple_lock_init.
For example,

              struct simplelock slock = SIMPLELOCK_INITIALIZER;

              The simplelock slock is locked.  If the  simplelock
is held then
              execution  will  spin  until  the simplelock is acquired.  Care must
              be taken that the calling process does not  already
hold the simplelock.
  In this case, the simplelock can never be
              If kernel option LOCKDEBUG is enabled,  a  "locking
against myself"
 panic will occur.

              Try  to  acquire the simplelock slock without spinning.  If the
              simplelock is held by another process then the  return value is
              0.   If  the  simplelock  was acquired successfully
then the return
              value is 1.

              The simplelock slock is unlocked.   The  simplelock
must be locked
              and  the  calling process must be the one that last
acquired the
              simplelock.  If the calling process does  not  hold
the simplelock,
  the simplelock will be released but the kernel behaviour
              is undefined.

     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

              flags    Flags to specify the lock behaviour permanently over
                       the lifetime  of  the  lock.   Valid  lock
flags are:

                                Processes  should  not sleep when
attempting to
                                acquire the lock.

                                Processes should sleep, then  return failure
                                when acquiring the lock.

                                Processes  can  acquire  the lock

     lockmgr(lock, flags, slock, p)
              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

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

                                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 exclusiveaccess
  locks  if  it  explicitly
 flag in the lock request,
or if the
                                LK_CANRECURSE  flag  was set when
the lock was

                                The process must hold  a  sharedaccess lock
                                that it wants to have upgraded to
an exclusive-access
 lock.  Other processes may get exclusive
  access  to the protected
resource between
 the time that  the  upgrade
is requested
                                and  the time that it is granted.

                                The process must hold  a  sharedaccess lock
                                that it wants to have upgraded to
an exclusive-access
 lock.  If the request
succeeds, no
                                other  processes  will  have  acquired exclusive
                                access to the protected  resource
between the
                                time that the upgrade is requested and the
                                time that it is granted.   However, if another
                                process  has already requested an
upgrade, the
                                request will fail.

                                The process must hold  an  exclusive-access lock
                                that  it wants to have downgraded
to a sharedaccess
  lock.   If  the   process
holds multiple
                                (recursive)      exclusive-access
locks, they will
                                all be downgraded  to  shared-access locks.

                                Release one instance of a lock.

                                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

                                Lock  is  to  be re-enabled after
drain.  The
                                LK_REENABLE flag may be set  only
at the release
  of  a  lock  obtained by a

                                Other locks while we have it  OK.

                                Attempt  at recursive lock fails.

                       LK_SPIN  Lock spins instead of sleeping.

                                Unlock the simplelock slock  when
the lock is

              slock     Simplelock interlock.  If the flag LK_INTERLOCK is set
                       in flags, slock is a  simplelock  held  by
the caller.
                       When  the  lock lock is acquired, the simplelock is released.
  If the flag LK_INTERLOCK  is  not
set, slock is

              p        Should always point to the current process

              Determine the status of lock lock.  Returns  LK_EXCLUSIVE or
              LK_SHARED  for  exclusive-access  and shared-access
locks respectively.

              Print out information about state of lock lock.

RETURN VALUES    [Toc]    [Back]

     Successfully acquired locks return 0.  A failed lock attempt
always returns
  a non-zero error value.  No lock is held after an error return (in
     particular, a failed LK_UPGRADE or LK_FORCEUPGRADE will have
released its
     shared-access  lock).   Locks will always succeed unless one
of the following
 is true:

     [EBUSY]       LK_FORCEUPGRADE is requested  and  some  other
process has already
 requested a lock upgrade or LK_NOWAIT is
set and a
                   sleep would be required.

     [ENOLCK]      LK_SLEEPFAIL is set and a sleep was done.

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

                   Non-null lock timeout and timeout expires.

CODE REFERENCES    [Toc]    [Back]

     This section describes places within the OpenBSD source tree
where actual
     code  implementing or utilising the locking framework can be
found.  All
     pathnames are relative to /usr/src.

     The locking framework itself is implemented within the file
     sys/kern/kern_lock.c.  Data structures and  function  prototypes for the
     framework are located in sys/sys/lock.h.

SEE ALSO    [Toc]    [Back]

     pmap(9), spl(9), tsleep(9), uvm(9)

HISTORY    [Toc]    [Back]

     The kernel locking API first appeared in 4.4BSD-lite2.

OpenBSD      3.6                           June      23,     2000
[ Back ]
 Similar pages
Name OS Title
sx_xunlock FreeBSD kernel shared/exclusive lock
sx_try_upgrade FreeBSD kernel shared/exclusive lock
sx FreeBSD kernel shared/exclusive lock
sx_assert FreeBSD kernel shared/exclusive lock
sx_destroy FreeBSD kernel shared/exclusive lock
sx_try_xlock FreeBSD kernel shared/exclusive lock
sx_sunlock FreeBSD kernel shared/exclusive lock
sx_downgrade FreeBSD kernel shared/exclusive lock
SX_SYSINIT FreeBSD kernel shared/exclusive lock
sx_init FreeBSD kernel shared/exclusive lock
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service