diff --git a/man3/pthread_rwlockattr_setkind_np.3 b/man3/pthread_rwlockattr_setkind_np.3 new file mode 100644 index 000000000..86d5211b1 --- /dev/null +++ b/man3/pthread_rwlockattr_setkind_np.3 @@ -0,0 +1,102 @@ +.\"Copyright (c) 2010 Novell Inc., written by Robert Schweikert +.\" +.\" +.\" 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. +.\" +.TH PTHREAD_RWLOCKATTR_SETKIND_NP 3 2010-06-09 "Linux Programmer's Manual" +.SH NAME +pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get +the read-write lock kind of the thread read-write lock attribute object +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE 500 +.B #include + +.BI "int pthread_rwlockattr_setkind_np (pthread_rwlockattr_t *" attr , +.BI " int" pref); +.BI "int pthread_rwlockattr_getkind_np (const pthread_rwlockattr_t *" attr , +.BI " int *" pref); +.sp +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_rwlockattr_setkind_np () +function +sets the kind of read-write lock of the +thread read-write lock attribute object referred to by +.I attr +to the value specified with +.IR pref . +The argument +.I pref +may be set to +.IR PTHREAD_RWLOCK_PREFER_READER_NP , +.IR PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP , +or +.IR PTHREAD_RWLOCK_PREFER_WRITER_NP . +The default lock setting is +.IR PTHREAD_RWLOCK_PREFER_READER_NP . +A thread may hold multiple read locks, i.e. read locks are recursive. +According to The Single Unix Specification, the behavior is unspecified when a +reader tries to place a lock, and there is no write lock but writers are +waiting. Giving preference to the reader, as is set by default with the +.IR PTHREAD_RWLOCK_PREFER_READER_NP value +implies that the reader will receive the requested lock, even if +a writer is waiting. As long as there are readers the writer will be +starved. Setting the kind to +.IR PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP , +avoids writer starvation as long as any read locking is not done in a +recursive fashion. + +The +.BR pthread_rwlockattr_getkind_np () +function +returns the value of the read-write lock attribute of the +thread read-write lock attribute object referred to by +.IR attr +in the pointer +.IR pref . +.SH RETURN VALUE +On success, these functions return 0; +on error, +.BR pthread_rwlockattr_setkind_np () +returns a non-zero error number. +.SH ERRORS +.TP +.BR EINVAL +.I pref +is set to an unsupported value. +.SH BUGS +Setting the value read-write lock kind to +.IR PTHREAD_RWLOCK_PREFER_WRITER_NP , +results in the same behavior as setting the value to +.IR PTHREAD_RWLOCK_PREFER_READER_NP . +As long as a reader thread holds the lock the thread holding a +write lock will be starved. Setting the kind value to +.IR PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP , +allows the writer to run. However, the writer may not be +recursive as is implied by the name. See +http://sourceware.org/bugzilla/show_bug.cgi?id=7057 +.SH CONFORMING TO +These functions are non-standard GNU extensions; +hence the suffix "_np" (non-portable) in the names. +.SH SEE ALSO +.BR pthreads (7)