Skip to content

Improve -ftrivial-auto-var-init description #918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve -ftrivial-auto-var-init description #918

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,7 @@ Table 2: Recommended compiler options that enable run-time protection mechanisms
| [`-fno-delete-null-pointer-checks`](#-fno-delete-null-pointer-checks) | GCC 3.0.0<br/>Clang 7.0.0 | Force retention of null pointer checks |
| [`-fno-strict-overflow`](#-fno-strict-overflow) | GCC 4.2.0 | Define behavior for signed integer and pointer arithmetic overflows |
| [`-fno-strict-aliasing`](#-fno-strict-aliasing) | GCC 2.95.3<br/>Clang 2.9.0 | Do not assume strict aliasing |
| [`-ftrivial-auto-var-init`](#-ftrivial-auto-var-init) | GCC 12.0.0<br/>Clang 8.0.0 | Perform trivial auto variable initialization |
| [`-ftrivial-auto-var-init`](#-ftrivial-auto-var-init) | GCC 12.0.0<br/>Clang 8.0.0 | Initialize automatic variables that lack explicit initializers |
| [`-fexceptions`](#-fexceptions) | GCC 2.95.3<br/>Clang 2.6.0 | Enable exception propagation to harden multi-threaded C code |
| [`-fhardened`](#-fhardened) | GCC 14.0.0 | Enable pre-determined set of hardening options in GCC |
| [`-Wl,--as-needed`](#-Wl,--as-needed)<br/>[`-Wl,--no-copy-dt-needed-entries`](#-Wl,--no-copy-dt-needed-entries) | Binutils 2.20.0 | Allow linker to omit libraries specified on the command line to link against if they are not used |
Expand Down Expand Up @@ -1037,15 +1037,15 @@ This option eliminates this problem. It's used by the Linux kernel.

---

### Perform trivial auto variable initialization
### Initialize automatic variables that lack explicit initializers

| Compiler Flag | Supported since | Description |
|:--------------------------------------------------------------------|:-------------------:|:---------------------------------------------|
| <span id="-ftrivial-auto-var-init">`-ftrivial-auto-var-init`</span> | GCC 12.0.0<br/>Clang 8.0.0| Perform trivial auto variable initialization |
| Compiler Flag | Supported since | Description |
|:--------------------------------------------------------------------|:--------------------------:|:---------------------------------------------------------------|
| <span id="-ftrivial-auto-var-init">`-ftrivial-auto-var-init`</span> | GCC 12.0.0<br/>Clang 8.0.0 | Initialize automatic variables that lack explicit initializers |

#### Synopsis

This option controls if (and how) automatic variables are initialized. Even with the option, the compiler will consider an automatic variable as uninitialized unless it is explicitly initialized.
This option controls if (and how) automatic, (i.e., stack-allocated) variables are initialized by the compiler in the absence of an explicit initializer.

This option has three choices:

Expand All @@ -1055,7 +1055,27 @@ This option has three choices:

We recommend using `zero` for production code, to reduce the risk of a logic bug leading to a security vulnerability.

This setting can sometimes interfere with other tools that are being used to monitor executable code, since it is expressly setting a value that was not set by the source code.
Even when this option is used, GCC will still considers an automatic variable without an explicit initializer as uninitialized for the purpoes of the static analysis performed by `-Wuninitialized` and `-Wanalyzer-use-of-uninitialized-value` and report warning diagnostics accordingly[^gcc-trivial-auto-var-init]. GCC will also perform optimization as if the variable were uninitialized.

#### Performance implications

This option initializes automatic variables at the time they are allocated which can add overhead to programs. For example, in performance-critical code, the initialization of variables might be required to happen at a specific point in the code later than when storage for the variable is allocated on the stack, and the code generated by the compiler when can `-ftrivial-auto-var-init` slow down execution if the generated initialization occurs in a performance-critical code path.

The overhead added by `-ftrivial-auto-var-init` scales with the size and frequency of allocations for which the compiler generates initialization code.

#### When not to use?

Automatic initialization can interfere with dynamic analysis tools such as Valgrind[^valgrind], Dr. Memory[^drmemory], and Clang's Memory Sanitizer[^msan], since it is expressly setting a value that was not set by the source code. This can mask issues with uninitialized variables that could otherwise be detected and fixed, making it less suitable for debugging and software testing. Consequently, we discourage the use of `-ftrivial-auto-var-init` for instrumented test code intended to be used for dynamic analysis of unitialized variables issues.

In specific cases, the `pattern` variant of this option can make uninitialized memory easier to spot when debugging because the patterns used are less likely to be used as real values[^arm-ftrivial-auto-var-init]. For example, the pointer values are chosen to be invalid for many systems.

In addition, initializing all automatic variables can lead to an increase in the binary size of the compiled program[^arm-ftrivial-auto-var-init]. This can be an issue in embedded environments where memory is limited.

[^gcc-trivial-auto-var-init]: GCC team, [Options That Control Optimization: `-ftrivial-auto-var-init`](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftrivial-auto-var-init), GCC Manual, 2025-05-30..
[^arm-ftrivial-auto-var-init]: Arm, [Arm Compiler for Embedded Reference Guide: `-ftrivial-auto-var-init`](https://developer.arm.com/documentation/101754/0624/armclang-Reference/armclang-Command-line-Options/-ftrivial-auto-var-init), Arm Compiler for Embedded Reference Guide, Version 6.24, 2025-05-31.
[^valgrind]: Valgrind Developers, [Valgrind](https://valgrind.org/), 2025-05-20.
[^drmemory]: Dr. memory team, [Dr. Memory](https://drmemory.org/), 2025-04-11.
[^msan]: LLVM Sanitizers team, [NemorySanitizer](https://github.com/google/sanitizers/wiki/memorysanitizerr), GitHub google/sanitizers Wiki, 2024-06-09.

<!-- More information
https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftrivial-auto-var-init
Expand Down