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_init.3,v 1.3 2007/10/22 10:08:01 ru Exp $
26.\"
27.Dd July 10, 2009
28.Dt PTHREAD_SPIN_INIT 3
29.Os
30.Sh NAME
31.Nm pthread_spin_init , pthread_spin_destroy
32.Nd "initialize or destroy a spin lock"
33.Sh LIBRARY
34.Lb libpthread
35.Sh SYNOPSIS
36.In pthread.h
37.Ft int
38.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared"
39.Ft int
40.Fn pthread_spin_destroy "pthread_spinlock_t *lock"
41.Sh DESCRIPTION
42The
43.Fn pthread_spin_init
44function will initialize
45.Fa lock
46to an unlocked state and
47allocate any resources necessary to begin using it.
48If
49.Fa pshared
50is set to
51.Dv PTHREAD_PROCESS_SHARED ,
52any thread,
53whether belonging to the process in which the spinlock was created or not,
54that has access to the memory area where
55.Fa lock
56resides, can use
57.Fa lock .
58If it is set to
59.Dv PTHREAD_PROCESS_PRIVATE ,
60it can only be used by threads within the same process.
61.Pp
62The
63.Fn pthread_spin_destroy
64function will destroy
65.Fa lock
66and release any resources that may have been allocated on its behalf.
67.Sh RETURN VALUES
68If successful,
69both
70.Fn pthread_spin_init
71and
72.Fn pthread_spin_destroy
73will return zero.
74Otherwise, an error number will be returned to indicate the error.
75.Pp
76Neither of these functions will return
77.Er EINTR .
78.Sh ERRORS
79The
80.Fn pthread_spin_init
81and
82.Fn pthread_spin_destroy
83functions will fail if:
84.Bl -tag -width Er
85.It Bq Er EBUSY
86An attempt to initialize or destroy
87.Fa lock
88while it is in use.
89.It Bq Er EINVAL
90The value specified by
91.Fa lock
92is invalid.
93.El
94.Pp
95The
96.Fn pthread_spin_init
97function will fail if:
98.Bl -tag -width Er
99.It Bq Er EAGAIN
100Insufficient resources,
101other than memory,
102to initialize
103.Fa lock .
104.It Bq Er ENOMEM
105Insufficient memory to initialize
106.Fa lock .
107.El
108.Sh SEE ALSO
109.Xr pthread_spin_lock 3 ,
110.Xr pthread_spin_unlock 3
111.Sh BUGS
112The implementation of
113.Fn pthread_spin_init
114does not fully conform to
115.St -p1003.2
116because the
117.Fa pshared
118argument is ignored;
119if any value other than
120.Dv PTHREAD_PROCESS_PRIVATE
121is specified, it returns
122.Er EINVAL .
123