Man Linux: Main Page and Category List

NAME

       pthread_rwlock_timedwrlock - lock a read-write lock for writing

SYNOPSIS

       #include <pthread.h>
       #include <time.h>

       int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict rwlock,
              const struct timespec *restrict abs_timeout);

DESCRIPTION

       The  pthread_rwlock_timedwrlock()  function shall apply a write lock to
       the   read-write   lock   referenced    by    rwlock    as    in    the
       pthread_rwlock_wrlock()  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  abs_timeout
       passes,  as measured by the clock on which timeouts are based (that is,
       when the value of that clock equals or exceeds abs_timeout), or if  the
       absolute  time  specified by abs_timeout has already been passed at the
       time of the call.

       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  time()
       function.  The resolution of the timeout shall be the resolution of the
       clock on which it is based. The timespec data type is  defined  in  the
       <time.h>  header. Under no circumstances shall the function fail with a
       timeout if the lock can be acquired immediately. The  validity  of  the
       abs_timeout   parameter  need  not  be  checked  if  the  lock  can  be
       immediately acquired.

       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
       pthread_rwlock_timedwrlock(), upon return from the signal  handler  the
       thread  shall resume waiting for the lock as if it was not interrupted.

       The calling thread may deadlock if at the time  the  call  is  made  it
       holds  the  read-write lock. The results are undefined if this function
       is called with an uninitialized read-write lock.

RETURN VALUE

       The pthread_rwlock_timedwrlock() function shall return zero if the lock
       for  writing  on  the  read-write  lock  object referenced by rwlock is
       acquired. Otherwise, an error number shall be returned to indicate  the
       error.

ERRORS

       The pthread_rwlock_timedwrlock() function shall fail if:

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

       The pthread_rwlock_timedwrlock() function may fail if:

       EDEADLK
              The calling thread already holds the rwlock.

       EINVAL The value specified by rwlock does not refer to  an  initialized
              read-write  lock  object, or the abs_timeout nanosecond value is
              less than zero or greater than or equal to 1000 million.

       This function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       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.

       The pthread_rwlock_timedwrlock() function is part of  the  Threads  and
       Timeouts options and need not be provided on all implementations.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_rwlock_destroy()        ,       pthread_rwlock_rdlock()       ,
       pthread_rwlock_timedrdlock()     ,     pthread_rwlock_tryrdlock()     ,
       pthread_rwlock_trywrlock()       ,       pthread_rwlock_unlock()      ,
       pthread_rwlock_wrlock()   ,   the   Base    Definitions    volume    of
       IEEE Std 1003.1-2001, <pthread.h>, <time.h>

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 .