| 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) |