THRD(3)

THRD(3) | Library Functions Manual | THRD(3)

# NAME

`thrd` —
thread functions

# LIBRARY

POSIX Threads Library (libpthread, -lpthread)

# SYNOPSIS

`#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);

# DESCRIPTION

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

The `thrd_create`() 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 `thrd_current`() function returns the thread identifier of the current thread.

The `thrd_detach`() 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 `thrd_equal`() function is used to check whether two t1 and t2 objects refer to the same thread.

The `thrd_exit`() function terminates the calling thread and passes the res value that might be read by the `thrd_join`() 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 `thrd_sleep`() 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 `thrd_yield`() function yields a process voluntarily and gives other threads a chance to run without waiting for any involuntary preemptive switch.

# RETURN VALUES

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.

# SEE ALSO

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

# STANDARDS

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

# HISTORY

This interface first appeared in NetBSD 9.

# AUTHORS

Kamil Rytarowski <kamil@NetBSD.org>

October 16, 2016 | NetBSD 9.0