stdatomic.h — atomics
#include <stdatomic.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 that define the macro __STDC_NO_ATOMICS__ need not provide this header nor support any of its facilities.
The <stdatomic.h> header shall define the atomic_flag type as a structure type. This type provides the classic test-and-set functionality. It shall have two states, set and clear. Operations on an object of type atomic_flag shall be lock free.
The <stdatomic.h> header shall define each of the atomic integer types in the following table as a type that has the same representation and alignment requirements as the corresponding direct type.
- Note:
- The same representation and alignment requirements are meant to imply interchangeability as arguments to functions, return values from functions, and members of unions.
Atomic type name
Direct type
atomic_bool
_Atomic _Bool
atomic_char
_Atomic char
atomic_schar
_Atomic signed char
atomic_uchar
_Atomic unsigned char
atomic_short
_Atomic short
atomic_ushort
_Atomic unsigned short
atomic_int
_Atomic int
atomic_uint
_Atomic unsigned int
atomic_long
_Atomic long
atomic_ulong
_Atomic unsigned long
atomic_llong
_Atomic long long
atomic_ullong
_Atomic unsigned long long
atomic_char16_t
_Atomic char16_t
atomic_char32_t
_Atomic char32_t
atomic_wchar_t
_Atomic wchar_t
atomic_int_least8_t
_Atomic int_least8_t
atomic_uint_least8_t
_Atomic uint_least8_t
atomic_int_least16_t
_Atomic int_least16_t
atomic_uint_least16_t
_Atomic uint_least16_t
atomic_int_least32_t
_Atomic int_least32_t
atomic_uint_least32_t
_Atomic uint_least32_t
atomic_int_least64_t
_Atomic int_least64_t
atomic_uint_least64_t
_Atomic uint_least64_t
atomic_int_fast8_t
_Atomic int_fast8_t
atomic_uint_fast8_t
_Atomic uint_fast8_t
atomic_int_fast16_t
_Atomic int_fast16_t
atomic_uint_fast16_t
_Atomic uint_fast16_t
atomic_int_fast32_t
_Atomic int_fast32_t
atomic_uint_fast32_t
_Atomic uint_fast32_t
atomic_int_fast64_t
_Atomic int_fast64_t
atomic_uint_fast64_t
_Atomic uint_fast64_t
atomic_intptr_t
_Atomic intptr_t
atomic_uintptr_t
_Atomic uintptr_t
atomic_size_t
_Atomic size_t
atomic_ptrdiff_t
_Atomic ptrdiff_t
atomic_intmax_t
_Atomic intmax_t
atomic_uintmax_t
_Atomic uintmax_t
The <stdatomic.h> header shall define the memory_order type as an enumerated type whose enumerators shall include at least the following:
memory_order_relaxed memory_order_consume memory_order_acquire memory_order_release memory_order_acq_rel memory_order_seq_cstThe <stdatomic.h> header shall define the following atomic lock-free macros:
ATOMIC_BOOL_LOCK_FREE
ATOMIC_CHAR_LOCK_FREE
ATOMIC_CHAR16_T_LOCK_FREE
ATOMIC_CHAR32_T_LOCK_FREE
ATOMIC_WCHAR_T_LOCK_FREE
ATOMIC_SHORT_LOCK_FREE
ATOMIC_INT_LOCK_FREE
ATOMIC_LONG_LOCK_FREE
ATOMIC_LLONG_LOCK_FREE
ATOMIC_POINTER_LOCK_FREEwhich shall expand to constant expressions suitable for use in #if preprocessing directives and which shall indicate the lock-free property of the corresponding atomic types (both signed and unsigned). A value of 0 shall indicate that the type is never lock-free; a value of 1 shall indicate that the type is sometimes lock-free; a value of 2 shall indicate that the type is always lock-free.
The <stdatomic.h> header shall define the macro ATOMIC_FLAG_INIT which shall expand to an initializer for an object of type atomic_flag. This macro shall initialize an atomic_flag to the clear state. An atomic_flag that is not explicitly initialized with ATOMIC_FLAG_INIT is initially in an indeterminate state.
[OB] The <stdatomic.h> header shall define the macro ATOMIC_VAR_INIT(value) which shall expand to a token sequence suitable for initializing an atomic object of a type that is initialization-compatible with the non-atomic type of its value argument. An atomic object with automatic storage duration that is not explicitly initialized is initially in an indeterminate state.
The <stdatomic.h> header shall define the macro kill_dependency() which shall behave as described in kill_dependency .
The <stdatomic.h> header shall declare the following generic functions, where A refers to an atomic type, C refers to its corresponding non-atomic type, and M is C for atomic integer types or ptrdiff_t for atomic pointer types.
_Bool atomic_compare_exchange_strong(volatile A *, C *, C); _Bool atomic_compare_exchange_strong_explicit(volatile A *, C *, C, memory_order, memory_order); _Bool atomic_compare_exchange_weak(volatile A *, C *, C); _Bool atomic_compare_exchange_weak_explicit(volatile A *, C *, C, memory_order, memory_order); C atomic_exchange(volatile A *, C); C atomic_exchange_explicit(volatile A *, C, memory_order); C atomic_fetch_add(volatile A *, M); C atomic_fetch_add_explicit(volatile A *, M, memory_order); C atomic_fetch_and(volatile A *, M); C atomic_fetch_and_explicit(volatile A *, M, memory_order); C atomic_fetch_or(volatile A *, M); C atomic_fetch_or_explicit(volatile A *, M, memory_order); C atomic_fetch_sub(volatile A *, M); C atomic_fetch_sub_explicit(volatile A *, M, memory_order); C atomic_fetch_xor(volatile A *, M); C atomic_fetch_xor_explicit(volatile A *, M, memory_order); void atomic_init(volatile A *, C); _Bool atomic_is_lock_free(const volatile A *); C atomic_load(const volatile A *); C atomic_load_explicit(const volatile A *, memory_order); void atomic_store(volatile A *, C); void atomic_store_explicit(volatile A *, C, memory_order);It is unspecified whether any generic function declared in <stdatomic.h> is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name of a generic function, the behavior is undefined.
The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.
void atomic_flag_clear(volatile atomic_flag *); void atomic_flag_clear_explicit(volatile atomic_flag *, memory_order); _Bool atomic_flag_test_and_set(volatile atomic_flag *); _Bool atomic_flag_test_and_set_explicit( volatile atomic_flag *, memory_order); void atomic_signal_fence(memory_order); void atomic_thread_fence(memory_order);
None.
Since operations on the atomic_flag type are lock free, the operations should also be address-free. No other type requires lock-free operations, so the atomic_flag type is the minimum hardware-implemented type needed to conform to this standard. The remaining types can be emulated with atomic_flag, though with less than ideal properties.
The representation of atomic integer types need not have the same size as their corresponding regular types. They should have the same size whenever possible, as it eases effort required to port existing code.
The ISO C standard states that the macro ATOMIC_VAR_INIT is an obsolescent feature. This macro may be removed in a future version of this standard.
XSH atomic_compare_exchange_strong , atomic_exchange , atomic_fetch_add , atomic_flag_clear , atomic_flag_test_and_set , atomic_init , atomic_is_lock_free , atomic_load , atomic_signal_fence , atomic_store , kill_dependency .
First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.
return to top of page