Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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>

NetBSD 10.99                   October 16, 2016                   NetBSD 10.99