---
name: "atomic_load"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/ATOMIC_VAR_INIT"
---

# atomic\_load(3)

type-generic atomic operations

Part of [ATOMIC\_VAR\_INIT(3)](/ATOMIC_VAR_INIT/3.md).

## 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);

*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 macros for atomic operations. Atomic operations can be used by multithreaded programs to provide shared variables between threads that in most cases may be modified without acquiring locks.

Atomic variables are declared using the **\_Atomic**() type specifier. These variables are not type-compatible with their non-atomic counterparts. Depending on the compiler used, atomic variables may be opaque and can therefore only be influenced using the macros described.

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

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

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

The **atomic\_compare\_exchange\_strong**() macro stores a *desired* value into atomic variable *object*, only if the atomic variable is equal to its *expected* value. Upon success, the macro returns true. Upon failure, the *desired* value is overwritten with the value of the atomic variable and false is returned. The **atomic\_compare\_exchange\_weak**() macro is identical to **atomic\_compare\_exchange\_strong**(), but is allowed to fail even if atomic variable *object* is equal to its *expected* value.

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

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

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

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

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

The **atomic\_is\_lock\_free**() macro returns whether atomic variable *object* uses locks when using atomic operations.

## BARRIERS

The atomic operations described previously are implemented in such a way that they disallow both the compiler and the executing processor to re-order any nearby memory operations across the atomic operation. In certain cases this behaviour may cause suboptimal performance. To mitigate this, every atomic operation has an **\_explicit**() version that allows the re-ordering to be configured.

The *order* parameter of these **\_explicit**() macros can have one of the following values.

- memory\_order\_relaxed

  No operation orders memory.

- memory\_order\_consume

  Perform consume operation.

- memory\_order\_acquire

  Acquire fence.

- memory\_order\_release

  Release fence.

- memory\_order\_acq\_rel

  Acquire and release fence.

- memory\_order\_seq\_cst

  Sequentially consistent acquire and release fence.

The previously described macros are identical to the **\_explicit**() macros, when *order* is memory\_order\_seq\_cst.

## COMPILER SUPPORT

These atomic operations are typically implemented by the compiler, as they must be implemented type-generically and must often use special hardware instructions. As this interface has not been adopted by most compilers yet, the ⟨stdatomic.h⟩ header implements these macros on top of existing compiler intrinsics to provide forward compatibility.

This means that certain aspects of the interface, such as support for different barrier types may simply be ignored. When using GCC, all atomic operations are executed as if they are using memory\_order\_seq\_cst.

Instead of using the atomic operations provided by this interface, ISO/IEC 9899:2011 (“ISO C11”) allows the atomic variables to be modified directly using built-in language operators. This behaviour cannot be emulated for older compilers. To prevent unintended non-atomic access to these variables, this header file places the atomic variable in a structure when using an older compiler.

When using GCC on architectures on which it lacks support for built-in atomic intrinsics, these macros may emit function calls to fallback routines. These fallback routines are only implemented for 32-bits and 64-bits datatypes, if supported by the CPU.

## SEE ALSO

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

## STANDARDS

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

## HISTORY

These macros appeared in FreeBSD 10.0.

## AUTHORS

Ed Schouten ⟨*ed@FreeBSD.org*⟩ David Chisnall ⟨*theraven@FreeBSD.org*⟩