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 thread 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 mtx *interlkp" "struct thread *td" 44.Ft int 45.Fn lockcount "struct lock *lkp" 46.Ft int 47.Fn lockstatus "struct lock *lkp" "struct thread *td" 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 ".Dv LK_EXCLUPGRADE" 65.It Dv LK_SHARED 66get one of many possible shared locks. 67If a thread 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 thread holding an exclusive lock may get additional exclusive 75locks if it explicitly sets the 76.Dv LK_CANRECURSE 77flag in the lock request, or if the 78.Dv LK_CANRECURSE 79flag was set when the lock was initialized. 80.It Dv LK_UPGRADE 81the thread must hold a shared lock that it wants to 82have upgraded to an exclusive lock. 83Other threads may get exclusive access to the resource between 84the time that the upgrade is requested and the time that it is 85granted. 86.It Dv LK_EXCLUPGRADE 87the thread must hold a shared lock that it wants to 88have upgraded to an exclusive lock. 89If the request succeeds, no other thread will have gotten 90exclusive access to the resource between the time that the upgrade 91is requested and the time that it is granted. 92However, if another thread has already requested an upgrade, 93the request will fail. 94.It Dv LK_DOWNGRADE 95the thread must hold an exclusive lock that it wants 96to have downgraded to a shared lock. 97If the thread holds multiple (recursive) exclusive locks, 98they will all be downgraded to shared locks. 99.It Dv LK_RELEASE 100release one instance of a lock. 101.It Dv LK_DRAIN 102wait for all activity on the lock to end, then mark it 103decommissioned. 104This feature is used before freeing a lock that is part of a 105piece of memory that is about to be freed. 106.It Dv LK_EXCLOTHER 107return for 108.Fn lockstatus . 109Used when another thread holds the lock exclusively. 110.El 111.Sh RETURN VALUES 112Successfully obtained locks return 0. 113Locks will always succeed unless one of the following is true: 114.Dv LK_FORCEUPGRADE 115is requested and some other thread has already 116requested a lock upgrade; returns 117.Er EBUSY . 118.Dv LK_WAIT 119is set and a sleep would be required; returns 120.Er EBUSY . 121.Dv LK_SLEEPFAIL 122is set and a sleep was done; returns 123.Er ENOLCK . 124.Dv PCATCH 125is set in lock priority and a signal arrives; returns 126either 127.Er EINTR 128or 129.Er ERESTART 130if system calls is to be restarted. 131Non-null lock timeout and timeout expires; returns 132.Er EWOULDBLOCK . 133A failed lock attempt always returns a non-zero error value. 134No lock is held after an error return (in particular, a failed 135.Dv LK_UPGRADE 136or 137.Dv LK_FORCEUPGRADE 138will have released its shared 139access lock). 140