Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_mutex_getname_np

> Obtains the object name from a mutex object.

### Syntax

> pthread_mutex_getname_np(
> mutex ,
> name ,
> len );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | read
> name | char | write
> len | opaque size_t | read

C Binding #include <pthread.h>

int
pthread_mutex_getname_np (
pthread_mutex_t *mutex,
char *name,
size_t len);

### Arguments

> #### mutex

> Address of the mutex object whose object name is to be obtained.

> #### name

> Location to store the obtained object name.

> #### len

> Length in bytes of buffer at the location specified by name.

### Description

> This routine copies the object name from the mutex object specified by the mutex argument to the buffer at the location specified by the name argument. Before calling this routine, your program must allocate the buffer indicated by name.

> The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

> If the specified condition variable object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by mutex is not a valid mutex.

#### Associated Routines

> `pthread_mutex_setname_np()`

## pthread_mutex_init

> Initializes a mutex.

### Syntax

> pthread_mutex_init(
> mutex ,
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | write
> attr | opaque pthread_mutexattr_t | read

C Binding #include <pthread.h>

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

### Arguments

> #### mutex

> Mutex to be initialized.

> #### attr

> 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_mutexattr_settype()` routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck).

> See Chapter 2 for more information about mutex usage.

> 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()` . 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:

Return | Description
--- | ---
0 | Successful completion.
[EAGAIN] | The system lacks the necessary resources to initialize the mutex.
[EBUSY] | The implementation has detected an attempt to reinitialize the mutex (a previously initialized, but not yet destroyed mutex).
[EINVAL] | The value specified by mutex is not a valid mutex.
[ENOMEM] | Insufficient memory exists to initialize the mutex.
[EPERM] | The caller does not have privileges to perform this operation.

#### Associated Routines

> `pthread_mutexattr_init()`
> `pthread_mutexattr_gettype()`
> `pthread_mutexattr_settype()`
> `pthread_mutex_lock()`
> `pthread_mutex_trylock()`
> `pthread_mutex_unlock()`

## pthread_mutex_lock

> Locks an unlocked mutex.

### Syntax

> pthread_mutex_lock(
> mutex );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | read

C Binding #include <pthread.h>

int
pthread_mutex_lock (
pthread_mutex_t *mutex);

### Arguments

> #### mutex

> Mutex to be locked.

### Description

> This routine locks a mutex with behavior that depends upon the type of mutex, as follows:
> - If a normal or default mutex is specified, a deadlock can result if the current owner of the mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.)
> - If a recursive mutex is specified, the current owner of the mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread.
> - If an errorcheck mutex is specified and the current owner tries to lock the mutex a second time, this routine reports the [EDEADLK] error. If the mutex is locked by another thread, the calling thread waits for the mutex to become available.

> Use the `pthread_mutexattr_settype()` routine to set the type of the mutex to normal, default, recursive, or errorcheck. For more information about mutexes, see Chapter 2.

> The thread that has locked a mutex becomes its current owner and remains its owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the calling thread as the mutex's current owner.

> A recursive or errorcheck mutex records the identity of the thread that locks it, allowing debuggers to display this information. In most cases, normal and default mutexes do not record the owning thread's identity.

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

Return | Description
--- | ---
0 | Successful completion.
[EDEADLK] | A deadlock condition is detected.
[EINVAL] | The value specified by mutex is not a valid mutex.

#### Associated Routines

> `pthread_mutexattr_settype()`
> `pthread_mutex_destroy()`
> `pthread_mutex_init()`
> `pthread_mutex_trylock()`
> `pthread_mutex_unlock()`

## pthread_mutex_setname_np

> Changes the object name in a mutex object.

### Syntax

> pthread_mutex_setname_np(
> mutex ,
> name ,
> mbz );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | write
> name | char | read
> mbz | void | read

C Binding #include <pthread.h>

int
pthread_mutex_setname_np (
pthread_mutex_t *mutex,
const char *name,
void *mbz);

### Arguments

> #### mutex

> Address of the mutex object whose object name is to be changed.

> #### name

> Object name value to copy into the mutex object.

> #### mbz

> Reserved for future use. The value must be zero (0).

### Description

> This routine changes the object name in the mutex object specified by the mutex argument to the value specified by the name argument. To set a new mutex object's object name, call this routine immediately after initializing the mutex object.

> The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by mutex is not a valid mutex, or the length in characters of name exceeds 31.
[ENOMEM] | Insufficient memory to create a copy of the object name string.

#### Associated Routines

> `pthread_mutex_getname_np()`

## pthread_mutex_trylock

> Attempts to lock the specified mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available.

### Syntax

> pthread_mutex_trylock(
> mutex );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | read

C Binding #include <pthread.h>

int
pthread_mutex_trylock (
pthread_mutex_t *mutex);

### Arguments

> #### mutex

> Mutex to be locked.

### Description

> This routine attempts to lock the mutex specified in the mutex argument. When a thread calls this routine, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, this routine returns zero (0) and the calling thread becomes the mutex's current owner. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available.

> The behavior of this routine is as follows:

> - For a normal, default, or errorcheck mutex: if the mutex is locked by any thread (including the calling thread) when this routine is called, this routine returns [EBUSY] and the calling thread does not wait to acquire the lock.
> - For a normal or errorcheck mutex: if the mutex is not owned, this routine returns zero (0) and the mutex becomes locked by the calling thread.
> - For a recursive mutex: if the mutex is owned by the current thread, this routine returns zero (0) and the mutex lock count is incremented. (To unlock a recursive mutex, each call to `pthread_mutex_trylock()` must be matched by a call to `pthread_mutex_unlock()` .)

