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 May 31, 2016 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 HISTORY 112The 113.Fn pthread_spin_init 114and 115.Fn pthread_spin_destroy 116functions first appeared in 117.Lb libkse 118in 119.Fx 5.2 , 120and in 121.Lb libthr 122in 123.Fx 5.3 . 124Support for process-shared spinlocks appeared in 125.Fx 11.0 . 126