mirror of https://github.com/mkerrisk/man-pages
146 lines
5.5 KiB
Plaintext
146 lines
5.5 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "PTHREAD_RWLOCK_RDLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" pthread_rwlock_rdlock
|
||
|
.SH NAME
|
||
|
pthread_rwlock_rdlock, pthread_rwlock_tryrdlock \- lock a read-write
|
||
|
lock object for reading
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <pthread.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int pthread_rwlock_rdlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB);
|
||
|
.br
|
||
|
int pthread_rwlock_tryrdlock(pthread_rwlock_t\fP \fI*rwlock\fP\fB);
|
||
|
\fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_rdlock\fP() function shall apply a read lock
|
||
|
to the read-write lock referenced by \fIrwlock\fP. The
|
||
|
calling thread acquires the read lock if a writer does not hold the
|
||
|
lock and there are no writers blocked on the lock.
|
||
|
.LP
|
||
|
If the Thread Execution Scheduling option is supported, and the threads
|
||
|
involved in the lock are executing with the scheduling
|
||
|
policies SCHED_FIFO or SCHED_RR, the calling thread shall not acquire
|
||
|
the lock if a writer holds the lock or if writers of higher
|
||
|
or equal priority are blocked on the lock; otherwise, the calling
|
||
|
thread shall acquire the lock.
|
||
|
.LP
|
||
|
If the Threads Execution Scheduling option is supported, and the threads
|
||
|
involved in the lock are executing with the
|
||
|
SCHED_SPORADIC scheduling policy, the calling thread shall not acquire
|
||
|
the lock if a writer holds the lock or if writers of higher
|
||
|
or equal priority are blocked on the lock; otherwise, the calling
|
||
|
thread shall acquire the lock.
|
||
|
.LP
|
||
|
If the Thread Execution Scheduling option is not supported, it is
|
||
|
implementation-defined whether the calling thread acquires the
|
||
|
lock when a writer does not hold the lock and there are writers blocked
|
||
|
on the lock. If a writer holds the lock, the calling thread
|
||
|
shall not acquire the read lock. If the read lock is not acquired,
|
||
|
the calling thread shall block until it can acquire the lock.
|
||
|
The calling thread may deadlock if at the time the call is made it
|
||
|
holds a write lock.
|
||
|
.LP
|
||
|
A thread may hold multiple concurrent read locks on \fIrwlock\fP (that
|
||
|
is, successfully call the \fIpthread_rwlock_rdlock\fP()
|
||
|
function \fIn\fP times). If so, the application shall ensure that
|
||
|
the thread performs matching unlocks (that is, it calls the \fIpthread_rwlock_unlock\fP()
|
||
|
function \fIn\fP times).
|
||
|
.LP
|
||
|
The maximum number of simultaneous read locks that an implementation
|
||
|
guarantees can be applied to a read-write lock shall be
|
||
|
implementation-defined. The \fIpthread_rwlock_rdlock\fP() function
|
||
|
may fail if this maximum would be exceeded.
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_tryrdlock\fP() function shall apply a read lock
|
||
|
as in the \fIpthread_rwlock_rdlock\fP() function, with
|
||
|
the exception that the function shall fail if the equivalent \fIpthread_rwlock_rdlock\fP()
|
||
|
call would have blocked the calling
|
||
|
thread. In no case shall the \fIpthread_rwlock_tryrdlock\fP() function
|
||
|
ever block; it always either acquires the lock or fails and
|
||
|
returns immediately.
|
||
|
.LP
|
||
|
Results are undefined if any of these functions are called with an
|
||
|
uninitialized read-write lock.
|
||
|
.LP
|
||
|
If a signal is delivered to a thread waiting for a read-write lock
|
||
|
for reading, upon return from the signal handler the thread
|
||
|
resumes waiting for the read-write lock for reading as if it was not
|
||
|
interrupted.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
If successful, the \fIpthread_rwlock_rdlock\fP() function shall return
|
||
|
zero; otherwise, an error number shall be returned to
|
||
|
indicate the error.
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_tryrdlock\fP() function shall return zero if
|
||
|
the lock for reading on the read-write lock object
|
||
|
referenced by \fIrwlock\fP is acquired. Otherwise, an error number
|
||
|
shall be returned to indicate the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_tryrdlock\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EBUSY
|
||
|
The read-write lock could not be acquired for reading because a writer
|
||
|
holds the lock or a writer with the appropriate priority
|
||
|
was blocked on it.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_rdlock\fP() and \fIpthread_rwlock_tryrdlock\fP()
|
||
|
functions may fail if:
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value specified by \fIrwlock\fP does not refer to an initialized
|
||
|
read-write lock object.
|
||
|
.TP 7
|
||
|
.B EAGAIN
|
||
|
The read lock could not be acquired because the maximum number of
|
||
|
read locks for \fIrwlock\fP has been exceeded.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIpthread_rwlock_rdlock\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B EDEADLK
|
||
|
The current thread already owns the read-write lock for writing.
|
||
|
.sp
|
||
|
.LP
|
||
|
These functions shall not return an error code of [EINTR].
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
Applications using these functions may be subject to priority inversion,
|
||
|
as discussed in the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_timedrdlock\fP()
|
||
|
, \fIpthread_rwlock_timedwrlock\fP() , \fIpthread_rwlock_trywrlock\fP()
|
||
|
, \fIpthread_rwlock_unlock\fP() , \fIpthread_rwlock_wrlock\fP() ,
|
||
|
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|