Debian Codegraph @

upstream/debian-unstable/man3/pthread_rwlockattr_setkind_np.3

raw
1 .\" Copyright 2010, Novell, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_rwlockattr_setkind_np 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get
9 the read-write lock kind of the thread read-write lock attribute object
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_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr ,
18 .BI " int " pref );
19 .B int pthread_rwlockattr_getkind_np(
20 .BI " const pthread_rwlockattr_t *restrict " attr ,
21 .BI " int *restrict " pref );
22 .P
23 .fi
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR pthread_rwlockattr_setkind_np (),
30 .BR pthread_rwlockattr_getkind_np ():
31 .nf
32 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
33 .fi
34 .SH DESCRIPTION
35 The
36 .BR pthread_rwlockattr_setkind_np ()
37 function sets the "lock kind" attribute of the
38 read-write lock attribute object referred to by
39 .I attr
40 to the value specified in
41 .IR pref .
42 The argument
43 .I pref
44 may be set to one of the following:
45 .TP
46 .B PTHREAD_RWLOCK_PREFER_READER_NP
47 This is the default.
48 A thread may hold multiple read locks;
49 that is,
50 read locks are recursive.
51 According to The Single Unix Specification,
52 the behavior is unspecified
53 when a reader tries to place a lock,
54 and there is no write lock but writers are waiting.
55 Giving preference to the reader,
56 as is set by
57 .BR PTHREAD_RWLOCK_PREFER_READER_NP ,
58 implies that the reader will receive the requested lock,
59 even if a writer is waiting.
60 As long as there are readers,
61 the writer will be starved.
62 .TP
63 .B PTHREAD_RWLOCK_PREFER_WRITER_NP
64 This is intended as the write lock analog of
65 .BR PTHREAD_RWLOCK_PREFER_READER_NP .
66 This is ignored by glibc because the POSIX requirement to support
67 recursive read locks would cause this option to create trivial deadlocks;
68 instead use
69 .B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP
70 which ensures the application developer will not take recursive read locks
71 thus avoiding deadlocks.
72 .\" ---
73 .\" Here is the relevant wording:
74 .\"
75 .\" A thread may hold multiple concurrent read locks on rwlock (that is,
76 .\" successfully call the pthread_rwlock_rdlock() function n times). If
77 .\" so, the thread must perform matching unlocks (that is, it must call
78 .\" the pthread_rwlock_unlock() function n times).
79 .\"
80 .\" By making write-priority work correctly, I broke the above requirement,
81 .\" because I had no clue that recursive read locks are permissible.
82 .\"
83 .\" If a thread which holds a read lock tries to acquire another read lock,
84 .\" and now one or more writers is waiting for a write lock, then the algorithm
85 .\" will lead to an obvious deadlock. The reader will be suspended, waiting for
86 .\" the writers to acquire and release the lock, and the writers will be
87 .\" suspended waiting for every existing read lock to be released.
88 .\" ---
89 .\" https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html
90 .\" https://sourceware.org/legacy-ml/libc-alpha/2000-01/msg00055.html
91 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=7057
92 .TP
93 .B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP
94 Setting the lock kind to this
95 avoids writer starvation as long as any read locking is not done in a
96 recursive fashion.
97 .P
98 The
99 .BR pthread_rwlockattr_getkind_np ()
100 function returns the value of the lock kind attribute of the
101 read-write lock attribute object referred to by
102 .I attr
103 in the pointer
104 .IR pref .
105 .SH RETURN VALUE
106 On success, these functions return 0.
107 Given valid pointer arguments,
108 .BR pthread_rwlockattr_getkind_np ()
109 always succeeds.
110 On error,
111 .BR pthread_rwlockattr_setkind_np ()
112 returns a nonzero error number.
113 .SH ERRORS
114 .TP
115 .B EINVAL
116 .I pref
117 specifies an unsupported value.
118 .SH STANDARDS
119 GNU;
120 hence the suffix "_np" (nonportable) in the names.
121 .SH HISTORY
122 glibc 2.1.
123 .SH SEE ALSO
124 .BR pthreads (7)