pthread_mutex_init(3) [osf1 man page]

pthread_mutex_init(3)					     Library Functions Manual					     pthread_mutex_init(3)

NAME

       pthread_mutex_init - Initializes a mutex.

LIBRARY

       DECthreads POSIX 1003.1c Library (libpthread.so)

SYNOPSIS

       #include <pthread.h>

       int   pthread_mutex_init(
			     pthread_mutex_t   *mutex,
			     const pthread_mutexattr_t *attr);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS

       Mutex to be initialized.  Mutex attributes object that defines the characteristics of the mutex to be initialized.

DESCRIPTION

       This routine initializes a mutex with the attributes specified by the mutex attributes object specified in the attr argument.  A mutex is a
       synchronization object that allows multiple threads to serialize their access to shared data.

       The mutex is initialized and set to the unlocked state.	If attr is set to NULL, the default mutex attributes are used.	The pthread_mutex-
       attr_settype(3) routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck).

       Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex without calling this routine.  Statically initialized mutexes need
       not be destroyed using pthread_mutex_destroy(3).  Use this macro as follows:

       pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER

       Only normal mutexes can be statically initialized.

       A mutex is a resource of the process, not part of any particular thread.  A mutex is neither destroyed nor unlocked automatically when  any
       thread exits.  If a mutex is allocated on a stack, static initializers cannot be used on the mutex.

RETURN VALUES

       If  an  error  condition  occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the
       contents of mutex are undefined.  Possible return values are as follows: Successful completion.	The system lacks the  necessary  resources
       to  initialize  the  mutex.   The  implementation  has detected an attempt to reinitialize the mutex (a previously initialized, but not yet
       destroyed mutex).  The value specified by mutex is not a valid mutex.  Insufficient memory exists to initialize the mutex.  The caller does
       not have privileges to perform the operation.

ERRORS

       None

RELATED INFORMATION

       Functions: pthread_mutexattr_init(3), pthread_mutexattr_gettype(3), pthread_mutexattr_settype(3), pthread_mutex_lock(3), pthread_mutex_try-
       lock(3), pthread_mutex_unlock(3)

       Manuals: Guide to DECthreads and Programmer's Guide

       delim off

															     pthread_mutex_init(3)

pthread_mutex_init(3T)													    pthread_mutex_init(3T)

NAME

       pthread_mutex_init(), pthread_mutex_destroy() - initialize or destroy a mutex

SYNOPSIS

PARAMETERS

	      mutex	Pointer to the mutex to be initialized or destroyed.

	      attr	Pointer to the attributes object that defines the characteristics of the mutex to be initialized.  If the pointer is NULL,
			default attributes are used.

DESCRIPTION

       The function initializes the mutex referenced by mutex with the attributes attr.   If  the  parameter  attr  is	NULL,  the  default  mutex
       attributes are used.  See pthread_mutexattr_init(3T) for a list of default mutex attributes.  After successful initialization, the mutex is
       initialized, unlocked, and ready to be used in mutex operations.  A mutex should be initialized only once  or  the  resulting  behavior	is
       undefined.  The function provides a way to ensure that a mutex is initialized only once.

       The macro can be used to initialize mutexes that are statically allocated.  These mutexes will be initialized with default attributes.  The
       function does not need to be called for statically initialized mutexes.

       If the process-shared attribute in the mutex attributes object referenced by attr is defined as the mutex must be allocated such  that  the
       processes  sharing  the	mutex have access to it.  This may be done through the memory-mapping functions (see mmap(2)) or the shared memory
       functions (see shmget(2)).

       The function destroys the mutex referenced by mutex.  This function may set mutex to an invalid value.  The destroyed mutex can	be  reini-
       tialized using the function If the mutex is used after destruction in any mutex call, the resulting behavior is undefined.

       A mutex should be destroyed only when it is unlocked.  Destroying a mutex that is currently being used results in undefined behavior.

RETURN VALUE

       Upon successful completion, and return zero.  Otherwise, an error number is returned to indicate the error (the variable is not set).

ERRORS

       If any of the following occur, the function returns the corresponding error number:

	      The necessary resources (other than memory) to initialize
			     mutex were not available.

	      mutex	     is an already initialized mutex.  However, getting for reinitializing the mutex cannot be expected all the time since
			     the behavior of reinitializing the mutex is undefined.

	      mutex	     points to an illegal address.

	      The value specified by
			     mutex or attr is invalid.

	      There is insufficient memory available in which to initialize
			     mutex.

	      The caller does not have the necessary permission to perform the
			     mutex initialization.

       If any of the following occur, the function returns the corresponding error number:

	      mutex	     is currently locked or in use by another thread.

	      mutex	     is not a valid mutex.

WARNINGS

       The space for the mutex must be allocated before calling Undefined behavior will result if the process-shared attribute of attr is and  the
       space allocated for the mutex is not accessible to cooperating threads.

AUTHOR

       and were derived from the IEEE POSIX P1003.1c standard.

SEE ALSO

       pthread_mutex_lock(3T), pthread_mutex_trylock(3T), pthread_mutex_unlock(3T).

STANDARDS CONFORMANCE

								  Pthread Library					    pthread_mutex_init(3T)