> Use the `pthread_mutexattr_settype()` routine to set the mutex type attribute (normal, default, recursive, or errorcheck). For information about mutex types and their usage, see Chapter 2.

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

Return | Description
--- | ---
0 | Successful completion.
[EBUSY] | The mutex is already locked; therefore, it was not acquired.
[EINVAL] | The value specified by mutex is not a valid mutex.

#### Associated Routines

> `pthread_mutexattr_settype()`
> `pthread_mutex_destroy()`
> `pthread_mutex_init()`
> `pthread_mutex_lock()`
> `pthread_mutex_unlock()`

## pthread_mutex_unlock

> Unlocks the specified mutex.

### Syntax

> pthread_mutex_unlock(
> mutex );

> Argument | Data Type | Access
> --- | --- | ---
> mutex | opaque pthread_mutex_t | read

C Binding #include <pthread.h>

int
pthread_mutex_unlock (
pthread_mutex_t *mutex);

### Arguments

> #### mutex

> Mutex to be unlocked.

### Description

> This routine unlocks the mutex specified by the mutex argument.

> This routine behaves as follows, based on the type of the specified mutex:

> - For a normal, default, or errorcheck mutex: if the mutex is owned by the calling thread, it is unlocked with no current owner. Further, for a normal or default mutex: if the mutex is not locked or is locked by another thread, this routine can also return [EPERM], but this is not guaranteed. For an errorcheck mutex: if the mutex is not locked or is locked by another thread, this routine returns [EPERM].
> - For a recursive mutex: if the mutex is owned by the calling thread, the lock count is decremented. The mutex remains locked and owned until the lock count reaches zero (0). When the lock count reaches zero, the mutex becomes unlocked with no current owner.

> If one or more threads are waiting to lock the specified mutex, and the mutex becomes unlocked, this routine causes one thread to unblock and to try to acquire the mutex. The scheduling policy is used to determine which thread to unblock. For the `SCHED_FIFO` and `SCHED_RR` policies, a blocked thread is chosen in priority order, using first-in/first-out within priorities. Note that the mutex might not be acquired by the awakened thread, if any other running thread attempts to lock the mutex first.

> On Tru64 UNIX, if a signal is delivered to a thread waiting for a mutex, upon return from the signal handler, the thread resumes waiting for the mutex as if it was not interrupted.

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified for mutex is not a valid mutex.
[EPERM] | The calling thread does not own the mutex.

#### Associated Routines

> `pthread_mutexattr_settype()`
> `pthread_mutex_destroy()`
> `pthread_mutex_init()`
> `pthread_mutex_lock()`
> `pthread_mutex_trylock()`

## pthread_once

> Calls a routine that is executed by a single thread, once.

### Syntax

> pthread_once(
> once _control,
> routine );

> Argument | Data Type | Access
> --- | --- | ---
> once_control | opaque pthread_once_t | modify
> routine | procedure | read

C Binding #include <pthread.h>

int
pthread_once (
pthread_once_t *once_control,
void (*routine) (void));

### Arguments

> #### once_control

> Address of a record that controls the one-time execution code. Each one-time execution routine must have its own unique `pthread_once_t` record.

> #### routine

> Address of a procedure to be executed once. This routine is called only once, regardless of the number of times it and its associated once_control block are passed to `pthread_once()` .

### Description

> The first call to this routine by any thread in a process with a given once_control will call the specified routine with no arguments. Subsequent calls to `pthread_once()` with the same once_control will not call the routine. On return from `pthread_once()` , it is guaranteed that the routine has completed.

> For example, a mutex or a per-thread context key must be created exactly once. Calling `pthread_once()` ensures that the initialization is serialized across multiple threads. Other threads that reach the same point in the code would be delayed until the first thread is finished.

> Note If you specify a routine that directly or indirectly results in a recursive call to `pthread_once()` and that specifies the same routine argument, the recursive call can result in a deadlock.

> To initialize the once_control record, your program can zero out the entire structure, or you can use the `PTHREAD_ONCE_INIT` macro, which is defined in the `pthread.h` header file, to statically initialize that structure. If using `PTHREAD_ONCE_INIT` , declare the once_control record as follows:

>     pthread_once_t  once_control = PTHREAD_ONCE_INIT;

> Note that it is often easier to simply lock a statically initialized mutex, check a control flag, and perform necessary initialization (in-line) rather than using `pthread_once()` . For example, you can code an initialization routine that begins with the following basic logic:

>       init()
>       {
>        static pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;
>        static int                flag = FALSE;

>        pthread_mutex_lock(&mutex);
>        if(!flag)
>          {
>           /* initialization code goes here */
>           flag = TRUE;
>          }
>        pthread_mutex_unlock(&mutex);
>       }

Return Values If an error occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:

Return | Description
--- | ---
0 | Successful completion
[EINVAL] | Invalid argument

## pthread_rwlockattr_destroy

> Destroys a previously initialized read-write lock attributes object.

### Syntax

> pthread_rwlockattr_destroy(
> attr );

> Argument | Data Type | Access
> --- | --- | ---
> attr | opaque pthread_rwlockattr_t | write

C Binding #include <pthread.h>

int
pthread_rwlockattr_destroy (
pthread_rwlockattr_t *attr);

### Arguments

> #### attr

> Address of the read-write lock attributes object to be destroyed.

### Description

> This routine destroys the read-write lock attributes object referenced by attr; that is, the object becomes uninitialized.

> After successful completion of this routine, the results of using attr in a call to any routine (other than `pthread_rwlockattr_init()` ) are unpredictable.

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

Return | Description
--- | ---
0 | Successful completion.
[EINVAL] | The value specified by attr is not a valid attributes block.

#### Associated Routines

> `pthread_rwlockattr_init()`
> `pthread_rwlock_init()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_022.HTML