Document revision date: 30 March 2001

Delivers a signal to a specified target thread.

This routine is for Tru64 UNIX systems only.

Syntax

pthread_kill(
thread ,
sig );

Argument	Data Type	Access
thread	opaque pthread_t	read
sig	integer	read

int
pthread_kill (
pthread_t thread,
int sig);

Arguments

thread

Thread to receive a signal request.

sig

A signal request.

Description

This routine sends a signal to the specified target thread thread. Any signal defined to stop, continue, or terminate will stop or terminate the process, even though it can be handled by the target thread. For example, SIGTERM terminates all threads in the process, even though it can be handled by the target thread.

Specifying a sig argument of 0 (zero) causes this routine to validate the thread argument but not to deliver any signal.

The name of the "kill" routine is sometimes misleading, because many signals do not terminate a thread.

The various signals are as follows:

	SIGHUP	SIGPIPE	SIGTTIN
	SIGINT	SIGALRM	SIGTTOU
	SIGQUIT	SIGTERM	SIGIO
	SIGTRAP	SIGUSR1	SIGXCPU
	SIGABRT	SIGSYS	SIGXFSZ
	SIGEMT	SIGURG	SIGVTALRM
	SIGFPE	SIGSTOP	SIGPROF
	SIGKILL	SIGTSTP	SIGINFO
	SIGBUS	SIGCONT	SIGUSR1
	SIGSEGV	SIGCHLD	SIGUSR2

If this routine does not execute successfully, no signal is sent.

Locks the Threads Library global mutex.

Syntax

pthread_lock_global_np( );

int
pthread_lock_global_np (void);

Arguments

None

Description

This routine locks the Threads Library global mutex. If the global mutex is currently held by another thread when a thread calls this routine, the calling thread waits for the global mutex to become available and then locks it.

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

Use the global mutex when calling a library package that is not designed to run in a multithreaded environment. Unless the documentation for a library function specifically states that it is thread-safe, assume that it is not compatible; in other words, assume it is nonreentrant.

The global mutex is one lock. Any code that calls any function that is not known to be reentrant should use the same lock. This prevents problems resulting from dependencies among threads that call library functions and those functions' calling other functions, and so on.

The global mutex is a recursive mutex. A thread that has locked the global mutex can relock it without deadlocking. The locking thread must call pthread_unlock_global_np() as many times as it called this routine, to allow another thread to lock the global mutex.

Associated Routines

pthread_unlock_global_np()

Destroys the specified mutex attributes object.

Syntax

pthread_mutexattr_destroy(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

int
pthread_mutexattr_destroy (
pthread_mutexattr_t *attr);

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, the Threads Library 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.

Associated Routines

pthread_mutexattr_init()

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

This routine is for Tru64 UNIX systems only.

Syntax

pthread_mutexattr_getpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	read
pshared	int	write

int
pthread_mutexattr_getpshared (
const pthread_mutexattr_t *attr,
int *pshared);

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.

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

int
pthread_mutexattr_gettype (
const pthread_mutexattr_t *attr,
int *type);

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.

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

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is not a valid mutex attributes object.

Associated Routines

pthread_mutexattr_init()
pthread_mutexattr_settype()
pthread_mutex_init()

Initializes a mutex attributes object.

Syntax

pthread_mutexattr_init(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

int
pthread_mutexattr_init (
pthread_mutexattr_t *attr);

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	Description
0	Successful completion.
[ENOMEM]	Insufficient memory to create the mutex attributes object.

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 Tru64 UNIX systems only.

Syntax

pthread_mutexattr_setpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write
pshared	int	read

int
pthread_mutexattr_setpshared (
pthread_mutexattr_t *attr,
int pshared);

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.

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

int
pthread_mutexattr_settype (
pthread_mutexattr_t *attr,
int type);

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	Description
0	Successful completion.
[EINVAL]	The value specified by attr or type is not a valid mutex attributes type.
[ESRCH]	The value specified by attr does not refer to an existing mutex attributes object.

Associated Routines

pthread_mutexattr_init()
pthread_mutexattr_gettype()
pthread_mutex_init()

Destroys a mutex.

Syntax

pthread_mutex_destroy(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
pthread_mutex_destroy (
pthread_mutex_t *mutex);

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, the Threads Library 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.

Associated Routines

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

	privacy and legal statement
6101PRO_021.HTML