pthread_spin_init.3: New page describing pthread_spin_init(3) and pthread_spin_destroy(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3
new file mode 100644 (file)
index 0000000..af9a926
--- /dev/null
+++ b/man3/pthread_spin_init.3
@@ -0,0 +1,122 @@
+.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.TH PTHREAD_SPIN_INIT 3 2017-09-30 "Linux" "Linux Programmer's Manual"
+.SH NAME
+pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_spin_init(pthread_spinlock_t *" clock " int " pshared ");"
+.BI "int pthread_spin_destroy(pthread_spinlock_t *" clock ");"
+.fi
+.PP
+Compile and link with \fI\-pthread\fP.
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.BR pthread_spin_init (),
+.BR pthread_spin_destroy ():
+.br
+.RS 4
+.ad l
+_POSIX_C_SOURCE >= 200112L
+.RE
+.ad
+.SH DESCRIPTION
+The
+.BR pthread_spin_init ()
+function allocates any resources required for the use of
+the spin lock referred to by
+.I lock
+and initializes the lock to be in the unlocked state.
+The
+.I pshared
+argument must have one of the following values:
+.TP
+.B PTHREAD_PROCESS_PRIVATE
+The spin lock is to be operated on only by threads in the same process
+as the thread that calls
+.BR pthread_spin_init ().
+(Attempting to share the spin lock between processes
+results in undefined behavior.)
+.TP
+.B PTHREAD_PROCESS_SHARED
+The spin lock may be operated on by any thread in any process that
+has access to the memory containing the lock
+(i.e.., the lock may be in a shared memory object that is
+shared among multiple processes).
+.PP
+Calling
+.BR pthread_spin_init ()
+on a spin lock that has already been initialized results
+in undefined behavior.
+.PP
+The
+.BR pthread_spin_destroy ()
+function destroys a previously initialized spin lock,
+freeing any resources that were allocated for that lock.
+Destroying a spin lock that has not been previously been initialized
+or destroying a spin lock while another thread holds the lock
+results in undefined behavior.
+.PP
+Once a spin lock has been destroyed,
+performing any operation on the lock other than
+once more initializing it with
+.BR pthread_spin_init ()
+results in undefined behavior.
+.SH RETURN VALUE
+On success, there functions return zero.
+On failure, they return an error number.
+In the event that
+.BR pthread_spin_init ()
+fails, the lock is not initialized.
+.SH ERRORS
+.BR pthread_spin_init ()
+may fail with the following errors:
+.\" These errors don't occur on the glibc implementation
+.TP
+.B EAGAIN
+The system has insufficient resources to initialize
+a new spin lock.
+.TP
+.B ENOMEM
+Insufficient memory to initialize the spin lock.
+.SH VERSIONS
+These functions first appeared in glibc in version 2.2.
+.SH CONFORMING TO
+POSIX.1-2001.
+.PP
+Support for process-shared spin locks is a POSIX option.
+The option is supported in the glibc implementation.
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_spin_lock (3),
+.BR pthread_spin_unlock (3),
+.BR pthreads (7)