'\" et

.TH PTHREAD_RWLOCK_TIMEDRDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

pthread_rwlock_timedrdlock

\(em lock a read-write lock for reading

.SH SYNOPSIS

.LP

.nf

#include <pthread.h>

#include <time.h>

.P

int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict \fIrwlock\fP,

    const struct timespec *restrict \fIabstime\fP);

.fi

.SH DESCRIPTION

The

\fIpthread_rwlock_timedrdlock\fR()

function shall apply a read lock to the read-write lock referenced by

.IR rwlock

as in the

\fIpthread_rwlock_rdlock\fR()

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

.IR abstime

passes, as measured by the clock on which timeouts are based (that is,

when the value of that clock equals or exceeds

.IR abstime ),

or if the absolute time specified by

.IR abstime

has already been passed at the time of the call.

.P

The timeout shall be based on the CLOCK_REALTIME clock.

The resolution of the timeout shall be the resolution of the

CLOCK_REALTIME clock. The

.BR timespec

data type is defined in the

.IR <time.h> 

header. Under no circumstances shall the function fail with a timeout

if the lock can be acquired immediately. The validity of the

.IR abstime

parameter need not be checked if the lock can be immediately acquired.

.P

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\fR(),

upon return from the signal handler the thread shall resume waiting for

the lock as if it was not interrupted.

.P

The calling thread may deadlock if at the time the call is made it

holds a write lock on

.IR rwlock .

The results are undefined if this function is called with an

uninitialized read-write lock.

.SH "RETURN VALUE"

The

\fIpthread_rwlock_timedrdlock\fR()

function shall return zero if the lock for reading on the read-write

lock object referenced by

.IR rwlock

is acquired. Otherwise, an error number shall be returned to indicate

the error.

.SH ERRORS

The

\fIpthread_rwlock_timedrdlock\fR()

function shall fail if:

.TP

.BR ETIMEDOUT

The lock could not be acquired before the specified timeout expired.

.P

The

\fIpthread_rwlock_timedrdlock\fR()

function may fail if:

.TP

.BR EAGAIN

The read lock could not be acquired because the maximum number of read

locks for lock would be exceeded.

.TP

.BR EDEADLK

A deadlock condition was detected or the calling thread already holds a

write lock on

.IR rwlock .

.TP

.BR EINVAL

The

.IR abstime

nanosecond value is less than zero or greater than or equal to 1\|000

million.

.P

This function shall not return an error code of

.BR [EINTR] .

.LP

.IR "The following sections are informative."

.SH EXAMPLES

None.

.SH "APPLICATION USAGE"

Applications using this function may be subject to priority inversion,

as discussed in the Base Definitions volume of POSIX.1\(hy2008,

.IR "Section 3.287" ", " "Priority Inversion".

.SH RATIONALE

If an implementation detects that the value specified by the

.IR rwlock

argument to

\fIpthread_rwlock_timedrdlock\fR()

does not refer to an initialized read-write lock object, it is

recommended that the function should fail and report an

.BR [EINVAL] 

error.

.SH "FUTURE DIRECTIONS"

None.

.SH "SEE ALSO"

.ad l

.IR "\fIpthread_rwlock_destroy\fR\^(\|)",

.IR "\fIpthread_rwlock_rdlock\fR\^(\|)",

.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)",

.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)",

.IR "\fIpthread_rwlock_unlock\fR\^(\|)"

.ad b

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "Section 3.287" ", " "Priority Inversion",

.IR "Section 4.11" ", " "Memory Synchronization",

.IR "\fB<pthread.h>\fP",

.IR "\fB<time.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .