THREADS.H(7) Miscellaneous Information Manual THREADS.H(7)

threads.h — ISO C threads

#include <threads.h>

[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard. Implementations shall not define the macro __STDC_NO_THREADS__, except for profile implementations that define _POSIX_SUBPROFILE (see V1_chap02(7)) in <unistd.h>, which may define __STDC_NO_THREADS__ and, if they do so, need not provide this header nor support any of its facilities.

The <threads.h> header shall define the following macros:

Expands to _Thread_local .
Expands to a value that can be used to initialize an object of type once_flag .

Expands to an integer constant expression representing the maximum number of times that destructors will be called when a thread terminates and shall be suitable for use in #if preprocessing directives.

[CX] If {PTHREAD_DESTRUCTOR_ITERATIONS} is defined in <limits.h>, the value of TSS_DTOR_ITERATIONS shall be equal to {PTHREAD_DESTRUCTOR_ITERATIONS}; otherwise, the value of TSS_DTOR_ITERATIONS shall be greater than or equal to the value of {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} and shall be less than or equal to the maximum positive value that can be returned by a call to (_SC_THREAD_DESTRUCTOR_ITERATIONS) in any process.

The <threads.h> header shall define the types cnd_t, mtx_t, , thrd_t, and tss_t as complete object types, the type as the function pointer type , and the type as the function pointer type . [CX] The type thrd_t shall be defined to be the same type that pthread_t is defined to be in <pthread.h>.

The <threads.h> header shall define the enumeration constants mtx_plain, mtx_recursive, mtx_timed, thrd_busy, thrd_error, thrd_nomem, thrd_success and thrd_timedout.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

void            call_once(once_flag *, void (*)(void));
int             cnd_broadcast(cnd_t *);
void            cnd_destroy(cnd_t *);
int             cnd_init(cnd_t *);
int             cnd_signal(cnd_t *);
int             cnd_timedwait(cnd_t * restrict, mtx_t * restrict,
                    const struct timespec * restrict);
int             cnd_wait(cnd_t *, mtx_t *);
void            mtx_destroy(mtx_t *);
int             mtx_init(mtx_t *, int);
int             mtx_lock(mtx_t *);
int             mtx_timedlock(mtx_t * restrict,
                    const struct timespec * restrict);
int             mtx_trylock(mtx_t *);
int             mtx_unlock(mtx_t *);
int             thrd_create(thrd_t *, thrd_start_t, void *);
thrd_t          thrd_current(void);
int             thrd_detach(thrd_t);
int             thrd_equal(thrd_t, thrd_t);
_Noreturn void  thrd_exit(int);
int             thrd_join(thrd_t, int *);
int             thrd_sleep(const struct timespec *, struct timespec *);
void            thrd_yield(void);
int             tss_create(tss_t *, tss_dtor_t);
void            tss_delete(tss_t);
void           *tss_get(tss_t);
int             tss_set(tss_t, void *);

Inclusion of the <threads.h> header shall make symbols defined in the header <time.h> visible.

The <threads.h> header is optional in the ISO C standard but is mandated by POSIX.1-2024. Note however that subprofiles can choose to make this header optional (see V1_chap02(7)), and therefore application portability to subprofile implementations would benefit from checking whether __STDC_NO_THREADS__ is defined before inclusion of <threads.h>.

The features provided by <threads.h> are not as extensive as those provided by <pthread.h>. It is present on POSIX.1 implementations in order to facilitate porting of ISO C programs that use it. It is recommended that applications intended for use on POSIX.1 implementations use <pthread.h> rather than <threads.h> even if none of the additional features are needed initially, to save the need to convert should the need to use them arise later in the application's lifecycle.

Although the <threads.h> header is optional in the ISO C standard, it is mandated by POSIX.1-2024 because <pthread.h> is mandatory and the interfaces in <threads.h> can easily be implemented as a thin wrapper for interfaces in <pthread.h>.

The type thrd_t is required to be defined as the same type that pthread_t is defined to be in <pthread.h> because thrd_current(3) and pthread_self(3) need to return the same thread ID when called from the initial thread. However, these types are not fully interchangeable (that is, it is not always possible to pass a thread ID obtained as a thrd_t to a function that takes a pthread_t, and vice versa) because threads created using thrd_create(3) have a different exit status than threads, which is reflected in differences between the prototypes for thrd_create(3) and pthread_create(3), thrd_exit(3) and pthread_exit(3), and thrd_join(3) and pthread_join(3); also, thrd_join(3) has no way to indicate that a thread was cancelled.

The standard developers considered making it implementation-defined whether the types mtx_t and tss_t are interchangeable with the corresponding types pthread_cond_t, and defined in <pthread.h> (that is, whether any function that can be called with a valid cnd_t can also be called with a valid pthread_cond_t, and vice versa, and likewise for the other types). However, this would have meant extending mtx_lock(3) to provide a way for it to indicate that the owner of a mutex has terminated (equivalent to [EOWNERDEAD]). It was felt that such an extension would be invention. Although there was no similar concern for cnd_t and they were treated the same way as mtx_t for consistency. See also the RATIONALE for mtx_lock(3) concerning the inability of mtx_t to contain information about whether or not a mutex supports timeout if it is the same type as

None.

<limits.h>, <pthread.h>, <time.h>

XSH V2_chap02(3), call_once(3), cnd_broadcast(3), cnd_destroy(3), cnd_timedwait(3), mtx_destroy(3), mtx_lock(3), sysconf(3), thrd_create(3), thrd_current(3), thrd_detach(3), thrd_equal(3) , thrd_exit(3), thrd_join(3), thrd_sleep(3), thrd_yield(3), tss_create(3), tss_delete(3), tss_get(3)

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.

June 14, 2024 posix.fail