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 31.Sh NAME 32.Nm lockinit , 33.Nm lockmgr , 34.Nm lockcount , 35.Nm lockstatus 36.Nd kernel process locking 37.Sh SYNOPSIS 38.In sys/types.h 39.In 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 49The function 50.Fn lockinit 51is used to initialise a lock. 52It is required if locks are used. 53The function 54.Fn lockmgr 55is used to manage locks. 56The function 57.Fn lockcount 58returns the number of shared lock holders on a lock. 59The function 60.Fn lockstatus 61determines the status of a lock. 62.Pp 63The following values are defined: 64.Bl -tag -width "LK_XXXXXXXXXXXX" -compact 65.It Dv LK_SHARED 66get one of many possible shared locks. 67If a process holding an exclusive lock requests a shared lock, 68the exclusive lock(s) will be downgraded to shared locks. 69.It Dv LK_EXCLUSIVE 70stop further shared locks, when they are cleared, 71grant a pending upgrade if it exists, then grant an exclusive 72lock. 73Only one exclusive lock may exist at a time, except that 74a process holding an exclusive lock may get additional exclusive 75locks if it explicitly sets the LK_CANRECURSE flag in the lock 76request, or if the LK_CANRECUSE flag was set when the lock was 77initialized. 78.It Dv LK_UPGRADE 79the process must hold a shared lock that it wants to 80have upgraded to an exclusive lock. 81Other processes may get exclusive access to the resource between 82the time that the upgrade is requested and the time that it is 83granted. 84.It Dv LK_EXCLUPGRADE 85the process must hold a shared lock that it wants to 86have upgraded to an exclusive lock. 87If the request succeeds, no other processes will have gotten 88exclusive access to the resource between the time that the upgrade 89is requested and the time that it is granted. 90However, if another process has already requested an upgrade, 91the request will fail. 92.It Dv LK_DOWNGRADE 93the process must hold an exclusive lock that it wants 94to have downgraded to a shared lock. 95If the process holds multiple (recursive) exclusive locks, 96they will all be downgraded to shared locks. 97.It Dv LK_RELEASE 98release one instance of a lock. 99.It Dv LK_DRAIN 100wait for all activity on the lock to end, then mark it 101decommissioned. 102This feature is used before freeing a lock that is part of a 103piece of memory that is about to be freed. 104.It Dv LK_EXCLOTHER 105return for lockstatus(). 106Used when another process holds the lock exclusively. 107.El 108.Sh RETURN VALUES 109Successfully obtained locks return 0. 110Locks will always succeed unless one of the following is true: 111LK_FORCEUPGRADE is requested and some other process has already 112requested a lock upgrade; returns 113.Er EBUSY . 114LK_WAIT is set and a sleep would be required; returns 115.Er EBUSY . 116LK_SLEEPFAIL is set and a sleep was done; returns 117.Er ENOLCK . 118PCATCH is set in lock priority and a signal arrives; returns 119either 120.Er EINTR 121or 122.Er ERESTART 123if system calls is to be restarted. 124Non-null lock timeout and timeout expires; returns 125.Er EWOULDBLOCK . 126A failed lock attempt always returns a non-zero error value. 127No lock is held after an error return (in particular, a failed 128LK_UPGRADE or LK_FORCEUPGRADE will have released its shared 129access lock). 130