What must a freestanding C++ implementation provide, and how did C++23 and C++26 widen the freestanding standard library?
answer
- the kind is implementation-defined
- main may not be required
- a minimum list of headers
- freestanding items within a header
- freestanding-deleted members
basics
~20 sA freestanding implementation must supply at least a listed set of headers and their freestanding items; whether main is required is implementation-defined. The C++23 list has 26 headers, including utility, memory and ranges; C++26 lists 48, adding array, optional and inplace_vector.
solid answer
~50 sThe standard defines two kinds of implementation, **hosted** and **freestanding**, and which one you have is implementation-defined. A freestanding implementation runs without an operating system's help: whether `main` is required, and how start-up and termination work, are implementation-defined. Its library must include at least the headers in the freestanding table, and within each header only the declarations marked *freestanding* are required. In the C++23 draft that table has 26 headers: the language-support core (`<cstddef>`, `<new>`, `<exception>`, `<type_traits>`, `<atomic>` and so on) plus partial `<utility>`, `<tuple>`, `<memory>`, `<functional>`, `<iterator>` and `<ranges>`. The C++26 final draft lists 48, adding among others `<array>`, `<optional>`, `<variant>`, `<expected>`, `<span>`, `<string_view>`, `<inplace_vector>`, `<algorithm>`, `<charconv>` and `<cstring>`. Members that throw, such as `std::array::at` or `std::optional::value`, are **freestanding-deleted**: they may be deleted functions. In C++26 the default global `operator new` need not even work.
go deeper
Know that freestanding means no operating system and a smaller standard library than a hosted build.
Describe the header table, freestanding items within a header, and why main and start-up are implementation-defined.
Track what C++23 and C++26 added, what freestanding-deleted means for code that throws, and the C++26 operator new rule.
Decide whether the firmware targets the freestanding subset or a full hosted library for the target, and what that costs in portability.
## Two kinds of implementation The C++ standard describes two kinds of implementation: - A **hosted** implementation has the whole standard library and runs programs under an operating system. - A **freestanding** implementation may run without the benefit of an operating system, the situation of most microcontroller firmware, and provides a smaller, implementation-defined library. Which kind a given toolchain is, is itself implementation-defined. For a freestanding environment the standard also leaves to the implementation whether a program must define `main` at all, and how start-up and termination happen; start-up still includes running constructors of objects with static storage duration, and termination their destructors. A pacemaker image typically starts at a reset handler that sets up memory and then calls a function of the firmware's choosing. ## What the library must contain The freestanding library is specified in two layers: 1. **A minimum set of headers.** The implementation's set of headers is implementation-defined but must include at least those in the freestanding table. 2. **Freestanding items within each header.** Only the declarations the synopsis marks *freestanding*, or every declaration in a header whose synopsis begins with a *freestanding* comment (minus those marked *hosted*), are required. A freestanding `<string>` in C++26, for example, must provide `std::char_traits` but not `std::string`. ## How the table grew | Standard draft | Headers in the freestanding table | Notable contents | |---|---|---| | C++23 (N4950) | 26 | language support (`<cstddef>`, `<cstdint>`, `<new>`, `<exception>`, `<typeinfo>`, `<initializer_list>`, `<compare>`, `<coroutine>`), `<type_traits>`, `<concepts>`, `<bit>`, `<atomic>`, `<limits>`, plus partial `<utility>`, `<tuple>`, `<memory>`, `<functional>`, `<ratio>`, `<iterator>`, `<ranges>` | | C++26 (N5050) | 48 | all of the above plus `<array>`, `<optional>`, `<variant>`, `<expected>`, `<span>`, `<mdspan>`, `<string_view>`, `<inplace_vector>`, `<algorithm>`, `<numeric>`, `<charconv>`, `<cstring>`, `<cmath>`, `<random>`, `<system_error>`, `<cerrno>` and others | The C++23 additions came mainly from P1642, which made parts of the utilities, ranges and iterators clauses freestanding; the C++26 additions came from several papers, including ones covering the C library's character primitives, "partial classes" such as `std::array` and `std::optional`, and the algorithms. ## Freestanding-deleted members A class can be useful on a microcontroller even if a few members cannot be, typically those that report errors by throwing. C++26 marks such members **freestanding-deleted**. On a freestanding implementation it is implementation-defined whether each one is a deleted function or behaves exactly as in a hosted implementation. Examples from the C++26 draft: - `std::array::at`, which throws `std::out_of_range`. - `std::optional::value`, which throws `std::bad_optional_access`. - `std::inplace_vector::push_back`, which throws `std::bad_alloc` when full, and its sized constructors. The standard's note explains the choice of *deleted* over *absent*: a deleted declaration still takes part in overload resolution, so code does not silently pick a different overload when it moves between freestanding and hosted builds. ## Allocation in C++26 Placement new is always available, since `<new>` is freestanding. C++26 goes further for ordinary `new`: on a freestanding implementation it is implementation-defined whether the default replaceable global allocation functions satisfy their required behaviour, and the standard's note says they can cause undefined behaviour when invoked. A program that needs `new` must supply its own `operator new`; the feature-test macro `__cpp_lib_freestanding_operator_new` tells code which situation it is in. ## Asking the implementation from code Code shared between a host build and a firmware build can ask what it is running on: - `__STDC_HOSTED__` is the integer literal 1 on a hosted implementation and 0 on a freestanding one. - C++26 adds feature-test macros for the freestanding pieces, such as `__cpp_lib_freestanding_array`, `__cpp_lib_freestanding_optional` and `__cpp_lib_freestanding_operator_new`, defined in `<version>` and the matching headers. Testing a macro is more reliable than guessing from the compiler's name, because the same compiler can be configured either way. ## What this means in practice - The headers on the list are a floor, not a ceiling: many embedded toolchains ship far more, often a hosted library built for the target. - Library support lags the draft: LLVM 23's libc++ status pages list the C++26 freestanding papers as not yet implemented. - Writing to the freestanding subset keeps code portable to the smallest toolchains: prefer `try_` and `unchecked_` members, avoid members that throw, and do not assume `operator new` works.
- Must a freestanding C++ program define main?Not necessarily. The standard makes it implementation-defined whether a program in a freestanding environment is required to define `main`, and start-up and termination are implementation-defined too. Firmware usually enters at a reset handler that initializes memory, runs static constructors and calls the application's entry function.
- Why mark a member freestanding-deleted instead of leaving it out of the freestanding library?A deleted function still participates in overload resolution, so a call that would pick it fails to compile instead of silently resolving to a different overload. That keeps a freestanding build and a hosted build of the same code choosing the same functions. The standard's note on freestanding deleted functions gives this reason.
- A freestanding implementation has no standard library at all.
- Every freestanding program must define main.
- std::array is freestanding in C++23.
- Freestanding-deleted members are always missing on freestanding builds.
- The default operator new always works on a C++26 freestanding implementation.
Freestanding header lists read from the C++23 (N4950) and C++26 (N5050) drafts; the C++26 changes are not yet in every library.