.. Generated by `aurora-lint --list-options rst`. Do not edit by hand: change the table in src/settings/mod.rs and regenerate. Policy and Environment Options ============================== Every assumption the analyzer can be told to make or drop is a named option below, with its value under each preset. This list is the complete record of what the default preset relaxes. See :doc:`configuration` for how to set them. - The **default** preset is ``policy = default`` with a ``hosted`` environment and the ISO C + POSIX library model. - The **strict** preset is ``policy = strict`` with a ``freestanding`` environment and no library model. Policy options -------------- ``assert_is_guard`` A dominating assert whose condition establishes the property is a guard, even if NDEBUG can strip it. - Default preset: ``true``; strict preset: ``false`` - Scope: cross-cutting - Oracle tag: ``assert-dominated`` - Basis: The Clang Static Analyzer, Polyspace and Coverity's models treat a live assert as an assumption; CERT's EXP34-C compliant solution uses one. ``first_site_only`` In a proof chain, only the first failing site is reported, not the sites that depend on the same missing check. - Default preset: ``true``; strict preset: ``false`` - Scope: cross-cutting - Oracle tag: ``dependent-site`` - Basis: Mainstream path-sensitive analyzers report one missing check once. ``trust_noreturn_keyword`` A function declared _Noreturn (or noreturn, or C23 [[noreturn]]) is trusted not to return; otherwise only a body verified never to return proves it. - Default preset: ``true``; strict preset: ``false`` - Scope: cross-cutting - Oracle tag: ``noreturn-trusted`` - Basis: C11 6.7.4p8, 7.23; C23 6.7.13.7. A GNU noreturn attribute, [[gnu::noreturn]] included, is proof under neither policy. ``pre31_unknown_call_pure`` PRE31-C: an unproven call, in an argument an unsafe macro may evaluate other than once, is not treated as a side effect: a call to a function with no definition in the scanned files and no library contract, a call through a pointer, strerror, inet_ntoa, strsignal, gai_strerror, getenv, gmtime and asctime (whose only effect is the static buffer they return), or a call to a scanned function that reaches one of these and nothing shown to have a side effect. A callee shown to have a side effect, in whichever scanned file it is defined, is reported either way. - Default preset: ``true``; strict preset: ``false`` - Scope: PRE31-C - Oracle tag: ``call-side-effect-unproven`` - Basis: C11 5.1.2.3p2 (which CERT quotes) makes a call a side effect only when the function does one. cppcheck's assertWithSideEffect and Polyspace's MISRA C:2012 Rule 13.5 flag only callees they can show are impure. clang-tidy's bugprone-assert-side-effect ignores calls by default. PC-lint and Parasoft's CERT_C-PRE31-c count every call, as the strict policy does. Environment contracts --------------------- ``closed_program`` The scanned files are the whole program: nothing outside them links against it, dlopens it, or loads into it. Then a non-static, non-const global that no scanned file writes, and a non-static function that only returns a literal, are constants EXP33-C may fold to prune a branch. Undeclared, another translation unit may write the global or interpose the function, so neither is folded. - Default preset: ``false``; strict preset: ``false`` - Scope: EXP33-C - Oracle tag: ``contract:closed_program`` - Basis: ADR-0011: libraries count as external, and an executable that exports its symbols (-rdynamic, dlopen'ed plugins) is a library too, so in-tree writes prove nothing about a global with external linkage. C11 6.2.2p2: every declaration of an identifier with external linkage, in any translation unit, denotes the same object. Declared by the user, never assumed: a Juliet testcase set is a closed program; a library is not. ``free_null_is_noop`` free(NULL) does nothing. - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:free_null_is_noop`` - Basis: C11 7.22.3.3p2. ``realloc_null_is_malloc`` realloc(NULL, size) behaves like malloc(size). - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:realloc_null_is_malloc`` - Basis: C11 7.22.3.5p3. ``stdlib_noreturn`` abort, exit, _Exit, quick_exit, longjmp, thrd_exit and POSIX _exit never return to their caller. - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:stdlib_noreturn`` - Basis: C11 7.22.4.1, 7.22.4.4, 7.22.4.5, 7.22.4.7, 7.13.2.1 and 7.26.5.5; POSIX.1-2024 _exit(). A freestanding implementation need not provide , or at all. Known limitation: two cross-file summaries built by the prescan (a parameter's null state after `if (!p) exit(1);`, and whether a function never returns) still credit these calls whatever this option says. ``stdlib_call_effects`` The ISO C and POSIX functions the tool lists as free of side effects (strlen, memcmp, isdigit, fabs, ntohs, ...) have none, and every other ISO C or POSIX function it knows has one (it sets errno, touches a stream, allocates, or keeps hidden state). Withdrawn, a library call is a call to an unknown function. - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:stdlib_call_effects`` - Basis: C11 7.24 and 7.4: memcmp, strcmp, strncmp, memchr, strchr, strcspn, strpbrk, strrchr, strspn, strstr, strlen and the character classification and case mapping functions modify no object; 7.22.1.4p8 and 7.12.1 (strtol and math functions report errors through errno); CERT PRE31-C-EX1: "even changing errno is a side effect". ``library_macros_evaluate_once`` A C library function the implementation's headers define as a macro (glibc's tolower) evaluates each argument exactly once, whatever its replacement list looks like, including when a project macro hands it an argument. "The implementation's headers" are any defining the name outside the scanned project, so a third-party library on the search path that redefines a standard name is trusted too (a redefinition C11 7.1.3 already makes undefined). Withdrawn, such a macro is judged by its definition like any other. - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:library_macros_evaluate_once`` - Basis: C11 7.1.4p1: "Any invocation of a library function that is implemented as a macro shall expand to code that evaluates each of its arguments exactly once". The standard's own exceptions (the stream argument of getc, putc, getwc and putwc, and assert) stay unsafe. ``main_argv_guarantees`` main's argc is nonnegative, argv[argc] is a null pointer, and argv[0..argc) point to strings. - Default preset: ``true``; strict preset: ``false`` - Scope: contract - Oracle tag: ``contract:main_argv_guarantees`` - Basis: C11 5.1.2.2.1p2, which binds hosted environments only. ``static_zero_init`` Objects with static storage duration and no initializer are zeroed before main runs. - Default preset: ``true``; strict preset: ``true`` - Scope: contract - Oracle tag: ``contract:static_zero_init`` - Basis: C11 6.7.9p10. Startup code that skips clearing .bss breaks it. Withdrawn, a block-scope static read before its function writes it is indeterminate; file-scope objects, which any function may write first, are not tracked. Toolchain --------- ``include_names`` How an ``#include`` name is matched against the files on disk: ``exact``, or ``case-insensitive`` as cl does on Windows, where an exact-case entry still wins. It is a fact about the toolchain rather than an assumption the rules trust, so neither preset sets it and it carries no oracle tag. Unset, it is ``case-insensitive`` when ``--compile-commands`` names a cl or clang-cl build and ``exact`` otherwise; the scanning host's own file system never decides it. - Set with ``[environment] include_names`` or ``--include-names`` - Part of the settings hash only when ``case-insensitive`` - Basis: Windows looks file names up case-insensitively unless a directory is marked case-sensitive (Microsoft Learn, "Case sensitivity"). ``data_model`` How wide the integer types are: ``iso``, the default, credits only what ISO C guarantees (``CHAR_BIT`` at least 8, ``short`` and ``int`` at least 16 bits, ``long`` at least 32, ``long long`` at least 64, and the exact width of ``int32_t`` and its kind); ``ilp32``, ``lp64`` or ``llp64`` declares the target's model, so ``INT_MAX``, ``sizeof(long)`` and the like have their values there. Under ``iso`` a limit such as ``INT_MAX`` is unknown, a value is proven to fit a type only within the guaranteed range, and a defect that occurs on some conforming width is reported. Neither preset sets it. - Set with ``[environment] data_model`` or ``--data-model`` - Part of the settings hash only when not ``iso`` - Basis: C11 5.2.4.2.1 (minimum magnitudes), 6.3.1.1 (rank order) and 7.20.1.1 (exact-width types); integer widths are otherwise implementation-defined. Declared memory functions ------------------------- ``allocators`` and ``deallocators`` A function the scan has no body for (a platform hook supplied at build time, or a library outside the scanned tree) cannot be proven to allocate or to free. A project declares what such a function does: a deallocator frees the argument its position names (counting from 1), and an allocator returns fresh memory under the contract of the standard allocator it names (``malloc``, ``calloc``, ``realloc``, ``aligned_alloc``, ``strdup`` or ``strndup``). A ``realloc``-like allocator also releases the block its first argument points at. The memory-lifetime rules (MEM00-C, MEM01-C, MEM03-C, MEM30-C, MEM31-C, MEM34-C) and the function summaries that credit a wrapper with what it frees read the declarations, whichever way they cut: a free through a declared hook excuses a leak and makes a second free a double free. A rule that only asks whether a call allocates at all counts a declared allocator too. Null-state, unchecked-result and allocation-size checks still recognize the standard names only. A function whose body the scan reads needs no declaration, and a C library function cannot be declared, since its contract is the library's. - Set with ``[environment.allocators]`` ``NAME = "CONTRACT"`` and ``[environment.deallocators]`` ``NAME = ARG``, or ``--allocator NAME[=CONTRACT]`` (default ``malloc``) and ``--deallocator NAME[=ARG]`` (default 1) - Part of the settings hash only when something is declared - Basis: the project's own statement of its environment (ADR-0001, ADR-0015)