1.\" Copyright (c) 2004 Michael Telahun Makonnen
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/share/man/man3/pthread_spin_lock.3,v 1.4 2007/10/22 10:08:01 ru Exp $
26.\"
27.Dd July 10, 2009
28.Dt PTHREAD_SPIN_LOCK 3
29.Os
30.Sh NAME
31.Nm pthread_spin_lock , pthread_spin_trylock , pthread_spin_unlock
32.Nd "lock or unlock a spin lock"
33.Sh LIBRARY
34.Lb libpthread
35.Sh SYNOPSIS
36.In pthread.h
37.Ft int
38.Fn pthread_spin_lock "pthread_spinlock_t *lock"
39.Ft int
40.Fn pthread_spin_trylock "pthread_spinlock_t *lock"
41.Ft int
42.Fn pthread_spin_unlock "pthread_spinlock_t *lock"
43.Sh DESCRIPTION
44The
45.Fn pthread_spin_lock
46function will acquire
47.Fa lock
48if it is not currently owned by another thread.
49If the lock cannot be acquired immediately, it will
50spin attempting to acquire the lock (it will not sleep) until
51it becomes available.
52.Pp
53The
54.Fn pthread_spin_trylock
55function is the same as
56.Fn pthread_spin_lock
57except that if it cannot acquire
58.Fa lock
59immediately it will return with an error.
60.Pp
61The
62.Fn pthread_spin_unlock
63function will release
64.Fa lock ,
65which must have been previously locked by a call to
66.Fn pthread_spin_lock
67or
68.Fn pthread_spin_trylock .
69.Sh RETURN VALUES
70If successful, all these functions will return zero.
71Otherwise, an error number will be returned to indicate the error.
72.Pp
73None of these functions will return
74.Er EINTR .
75.Sh ERRORS
76The
77.Fn pthread_spin_lock ,
78.Fn pthread_spin_trylock
79and
80.Fn pthread_spin_unlock
81functions will fail if:
82.Bl -tag -width Er
83.It Bq Er EINVAL
84The value specified by
85.Fa lock
86is invalid or is not initialized.
87.El
88.Pp
89The
90.Fn pthread_spin_lock
91function may fail if:
92.Bl -tag -width Er
93.It Bq Er EDEADLK
94The calling thread already owns the lock.
95.El
96.Pp
97The
98.Fn pthread_spin_trylock
99function will fail if:
100.Bl -tag -width Er
101.It Bq Er EBUSY
102Another thread currently holds
103.Fa lock .
104.El
105.Pp
106The
107.Fn pthread_spin_unlock
108function may fail if:
109.Bl -tag -width Er
110.It Bq Er EPERM
111The calling thread does not own
112.Fa lock .
113.El
114.Sh SEE ALSO
115.Xr pthread_spin_destroy 3 ,
116.Xr pthread_spin_init 3
117.Sh BUGS
118The implementation of
119.Fn pthread_spin_lock ,
120.Fn pthread_spin_trylock
121and
122.Fn pthread_spin_unlock
123is expected to conform to
124.St -p1003.2 .
125