# Program startup and termination

> Before main runs, every static variable is zero- or constant-initialized and then dynamically initialized in a partly specified order. After it, std::exit unwinds that work in reverse, interleaved with atexit handlers, while quick_exit, abort and terminate each skip different parts.

- **Source:** C++ Atlas (https://cppatlas.com/topics/program-startup-and-termination)
- **Track:** Program structure
- **Estimated reading time:** 14 minutes
- **ISO C++ clauses:** [basic.start.main] (https://eel.is/c++draft/basic.start.main), [basic.start.static] (https://eel.is/c++draft/basic.start.static), [basic.start.dynamic] (https://eel.is/c++draft/basic.start.dynamic), [basic.start.term] (https://eel.is/c++draft/basic.start.term), [stmt.dcl] (https://eel.is/c++draft/stmt.dcl), [support.start.term] (https://eel.is/c++draft/support.start.term), [except.terminate] (https://eel.is/c++draft/except.terminate), [except.handle] (https://eel.is/c++draft/except.handle)
- **cppreference links:** [Main function](https://en.cppreference.com/w/cpp/language/main_function), [Initialization (non-local variables)](https://en.cppreference.com/w/cpp/language/initialization), [Constant initialization](https://en.cppreference.com/w/cpp/language/constant_initialization), [std::exit](https://en.cppreference.com/w/cpp/utility/program/exit), [std::atexit](https://en.cppreference.com/w/cpp/utility/program/atexit), [std::quick_exit](https://en.cppreference.com/w/cpp/utility/program/quick_exit), [std::abort](https://en.cppreference.com/w/cpp/utility/program/abort), [std::terminate](https://en.cppreference.com/w/cpp/error/terminate)
- **Prerequisites:** object-lifetime-and-storage, translation-units-and-linkage, exceptions-and-stack-unwinding

## The one idea

A C++ program does real work before `main` and after it. Before, every variable with static storage duration is initialized, in two phases with different guarantees. After, the objects that were constructed are destroyed in reverse, with functions registered through `std::atexit` slotted into the same reverse sequence.

The rules are sharp at the two extremes and vague in the middle. Static initialization is complete before any dynamic initialization begins. Within one translation unit, ordinary dynamic initialization follows definition order. Across translation units, the order is unspecified, and an implementation may even defer it until first use. On the way out, only `std::exit`, which returning from `main` calls, runs the full teardown. The other exits each skip a different part of it.

> **Mental model.** Startup is a stack being pushed: every completed static initialization, and every `atexit` registration, is pushed in the order it happened. `std::exit` pops the stack. `quick_exit` pops a different, smaller stack, and `abort` throws the stack away.

The object-lifetime-and-storage topic introduces storage durations and the cross-file initialization order fiasco. This topic goes into the phases themselves and into every way a program can end.

## `main` is special

[basic.start.main] gives `main` rules no other function has:

- Its return type must be declared as `int`. `auto main() -> int` is fine; `auto main()` with a deduced type is not.
- It may not be `inline`, `static`, `constexpr`, `consteval`, deleted, or a coroutine. A global variable named `main` is ill-formed, and so is a global function `main` attached to a named module.
- It may not be *used* by the program: no recursive call, no taking its address. GCC accepts both with only a `-Wpedantic` warning.
- Falling off the end is equivalent to `return 0;`. No other value-returning function gets that.
- `argv[argc]` is guaranteed to be a null pointer.

Returning from `main` first destroys `main`'s automatic objects, then calls `std::exit` with the returned value. That one detail separates `return 0;` from `std::exit(0);`, as the termination section shows.

A function-try-block on `main` cannot catch everything that happens around it. Exceptions from constructors of namespace-scope objects and from destructors of static objects happen outside `main`'s body, and [except.handle] says the handler does not see them.

## Static initialization: zero and constant

[basic.start.static] defines the first phase. A variable with static or thread storage duration is *constant-initialized* if its initialization is a constant expression; otherwise it is first *zero-initialized*. These two together are called static initialization, and all of it strongly happens before any dynamic initialization. In practice the values are in the executable image and no code runs.

This is the one cross-file order guarantee you get for free. A constant-initialized variable can be read safely from any dynamic initializer anywhere in the program.

```cpp
// file a.cpp
int f();
int x = f();          // dynamic initialization

// file b.cpp
int y = 5;            // constant initialization: done before any dynamic init
int f() { return y; } // so x is 5, whichever file runs first
```

C++20's `constinit` turns this into a checked promise: the variable must be constant-initialized or the program is ill-formed. Unlike `constexpr`, it does not make the variable `const`.

The standard also lets an implementation turn dynamic initialization into static initialization, as long as the variable ends with the value dynamic initialization would have given it, and no other variable changes before its own initialization. The standard's own example shows the consequence: another variable that reads it early may see either value.

```cpp
inline double fd() { return 1.0; }
extern double d1;
double d2 = d1;     // unspecified: 0.0 if d1 is still zero, 1.0 if d1 was done statically
double d1 = fd();   // dynamic in principle, but may be performed statically
```

GCC and Clang both print 0 for `d2` here, but the standard permits 1.

## Dynamic initialization: three orderings

Everything else is dynamic initialization, and [basic.start.dynamic] sorts non-block variables into three groups:

| Kind | Which variables | Order guarantee |
| --- | --- | --- |
| ordered | ordinary namespace-scope variables and static data members | definition order within one translation unit |
| partially ordered | inline variables that are not template specializations | before a later variable if defined before it in every file that defines that one |
| unordered | static data members of class templates and variable template specializations, unless explicitly specialized | none, even within one file |

Across translation units nothing is ordered. Initializations in different files happen in an unspecified order, and once the program has started a thread, which deferred initialization makes possible, they may even run on different threads.

```cpp
int next_id();

template <class T> struct Tag { static int id; };
template <class T> int Tag<T>::id = next_id();   // unordered

int first = next_id();                            // ordered, but not relative to Tag<T>::id
```

The implementation may also *defer* dynamic initialization until after `main` starts. If it does, a variable is initialized before the first odr-use of any non-inline function or variable defined in its translation unit. Whether that deferral happens is implementation-defined; mainstream toolchains initialize everything before `main`.

> **Pitfall.** Self-registering objects, such as a factory entry created by a namespace-scope constructor, are fragile for a separate reason. If they live in a static library and nothing references their object file, the linker never includes it, and the constructor never runs. That is linker behavior, not a C++ rule, so no language feature fixes it.

If a dynamic initializer of a non-block variable exits with an exception, `std::terminate` is called.

## Block-scope statics

A static local is the standard tool for controlled order. [stmt.dcl] says its dynamic initialization happens the first time control passes through its declaration. Since C++11 that initialization is thread-safe: a concurrent caller waits for the first one to finish. If the initializer throws, the variable is not initialized, and the next pass through the declaration tries again.

```cpp
int attempts = 0;
int init() { if (++attempts < 3) throw attempts; return attempts; }
int get() { static int v = init(); return v; }   // third call succeeds, then no more calls
```

Re-entering the declaration recursively while it is being initialized is undefined behavior, and in practice usually deadlocks or throws. A block-scope static that is constant-initialized never runs an initializer at all.

## Five ways to end a program

| Path | Automatic objects in the current thread | `atexit` handlers and static destructors | `at_quick_exit` handlers | C streams flushed |
| --- | --- | --- | --- | --- |
| `return` from `main` | destroyed (`main`'s own) | yes, interleaved in reverse | no | yes |
| `std::exit(status)` | not destroyed | yes, interleaved in reverse | no | yes |
| `std::quick_exit(status)` | not destroyed | no | yes, in reverse | implementation-defined |
| `std::abort()` | not destroyed | no | no | implementation-defined |
| `std::terminate()` | depends on why it was called | no, with the default handler | no | implementation-defined |

`std::exit` destroys the calling thread's thread-local objects, then runs static destructors and `atexit` handlers, then flushes and closes C streams, removes files made by `std::tmpfile`, and returns the status. Status 0 or `EXIT_SUCCESS` means success, `EXIT_FAILURE` means failure, and any other value has implementation-defined meaning.

```cpp
#include <cstdio>
#include <cstdlib>

struct T { const char* n; ~T() { std::printf("~%s\n", n); } };
T g{"global"};

int main() {
  T l{"local"};
  std::exit(0);     // prints ~global only: l is never destroyed
}
```

`std::quick_exit` (C++11) runs only the `at_quick_exit` handlers, in reverse order of registration, and then calls `std::_Exit`. No objects are destroyed. It exists for programs whose static destructors might race with or deadlock against still-running threads. `std::abort` ends the program abnormally, by way of `SIGABRT`, and runs nothing at all: neither destructors nor handlers.

`std::terminate` calls the current terminate handler, which by default calls `std::abort`. The runtime calls it when an exception escapes `main` or a thread's initial function, escapes a `noexcept` function, escapes a static initializer, a static destructor or an `atexit` handler, or escapes a destructor during stack unwinding. When no handler is found, [except.handle] makes it implementation-defined whether the stack is unwound first; GCC does not unwind, so destructors of `main`'s locals do not run. A terminate handler must not return.

> **Standardese.** [basic.start.term] says the call to `std::exit` is sequenced before the destructions and registered functions it causes, and that destroying statics and calling `atexit` functions are parts of that call. Returning from `main` is defined in [basic.start.main] as leaving `main` and then calling `std::exit` with the returned value.

## Destruction order and `atexit`

Static objects are destroyed in the reverse order in which their constructors, or their dynamic initializations, completed. A statically initialized object is destroyed as if it had been dynamically initialized in its place.

`atexit` handlers are not a separate stack run before or after the destructors. [basic.start.term] places each registration into the same sequence: if an object finishes initialization before a handler is registered, the handler runs before the object is destroyed, and if the registration comes first, the object is destroyed first.

```cpp
#include <cstdio>
#include <cstdlib>

struct T {
  const char* n;
  T(const char* s) : n(s) { std::printf("+%s ", n); }
  ~T() { std::printf("~%s ", n); }
};

void handler() { std::printf("handler "); }

T a("a");
int reg = (std::atexit(handler), 0);
T b("b");

int main() { std::printf("main "); }   // +a +b main ~b handler ~a
```

Two more teardown hazards are worth knowing. A function that contains a static local which has already been destroyed is still callable during later static destruction, but passing through that local's declaration is undefined behavior. And a detached thread that touches a destroyed static object, or uses most of the standard library, during or after static destruction has undefined behavior; this is the hazard `quick_exit` sidesteps.

## What to remember

- `main` must return `int`, may not be used, inlined, made static or constexpr, and falls off the end as `return 0;`.
- Returning from `main` destroys its locals and then calls `std::exit`; calling `std::exit` directly skips the locals.
- Zero and constant initialization happen before all dynamic initialization, so constant-initialized variables are safe everywhere; `constinit` enforces it.
- An implementation may perform dynamic initialization statically, which can change what an early reader sees.
- Dynamic initialization is ordered within a file, partially ordered for inline variables, unordered for template statics, and unordered across files.
- Static locals initialize on first pass, thread-safely, and retry after an exception.
- Static destructors and `atexit` handlers run as one reverse sequence of everything that completed.
- `quick_exit` runs only `at_quick_exit` handlers; `abort` runs nothing; `terminate` calls a handler that defaults to `abort`.
- Whether the stack unwinds before `terminate` for an uncaught exception is implementation-defined.

## Concept Map Outline

- **Startup and termination:** Static initialization, then dynamic initialization, then main, then a reverse teardown chosen by the exit path.
  - **main:** The program's entry point, with rules no other function has.
    - **Declared int:** Return type must be declared int; auto main() -> int is fine, deduction is not.
    - **Forbidden forms:** No inline, static, constexpr, consteval, deleted or coroutine main; it may not be used.
    - **Implicit return 0:** Falling off the end of main is equivalent to return 0.
    - **Return calls exit:** Returning destroys main's locals, then calls std::exit with the value.
  - **Static initialization:** Zero and constant initialization, complete before any dynamic initialization.
    - **Constant init:** Used when the initialization is a constant expression; safe to read from anywhere.
    - **Zero init:** Everything else with static storage is zeroed first.
    - **constinit (C++20):** Requires constant initialization without making the variable const.
    - **Static instead of dynamic:** An implementation may do dynamic init statically, so early readers may see either value.
  - **Dynamic initialization:** Runs code; order depends on the kind of variable.
    - **Ordered:** Ordinary namespace-scope variables follow definition order within one file.
    - **Partially ordered:** Non-template inline variables keep the order they have in every defining file.
    - **Unordered:** Static members of class templates and variable template specializations have no order.
    - **Deferral:** May be deferred until first odr-use of something in the same file; implementation-defined.
    - **Block statics:** Initialized on first pass, thread-safe since C++11, retried if the initializer throws.
  - **Exit paths:** Each way out runs a different subset of the teardown.
    - **std::exit:** Thread-locals, then statics and atexit handlers in one reverse sequence, then C streams.
    - **std::quick_exit:** Only at_quick_exit handlers, in reverse, then _Exit; no objects destroyed.
    - **std::abort:** Abnormal termination; no destructors and no handlers of any kind.
    - **std::terminate:** Calls the terminate handler, abort by default; unwinding before it may not happen.
  - **Teardown order:** Reverse of completion, with atexit registrations in the same sequence.
    - **Reverse completion:** The static object constructed last is destroyed first.
    - **atexit interleaving:** A handler registered after an object completed runs before that object is destroyed.
    - **Dead statics:** Passing through a destroyed static local during later teardown is UB.
    - **Exceptions:** An exception from a static initializer, destructor or atexit handler calls terminate.

## Standardese Quiz Questions

### Question 1 [warmup] ([support.start.term], [basic.start.main], [basic.start.term])

What does this program print?

```cpp
#include <cstdio>
#include <cstdlib>

struct T {
  const char* n;
  ~T() { std::printf("~%s\n", n); }
};

T g{"global"};

int main() {
  T l{"local"};
  std::exit(0);
}
```

A. `~local` then `~global`
B. `~global` only
C. Nothing: `std::exit` runs no destructors
D. `~global` then `~local`

**Answer (B):** `~global` only

**Why:** `std::exit` destroys objects with static storage duration, and thread-locals of the calling thread, but it never returns to its caller, so the automatic object `l` is never destroyed. `return 0;` would print `~local` first, because returning from `main` leaves the function, destroying its locals, before calling `std::exit`. The third option describes `std::quick_exit` or `std::abort`.

### Question 2 [warmup] ([basic.start.main])

Which of these definitions of `main` is well-formed in C++23?

A. `auto main() { return 0; }`
B. `static int main() { return 0; }`
C. `auto main() -> int { }`
D. `constexpr int main() { return 0; }`

**Answer (C):** `auto main() -> int { }`

**Why:** `main` must have a declared return type of `int`, and a trailing return type counts as declaring it, so `auto main() -> int` is fine. Falling off the end of `main` is equivalent to `return 0;`, so the empty body is fine too. A deduced return type is not a declared `int`, and `main` may not be `static`, `inline`, `constexpr` or `consteval`; GCC rejects all three of the others.

### Question 3 [warmup] ([stmt.dcl])

What does this program print?

```cpp
#include <cstdio>

int attempts = 0;

int init() {
  if (++attempts < 3) throw attempts;
  return attempts * 10;
}

int get() {
  static int v = init();
  return v;
}

int main() {
  for (int i = 0; i < 5; ++i) {
    try { get(); } catch (int) {}
  }
  std::printf("%d\n", attempts);
}
```

A. `3`
B. `1`
C. `5`
D. Undefined behavior: `v` is used after its initialization failed

**Answer (A):** `3`

**Why:** [stmt.dcl] says that if the initialization of a block-scope static exits by an exception, the variable is not initialized, and initialization is attempted again the next time control enters the declaration. The first two calls throw, the third succeeds and sets `v` to 30, and the last two calls skip the initializer. `1` would be right only if a failed initialization were never retried.

### Question 4 [tricky] ([basic.start.term], [basic.start.dynamic])

What does this program print?

```cpp
#include <cstdio>
#include <cstdlib>

struct T {
  const char* n;
  T(const char* s) : n(s) { std::printf("+%s ", n); }
  ~T() { std::printf("~%s ", n); }
};

void handler() { std::printf("handler "); }

T a("a");
int reg = (std::atexit(handler), 0);
T b("b");

int main() { std::printf("main "); }
```

A. `+a +b main handler ~b ~a`
B. `+a +b main ~b ~a handler`
C. `+a +b main ~b handler ~a`
D. The relative order of `handler` and the destructors is unspecified

**Answer (C):** `+a +b main ~b handler ~a`

**Why:** The three dynamic initializations are ordered by definition in one file: `a` completes, then `handler` is registered, then `b` completes. [basic.start.term] runs destructors and `atexit` functions as one sequence in reverse: what completed after a registration is destroyed before that handler runs, and what completed before it is destroyed after. So `~b`, `handler`, `~a`. Treating `atexit` handlers as a separate stack gives either of the first two answers.

### Question 5 [tricky] ([support.start.term])

When this program calls `std::quick_exit(0)`, which of the following run?

```cpp
#include <cstdio>
#include <cstdlib>

struct T {
  const char* n;
  ~T() { std::printf("~%s\n", n); }
};

T g{"global"};

void on_exit_fn() { std::puts("atexit"); }
void on_quick() { std::puts("at_quick_exit"); std::fflush(stdout); }

int main() {
  T l{"local"};
  std::atexit(on_exit_fn);
  std::at_quick_exit(on_quick);
  std::quick_exit(0);
}
```

A. Only `on_quick`
B. `on_quick`, then `on_exit_fn`
C. `on_quick`, then the destructor of `g`
D. Nothing: `quick_exit` is like `abort`

**Answer (A):** Only `on_quick`

**Why:** `std::quick_exit` calls the functions registered with `at_quick_exit` in reverse order of registration and then calls `std::_Exit`. It destroys no objects and calls no `atexit` handlers, and whether `_Exit` flushes streams is implementation-defined, which is why the handler flushes `stdout` itself. The second and third options mix in parts of `std::exit`.

### Question 6 [tricky] ([basic.start.static], [basic.start.dynamic])

Two files, `a.cpp` and `b.cpp`, are linked into one program. When `main` starts, what is the value of `x`?

```cpp
// file a.cpp
int f();
int x = f();
int main() { return x; }

// file b.cpp
int y = 5;
int f() { return y; }
```

A. Unspecified: 0 or 5, depending on which file is initialized first
B. 0, because `x` is initialized first
C. Undefined behavior: `y` is read before its initialization
D. 5, guaranteed

**Answer (D):** 5, guaranteed

**Why:** `y` is constant-initialized, and [basic.start.static] says all static initialization strongly happens before any dynamic initialization. So `y` already holds 5 when the dynamic initializer of `x` calls `f`, whichever file's dynamic initialization runs first. The unspecified answer would be right if `y` had a dynamic initializer, such as `int y = compute();`.

### Question 7 [standardese] ([basic.start.static])

These are the only definitions in one file. What does the C++23 standard say about the value of `d2` once initialization is complete?

```cpp
inline double fd() { return 1.0; }
extern double d1;
double d2 = d1;
double d1 = fd();
```

A. It is 0.0, because `d2` is initialized before `d1` in the same file
B. It is unspecified whether it is 0.0 or 1.0
C. It is 1.0, because `fd()` can be evaluated at compile time
D. Undefined behavior: `d1` is read before its lifetime begins

**Answer (B):** It is unspecified whether it is 0.0 or 1.0

**Why:** Both variables have dynamic initializers, since `fd` is not `constexpr`. But [basic.start.static] lets an implementation perform a dynamic initialization statically when the result is the same, and doing that for `d1` is allowed. If it does, `d2` sees 1.0; if not, `d2` is initialized first and sees the zero-initialized 0.0. This is the standard's own example; GCC and Clang give 0.0, which is why the first option is tempting. There is no undefined behavior, because a zero-initialized `double` may be read.

### Question 8 [standardese] ([except.handle], [except.terminate])

The exception escapes `main` and no handler exists. Is the destructor of `local` guaranteed to run?

```cpp
#include <cstdio>

struct T { ~T() { std::puts("~T"); } };

int main() {
  T local;
  throw 42;
}
```

A. Yes: the stack is always unwound before `std::terminate` is called
B. No: it is guaranteed not to run, because `std::terminate` is called at the throw
C. Undefined behavior: throwing out of `main` is not allowed
D. It is implementation-defined whether the stack is unwound before `std::terminate` is called

**Answer (D):** It is implementation-defined whether the stack is unwound before `std::terminate` is called

**Why:** When no matching handler is found, [except.handle] says `std::terminate` is called and whether the stack is unwound first is implementation-defined. GCC does not unwind, so `~T` is not printed there, but another implementation may unwind. This is why long-running programs catch everything in `main` when they need destructors to run.
