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(3C)					   Standard C Library Functions 				    pthread_mutex_init(3C)

NAME

       pthread_mutex_init, pthread_mutex_destroy - initialize or destroy a mutex

SYNOPSIS

       cc -mt [ flag... ] file... -lpthread [ library... ]
       #include <pthread.h>

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

       int pthread_mutex_destroy(pthread_mutex_t *mutex);

       pthread_mutex_t mutex= PTHREAD_MUTEX_INITIALIZER;

DESCRIPTION

       The  pthread_mutex_init()  function  initializes  the  mutex  referenced  by mutex with attributes specified by attr. If attr is  NULL, the
       default mutex attributes are used; the effect is the same as passing the address of a default mutex attributes object. Upon successful ini-
       tialization, the state of the mutex becomes initialized and unlocked.

       Except for robust mutexes, attempting to initialize an already initialized mutex results in undefined behavior.

       The  pthread_mutex_destroy()  function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A
       destroyed mutex object can be re-initialized using pthread_mutex_init(); the results of otherwise referencing the object after it has  been
       destroyed are undefined.

       It is safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked mutex results in undefined behavior.

       In  cases  where  default  mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are
       statically allocated. The effect is equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as
       NULL, except that no error checks are performed.

RETURN VALUES

       If successful, the pthread_mutex_init() and pthread_mutex_destroy() functions return  0. Otherwise, an error number is returned to indicate
       the error.

ERRORS

       The pthread_mutex_init() function will fail if:

       EAGAIN	 The system lacked the necessary resources (other than memory) to initialize another mutex.

       EBUSY	 An attempt was detected to  re-initialize a robust mutex  previously  initialized  but  not  yet  destroyed.  See  pthread_mutex-
		 attr_setrobust(3C).

       EINVAL	 An  attempt  was  detected  to  re-initialize	a  robust  mutex  previously  initialized  with a different set of attributes. See
		 pthread_mutexattr_setrobust(3C).

       ENOMEM	 Insufficient memory exists to initialize the mutex.

       EPERM	 The caller does not have the privilege to perform the operation.

       The pthread_mutex_init() function may fail if:

       EBUSY	 An attempt was detected to re-initialize the object referenced by mutex, a mutex previously initialized but not yet destroyed.

       EINVAL	 The value specified by attr or mutex is invalid.

       The pthread_mutex_destroy() function may fail if:

       EBUSY	 An attempt was detected to destroy the object referenced by mutex while it is locked or referenced (for example, while being used
		 in a pthread_cond_wait(3C) or pthread_cond_timedwait(3C)) by another thread.

       EINVAL	 The value specified by mutex is invalid.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       pthread_cond_wait(3C),	pthread_mutex_lock(3C),  pthread_mutexattr_setprioceiling(3C),	pthread_mutexattr_setprotocol(3C),  pthread_mutex-
       attr_setpshared(3C), pthread_mutexattr_setrobust(3C), pthread_mutexattr_settype(3C), attributes(5), mutex(5), standards(5)

SunOS 5.11							    11 Nov 2008 					    pthread_mutex_init(3C)