Freestanding and hosted implementations
There are two kinds of implementations defined by the C++ standard: hosted and freestanding implementations. For hosted implementations, the set of standard library headers required by the C++ standard is much larger than for freestanding ones. In a freestanding implementation, execution may happen without an operating system.
The kind of the implementation is implementation-defined. The macro __STDC_HOSTED__ is predefined to 1 for hosted implementations and 0 for freestanding implementations. (since C++11)
Requirements on multi-threaded executions and data races
|
(since C++11) |
Requirements on the main function
| freestanding | hosted |
|---|---|
| In a freestanding implementation, it is implementation-defined whether a program is required to define a main function. Start-up and termination is implementation-defined; start-up contains the execution of constructors for objects of namespace scope with static storage duration; termination contains the execution of destructors for objects with static storage duration. | In a hosted implementation, a program must contain a global function called main. Executing a program starts a main thread of execution in which the main function is invoked, and in which variables of static storage duration might be initialized and destroyed.
|
Requirements on standard library headers
A freestanding implementation has an implementation-defined set of headers. This set includes at least the headers in the following table:
| Types | <cstddef> |
| Implementation properties | <limits> <cfloat> <climits> (since C++11) <version> (since C++20) |
| Integer types | <cstdint> (since C++11) |
| Start and termination | <cstdlib> (partial)[1] |
| Dynamic memory management | <new> |
| Type identification | <typeinfo> |
| Source location | <source_location> (since C++20) |
| Exception handling | <exception> |
| Initializer lists | <initializer_list> (since C++11) |
| Comparisons | <compare> (since C++20) |
| Coroutines support | <coroutine> (since C++20) |
| Other runtime support | <cstdarg> |
| Fundamental library concepts | <concepts> (since C++20) |
| Type traits | <type_traits> (since C++11) |
| Bit manipulation | <bit> (since C++20) |
| Atomics | <atomic> (since C++11)[2] |
| Utility components | <utility> (since C++23) |
| Tuples | <tuple> (since C++23) |
| Memory | <memory> (since C++23) (partial) |
| Function objects | <functional> (since C++23) (partial) |
| Compile-time rational arithmetic | <ratio> (since C++23) |
| Iterators library | <iterator> (since C++23) (partial) |
| Ranges library | <ranges> (since C++23) (partial) |
| Deprecated headers | <ciso646> (until C++20) <cstdalign> (since C++11)(until C++20) <cstdbool> (since C++11)(until C++20) |
- ↑ The supplied version of the <cstdlib> shall declare at least the functions std::abort, std::atexit, std::exit, std::at_quick_exit and std::quick_exit (since C++11).
- ↑ Support for always lock-free integral atomic types and presence of type aliases std::atomic_signed_lock_free and std::atomic_unsigned_lock_free are implementation-defined in a freestanding implementation. (since C++20)
Notes
It's important to note that some compiler vendors may not fully support freestanding implementation. For example, GCC libstdc++ has had implementation and build issues before version 13, while LLVM libcxx and MSVC STL do not support freestanding.
In C++23, many features will be made freestanding with partial headers. However, it's still up for discussion in WG21 whether headers like <array> will be made freestanding in the future standard (C++26, maybe). Regardless, containers like vector, list, deque, and map will never be freestanding due to their dependencies on exceptions and heap.
GCC 13 provides more headers, such as optional, span, array, and bitset, for freestanding. However, it's important to note that these headers may not be portable or provide the same experience as a hosted implementation. It's better to avoid using them in a freestanding environment, even if the toolchain provides them.
References
- C++23 standard (ISO/IEC 14882:2023):
- 4.1 Implementation compliance [intro.compliance] (p: 10)
- 6.9.2 Multi-threaded executions and data races [intro.multithread] (p: 84)
- 6.9.3.1 main function [basic.start.main] (p: 89)
- 16.4.2.5 Freestanding implementations [compliance] (p: 483)
- C++20 standard (ISO/IEC 14882:2020):
- 4.1 Implementation compliance [intro.compliance] (p: 7)
- 6.9.2 Multi-threaded executions and data races [intro.multithread] (p: 77)
- 6.9.3.1 main function [basic.start.main] (p: 82)
- 16.5.1.3 Freestanding implementations [compliance] (p: 470)
- C++17 standard (ISO/IEC 14882:2017):
- 4.1 Implementation compliance [intro.compliance] (p: 5)
- 4.7 Multi-threaded executions and data races [intro.multithread] (p: 15)
- 6.6.1 main function [basic.start.main] (p: 66)
- 20.5.1.3 Freestanding implementations [compliance] (p: 458)
- C++14 standard (ISO/IEC 14882:2014):
- 1.4 Implementation compliance [intro.compliance] (p: 5)
- 1.10 Multi-threaded executions and data races [intro.multithread] (p: 11)
- 3.6.1 Main function [basic.start.main] (p: 62)
- 17.6.1.3 Freestanding implementations [compliance] (p: 441)
- C++11 standard (ISO/IEC 14882:2011):
- 1.4 Implementation compliance [intro.compliance] (p: 5)
- 1.10 Multi-threaded executions and data races [intro.multithread] (p: 11)
- 3.6.1 Main function [basic.start.main] (p: 58)
- 17.6.1.3 Freestanding implementations [compliance] (p: 408)
- C++03 standard (ISO/IEC 14882:2003):
- 1.4 Implementation compliance [intro.compliance] (p: 3)
- 3.6.1 Main function [basic.start.main] (p: 43)
- 17.4.1.3 Freestanding implementations [lib.compliance] (p: 326)
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| CWG 1938 | C++98 | an implementation did not need to document whether it is hosted |
made the implementation kind implementation- defined (thus requires a documentation) |
| LWG 3653 | C++20 | <coroutine> is freestanding, but uses std::hash which is not |
Fixed in C++23 with <functional> being partial freestanding |