diff options
Diffstat (limited to 'man3p/pthread_rwlock_timedrdlock.3p')
| -rw-r--r-- | man3p/pthread_rwlock_timedrdlock.3p | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/man3p/pthread_rwlock_timedrdlock.3p b/man3p/pthread_rwlock_timedrdlock.3p new file mode 100644 index 000000000..1e8629335 --- /dev/null +++ b/man3p/pthread_rwlock_timedrdlock.3p @@ -0,0 +1,123 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "PTHREAD_RWLOCK_TIMEDRDLOCK" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" pthread_rwlock_timedrdlock +.SH NAME +pthread_rwlock_timedrdlock \- lock a read-write lock for reading +.SH SYNOPSIS +.LP +\fB#include <pthread.h> +.br +#include <time.h> +.br +.sp +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict\fP \fIrwlock\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIpthread_rwlock_timedrdlock\fP() function shall apply a read +lock to the read-write lock referenced by \fIrwlock\fP as +in the \fIpthread_rwlock_rdlock\fP() function. However, if the lock +cannot +be acquired without waiting for other threads to unlock the lock, +this wait shall be terminated when the specified timeout expires. +The timeout shall expire when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which timeouts +are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fP), or if the absolute time specified by +\fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock. If the Timers option is not supported, the +timeout shall be based on the system clock as returned by the +\fItime\fP() function. The resolution of the timeout shall be the +resolution of the clock on +which it is based. The \fBtimespec\fP data type is defined in the +\fI<time.h>\fP +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +\fIabs_timeout\fP parameter need not be checked if the lock can be +immediately acquired. +.LP +If a signal that causes a signal handler to be executed is delivered +to a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedrdlock\fP(), upon return from the signal handler +the thread shall resume waiting for the lock as if it was +not interrupted. +.LP +The calling thread may deadlock if at the time the call is made it +holds a write lock on \fIrwlock\fP. The results are +undefined if this function is called with an uninitialized read-write +lock. +.SH RETURN VALUE +.LP +The \fIpthread_rwlock_timedrdlock\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_timedrdlock\fP() function shall fail if: +.TP 7 +.B ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.sp +.LP +The \fIpthread_rwlock_timedrdlock\fP() function may fail if: +.TP 7 +.B EAGAIN +The read lock could not be acquired because the maximum number of +read locks for lock would be exceeded. +.TP 7 +.B EDEADLK +The calling thread already holds a write lock on \fIrwlock\fP. +.TP 7 +.B EINVAL +The value specified by \fIrwlock\fP does not refer to an initialized +read-write lock object, or the \fIabs_timeout\fP +nanosecond value is less than zero or greater than or equal to 1000 +million. +.sp +.LP +This function 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 this function may be subject to priority inversion, +as discussed in the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 3.285, Priority Inversion. +.LP +The \fIpthread_rwlock_timedrdlock\fP() function is part of the Threads +and Timeouts options and need not be provided on all +implementations. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpthread_rwlock_destroy\fP() , \fIpthread_rwlock_rdlock\fP() , \fIpthread_rwlock_timedwrlock\fP() +, \fIpthread_rwlock_tryrdlock\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, +\fI<time.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 . |