xref: /freebsd/share/man/man3/pthread_spin_init.3 (revision c98323078dede7579020518ec84cdcb478e5c142)
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$
26.\"
27.Dd January 22, 2004
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.Lb libthr
36.Sh SYNOPSIS
37.In pthread.h
38.Ft int
39.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared"
40.Ft int
41.Fn pthread_spin_destroy "pthread_spinlock_t *lock"
42.Sh DESCRIPTION
43The
44.Fn pthread_spin_init
45function will initialize
46.Fa lock
47to an unlocked state and
48allocate any resources necessary to begin using it.
49If
50.Fa pshared
51is set to
52.Dv PTHREAD_PROCESS_SHARED ,
53any thread,
54whether belonging to the process in which the spinlock was created or not,
55that has access to the memory area where
56.Fa lock
57resides, can use
58.Fa lock .
59If it is set to
60.Dv PTHREAD_PROCESS_PRIVATE ,
61it can only be used by threads within the same process.
62.Pp
63The
64.Fn pthread_spin_destroy
65function will destroy
66.Fa lock
67and release any resources that may have been allocated on its behalf.
68.Sh RETURN VALUES
69If successful,
70both
71.Fn pthread_spin_init
72and
73.Fn pthread_spin_destroy
74will return zero.
75Otherwise, an error number will be returned to indicate the error.
76.Pp
77Neither of these functions will return
78.Er EINTR .
79.Sh ERRORS
80The
81.Fn pthread_spin_init
82and
83.Fn pthread_spin_destroy
84functions will fail if:
85.Bl -tag -width Er
86.It Bq Er EBUSY
87An attempt to initialize or destroy
88.Fa lock
89while it is in use.
90.It Bq Er EINVAL
91The value specified by
92.Fa lock
93is invalid.
94.El
95.Pp
96The
97.Fn pthread_spin_init
98function will fail if:
99.Bl -tag -width Er
100.It Bq Er EAGAIN
101Insufficient resources,
102other than memory,
103to initialize
104.Fa lock .
105.It Bq Er ENOMEM
106Insufficient memory to initialize
107.Fa lock .
108.El
109.Sh SEE ALSO
110.Xr pthread_spin_lock 3 ,
111.Xr pthread_spin_unlock 3
112.Sh HISTORY
113The
114.Fn pthread_spin_init
115and
116.Fn pthread_spin_destroy
117functions first appeared in
118.Lb libpthread
119in
120.Fx 5.2 ,
121and in
122.Lb libthr
123in
124.Fx 5.3 .
125.Sh BUGS
126The implementation of
127.Fn pthread_spin_init
128does not fully conform to
129.St -p1003.2
130because the
131.Fa pshared
132argument is ignored in
133.Lb libthr ,
134and in
135.Lb libpthread
136if any value other than
137.Dv PTHREAD_PROCESSES_PRIVATE
138is specified, it returns
139.Er EINVAL .
140