Index for Section 3

Alphabetical listing for P

Bottom of page

pthread_rwlock_init(3)
NAME
  pthread_rwlock_init - Initializes a read-write lock object

SYNOPSIS
  #include <pthread.h>

  int pthread_rwlock_init(
	  pthread_rwlock_t *rwlock,
	  const pthread_rwlockattr_t *attr );

LIBRARY
  DECthreads POSIX 1003.1c Library (libpthread.so)

PARAMETERS
  rwlock
      Read-write lock object to be initialized.

  attr
      Read-write lock attributes object that defines the characteristics of
      the read-write lock to be initialized.

DESCRIPTION
  This routine initializes a read-write lock object with the attributes
  specified by the read-write lock attributes object specified in attr.	 A
  read-write lock is a synchronization object that serializes access to
  shared information that needs to be read frequently and written only
  occasionally.	 A thread can acquire a read-write lock for shared read
  access or for exclusive write access.

  Upon successful completion of this routine, the read-write lock is
  initialized and set to the unlocked state. If attr is set to NULL, the
  default read-write lock attributes are used; the effect is the same as
  passing the address of a default read-write lock attributes object. Once
  initialized, the lock can be used any number of times without being
  reinitialized.

  Results of calling this routine are undefined if attr specifies an already
  initialized read-write lock or if rwlock is used without first being
  initialized.

  If this routine returns unsuccessfully, rwlock is not initialized and the
  contents of rwlock are undefined.

  A read-write lock is a resource of the process, not part of any particular
  thread. A read-write lock is neither destroyed not unlocked automatically
  when any thread exits. Because read-write locks are shared, they may be
  allocated in heap or static memory, but not on a stack.

  In cases where default read-write lock attributes are appropriate, you may
  use the PTHREAD_RWLOCK_INITIALIZER macro to statically initialize the lock
  object without calling this routine. The effect is equivalent to dynamic
  initialization by a call to pthread_rwlock_init with attr specified as
  NULL, except that no error checks are performed.  Statically initialized
  read-write locks need not be destroyed using pthread_rwlock_destroy.

  Use the PTHREAD_RWLOCK_INITIALIZER macro as follows:

  pthread_rwlock_t  rwlock= PTHREAD_RWLOCK_INITIALIZER;

RETURN VALUES
  If an error condition occurs, this routine returns an integer value
  indicating the type of error. Possible return values are as follows:

  0   Successful completion.

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

  [EBUSY]
      The implementation has detected an attempt to reinitialize the read-
      write lock (a previously initialized, but not yet destroyed read-write
      lock object).

  [EINVAL]
      The value specified by attr is not a valid attributes block.

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

  [EPERM]
      The caller does not have privileges to perform this operation.

ERRORS
  None

SEE ALSO
  Functions: pthread_rwlock_destroy(3)

  Manuals: Guide to DECthreads and Programmer's Guide

Index for Section 3

Alphabetical listing for P

Top of page