Miscellaneous Thread Functions

Function: pthread_t pthread_self (void)

pthread_self returns the thread identifier for the calling thread.

Function: int pthread_equal (pthread_t thread1, pthread_t thread2)

pthread_equal determines if two thread identifiers refer to the same thread.

A non-zero value is returned if thread1 and thread2 refer to the same thread. Otherwise, 0 is returned.

Function: int pthread_detach (pthread_t th)

pthread_detach puts the thread th in the detached state. This guarantees that the memory resources consumed by th will be freed immediately when th terminates. However, this prevents other threads from synchronizing on the termination of th using pthread_join.

A thread can be created initially in the detached state, using the detachstate attribute to pthread_create. In contrast, pthread_detach applies to threads created in the joinable state, and which need to be put in the detached state later.

After pthread_detach completes, subsequent attempts to perform pthread_join on th will fail. If another thread is already joining the thread th at the time pthread_detach is called, pthread_detach does nothing and leaves th in the joinable state.

On success, 0 is returned. On error, one of the following codes is returned:

ESRCH

No thread could be found corresponding to that specified by th

EINVAL

The thread th is already in the detached state

Function: int pthread_atfork (void (*prepare)(void), void (*parent)(void), void (*child)(void))

pthread_atfork registers handler functions to be called just before and just after a new process is created with fork. The prepare handler will be called from the parent process, just before the new process is created. The parent handler will be called from the parent process, just before fork returns. The child handler will be called from the child process, just before fork returns.

pthread_atfork returns 0 on success and a non-zero error code on error.

One or more of the three handlers prepare, parent and child can be given as NULL, meaning that no handler needs to be called at the corresponding point.

pthread_atfork can be called several times to install several sets of handlers. At fork time, the prepare handlers are called in LIFO order (last added with pthread_atfork, first called before fork), while the parent and child handlers are called in FIFO order (first added, first called).

If there is insufficient memory available to register the handlers, pthread_atfork fails and returns ENOMEM. Otherwise it returns 0.

To understand the purpose of pthread_atfork, recall that fork duplicates the whole memory space, including mutexes in their current locking state, but only the calling thread: other threads are not running in the child process. Thus, if a mutex is locked by a thread other than the thread calling fork, that mutex will remain locked forever in the child process, possibly blocking the execution of the child process. To avoid this, install handlers with pthread_atfork as follows: the prepare handler locks the global mutexes (in locking order), and the parent and child handlers unlock them (in reverse order). Alternatively, prepare and parent can be set to NULL and child to a function that calls pthread_mutex_init on the global mutexes.

Function: void pthread_kill_other_threads_np (void)

pthread_kill_other_threads_np is a non-portable LinuxThreads extension. It causes all threads in the program to terminate immediately, except the calling thread which proceeds normally. It is intended to be called just before a thread calls one of the exec functions, e.g. execve.

Termination of the other threads is not performed through pthread_cancel and completely bypasses the cancellation mechanism. Hence, the current settings for cancellation state and cancellation type are ignored, and the cleanup handlers are not executed in the terminated threads.

According to POSIX 1003.1c, a successful exec* in one of the threads should automatically terminate all other threads in the program. This behavior is not yet implemented in LinuxThreads. Calling pthread_kill_other_threads_np before exec* achieves much of the same behavior, except that if exec* ultimately fails, then all other threads are already killed.

Function: int pthread_once (pthread_once_t *once_control, void (*init_routine) (void))

The purpose of pthread_once is to ensure that a piece of initialization code is executed at most once. The once_control argument points to a static or extern variable statically initialized to PTHREAD_ONCE_INIT.

The first time pthread_once is called with a given once_control argument, it calls init_routine with no argument and changes the value of the once_control variable to record that initialization has been performed. Subsequent calls to pthread_once with the same once_control argument do nothing.

pthread_once always returns 0.

Function: int pthread_setschedparam (pthread_t target_thread, int policy, const struct sched_param *param)

pthread_setschedparam sets the scheduling parameters for the thread target_thread as indicated by policy and param. policy can be either SCHED_OTHER (regular, non-realtime scheduling), SCHED_RR (realtime, round-robin) or SCHED_FIFO (realtime, first-in first-out). param specifies the scheduling priority for the two realtime policies. See sched_setpolicy for more information on scheduling policies.

The realtime scheduling policies SCHED_RR and SCHED_FIFO are available only to processes with superuser privileges.

On success, pthread_setschedparam returns 0. On error it returns one of the following codes:

EINVAL

policy is not one of SCHED_OTHER, SCHED_RR, SCHED_FIFO, or the priority value specified by param is not valid for the specified policy

EPERM

Realtime scheduling was requested but the calling process does not have sufficient privileges.

ESRCH

The target_thread is invalid or has already terminated

EFAULT

param points outside the process memory space

Function: int pthread_getschedparam (pthread_t target_thread, int *policy, struct sched_param *param)

pthread_getschedparam retrieves the scheduling policy and scheduling parameters for the thread target_thread and stores them in the locations pointed to by policy and param, respectively.

pthread_getschedparam returns 0 on success, or one of the following error codes on failure:

ESRCH

The target_thread is invalid or has already terminated.

EFAULT

policy or param point outside the process memory space.

Go to the first, previous, next, last section, table of contents.