Document revision date: 19 July 1999

Destroys the specified mutex attributes object.

Syntax

pthread_mutexattr_destroy(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

C Binding

Arguments

attr

Mutex attributes object to be destroyed.

Description

This routine destroys a mutex attributes object---that is, the object becomes uninitialized. Call this routine when your program no longer needs the specified mutex attributes object.

After this routine is called, DECthreads may reclaim the storage used by the mutex attributes object. Mutexes that were created using this attributes object are not affected by the destruction of the mutex attributes object.

The results of calling this routine are unpredictable, if the attributes object specified in the attr argument does not exist.

Return Values

Associated Routines

• pthread_mutexattr_init()

Obtains the value of the process-shared attribute of the specified mutex attributes object.

This routine is for DIGITAL UNIX systems only.

Syntax

pthread_mutexattr_getpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	read
pshared	int	write

C Binding

Arguments

attr

Address of the mutex attributes object whose process-shared attribute is obtained.

pshared

Value received from process-shared attribute of the mutex attributes object specified in attr.

Description

This routine obtains the value of the process-shared attribute of the mutex attributes object specified by the attr argument and stores it in the location specified by the pshared argument. This attributes object must already be initialized at the time this routine is called.

Setting the process-shared attribute to PTHREAD_PROCESS_PRIVATE permits a mutex to be operated upon by threads created within the same process as the thread that initialized the mutex. If threads of differing processes attempt to operate on such a mutex, the behavior is undefined.

The default value of the process-shared attribute of a mutex attributes object is PTHREAD_PROCESS_PRIVATE.

Setting the process-shared attribute to PTHREAD_PROCESS_SHARED permits a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes.

Return Values

Associated Routines

• pthread_mutex_init()
• pthread_mutexattr_destroy()
• pthread_mutexattr_init()
• pthread_mutexattr_setpshared()

Obtains the mutex type attribute in the specified mutex attribute object.

Syntax

pthread_mutexattr_gettype(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	read
type	integer	write

C Binding

Arguments

attr

Mutex attributes object whose mutex type attribute is obtained.

type

Receives the value of the mutex type attribute. The type argument specifies the type of mutex that can be created. Valid values are:

• PTHREAD_MUTEX_NORMAL
• PTHREAD_MUTEX_DEFAULT (default)
• PTHREAD_MUTEX_RECURSIVE
• PTHREAD_MUTEX_ERRORCHECK

Description

This routine obtains the value of the mutex type attribute in the mutex attributes object specified by the attr argument and stores it in the location specified by the type argument. See the pthread_mutexattr_settype() description for information about mutex types.

Return Values

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_settype()
• pthread_mutex_init()

Obtains the mutex type attribute in the specified mutex attribute object.

Syntax

pthread_mutexattr_gettype_np(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	read
type	integer	write

C Binding

Arguments

attr

Mutex attributes object whose mutex type attribute is obtained.

type

Receives the value of the mutex type attribute. The type argument specifies the type of mutex that can be created. Valid values are:

• PTHREAD_MUTEX_NORMAL
• PTHREAD_MUTEX_DEFAULT (default)
• PTHREAD_MUTEX_RECURSIVE
• PTHREAD_MUTEX_ERRORCHECK

Description

This routine obtains the value of the mutex type attribute in the mutex attributes object specified by the attr argument and stores it in the location specified by the type argument. See the pthread_mutexattr_settype() description for information about mutex types.

Note This routine has been superseded by the pthread_mutexattr_gettype() routine, as specified by the Single UNIX Specification, Version 2.

Return Values

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_settype_np()
• pthread_mutex_init()

Initializes a mutex attributes object.

Syntax

pthread_mutexattr_init(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

C Binding

Arguments

attr

Address of the mutex attributes object to be initialized.

Description

This routine initializes the mutex attributes object specified by the attr argument with a set of default values. A mutex attributes object is used to specify the attributes of one or more mutexes when they are created. The attributes object created by this routine is used only in calls to the pthread_mutex_init() routine.

When a mutex attributes object is used to create a mutex, the values of the individual attributes determine the characteristics of the new mutex. Thus, attributes objects act as additional arguments to mutex creation. Changing individual attributes in an attributes object does not affect any mutexes that were previously created using that attributes object.

You can use the same mutex attributes object in successive calls to pthread_mutex_init(), from any thread. If multiple threads can change attributes in a shared mutex attributes object, your program must use a mutex to protect the integrity of the attributes object's contents.

Results are undefined if this routine is called and the attr argument specifies a mutex attributes object that is already initialized.

Return Values

Associated Routines

• pthread_mutexattr_destroy()
• pthread_mutexattr_gettype()
• pthread_mutexattr_settype()
• pthread_mutex_init()

Changes the value of the process-shared attribute of the specified mutex attributes object.

This routine is for DIGITAL UNIX systems only.

Syntax

pthread_mutexattr_setpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write
pshared	int	read

C Binding

Arguments

attr

Address of the mutex attributes object whose process-shared attribute is to be modified.

pshared

Value to set in the process-shared attribute of the mutex attributes object specified by attr.

Description

This routine uses the value specified in the pshared argument to set the value of the process-shared attribute of an initialized mutex attributes object specified in the attr argument.

Setting the process-shared attribute to PTHREAD_PROCESS_PRIVATE permits a mutex to be operated upon by threads created within the same process as the thread that initialized the mutex. If threads of differing processes attempt to operate on such a mutex, the behavior is undefined.

The default value of the process-shared attribute of a mutex attributes object is PTHREAD_PROCESS_PRIVATE.

Setting the process-shared attribute to PTHREAD_PROCESS_SHARED permits a mutex to be operated upon by any thread that has access to the memory where the mutex is allocated, even if the mutex is allocated in memory that is shared by multiple processes.

Return Values

Associated Routines

• pthread_mutex_init()
• pthread_mutexattr_destroy()
• pthread_mutexattr_init()
• pthread_mutexattr_getpshared()

Specifies the mutex type attribute that is used when a mutex is created.

Syntax

pthread_mutexattr_settype(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write
type	integer	read

C Binding

Arguments

attr

Mutex attributes object whose mutex type attribute is to be modified.

type

New value for the mutex type attribute. The type argument specifies the type of mutex that will be created. Valid values are:

• PTHREAD_MUTEX_NORMAL
• PTHREAD_MUTEX_DEFAULT (default)
• PTHREAD_MUTEX_RECURSIVE
• PTHREAD_MUTEX_ERRORCHECK

Description

This routine sets the mutex type attribute that is used to determine which type of mutex is created based on a subsequent call to pthread_mutex_init(). See Section 2.4.1 for information on the types of mutexes.

Return Values

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_gettype()
• pthread_mutex_init()

Specifies the mutex type attribute that is used when a mutex is created.

Syntax

pthread_mutexattr_settype_np(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write
type	integer	read

C Binding

Arguments

attr

Mutex attributes object whose mutex type attribute is to be modified.

type

New value for the mutex type attribute. The type argument specifies the type of mutex that will be created. Valid values are:

• PTHREAD_MUTEX_NORMAL
• PTHREAD_MUTEX_DEFAULT (default)
• PTHREAD_MUTEX_RECURSIVE
• PTHREAD_MUTEX_ERRORCHECK

Description

This routine sets the mutex type attribute that is used to determine which type of mutex is created based on a subsequent call to pthread_mutex_init(). See Section 2.4.1 for information on the types of mutexes.

Note This routine has been superseded by the pthread_mutexattr_settype() routine, as specified by the Single UNIX Specification, Version 2.

Return Values

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_gettype_np()
• pthread_mutex_init()

Destroys a mutex.

Syntax

pthread_mutex_destroy(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

C Binding

Arguments

mutex

The mutex to be destroyed.

Description

This routine destroys the specified mutex by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, DECthreads may reclaim internal storage used by the specified mutex.

It is safe to destroy an initialized mutex that is unlocked. However, it is illegal to destroy a locked mutex.

The results of this routine are unpredictable if the mutex object specified in the mutex argument does not currently exist, or is not initialized.

Return Values

Associated Routines

• pthread_mutex_init()
• pthread_mutex_lock()
• pthread_mutex_trylock()
• pthread_mutex_unlock()

	privacy and legal statement
6101PRO_021.HTML