In C++, what does the value returned from main tell the launching process, and what happens if main has no return statement?
answer
- handed to std::exit
- zero means success
- two portable macros
- falling off the end
basics
~20 sReturning from main destroys main's locals and calls std::exit with the value. Zero or EXIT_SUCCESS reports success, EXIT_FAILURE reports failure, and any other value means what the platform says. Reaching main's closing brace is equivalent to return 0.
solid answer
~40 s`return n;` in `main` leaves `main`, destroying its automatic objects, and then calls `std::exit(n)`, which returns a status to the host environment. The standard defines only three meanings: `0` and `EXIT_SUCCESS` (from `<cstdlib>`) produce an implementation-defined form of *successful termination*, `EXIT_FAILURE` one of *unsuccessful termination*, and every other value is implementation-defined. A CI system running a C++ build tool therefore sees the step pass or fail from that value. `main` is special in two more ways: it must return `int` (clang rejects `void main` with "'main' must return 'int'"), and if control flows off the end of its body the effect is `return 0;`, while the same omission in any other non-`void` function is undefined behaviour.
code
cpp · 25 lines#include <cstdlib>
#include <exception>
#include <filesystem>
#include <iostream>
#include <stdexcept>
void compile(const std::filesystem::path& src) {
if (!std::filesystem::exists(src))
throw std::runtime_error("no such source: " + src.string());
std::cout << "compiled " << src << '\n';
}
int main(int argc, char** argv) {
if (argc < 2) {
std::cerr << "usage: build <source>\n";
return EXIT_FAILURE; // CI marks the step failed
}
try {
compile(argv[1]);
return EXIT_SUCCESS; // same meaning as return 0
} catch (const std::exception& e) {
std::cerr << "build failed: " << e.what() << '\n';
return EXIT_FAILURE; // locals destroyed, then std::exit
}
}go deeper
Know that main returns an int, that 0 or EXIT_SUCCESS means success and EXIT_FAILURE means failure, and that omitting the return means 0.
Explain that return from main destroys main's locals and then calls std::exit, and that only three status meanings are portable.
Structure a tool's main so every failure becomes a clean EXIT_FAILURE with a message, and threads are joined before main returns.
Define the exit-status contract for the team's tools so CI and scripts can depend on it, and keep it stable across releases.
## What `return` from `main` does In C++, `main` is the only function whose return value leaves the program. The standard spells out the sequence: a `return` statement in `main` leaves the function, which **destroys every object with automatic storage duration** in `main`, and then **calls `std::exit` with the returned value**. `std::exit` performs the rest of normal termination: thread-local and static objects are destroyed, `atexit` handlers run, C streams are flushed and closed, and control returns to the host environment with a status. ## The three meanings the standard defines | Value passed to `std::exit` | What the host is told | |---|---| | `0` | an implementation-defined form of **successful termination** | | `EXIT_SUCCESS` | an implementation-defined form of **successful termination** | | `EXIT_FAILURE` | an implementation-defined form of **unsuccessful termination** | | anything else | implementation-defined | `EXIT_SUCCESS` and `EXIT_FAILURE` are macros from `<cstdlib>`. In the macOS run below `EXIT_FAILURE` produced status `1`, but the value is the platform's, so portable code uses the macro. Tools that want distinct failure kinds, such as "compile error" versus "usage error", use small distinct integers and document them; the meaning of those values belongs to the platform and the tool, not to C++. ## A build tool that a CI system runs A CI step runs the build tool and reads only one thing back: whether the process reported success. The tool's `main` should therefore: 1. Return `EXIT_FAILURE` for bad usage, before doing any work. 2. Wrap the real work in a `try` block and return `EXIT_FAILURE` from a `catch (const std::exception&)` handler after printing the reason to `std::cerr`. 3. Return `EXIT_SUCCESS` only when the work completed. Returning from the handler, rather than letting the exception escape `main`, matters: the exception ends in a normal return, so `main`'s locals are destroyed and `std::exit` runs the rest of the cleanup. An exception that escapes `main` calls `std::terminate` instead, and a CI log shows an abort rather than a clean failure. ## What the CI system actually sees A CI runner treats the build tool as a black box with three outputs, and the status is the only one it acts on: - **The exit status** decides whether the step passes. Zero passes; anything the platform reports as unsuccessful fails the step and usually the pipeline. - **Standard error** is where the reason belongs. The status carries no text, so a failed step with an empty log is a debugging session waiting to happen. - **Standard output** carries the tool's normal results, which other steps may parse; mixing error text into it breaks them. A tool that prints "error" but returns `0` is the most common bug in this area: the pipeline goes green while the build is broken. A test that runs the tool on a missing file and asserts a non-zero status catches it. ## Rules special to `main` - **Return type.** `main` shall have a declared return type of `int`. Clang 21 rejects `void main() {}` with `error: 'main' must return 'int'`. - **Implicit `return 0`.** If control flows off the end of `main`'s body, the effect is a `return` with operand `0`. Flowing off the end of any other non-`void` function, except a coroutine, is undefined behaviour. - **Two standard signatures.** An implementation shall allow both `int main()` and `int main(int argc, char* argv[])`; others are implementation-defined, with extra parameters recommended after `argv`. - **Not an ordinary function.** `main` shall not be named by an expression, so a program cannot call it or take its address, and declaring it `inline`, `static`, `constexpr` or `consteval` is ill-formed. ## What returning from `main` does not cover - Objects in *other* threads: a thread still running when `main` returns races with static destruction. Join every thread before returning. - Buffered data in objects that are never destroyed, such as a heap-allocated logger nobody deletes: its buffer is lost even on a clean return. - Status values above what the platform can carry: how the host truncates or maps them is outside C++; keep codes small. ## Checklist - Return `EXIT_SUCCESS` or `0` only on full success. - Catch at the top of `main` and convert exceptions to `EXIT_FAILURE`. - Print the reason to `std::cerr`, since the status carries no message. - Join threads before `main` returns.
- Why is flowing off the end of main allowed when it is undefined behaviour elsewhere?The standard gives `main` a specific rule: flowing off the end of its body is equivalent to `return 0;`. For any other function with a non-`void` return type, except a coroutine, reaching the closing brace without a `return` has undefined behaviour. The special case keeps tiny programs and examples valid, but explicit `return EXIT_SUCCESS;` documents intent in a tool whose status matters.
- Should a build tool return different non-zero values for different failures?It can, and many do: one value for bad usage, another for a failed compilation. C++ defines only zero, `EXIT_SUCCESS` and `EXIT_FAILURE`; other values are implementation-defined, so their meaning is a contract between the tool and its callers. Keep them small, document them, and keep `EXIT_FAILURE` as the generic case.
- A main without a return statement has undefined behaviour.
- void main is fine on every C++ compiler.
- EXIT_SUCCESS and EXIT_FAILURE are keywords of the language.
- Letting the exception escape main is as good as returning EXIT_FAILURE.
- Returning from main skips the destructors of main's local objects.