xref: /freebsd/share/man/man9/lock.9 (revision 41466b50c1d5bfd1cf6adaae547a579a75d7c04e)
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