pthread_rwlock_wrlock(3) - NetBSD Manual Pages

PTHREAD_RWLOCK(3)       NetBSD Library Functions Manual      PTHREAD_RWLOCK(3)


NAME

     pthread_rwlock, pthread_rwlock_init, pthread_rwlock_destroy,
     pthread_rwlock_rdlock, pthread_rwlock_timedrdlock,
     pthread_rwlock_tryrdlock, pthread_rwlock_wrlock,
     pthread_rwlock_timedwrlock, pthread_rwlock_trywrlock,
     pthread_rwlock_unlock -- read/write lock interface


LIBRARY

     POSIX Threads Library (libpthread, -lpthread)


SYNOPSIS

     #include <pthread.h>

     int
     pthread_rwlock_init(pthread_rwlock_t * restrict lock,
         const pthread_rwlockattr_t * restrict attr);

     pthread_rwlock_t lock = PTHREAD_RWLOCK_INITIALIZER;

     int
     pthread_rwlock_destroy(pthread_rwlock_t *lock);

     int
     pthread_rwlock_rdlock(pthread_rwlock_t *lock);

     int
     pthread_rwlock_timedrdlock(pthread_rwlock_t * restrict lock,
         const struct timespec * restrict abstime);

     int
     pthread_rwlock_tryrdlock(pthread_rwlock_t *lock);

     int
     pthread_rwlock_wrlock(pthread_rwlock_t *lock);

     int
     pthread_rwlock_timedwrlock(pthread_rwlock_t * restrict lock,
         const struct timespec * restrict abstime);

     int
     pthread_rwlock_trywrlock(pthread_rwlock_t *lock);

     int
     pthread_rwlock_unlock(pthread_rwlock_t *lock);


DESCRIPTION

     The pthread_rwlock_init() function is used to initialize a read/write
     lock, with attributes specified by attr.  If attr is NULL, the default
     read/write lock attributes are used.

     The results of calling pthread_rwlock_init() with an already initialized
     lock are undefined.

     The macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize a
     read/write lock when the allocation can be done statically, no error
     checking is required, and the default attributes are appropriate.  The
     behavior is similar to calling pthread_rwlock_init() with attr specified
     as NULL.

     The pthread_rwlock_destroy() function is used to destroy a read/write
     lock previously created with pthread_rwlock_init().

     The pthread_rwlock_rdlock() function acquires a read lock on lock pro-
     vided that lock is not presently held for writing and no writer threads
     are presently blocked on the lock.  If the read lock cannot be immedi-
     ately acquired, the calling thread blocks until it can acquire the lock.

     The pthread_rwlock_timedrdlock() performs the same action, but will not
     wait beyond abstime to obtain the lock before returning.

     The pthread_rwlock_tryrdlock() function performs the same action as
     pthread_rwlock_rdlock(), but does not block if the lock cannot be immedi-
     ately obtained (i.e., the lock is held for writing or there are waiting
     writers).

     A thread may hold multiple concurrent read locks.  If so,
     pthread_rwlock_unlock() must be called once for each lock obtained.

     The results of acquiring a read lock while the calling thread holds a
     write lock are undefined.

     The pthread_rwlock_wrlock() function blocks until a write lock can be
     acquired against lock.

     The pthread_rwlock_timedwrlock() performs the same action, but will not
     wait beyond abstime to obtain the lock before returning.

     The pthread_rwlock_trywrlock() function performs the same action as
     pthread_rwlock_wrlock(), but does not block if the lock cannot be immedi-
     ately obtained.

     The results are undefined if the calling thread already holds the lock at
     the time the call is made.

     The pthread_rwlock_unlock() function is used to release the read/write
     lock previously obtained by pthread_rwlock_rdlock(),
     pthread_rwlock_wrlock(), pthread_rwlock_tryrdlock(), or
     pthread_rwlock_trywrlock().


RETURN VALUES

     If successful, the pthread_rwlock_init() function will return zero.  Oth-
     erwise an error number will be returned to indicate the error.

     If successful, the pthread_rwlock_destroy(), pthread_rwlock_rdlock(),
     pthread_rwlock_timedrdlock(), pthread_rwlock_tryrdlock(),
     pthread_rwlock_wrlock(), pthread_rwlock_timedwrlock(),
     pthread_rwlock_trywrlock(), and pthread_rwlock_unlock() will return zero.
     Otherwise an error number will be returned to indicate the error.

     The results are undefined if lock is not held by the calling thread.


ERRORS

     The pthread_rwlock_init() function may fail if:

     [EAGAIN]           The system lacks the resources to initialize another
                        read-write lock.

     [EBUSY]            The system has detected an attempt to re-initialize
                        the object referenced by lock, a previously initial-
                        ized but not yet destroyed read/write lock.

     [EINVAL]           The value specified by attr is invalid.

     [ENOMEM]           Insufficient memory exists to initialize the read-
                        write lock.

     The pthread_rwlock_destroy() function may fail if:

     [EBUSY]            The system has detected an attempt to destroy the
                        object referenced by lock while it is locked.

     [EINVAL]           The value specified by lock is invalid.

     The pthread_rwlock_tryrdlock() function shall fail if:

     [EBUSY]            The lock could not be acquired because a writer holds
                        the lock or was blocked on it.

     The pthread_rwlock_timedrdlock() function shall fail if:

     [ETIMEDOUT]        The time specified by abstime was reached before the
                        lock could be obtained.

     The pthread_rwlock_rdlock(), pthread_rwlock_timedrdlock(), and
     pthread_rwlock_tryrdlock() functions may fail if:

     [EAGAIN]           The lock could not be acquired because the maximum
                        number of read locks against lock has been exceeded.

     [EDEADLK]          The current thread already owns lock for writing.

     [EINVAL]           The value specified by lock is invalid.

     The pthread_rwlock_trywrlock() function shall fail if:

     [EBUSY]            The calling thread is not able to acquire the lock
                        without blocking.

     The pthread_rwlock_timedrdlock() function shall fail if:

     [ETIMEDOUT]        The time specified by abstime was reached before the
                        lock could be obtained.

     The pthread_rwlock_wrlock(), pthread_rwlock_timedwrlock(), and
     pthread_rwlock_trywrlock() functions may fail if:

     [EDEADLK]          The calling thread already owns the read/write lock
                        (for reading or writing).

     [EINVAL]           The value specified by lock is invalid.

     The pthread_rwlock_unlock() function may fail if:

     [EINVAL]           The value specified by lock is invalid.

     [EPERM]            The current thread does not own the read/write lock.


SEE ALSO

     pthread(3), pthread_barrier(3), pthread_cond(3), pthread_mutex(3),
     pthread_rwlockattr(3), pthread_spin(3)


STANDARDS

     These functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').


BUGS

     The PTHREAD_PROCESS_SHARED attribute is not supported.

NetBSD 9.1                       July 8, 2010                       NetBSD 9.1