THRD(3) FreeBSD 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 <
[email protected]>
FreeBSD 14.1-RELEASE-p8 October 16, 2016 FreeBSD 14.1-RELEASE-p8