HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/nan.3m
________________________________________________________________
___ ___
p
pthread_mutex_init(3T) pthread_mutex_init(3T)
(Pthread Library)
NAME
pthread_mutex_init(), pthread_mutex_destroy() - initialize or destroy a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_init(
pthread_mutex_t *mutex,
const pthread_mutexattr_t *attr
);
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
int pthread_mutex_destroy(
pthread_mutex_t *mutex
);
PARAMETERS
mutex Pointer to the mutex to be initializedor destroyed.
attr Pointer to the attributes object that defines the characteristics of the mutex to be initial-
ized. If the pointer is NULL, default attributes are used.
DESCRIPTION
The
pthread_mutex_init()
function initializes the mutex referenced by mutex with the attributes
attr. If the parameter attr is
NULL, the default mutex attributes are used. Refer to
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
pthread_once()
function provides a way to ensure that a
mutex is initializedonly once.
The macro
PTHREAD_MUTEX_INITIALIZER
can be used to initialize mutexes that are statically allo-
cated. These mutexes will be initialized with default attributes. The
pthread_mutex_init()
func-
tion does not need to be called for statically initializedmutexes.
If the process-shared attribute in the mutex attributes object referenced by attr is defined as
PTHREAD_PROCESS_SHARED
, 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
pthread_mutex_destroy()
function destroys the mutex referenced by mutex. This function
may set mutex to an invalid value. The destroyed mutex can be reinitialized using the function
pthread_mutex_init()
. 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,
pthread_mutex_init()
and pthread_mutex_destroy() return
zero. Otherwise, an error number is returned to indicate the error (the
errno variable is not set).
ERRORS
If any of the following occur, the
pthread_mutex_init()
function returns the corresponding error
number:
[EAGAIN] The necessary resources (other than memory) to initializemutex were not available.
[ENOMEM] There is insufficient memory availablein which to initializemutex.
[EPERM] The caller does not have the necessary permission to perform the mutex initialization.
For each of the following conditions, if the condition is detected, the
pthread_mutex_init() function
returns the corresponding error number:
[EINVAL] The value specified by mutex or attr is invalid.
[EBUSY] mutex is an already initializedmutex.
HP-UX Release 11i: December 2000 − 1 − Section 3−−689
___
___