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 2.1.5.1 Subprofiling Considerations ) 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:
- thread_local
- Expands to _Thread_local.
- ONCE_FLAG_INIT
- Expands to a value that can be used to initialize an object of type once_flag.
- TSS_DTOR_ITERATIONS
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 sysconf(_SC_THREAD_DESTRUCTOR_ITERATIONS) in any process.
The <threads.h> header shall define the types cnd_t, mtx_t, once_flag, thrd_t, and tss_t as complete object types, the type thrd_start_t as the function pointer type int (*)(void*), and the type tss_dtor_t as the function pointer type void (*)(void*). [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 2.1.5.1 Subprofiling Considerations ), 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() and pthread_self() 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() have a different exit status than pthreads threads, which is reflected in differences between the prototypes for thrd_create() and pthread_create(), thrd_exit() and pthread_exit(), and thrd_join() and pthread_join(); also, thrd_join() has no way to indicate that a thread was cancelled.
The standard developers considered making it implementation-defined whether the types cnd_t, mtx_t and tss_t are interchangeable with the corresponding types pthread_cond_t, pthread_mutex_t and pthread_key_t 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() 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 tss_t, they were treated the same way as mtx_t for consistency. See also the RATIONALE for mtx_lock() concerning the inability of mtx_t to contain information about whether or not a mutex supports timeout if it is the same type as pthread_mutex_t.
None.
<limits.h> , <pthread.h> , <time.h>
XSH 2.9 Threads , call_once , cnd_broadcast , cnd_destroy , cnd_timedwait , mtx_destroy , mtx_lock , sysconf , thrd_create , thrd_current , thrd_detach , thrd_equal , thrd_exit , thrd_join , thrd_sleep , thrd_yield , tss_create , tss_delete , tss_get
First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.
return to top of page