Debian Codegraph @

upstream/debian-unstable/man3/pthread_spin_lock.3

raw
1 .\" Copyright 2017, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_spin_lock 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \-
9 lock and unlock a spin lock
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <pthread.h>
16 .P
17 .BI "int pthread_spin_lock(pthread_spinlock_t *" lock );
18 .BI "int pthread_spin_trylock(pthread_spinlock_t *" lock );
19 .BI "int pthread_spin_unlock(pthread_spinlock_t *" lock );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR pthread_spin_lock (),
28 .BR pthread_spin_trylock ():
29 .nf
30 _POSIX_C_SOURCE >= 200112L
31 .fi
32 .SH DESCRIPTION
33 The
34 .BR pthread_spin_lock ()
35 function locks the spin lock referred to by
36 .IR lock .
37 If the spin lock is currently unlocked,
38 the calling thread acquires the lock immediately.
39 If the spin lock is currently locked by another thread,
40 the calling thread spins, testing the lock until it becomes available,
41 at which point the calling thread acquires the lock.
42 .P
43 Calling
44 .BR pthread_spin_lock ()
45 on a lock that is already held by the caller
46 or a lock that has not been initialized with
47 .BR pthread_spin_init (3)
48 results in undefined behavior.
49 .P
50 The
51 .BR pthread_spin_trylock ()
52 function is like
53 .BR pthread_spin_lock (),
54 except that if the spin lock referred to by
55 .I lock
56 is currently locked,
57 then, instead of spinning, the call returns immediately with the error
58 .BR EBUSY .
59 .P
60 The
61 .BR pthread_spin_unlock ()
62 function unlocks the spin lock referred to
63 .IR lock .
64 If any threads are spinning on the lock,
65 one of those threads will then acquire the lock.
66 .P
67 Calling
68 .BR pthread_spin_unlock ()
69 on a lock that is not held by the caller results in undefined behavior.
70 .SH RETURN VALUE
71 On success, these functions return zero.
72 On failure, they return an error number.
73 .SH ERRORS
74 .BR pthread_spin_lock ()
75 may fail with the following errors:
76 .TP
77 .B EDEADLOCK
78 .\" Not detected in glibc
79 The system detected a deadlock condition.
80 .P
81 .BR pthread_spin_trylock ()
82 fails with the following errors:
83 .TP
84 .B EBUSY
85 The spin lock is currently locked by another thread.
86 .SH STANDARDS
87 POSIX.1-2008.
88 .SH HISTORY
89 glibc 2.2.
90 POSIX.1-2001.
91 .SH CAVEATS
92 Applying any of the functions described on this page to
93 an uninitialized spin lock results in undefined behavior.
94 .P
95 Carefully read NOTES in
96 .BR pthread_spin_init (3).
97 .SH SEE ALSO
98 .ad l
99 .nh
100 .\" FIXME . .BR pthread_mutex_lock (3),
101 .BR pthread_spin_destroy (3),
102 .BR pthread_spin_init (3),
103 .BR pthreads (7)