---
name: "stdatomic"
section: "3"
platform: "macos"
package: "libplatform"
version: "375.120.2"
release: "macOS 26.5"
platforms: ["macos"]
url: "https://new.carta.tech/stdatomic"
---

# stdatomic(3)

type-generic atomic operations

## NAME

**ATOMIC\_VAR\_INIT**, **atomic\_init**, **atomic\_load**, **atomic\_store**, **atomic\_exchange**, **atomic\_compare\_exchange\_strong**, **atomic\_compare\_exchange\_weak**, **atomic\_fetch\_add**, **atomic\_fetch\_and**, **atomic\_fetch\_or**, **atomic\_fetch\_sub**, **atomic\_fetch\_xor**, **atomic\_is\_lock\_free** – type-generic atomic operations

## SYNOPSIS

**#include \<stdatomic.h\>**

*\_Atomic(T)* *v* = ATOMIC\_VAR\_INIT(*c*); *\_Atomic* *T* *v* = ATOMIC\_VAR\_INIT(*c*);

*void*\

**atomic\_init**(*\_Atomic(T) \*object*, *T value*);

*T*\

**atomic\_load**(*\_Atomic(T) \*object*);

*T*\

**atomic\_load\_explicit**(*\_Atomic(T) \*object*, *memory\_order order*);

*void*\

**atomic\_store**(*\_Atomic(T) \*object*, *T desired*);

*void*\

**atomic\_store\_explicit**(*\_Atomic(T) \*object*, *T desired*, *memory\_order order*);

*T*\

**atomic\_exchange**(*\_Atomic(T) \*object*, *T desired*);

*T*\

**atomic\_exchange\_explicit**(*\_Atomic(T) \*object*, *T desired*, *memory\_order order*);

*\_Bool*\

**atomic\_compare\_exchange\_strong**(*\_Atomic(T) \*object*, *T \*expected*, *T desired*);

*\_Bool*\

**atomic\_compare\_exchange\_strong\_explicit**(*\_Atomic(T) \*object*, *T \*expected*, *T desired*, *memory\_order success*, *memory\_order failure*);

*\_Bool*\

**atomic\_compare\_exchange\_weak**(*\_Atomic(T) \*object*, *T \*expected*, *T desired*);

*\_Bool*\

**atomic\_compare\_exchange\_weak\_explicit**(*\_Atomic(T) \*object*, *T \*expected*, *T desired*, *memory\_order success*, *memory\_order failure*);

*T*\

**atomic\_fetch\_add**(*\_Atomic(T) \*object*, *T operand*);

*T*\

**atomic\_fetch\_add\_explicit**(*\_Atomic(T) \*object*, *T operand*, *memory\_order order*);

*T*\

**atomic\_fetch\_and**(*\_Atomic(T) \*object*, *T operand*);

*T*\

**atomic\_fetch\_and\_explicit**(*\_Atomic(T) \*object*, *T operand*, *memory\_order order*);

*T*\

**atomic\_fetch\_or**(*\_Atomic(T) \*object*, *T operand*);

*T*\

**atomic\_fetch\_or\_explicit**(*\_Atomic(T) \*object*, *T operand*, *memory\_order order*);

*T*\

**atomic\_fetch\_sub**(*\_Atomic(T) \*object*, *T operand*);

*T*\

**atomic\_fetch\_sub\_explicit**(*\_Atomic(T) \*object*, *T operand*, *memory\_order order*);

*T*\

**atomic\_fetch\_xor**(*\_Atomic(T) \*object*, *T operand*);

*T*\

**atomic\_fetch\_xor\_explicit**(*\_Atomic(T) \*object*, *T operand*, *memory\_order order*);

*\_Bool*\

**atomic\_is\_lock\_free**(*const \_Atomic(T) \*object*);

## DESCRIPTION

The header ⟨stdatomic.h⟩ provides type-generic operations on atomic operations.

Atomic variables are declared using the *\_Atomic()* type specifier or the *\_Atomic* type qualifier. Such variables are not type-compatible with their non-atomic counterparts and may have different alignment.

Operations on atomic variables that do not use the **atomic\_**() interfaces, including compound assignment operations, will behave as if the non-**\_explicit**() versions of those interfaces had been used.

The **atomic\_init**() operation initializes the atomic variable *object* with *value*. Atomic variables can be initialized while being declared using **ATOMIC\_VAR\_INIT**().

The **atomic\_load**() operation returns the value of atomic variable *object*. The **atomic\_store**() operation sets the atomic variable *object* to the *desired* value.

The **atomic\_exchange**() operation combines the behaviour of **atomic\_load**() and **atomic\_store**(). It sets the atomic variable *object* to the desired *value* and returns the original contents of the atomic variable.

The **atomic\_compare\_exchange\_strong**() operation stores the *desired* value into atomic variable *object*, but only if the atomic variable is equal to the *expected* value. Upon success, the operation returns true. Upon failure, the *expected* value is overwritten with the contents of the atomic variable and false is returned.

The **atomic\_compare\_exchange\_weak**() operation is identical to **atomic\_compare\_exchange\_strong**(), but is allowed to fail even if atomic variable *object* is equal to the *expected* value. When an **atomic\_compare\_exchange**() operation is in a loop, the weak version will yield better performance on some platforms. When **atomic\_compare\_exchange\_weak**() would require a loop and **atomic\_compare\_exchange\_strong**() would not, the strong version is preferable.

The **atomic\_fetch\_add**() operation adds the value *operand* to atomic variable *object* and returns the original contents of the atomic variable.

The **atomic\_fetch\_and**() operation applies the *and* operator to atomic variable *object* and value *operand* and stores the result into *object*, while returning the original contents of the atomic variable.

The **atomic\_fetch\_or**() operation applies the *or* operator to atomic variable *object* and value *operand* and stores the result into *object*, while returning the original contents of the atomic variable.

The **atomic\_fetch\_sub**() operation subtracts the value *operand* from atomic variable *object* and returns the original contents of the atomic variable.

The **atomic\_fetch\_xor**() operation applies the *xor* operator to atomic variable *object* and value *operand* and stores the result into *object*, while returning the original contents of the atomic variable.

The **atomic\_is\_lock\_free**() operation returns whether atomic variable *object* uses locks to implement atomic operations.

## MEMORY ORDER

C11 defines a memory model that may allow for the reordering of operations in the absence of fences or explicit memory ordering operations. The non-**\_explicit**() interfaces use the strictest available memory order: sequential consistency. The **\_explicit**() interfaces allow for configuration of the memory order operation which is present.  The types of available memory order operations are explained in more detail in ISO/IEC 9899:2011 (“ISO C11”).

The *order* parameter of the **\_explicit**() interfaces can have one of the following values:

- memory\_order\_relaxed

  Operation does not order memory.

- memory\_order\_consume

  Performs a consume operation.

- memory\_order\_acquire

  Performs an acquire operation.

- memory\_order\_release

  Performs a release operation.

- memory\_order\_acq\_rel

  Performs both an acquire and a release operation.

- memory\_order\_seq\_cst

  Provides sequential consistency.

## SEE ALSO

[atomic(3)](/atomic/3.md), [pthread(3)](/pthread/3.md)

## STANDARDS

These interfaces conform to ISO/IEC 9899:2011 (“ISO C11”).