1.\" Copyright (c) 2000 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd October 24, 2000 29.Dt LOCK 9 30.Os FreeBSD 31.Sh NAME 32.Nm lockinit , 33.Nm lockmgr , 34.Nm lockcount , 35.Nm lockstatus 36.Nd kernel process locking 37.Sh SYNOPSIS 38.Fd #include <sys/types.h> 39.Fd #include <sys/lock.h> 40.Ft void 41.Fn lockinit "struct lock *lkp" "int prio" "char *wmesg" "int timo" "int flags" 42.Ft int 43.Fn lockmgr "struct lock *lkp" "u_int flags" "struct simplelock *interlkp" "struct proc *p" 44.Ft int 45.Fn lockcount "struct lock *lkp" 46.Ft int 47.Fn lockstatus "struct lock *lkp" "struct proc *p" 48.Sh DESCRIPTION 49.Pp 50The function 51.Fn lockinit 52is used to initialise a lock. 53It is required if locks are used. 54The function 55.Fn lockmgr 56is used to manage locks. 57The function 58.Fn lockcount 59returns the number of shared lock holders on a lock. 60The function 61.Fn lockstatus 62determines the status of a lock. 63.Pp 64The following values are defined: 65.Bl -tag -width "LK_XXXXXXXXXXXX" -compact 66.It Dv LK_SHARED 67get one of many possible shared locks. 68If a process holding an exclusive lock requests a shared lock, 69the exclusive lock(s) will be downgraded to shared locks. 70.It Dv LK_EXCLUSIVE 71stop further shared locks, when they are cleared, 72grant a pending upgrade if it exists, then grant an exclusive 73lock. 74Only one exclusive lock may exist at a time, except that 75a process holding an exclusive lock may get additional exclusive 76locks if it explicitly sets the LK_CANRECURSE flag in the lock 77request, or if the LK_CANRECUSE flag was set when the lock was 78initialized. 79.It Dv LK_UPGRADE 80the process must hold a shared lock that it wants to 81have upgraded to an exclusive lock. 82Other processes may get exclusive access to the resource between 83the time that the upgrade is requested and the time that it is 84granted. 85.It Dv LK_EXCLUPGRADE 86the process must hold a shared lock that it wants to 87have upgraded to an exclusive lock. 88If the request succeeds, no other processes will have gotten 89exclusive access to the resource between the time that the upgrade 90is requested and the time that it is granted. 91However, if another process has already requested an upgrade, 92the request will fail. 93.It Dv LK_DOWNGRADE 94the process must hold an exclusive lock that it wants 95to have downgraded to a shared lock. 96If the process holds multiple (recursive) exclusive locks, 97they will all be downgraded to shared locks. 98.It Dv LK_RELEASE 99release one instance of a lock. 100.It Dv LK_DRAIN 101wait for all activity on the lock to end, then mark it 102decommissioned. 103This feature is used before freeing a lock that is part of a 104piece of memory that is about to be freed. 105.It Dv LK_EXCLOTHER 106return for lockstatus(). 107Used when another process holds the lock exclusively. 108.El 109.Sh RETURN VALUES 110Successfully obtained locks return 0. 111Locks will always succeed unless one of the following is true: 112LK_FORCEUPGRADE is requested and some other process has already 113requested a lock upgrade; returns 114.Er EBUSY . 115LK_WAIT is set and a sleep would be required; returns 116.Er EBUSY . 117LK_SLEEPFAIL is set and a sleep was done; returns 118.Er ENOLCK . 119PCATCH is set in lock priority and a signal arrives; returns 120either 121.Er EINTR 122or 123.Er ERESTART 124if system calls is to be restarted. 125Non-null lock timeout and timeout expires; returns 126.Er EWOULDBLOCK . 127A failed lock attempt always returns a non-zero error value. 128No lock is held after an error return (in particular, a failed 129LK_UPGRADE or LK_FORCEUPGRADE will have released its shared 130access lock). 131