Return Values

pthread_kill() returns zero after completing successfully. Any other return value indicates that an error occurred. When either of the following conditions occurs, pthread_kill() fails and returns the corresponding value.

EINVAL

sig is not a valid signal number.

ESRCH

tid cannot be found in the current process.

Access the Signal Mask of the Calling Thread

pthread_sigmask(3THR)

Use pthread_sigmask(3THR) to change or examine the signal mask of the calling thread.

Prototype:
int	pthread_sigmask(int how, const sigset_t *new, sigset_t *old);

#include <pthread.h>
#include <signal.h>
int ret;
sigset_t old, new;

ret = pthread_sigmask(SIG_SETMASK, &new, &old); /* set new mask */
ret = pthread_sigmask(SIG_BLOCK, &new, &old); /* blocking mask */
ret = pthread_sigmask(SIG_UNBLOCK, &new, &old); /* unblocking */

how determines how the signal set is changed. It can have one of the following values:

• SIG_BLOCK--Add new to the current signal mask, where new indicates the set of signals to block.

• SIG_UNBLOCK--Delete new from the current signal mask, where new indicates the set of signals to unblock.

• SIG_SETMASK--Replace the current signal mask with new, where new indicates the new signal mask.

When the value of new is NULL, the value of how is not significant and the signal mask of the thread is unchanged. So, to inquire about currently blocked signals, assign a NULL value to the new argument.

The old variable points to the space where the previous signal mask is stored, unless it is NULL.

Return Values

pthread_sigmask() returns zero when it completes successfully. Any other return value indicates that an error occurred. When the following condition occurs, pthread_sigmask() fails and returns the corresponding value.

EINVAL

The value of how is not defined.

Forking Safely

pthread_atfork(3THR)

See the discussion about pthread_atfork(3THR) in The Solution--pthread_atfork(3THR).

Prototype:

int pthread_atfork(void (*prepare) (void), void (*parent) (void),
    void (*child) (void) );

Terminate a Thread

pthread_exit(3THR)

Use pthread_exit(3THR) to terminate a thread.

Prototype:
void	 pthread_exit(void *status);

#include <pthread.h>

void *status;

pthread_exit(status); /* exit with status */

The pthread_exit() function terminates the calling thread. All thread-specific data bindings are released. If the calling thread is not detached, then the thread's ID and the exit status specified by status are retained until the thread is waited for via pthread_join(). Otherwise, status is ignored and the thread's ID can be reclaimed immediately. For information on thread detachment, see Set Detach State.

Return Values

The calling thread terminates with its exit status set to the contents of status.

Finishing Up

A thread can terminate its execution in the following ways:

• By returning from its first (outermost) procedure, the threads start routine; see pthread_create(3THR)

• By calling pthread_exit(), supplying an exit status

• By termination with POSIX cancel functions; see pthread_cancel()

The default behavior of a thread is to linger until some other thread has acknowledged its demise by "joining" with it. This is the same as the default pthread_create() attribute being nondetached; see pthread_detach(3THR). The result of the join is that the joining thread picks up the exit status of the dying thread and the dying thread vanishes.

An important special case arises when the initial thread -- the one calling main(),-- returns from calling main() or calls exit(3C). This action causes the entire process to be terminated, along with all its threads. So take care to ensure that the initial thread does not return from main() prematurely.

Note that when the main thread merely calls pthread_exit(3THR), it terminates only itself--the other threads in the process, as well as the process, continue to exist. (The process terminates when all threads terminate.)

Cancellation

Cancellation allows a thread to terminate the execution of any other thread, or all threads, in the process. Cancellation is an option when all further operations of a related set of threads are undesirable or unnecessary.

One example of thread cancellation is an asynchronously generated cancel condition, such as, when a user requesting to close or exit some running application. Another example is the completion of a task undertaken by a number of threads. One of the threads might ultimately complete the task while the others continue to operate. Since they are serving no purpose at that point, they all should be cancelled.

There are dangers in performing cancellations. Most deal with properly restoring invariants and freeing shared resources. A thread that is cancelled without care might leave a mutex in a locked state, leading to a deadlock. Or it might leave a region of memory allocated with no way to identify it and therefore no way to free it.

The pthreads library specifies a cancellation interface that permits or forbids cancellation programmatically. The library defines the set of points at which cancellation can occur (cancellation points). It also allows the scope of cancellation handlers, which provide clean up services, to be defined so that they are sure to operate when and where intended.

Placement of cancellation points and the effects of cancellation handlers must be based on an understanding of the application. A mutex is explicitly not a cancellation point and should be held only the minimal essential time.

Limit regions of asynchronous cancellation to sequences with no external dependencies that could result in dangling resources or unresolved state conditions. Take care to restore cancellation state when returning from some alternate, nested cancellation state. The interface provides features to facilitate restoration: pthread_setcancelstate(3THR) preserves the current cancel state in a referenced variable; pthread_setcanceltype(3THR) preserves the current cancel type in the same way.

Cancellations can occur under three different circumstances:

• Asynchronously

• At various points in the execution sequence as defined by the standard

• At discrete points specified by the application

By default, cancellation can occur only at well-defined points as defined by the POSIX standard.

In all cases, take care that resources and state are restored to a condition consistent with the point of origin.