Tru64 UNIX
Guide to the POSIX Threads Library


Previous Contents Index


pthread_kill

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

C Binding #include <pthread.h>
include <signal.h>

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.

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 of sig is invalid or an unsupported signal value.
[ESRCH] The value of thread does not specify an existing thread.

pthread_lock_global_np

Locks the Threads Library global mutex.

Syntax

pthread_lock_global_np( );

C Binding #include <pthread.h>

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.

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.

Associated Routines

pthread_unlock_global_np()

pthread_mutexattr_destroy

Destroys the specified mutex attributes object.

Syntax

pthread_mutexattr_destroy(
attr );

Argument Data Type Access
attr opaque pthread_mutexattr_t write

C Binding #include <pthread.h>

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.

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 object.

Associated Routines

pthread_mutexattr_init()

pthread_mutexattr_getpshared

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

C Binding #include <pthread.h>

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.

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 object.

Associated Routines

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

pthread_mutexattr_gettype

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 #include <pthread.h>

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.
Return Values On successful completion, this routine returns the mutex type in the location specified by the type argument.

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()

pthread_mutexattr_init

Initializes a mutex attributes object.

Syntax

pthread_mutexattr_init(
attr );

Argument Data Type Access
attr opaque pthread_mutexattr_t write

C Binding #include <pthread.h>

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

Associated Routines

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

pthread_mutexattr_setpshared

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

C Binding #include <pthread.h>

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.

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 mutex attributes object, or the new value specified for the attribute is outside the range of legal values for that attribute.

Associated Routines

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

pthread_mutexattr_settype

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 #include <pthread.h>

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 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 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()

pthread_mutex_destroy

Destroys a mutex.

Syntax

pthread_mutex_destroy(
mutex );

Argument Data Type Access
mutex opaque pthread_mutex_t write

C Binding #include <pthread.h>

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.

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] An attempt was made to destroy the object referenced by mutex while it is locked.
[EINVAL] The value specified by mutex is not a valid mutex.

Associated Routines

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


Previous Next Contents Index