THRD(3) Library Functions Manual THRD(3)

thrd — thread functions

POSIX Threads Library (libpthread, -lpthread)

#include <threads.h>

typedef int (*thrd_start_t) (void *)

int
thrd_create(thrd_t *thr, thrd_start_t func, void *arg);

thrd_t
thrd_current(void);

int
thrd_detach(thrd_t thr);

int
thrd_equal(thrd_t t1, thrd_t t2);

_Noreturn void
thrd_exit(int res);

int
thrd_join(thrd_t thr, int *res);

int
thrd_sleep(const struct timespec *duration, struct timespec *remaining);

void
thrd_yield(void);

The thrd interface operates over opaque objects of the thrd_t type.

The () function is used to create a new thread, calling func with the arg parameter. This function initializes the thr object with the identifier of the newly created thread. The completion of thrd_create() is synchronized with the start of the newly produced thread. It is possible to reuse the thr object once the thread has terminated either by joining another thread operation or been detached.

The () function returns the thread identifier of the current thread.

The () function is used to indicate that storage for the thr object can be reclaimed on the thread's termination. The thr object cannot be already detached or joined.

The () function is used to check whether two t1 and t2 objects refer to the same thread.

The () function terminates the calling thread and passes the res value that might be read by the () function. The program terminates once all threads have been terminated with an exit code equivalent to calling the exit(3) function with the EXIT_SUCCESS status. The thrd_join() function joins the thr thread, waiting and blocking until it has terminated. The res parameter points to a variable that will store the status passed from the joined function. If res is NULL then the status from the thrd_exit() function is ignored.

The () function suspends execution of the calling thread until either a signal is received or the interval specified in the duration argument has been passed. The remaining parameter stores requested timeout reduced with the time actually suspended. This argument is used when thrd_sleep() has been interrupted. It is valid code to point both arguments duration and remaining to the same object. It is not guaranteed that sleep will not take longer than specified in duration, however unless interrupted with a signal it will not take shorter than the specified interval.

The () function yields a process voluntarily and gives other threads a chance to run without waiting for any involuntary preemptive switch.

The thrd_create() function returns thrd_success on success, otherwise thrd_nomem if not sufficient memory could be allocated, or thrd_error on other errors.

The thrd_current() function returns the identifier of the calling thread.

The thrd_detach() function returns thrd_current on success or thrd_error on failure.

The thrd_equal() function returns zero if t0 and t1 refer to the different threads, otherwise it will return non-zero.

The thrd_exit() function does not return.

The thrd_join() function returns thrd_success on success or thrd_error on failure.

The thrd_sleep() function returns 0 on success (as the requested time has elapsed), -1 once the function was interrupted by a signal, or a negative value to indicate error. The NetBSD implementation returns -2 on error.

The thrd_yield() function returns no value.

nanosleep(2), pthread_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3), pthread_join(3), pthread_self(3), sched(3), threads(3)

The thrd interface conforms to ISO/IEC 9899:2011 (“ISO C11”).

This interface first appeared in NetBSD 9.

Kamil Rytarowski <kamil@NetBSD.org>

October 16, 2016 NetBSD 11.0