--- name: "extraclangtools" section: "1" platform: "linux" package: "clang" version: "23.1.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/extraclangtools" --- # extraclangtools(1) Extra Clang Tools Documentation Welcome to the clang-tools-extra project which contains extra tools built using Clang's tooling APIs. ## NAME extraclangtools - Extra Clang Tools Documentation Welcome to the clang-tools-extra project which contains extra tools built using Clang's tooling APIs. ## EXTRA CLANG TOOLS 23.1.4 RELEASE NOTES - • Introduction - • What's New in Extra Clang Tools 23.1.4? - • Major New Features - • Potentially Breaking Changes - • Improvements to clangd - • Compile flags - • Diagnostics - • Clang-tidy integration - • Hover - • Code completion - • Cross-references - • Inlay hints - • Code actions - • Semantic Highlighting - • Call hierarchy - • Remote index - • Improvements to C++20 Modules support - • Miscellaneous - • Improvements to clang-doc - • Improvements to clang-query - • Improvements to clang-tidy - • New checks - • New check aliases - • Changes in existing checks - • Removed checks - • Miscellaneous - • Improvements to include-fixer - • Improvements to clang-include-fixer - • Improvements to modularize - • Improvements to pp-trace - • Clang-tidy Visual Studio plugin Written by the LLVM Team \ ### Introduction This document contains the release notes for the Extra Clang Tools, part of the Clang release 23.1.4. Here we describe the status of the Extra Clang Tools in some detail, including major improvements from the previous release and new feature work. All LLVM releases may be downloaded from the LLVM releases web site \. For more information about Clang or LLVM, including information about the latest release, please see the Clang Web Site \ or the LLVM Web Site \. Note that if you are reading this file from a Git checkout or the main Clang web page, this document applies to the *next* release, not the current one. To see the release notes for a specific release, please see the releases page \. ### What's New in Extra Clang Tools 23.1.4? Some of the major new features and improvements to Extra Clang Tools are listed here. Generic improvements to Extra Clang Tools as a whole or to its underlying infrastructure are described first, followed by tool-specific sections. ### Major New Features ### Potentially Breaking Changes - • The modernize-use-using \<\> check now sets the *IgnoreExternC* option to *true* by default. The check will no longer transform **typedef**s within **extern "C"** blocks. - • Deprecated the **clang-tidy** check performance-faster-string-find \<\>. It has been renamed to performance-prefer-single-char-overloads \<\>. The original check will be removed in the 25th release. - • Removed the **clang-tidy** **hicpp** module. All checks have been moved to the other modules. Use the replacement checks instead: | | | | --- | --- | | Removed check | Replacement check | | **hicpp-avoid-c-arrays** | modernize-avoid-c-arrays \<\> | | **hicpp-avoid-goto** | cppcoreguidelines-avoid-goto \<\> | | **hicpp-braces-around-statements** | readability-braces-around-statements \<\> | | **hicpp-deprecated-headers** | modernize-deprecated-headers \<\> | | **hicpp-exception-baseclass** | bugprone-std-exception-baseclass \<\> | | **hicpp-explicit-conversions** | misc-explicit-constructor \<\> | | **hicpp-function-size** | readability-function-size \<\> | | **hicpp-ignored-remove-result** | bugprone-unused-return-value \<\> | | **hicpp-invalid-access-moved** | bugprone-use-after-move \<\> | | **hicpp-member-init** | cppcoreguidelines-pro-type-member-init \<\> | | **hicpp-move-const-arg** | performance-move-const-arg \<\> | | **hicpp-multiway-paths-covered** | bugprone-unhandled-code-paths \<\> readability-trivial-switch \<\> | | **hicpp-named-parameter** | readability-named-parameter \<\> | | **hicpp-new-delete-operators** | misc-new-delete-overloads \<\> | | **hicpp-no-array-decay** | cppcoreguidelines-pro-bounds-array-to-pointer-decay \<\> | | **hicpp-no-assembler** | portability-no-assembler \<\> | | **hicpp-no-malloc** | cppcoreguidelines-no-malloc \<\> | | **hicpp-noexcept-move** | performance-noexcept-move-constructor \<\> | | **hicpp-signed-bitwise** | bugprone-signed-bitwise \<\> | | **hicpp-special-member-functions** | cppcoreguidelines-special-member-functions \<\> | | **hicpp-static-assert** | misc-static-assert \<\> | | **hicpp-uppercase-literal-suffix** | readability-uppercase-literal-suffix \<\> | | **hicpp-undelegated-constructor** | bugprone-undelegated-constructor \<\> | | **hicpp-use-auto** | modernize-use-auto \<\> | | **hicpp-use-emplace** | modernize-use-emplace \<\> | | **hicpp-use-equals-default** | modernize-use-equals-default \<\> | | **hicpp-use-equals-delete** | modernize-use-equals-delete \<\> | | **hicpp-use-noexcept** | modernize-use-noexcept \<\> | | **hicpp-use-nullptr** | modernize-use-nullptr \<\> | | **hicpp-use-override** | modernize-use-override \<\> | | **hicpp-vararg** | cppcoreguidelines-pro-type-vararg \<\> | - • Removed the **clang-doc** deprecated Markdown generator. **--format=md** now uses the new Mustache-backed MD generator. It is possible that there are some regressions in MD output. - • Removed the **clang-doc** YAML generator. Prefer the JSON generator to get documentation information in a reusable format. ### Improvements to clangd ### Compile flags - • The clang-cl flags **/std:c++23preview** and **/std:clatest** are recognized - • Improved logic for finding the resource directory containing clang's builtin headers, to handle cases where clangd and clang are installed in different prefixes - • Environment variables that influence compilation are logged on startup ### Diagnostics - • Driver diagnostics can be suppressed via config - • **pragma diagnostic push/pop** is handled correctly across a preamble boundary - • Unknown compiler options are dropped instead of causing a fatal error ### Clang-tidy integration - • **bugprone-bad-signal-to-kill-thread** now works with clangd - • Clang-tidy checks can properly see macro definitions located in the preamble region at the top of the file ### Hover - • When hovering over an accessor method, the comment for the accessed field is shown - • Improved handling of unknown doxygen commands - • Fixed a regression in whitespace escaping behaviour when processing documentation comments ### Code completion - • Clangd recognizes when a definition of a function (as opposed to a call) is being completed, and provides dedicated behaviour suitable for definitions - • Now also provides include files without extension, if they are in a directory only called **include**. - • Added support for **InsertReplaceEdit** in code completion (LSP 3.16), allowing clients that advertise **insertReplaceSupport** to receive both insert and replace ranges for completion items. - • Improved logic to avoid inserting a redundant parenthesis when completing in the middle of an identifier - • Changed completion-style default to **detailed**. This means function overloads will no longer be bundled together, but instead each have their own completion item. This gives the user a better overview of the possible overloads and also when accepting the item it will generate placeholder parameters, which was not possible due to ambiguity with **bundled**. To change back to the old behaviour, pass the argument **--completion-style=bundled** to clangd. - • The **ArgumentLists** config option is respected for lambdas - • Code completion for field names in **\_\_builtin\_offsetof** expressions - • Clangd tries harder to find parameter names to show during code completion, looking in other redeclarations of a function if necessary ### Cross-references - • Code navigation works correctly on tokens inside attributes, **\_\_builtin\_offsetof** expressions, and member pointers - • "Find implementations" finds implementations recursively - • "Go to definition" on a forwarding wrapper like **make\_unique** also offers the called constructor as a target - • "Document symbols" supports the new symbol tags added in LSP 3.18 - • "Workspace symbols" ensures that a primary definition is ranked above typedefs ### Inlay hints - • Correct inlay hints are shown for dependent calls to functions with an explicit object parameter (C++23 "deducing this") ### Code actions - • A new tweak "Create function body out-of-line" was added that creates an implementation for a function declaration. - • The "define out of line" code action has improved logic for finding an insertion point which considers **=default** functions. - • The "define out of line" code action has improved logic for using qualified names in the printed definition ### Semantic Highlighting - • Fixed a regression in the highlighting of using-declarations and symbols introduced by them ### Call hierarchy - • Removed redundant symbol name from hierarchy item details ### Remote index - • Improved cross platform support (e.g. serving an index to windows clients from a server running on linux) ### Improvements to C++20 Modules support - • Enabled content valiation for module input files - • Fixed handling of relative paths in prebuilt module files - • Clangd's preamble optimization is skipped for translation units that use modules. (The two features have buggy interactions, and modules independently provide much of the same performance benefit.) - • Support different modules with the same name in a project - • Cache built module files across clangd invocation - • Module builds respect compile command edits specified via **CompileFlags** in clangd configuration - • Invalidate preamble when new module imports are added ### Miscellaneous - • The "switch between source/header" command prefers an .hpp file over an .h file if both are present - • Added a new standalone tool **clangd-remap** for remapping paths inside clangd background index files - • Various crash fixes and stability improvements ### Improvements to clang-doc ### Improvements to clang-query ### Improvements to clang-tidy - • Improved **check\_clang\_tidy.py** script by adding the *-check-header* argument to simplify testing of header files. This argument automatically manages the creation of temporary header files and ensures that diagnostics and fixes are verified for the specified headers. - • Improved **clang-tidy** **-store-check-profile** by generating valid JSON when the source file path contains characters that require JSON escaping. - • Improved **clang-tidy** by preserving literal backslash characters in POSIX source paths. - • Ensured that **clang-tidy** and the clang compiler uses the same logic for the suppression of compiler diagnostics in system headers and expansions of macros defined in system headers. Previously the default setting of tidy overzealously suppressed some diagnostics that would have been emitted by the compiler. (E.g. tidy suppressed many **clang-diagnostic-invalid-offsetof** reports because they usually occur in expansion of the macro **offsetof**.) - • **clang-tidy** will no longer exit immediately if the only enabled checks are *clang-diagnostic-\** ones. This allows using **clang-tidy** purely as a frontend to Clang's builtin warnings. - • On Windows, **clang-tidy** will now better match mixes of forwards and backwards slashes when using the *--line-filter* option. This also improves piping from **git** to **clang-tidy-diff.py**, where slashes will now be automatically normalized. ### New checks - • New bugprone-assignment-in-selection-statement \<\> check. Finds assignments within selection statements. - • New bugprone-missing-end-comparison \<\> check. Finds instances where the result of a standard algorithm is used in a Boolean context without being compared to the end iterator. - • New bugprone-unsafe-to-allow-exceptions \<\> check. Finds functions where throwing exceptions is unsafe but the function is still marked as potentially throwing. - • New llvm-formatv-string \<\> check. Validates **llvm::formatv** format strings against the provided arguments, diagnosing mismatched argument counts, unused arguments, and mixed index styles. - • New llvm-redundant-casting \<\> check. Points out uses of **cast\<\>**, **dyn\_cast\<\>** and their **or\_null** variants that are unnecessary because the argument already is of the target type, or a derived type thereof. Also does similar analysis for calls to **isa\<\>** that always return **true**. - • New llvm-type-switch-case-types \<\> check. Finds **llvm::TypeSwitch::Case** calls with redundant explicit template arguments that can be inferred from the lambda parameter type. - • New llvm-use-vector-utils \<\> check. Finds calls to **llvm::to\_vector(llvm::map\_range(...))** and **llvm::to\_vector(llvm::make\_filter\_range(...))** that can be replaced with **llvm::map\_to\_vector** and **llvm::filter\_to\_vector**. - • New misc-static-initialization-cycle \<\> check. Finds cyclical initialization of static variables. - • New modernize-use-std-bit \<\> check. Finds common idioms which can be replaced by standard functions from the **\** C++20 header. - • New modernize-use-string-view \<\> check. Looks for functions returning **std::\[w\|u8\|u16\|u32\]string** and suggests to change it to **std::\[...\]string\_view** for performance reasons if possible. - • New modernize-use-structured-binding \<\> check. Finds places where structured bindings could be used to decompose pairs and suggests replacing them. - • New performance-string-view-conversions \<\> check. Finds and removes redundant conversions from **std::\[w\|u8\|u16\|u32\]string\_view** to **std::\[...\]string** in call expressions expecting **std::\[...\]string\_view**. - • New performance-use-std-move \<\> check. Suggests insertion of **std::move(...)** to turn copy assignment operator calls into move assignment ones, when deemed valid and profitable. - • New readability-redundant-lambda-parameter-list \<\> check. Finds lambda expressions with a redundant empty parameter list and removes it. - • New readability-redundant-nested-if \<\> check. Finds nested **if** statements that can be merged into a single **if** by combining conditions with **&&**. - • New readability-redundant-qualified-alias \<\> check. Finds redundant identity type aliases that re-expose a qualified name and can be replaced with a **using** declaration. - • New readability-trailing-comma \<\> check. Checks for presence or absence of trailing commas in enum definitions and initializer lists. ### New check aliases - • Renamed cert-exp45-c \<\> to bugprone-assignment-in-selection-statement \<\>. - • Renamed cppcoreguidelines-explicit-constructor \<\> to misc-explicit-constructor \<\>. The *cppcoreguidelines-explicit-constructor* name is kept as an alias. - • Renamed google-explicit-constructor \<\> to misc-explicit-constructor \<\>. The *google-explicit-constructor* name is kept as an alias. - • Renamed performance-faster-string-find \<\> to performance-prefer-single-char-overloads \<\>. The *performance-faster-string-find* name is kept as an alias. ### Changes in existing checks - • Improved altera-id-dependent-backward-branch \<\> check by fixing false positives when ordinary variable or field assignments are used in loop conditions and note locations for inferred ID-dependent fields. - • Improved altera-unroll-loops \<\> check by fixing a crash when analyzing a **for** loop whose initialization statement declares multiple variables. - • Improved bugprone-argument-comment \<\>: - • Checks for C++11 inherited constructors. - • Adds *CommentAnonymousInitLists*, *CommentTypedInitLists*, and *CommentParenthesizedTemporaries* options to comment braced-init list arguments and explicit temporary constructions (for example, **{}**, **Type{}**, and **Type()**). - • Improved bugprone-bad-signal-to-kill-thread \<\> check by fixing false negatives when the **SIGTERM** macro is obtained from a precompiled header. - • Improved bugprone-branch-clone \<\> check by fixing a false positive where **if**/**else** branches containing inline assembly that differed only in the asm string or clobber list were reported as identical. - • Improved bugprone-casting-through-void \<\> check by running only on C++ files because suggested **reinterpret\_cast** is not available in pure C. - • Improved bugprone-derived-method-shadowing-base-method \<\> check by correctly ignoring function templates. - • Improved bugprone-exception-escape \<\> check by adding *TreatFunctionsWithoutSpecificationAsThrowing* option to support reporting for unannotated functions, enabling reporting when no explicit **throw** is seen and allowing separate tuning for known and unknown implementations. - • Improved bugprone-fold-init-type \<\> check by detecting precision loss in overloads with transparent standard functors (e.g. **std::plus\<\>**) for **std::accumulate**, **std::reduce**, and **std::inner\_product**. - • Improved bugprone-inc-dec-in-conditions \<\> check by fixing a false positive when increment/decrement operators appear inside lambda bodies that are part of a condition expression. - • Improved bugprone-incorrect-enable-if \<\> check to not insert an extraneous **typename** on code like **typename std::enable\_if\<...\>**, where there's already a **typename** and only the **::type** at the end is missing. - • Improved bugprone-macro-parentheses \<\> check by printing the macro definition in the warning message if the macro is defined on command line. - • Improved bugprone-misplaced-widening-cast \<\> check by fixing a false positive on bit field assignments when the *CheckImplicitCasts* option is enabled. The check now uses the actual bit field width instead of the declared type to determine if widening occurs. - • Improved bugprone-move-forwarding-reference \<\> check by fixing some false positives in the context of moved lambda captures. - • Improved bugprone-narrowing-conversions \<\> check by fixing a false positive when converting a **bool** to a signed integer type. - • Improved bugprone-pointer-arithmetic-on-polymorphic-object \<\> check by fixing a false positive when **operator\[\]** is used in a dependent context. - • Improved bugprone-random-generator-seed \<\> check by adding a new note at the location of the field if the generator is implicitly initialized with a default seed value. - • Improved bugprone-std-namespace-modification \<\> check by fixing false positives when extending the standard library with a specialization of user-defined type and by removing detection of the compiler generated **std** namespace extensions. - • Improved bugprone-string-constructor \<\> check to detect suspicious string constructor calls when the string class constructor has a default allocator argument. - • Improved bugprone-throwing-static-initialization \<\> check by adding the *AllowedTypes* option. With this option it is possible to exclude static declarations with specific types from the check. - • Improved bugprone-unchecked-optional-access \<\> to recognize common GoogleTest macros such as **ASSERT\_TRUE** and **ASSERT\_FALSE**, reducing the number of false positives in test code. - • Improved bugprone-unsafe-functions \<\> check by adding the function **std::get\_temporary\_buffer** to the default list of unsafe functions. (This function is unsafe, useless, deprecated in C++17 and removed in C++20). - • Improved bugprone-use-after-move \<\> check: - • Include the name of the invalidating function in the warning message when a custom invalidation function is used (via the *InvalidationFunctions* option). - • Add support for annotation of user-defined types as having the same moved-from semantics as standard smart pointers. - • Do not report explicit call to destructor after move as an invalid use. - • Avoid false positives when moving object to a base type then accessing non-base members. - • Avoid false positives when moving object is reinitialized via the base class's **operator=**. - • Fix a false positive when a moved-from variable is reinitialized via a **std::tie()** assignment (e.g. **std::tie(a, b) = f(std::move(a),** **std::move(b))**). The tuple assignment writes back through the stored references, which fully reinitializes the captured variables. - • Avoid false positives when forwarding a derived object to initialize a base class subobject. - • Improved cert-err33-c \<\> check by not inheriting *CheckedReturnTypes* option from bugprone-unused-return-value \<\>, which caused false positives on functions returning **std::error\_code** or similar types. - • Improved cppcoreguidelines-avoid-capturing-lambda-coroutines \<\> check by adding the *AllowExplicitObjectParameters* option. When enabled, lambda coroutines using C++23 deducing **this** (explicit object parameter) are not flagged. - • Improved cppcoreguidelines-avoid-non-const-global-variables \<\> check by adding the *IgnoreMacros* option. When enabled, non-const global variables defined in macros are ignored. - • Improved cppcoreguidelines-init-variables \<\> check by ensuring that member pointers are correctly flagged as uninitialized. - • Fixed cppcoreguidelines-init-variables \<\> check by excluding Objective-C for-in loop variable declaration. - • Improved cppcoreguidelines-missing-std-forward \<\> check by: - • Correctly handling forwarding in deeply nested lambdas. - • Fixed false negative when multiple parameters are used in a lambda and only some of them are forwarded. - • Fixed false positive for constrained template parameters - • Fixed false positive with **std::forward** in brace-init and paren-init lambda captures such as **\[t{std::forward\(t)}\]**. - • Improved cppcoreguidelines-pro-type-member-init \<\> check by fixing a false positive when a base class has a forward declaration before its definition. - • Improved cppcoreguidelines-pro-type-vararg \<\> check by no longer warning on builtins with custom type checking (e.g., type-generic builtins like **\_\_builtin\_clzg**) that use variadic declarations as an implementation detail. - • Improved cppcoreguidelines-rvalue-reference-param-not-moved \<\> check: - • Fixed a false positive on implicitly generated functions such as inherited constructors. - • Added *AllowImplicitMove* option to not warn when an rvalue reference parameter is returned without an explicit **std::move**. - • Improved cppcoreguidelines-special-member-functions \<\> check by fixing a false positive with the *AllowImplicitlyDeletedCopyOrMove* option for classes whose copy operations are implicitly deleted by a non-copyable base class. - • Improved cppcoreguidelines-use-enum-class \<\> check by adding the *IgnoreMacros* option. When enabled, unscoped **enum** declarations within macros are ignored. - • Improved fuchsia-statically-constructed-objects \<\> check by fixing a crash when checking value-dependent static member initializers in class templates. - • Improved llvm-use-ranges \<\> check by adding support for the following algorithms: **std::accumulate**, **std::replace\_copy**, and **std::replace\_copy\_if**. - • Improved misc-const-correctness \<\> check: - • Added support for analyzing function parameters with the *AnalyzeParameters* option. - • Fixed false positive where an array of pointers to **const** was incorrectly diagnosed as allowing the pointee to be made **const**. - • Fixed false positive where a pointer used with placement new was incorrectly diagnosed as allowing the pointee to be made **const**. - • Enabled the check for variables declared with **auto** (configurable via the *AnalyzeAutoVariables* option) and lambdas (configurable via *AnalyzeLambdas* option). - • Fixed false positive where calling a non-const member function on a pointer was incorrectly treated as mutating the pointer, when it only mutates the pointee. - • Fixed false positives when pointers were later passed or bound through **const**-qualified pointer references. - • Fixed false positive where a pointer returned as a non-const **void \*** was incorrectly diagnosed as allowing its pointee to be made **const**. - • Improved misc-multiple-inheritance \<\> by avoiding false positives when virtual inheritance causes concrete bases to be counted more than once. - • Improved misc-redundant-expression \<\> check: - • Fixed a crash when evaluating bitwise comparisons against integer constants wider than 64 bits. - • Avoided false positives when comparing expressions that are structurally identical but use different type aliases. - • Improved misc-throw-by-value-catch-by-reference \<\> check: - • Fixed the *WarnOnLargeObject* option to use the correct name when storing the configuration. - • Fixed the *CheckThrowTemporaries* option to correctly reflect its configured value in exported settings. - • Improved misc-unused-parameters \<\> check by adding *IgnoreMacroParameters* option to suppress warnings for unused parameters whose declarations originate from macro expansions. - • Improved misc-unused-using-decls \<\> to not diagnose **using** declarations as unused if they're exported from a module. - • Improved misc-use-internal-linkage \<\> to not suggest giving internal linkage to entities defined in C++ module interface units. Because it only sees one file at a time, the check can't be sure such entities aren't referenced in any other files of that module. - • Improved modernize-avoid-c-style-cast \<\> check by fixing an invalid fix-it generated when replacing casts that directly follow a keyword or identifier. - • Improved modernize-deprecated-headers \<\> check by avoiding false positives on project headers that use the same name as a standard library header. - • Improve modernize-loop-convert \<\> checks to insert a space when replacing **\*it** with the loop variable in expressions like **delete\*it**, where the missing space would cause the keyword and the new variable to merge into a single identifier. - • Improved modernize-macro-to-enum \<\> check by preserving source file line endings in fix-it replacements. - • Improved modernize-pass-by-value \<\> check by adding *IgnoreMacros* option to suppress warnings in macros. - • Improved modernize-redundant-void-arg \<\> check to work in C23. - • Improved modernize-return-braced-init-list \<\> check to apply fix-it when type qualifiers and/or reference modifiers are used with parameters. - • Improved modernize-type-traits \<\> check to suggest usage of **std::remove\_cvref\_t** when applicable. - • Improved modernize-use-default-member-init \<\> check by fixing a false positive when a constructor initializer refers to a declaration that would not be visible from the inserted default member initializer. The *IgnoreNonVisibleReferences* option can be set to *false* to warn without emitting fix-its for these cases. - • Improved modernize-use-equals-delete \<\> check by only warning on private deleted functions, if they do not have a public overload or are a special member function. - • Improved modernize-use-nodiscard \<\> check by avoiding false positives on functions returning specializations of class templates marked **\[\[nodiscard\]\]**. - • Improved modernize-use-override \<\> check by adding the *AllowVirtualAndOverride* option to allow keeping **virtual** on methods that are also marked **override**. - • Improved modernize-use-ranges \<\> check: - • Preserved used iterator results when replacing **std::unique** calls with **std::ranges::unique**. - • Preserved used iterator results when replacing **std::remove**, **std::remove\_if**, **std::partition**, **std::stable\_partition**, and **std::rotate** calls with their **std::ranges** counterparts. - • Improved modernize-use-scoped-lock \<\> check by fixing a false negative where multiple **std::scoped\_lock** declarations, or a mix of **std::scoped\_lock** and **std::lock\_guard** declarations, in the same scope were not flagged. - • Improved modernize-use-std-format \<\> check: - • Fixed a crash when an argument is part of a macro expansion. - • Added missing **#include** insertion when the format function call appears as an argument to a macro. - • Improved modernize-use-std-print \<\> check by adding missing **#include** insertion when the format function call appears as an argument to a macro. - • Improved modernize-use-trailing-return-type \<\> check by fixing spurious **missing '(' after '\_\_has\_feature'** errors caused by builtin macros appearing in the return type of a function. - • Improved modernize-use-using \<\> check: - • Avoid generating invalid code for function types with redundant parentheses. - • Preserve inline comment blocks that appear between the **typedef**'s parts. - • The *IgnoreExternC* option is now set to *true* by default. - • Improved performance-enum-size \<\> check: - • Exclude **enum** in **extern "C"** blocks. - • Improved the ignore list to correctly handle **typedef** and **enum**. - • Improved performance-inefficient-string-concatenation \<\> check by adding support for detecting inefficient string concatenation in **do-while** loops. - • Improved performance-inefficient-vector-operation \<\> check by correctly handling vector-like classes when **push\_back**/**emplace\_back** are inherited. - • Improved performance-move-const-arg \<\> check by avoiding false positives on trivially copyable types with a non-public copy constructor. - • Improved performance-prefer-single-char-overloads \<\> check: - • Now analyzes calls to the **starts\_with**, **ends\_with**, **contains**, and **operator+=** string member functions. - • Fixes false negatives when using **std::set** from **libstdc++**. - • Improved performance-trivially-destructible \<\> check by fixing false positives when a class is seen through both a header include and a C++20 module import. - • Improved readability-braces-around-statements \<\> check by fixing a crash when diagnosing a statement that ends in the middle of a macro body expansion. - • Improved readability-container-size-empty \<\> check: - • Fix a crash when a member expression has a non-identifier name. - • Reduce verbosity by removing the note indicating source location of the **empty** function. - • Fixed a false positive with suggesting **empty** when comparing a container to a default-constructed object of an unrelated type. - • Extended to warn when the non-member **std::size()** function is used in a Boolean context or compared to **0** or **1**, consistent with the existing **size()**/**length()** member call detection. - • Improved readability-convert-member-functions-to-static \<\> check: - • Fixing a false positive where **const** member functions were incorrectly flagged when they are part of a const/non-const overload pair. - • Correctly detecting **this** usage when a generic lambda calls an overloaded member function. - • Improved readability-delete-null-pointer \<\> check by avoiding invalid fix-its for **if** statements with condition variables or initializers. - • Improved readability-else-after-return \<\> check: - • Fixed missed diagnostics when **if** statements appear in unbraced **switch** case labels. - • Fixed a false positive involving **if** statements which contain a **return**, **break**, etc., jumped over by a **goto**. - • Fixed the check potentially breaking code by deleting one too many characters following an **else** or a curly brace. - • Added support for handling attributed **if** then-branches such as **\[\[likely\]\]** and **\[\[unlikely\]\]**. - • Diagnose and remove redundant **else** branches after calls to **\[\[noreturn\]\]** functions. - • Improved readability-enum-initial-value \<\> check: the warning message now uses separate note diagnostics for each uninitialized enumerator, making it easier to see which specific enumerators need explicit initialization. - • Improved readability-function-size \<\> check by adding an *IgnoreMacros* option to exclude statements, branches, nesting levels, and variable declarations inside macros from the reported metrics. - • Improved readability-identifier-length \<\> check: - • A new option, named *LineCountThreshold*, is added to silence warnings for short-lived variables, based on distance between declaration and last use. - • Support for structured bindings is added. Two new options, named *MinimumBindingNameLength* and *IgnoredBindingNames* respectively, are added to configure the behavior of the check regarding this new identifier kind. By default, names with at least 2 characters are required and the only exception allowed is *\_*. - • Improved readability-identifier-naming \<\> check: - • Fixed incorrect naming style application to C++17 structured bindings. - • Fixed a false positive where function templates could be diagnosed as generic identifiers when *DefaultCase* was enabled. - • Fixed a crash in dependent base lookup when *AggressiveDependentMemberLookup* option is enabled. - • Fixed a false positive from naming style lookup for declarations inside macro arguments. - • Improved readability-implicit-bool-conversion \<\> check: - • Fixed a false positive where *AllowPointerConditions* and *AllowIntegerConditions* options did not suppress warnings when the condition expression involved temporaries (e.g. passing a string literal to a **const std::string&** parameter). - • Warn and provide fix-its when a macro defined in a system header (e.g. **NULL**) is implicitly converted to **bool**. - • Added *AllowLogicalOperatorConversion* option to suppress warnings on implicit conversions of logical operator results (**&&**, **\|\|**, **!**) to **bool** in C. - • Fixed a false positive where **bool** conditions in C conditional operators were diagnosed as implicit conversions to **int**. - • Improved readability-inconsistent-ifelse-braces \<\> check to correctly handle labeled statements of **if**/**else** bodies. - • Improved readability-non-const-parameter \<\> check: - • Avoid false positives on parameters used in dependent expressions (e.g. inside generic lambdas), including constructor-style dependent initializers. - • Fixed a false positive in array subscript expressions where the types are not yet resolved. - • Fixed a false positive when adding **const** to a pointer parameter would conflict with an existing overload. - • Fixed a crash when analyzing a redeclaration whose initializer is attached to another declaration. - • Improved readability-redundant-casting \<\> check by adding the *IgnoreImplicitCasts* option (default *false*) to flag casts as redundant when at least one operand of a binary operation matches the cast type due to implicit conversion. For example, **static\_cast\(1.0f + 1)** is now identified as redundant since **1** is implicitly converted to **float**. Setting this option to *true* restores the previous behavior. - • Improved readability-redundant-member-init \<\> check by adding an *IgnoreMacros* option to suppress warnings when the initializer involves macros that may expand differently in other configurations. - • Improved readability-redundant-parentheses \<\> check: - • Fixed a false positive for parentheses present around an overloaded operator in the context of a binary operation. - • Fixed a bug where clients that apply fix-its without **clang-tidy**'s cleanup could produce invalid code by joining adjacent tokens. - • Added support for parentheses around subscript operators (**(E1\[E2\])** -\> **E1\[E2\]**). - • Improved readability-redundant-preprocessor \<\> check by fixing a false positive for nested **#if** directives using different builtin expressions such as **\_\_has\_builtin** and **\_\_has\_cpp\_attribute**. - • Improved readability-simplify-boolean-expr \<\> check to provide valid fix suggestions for C23 and later by not using **static\_cast**. - • Improved readability-simplify-subscript-expr \<\> check by fixing missing warnings when subscripting an object held inside a generic container (e.g. subscripting a **std::string** held inside a **std::vector\**). - • Improved readability-suspicious-call-argument \<\> check by avoiding a crash from invalid **Abbreviations** option. - • Improved readability-trivial-switch \<\> check by adding an *IgnoreMacros* option. When enabled, the check will ignore switch statements originating from macros. - • Improved readability-use-anyofallof \<\> check by emitting a diagnostic note to suggest materializing the temporary range when iterating over temporary range expressions or initializer lists, as reusing them directly could be unsafe. ### Removed checks ### Miscellaneous ### Improvements to include-fixer ### Improvements to clang-include-fixer - • Fixed crashes when command-line argument parsing failed at unknown tool options. ### Improvements to modularize ### Improvements to pp-trace ### Clang-tidy Visual Studio plugin ## CLANG-TIDY ### Contents - • Clang-Tidy - • Using Clang-Tidy - • Running Clang-Tidy on CUDA Files - • Clang-Tidy Automation - • Running Clang-Tidy in Parallel - • Running Clang-Tidy on Diff - • Suppressing Undesired Diagnostics See also: ### Clang-Tidy Checks ### abseil-cleanup-ctad Suggests switching the initialization pattern of **absl::Cleanup** instances from the factory function to class template argument deduction (CTAD), in C++17 and higher. ``` auto c1 = absl::MakeCleanup([] {}); const auto c2 = absl::MakeCleanup(std::function([] {})); ``` becomes ``` absl::Cleanup c1 = [] {}; const absl::Cleanup c2 = std::function([] {}); ``` ### abseil-duration-addition Checks for cases where addition should be performed in the **absl::Time** domain. When adding two values, and one is known to be an **absl::Time**, we can infer that the other should be interpreted as an **absl::Duration** of a similar scale, and make that inference explicit. Examples: ``` // Original - Addition in the integer domain int x; absl::Time t; int result = absl::ToUnixSeconds(t) + x; // Suggestion - Addition in the absl::Time domain int result = absl::ToUnixSeconds(t + absl::Seconds(x)); ``` ### abseil-duration-comparison Checks for comparisons which should be in the **absl::Duration** domain instead of the floating point or integer domains. N.B.: In cases where a **Duration** was being converted to an integer and then compared against a floating-point value, truncation during the **Duration** conversion might yield a different result. In practice this is very rare, and still indicates a bug which should be fixed. Examples: ``` // Original - Comparison in the floating point domain double x; absl::Duration d; if (x < absl::ToDoubleSeconds(d)) ... // Suggested - Compare in the absl::Duration domain instead if (absl::Seconds(x) < d) ... // Original - Comparison in the integer domain int x; absl::Duration d; if (x < absl::ToInt64Microseconds(d)) ... // Suggested - Compare in the absl::Duration domain instead if (absl::Microseconds(x) < d) ... ``` ### abseil-duration-conversion-cast Checks for casts of **absl::Duration** conversion functions, and recommends the right conversion function instead. Examples: ``` // Original - Cast from a double to an integer absl::Duration d; int i = static_cast(absl::ToDoubleSeconds(d)); // Suggested - Use the integer conversion function directly. int i = absl::ToInt64Seconds(d); // Original - Cast from a double to an integer absl::Duration d; double x = static_cast(absl::ToInt64Seconds(d)); // Suggested - Use the integer conversion function directly. double x = absl::ToDoubleSeconds(d); ``` Note: In the second example, the suggested fix could yield a different result, as the conversion to integer could truncate. In practice, this is very rare, and you should use **absl::Trunc** to perform this operation explicitly instead. ### abseil-duration-division **absl::Duration** arithmetic works like it does with integers. That means that division of two **absl::Duration** objects returns an **int64** with any fractional component truncated toward 0. See this link \ for more information on arithmetic with **absl::Duration**. For example: ``` absl::Duration d = absl::Seconds(3.5); int64 sec1 = d / absl::Seconds(1); // Truncates toward 0. int64 sec2 = absl::ToInt64Seconds(d); // Equivalent to division. assert(sec1 == 3 && sec2 == 3); double dsec = d / absl::Seconds(1); // WRONG: Still truncates toward 0. assert(dsec == 3.0); ``` If you want floating-point division, you should use either the **absl::FDivDuration()** function, or one of the unit conversion functions such as **absl::ToDoubleSeconds()**. For example: ``` absl::Duration d = absl::Seconds(3.5); double dsec1 = absl::FDivDuration(d, absl::Seconds(1)); // GOOD: No truncation. double dsec2 = absl::ToDoubleSeconds(d); // GOOD: No truncation. assert(dsec1 == 3.5 && dsec2 == 3.5); ``` This check looks for uses of **absl::Duration** division that is done in a floating-point context, and recommends the use of a function that returns a floating-point value. ### abseil-duration-factory-float Checks for cases where the floating-point overloads of various **absl::Duration** factory functions are called when the more-efficient integer versions could be used instead. This check will not suggest fixes for literals which contain fractional floating point values or non-literals. It will suggest removing superfluous casts. Examples: ``` // Original - Providing a floating-point literal. absl::Duration d = absl::Seconds(10.0); // Suggested - Use an integer instead. absl::Duration d = absl::Seconds(10); // Original - Explicitly casting to a floating-point type. absl::Duration d = absl::Seconds(static_cast(10)); // Suggested - Remove the explicit cast absl::Duration d = absl::Seconds(10); ``` ### abseil-duration-factory-scale Checks for cases where arguments to **absl::Duration** factory functions are scaled internally and could be changed to a different factory function. This check also looks for arguments with a zero value and suggests using **absl::ZeroDuration()** instead. Examples: ``` // Original - Internal multiplication. int x; absl::Duration d = absl::Seconds(60 * x); // Suggested - Use absl::Minutes instead. absl::Duration d = absl::Minutes(x); // Original - Internal division. int y; absl::Duration d = absl::Milliseconds(y / 1000.); // Suggested - Use absl:::Seconds instead. absl::Duration d = absl::Seconds(y); // Original - Zero-value argument. absl::Duration d = absl::Hours(0); // Suggested = Use absl::ZeroDuration instead absl::Duration d = absl::ZeroDuration(); ``` ### abseil-duration-subtraction Checks for cases where subtraction should be performed in the **absl::Duration** domain. When subtracting two values, and the first one is known to be a conversion from **absl::Duration**, we can infer that the second should also be interpreted as an **absl::Duration**, and make that inference explicit. Examples: ``` // Original - Subtraction in the double domain double x; absl::Duration d; double result = absl::ToDoubleSeconds(d) - x; // Suggestion - Subtraction in the absl::Duration domain instead double result = absl::ToDoubleSeconds(d - absl::Seconds(x)); // Original - Subtraction of two Durations in the double domain absl::Duration d1, d2; double result = absl::ToDoubleSeconds(d1) - absl::ToDoubleSeconds(d2); // Suggestion - Subtraction in the absl::Duration domain instead double result = absl::ToDoubleSeconds(d1 - d2); ``` Note: As with other **clang-tidy** checks, it is possible that multiple fixes may overlap (as in the case of nested expressions), so not all occurrences can be transformed in one run. In particular, this may occur for nested subtraction expressions. Running **clang-tidy** multiple times will find and fix these overlaps. ### abseil-duration-unnecessary-conversion Finds and fixes cases where **absl::Duration** values are being converted to numeric types and back again. Floating-point examples: ``` // Original - Conversion to double and back again absl::Duration d1; absl::Duration d2 = absl::Seconds(absl::ToDoubleSeconds(d1)); // Suggestion - Remove unnecessary conversions absl::Duration d2 = d1; // Original - Division to convert to double and back again absl::Duration d2 = absl::Seconds(absl::FDivDuration(d1, absl::Seconds(1))); // Suggestion - Remove division and conversion absl::Duration d2 = d1; ``` Integer examples: ``` // Original - Conversion to integer and back again absl::Duration d1; absl::Duration d2 = absl::Hours(absl::ToInt64Hours(d1)); // Suggestion - Remove unnecessary conversions absl::Duration d2 = d1; // Original - Integer division followed by conversion absl::Duration d2 = absl::Seconds(d1 / absl::Seconds(1)); // Suggestion - Remove division and conversion absl::Duration d2 = d1; ``` Unwrapping scalar operations: ``` // Original - Multiplication by a scalar absl::Duration d1; absl::Duration d2 = absl::Seconds(absl::ToInt64Seconds(d1) * 2); // Suggestion - Remove unnecessary conversion absl::Duration d2 = d1 * 2; ``` Note: Converting to an integer and back to an **absl::Duration** might be a truncating operation if the value is not aligned to the scale of conversion. In the rare case where this is the intended result, callers should use **absl::Trunc** to truncate explicitly. ### abseil-faster-strsplit-delimiter Finds instances of **absl::StrSplit()** or **absl::MaxSplits()** where the delimiter is a single character string literal and replaces with a character. The check will offer a suggestion to change the string literal into a character. It will also catch code using **absl::ByAnyChar()** for just a single character and will transform that into a single character as well. These changes will give the same result, but using characters rather than single character string literals is more efficient and readable. Examples: ``` // Original - the argument is a string literal. for (auto piece : absl::StrSplit(str, "B")) { // Suggested - the argument is a character, which causes the more efficient // overload of absl::StrSplit() to be used. for (auto piece : absl::StrSplit(str, 'B')) { // Original - the argument is a string literal inside absl::ByAnyChar call. for (auto piece : absl::StrSplit(str, absl::ByAnyChar("B"))) { // Suggested - the argument is a character, which causes the more efficient // overload of absl::StrSplit() to be used and we do not need absl::ByAnyChar // anymore. for (auto piece : absl::StrSplit(str, 'B')) { // Original - the argument is a string literal inside absl::MaxSplits call. for (auto piece : absl::StrSplit(str, absl::MaxSplits("B", 1))) { // Suggested - the argument is a character, which causes the more efficient // overload of absl::StrSplit() to be used. for (auto piece : absl::StrSplit(str, absl::MaxSplits('B', 1))) { ``` ### abseil-no-internal-dependencies Warns if code using Abseil depends on internal details. If something is in a namespace that includes the word "internal", code is not allowed to depend upon it because it's an implementation detail. They cannot friend it, include it, you mention it or refer to it in any way. Doing so violates Abseil's compatibility guidelines and may result in breakage. See \ for more information. The following cases will result in warnings: ``` absl::strings_internal::foo(); // warning triggered on this line class foo { friend struct absl::container_internal::faa; // warning triggered on this line }; absl::memory_internal::MakeUniqueResult(); // warning triggered on this line ``` ### abseil-no-namespace Ensures code does not open **namespace absl** as that violates Abseil's compatibility guidelines. Code should not open **namespace absl** as that conflicts with Abseil's compatibility guidelines and may result in breakage. Any code that uses: ``` namespace absl { ... } ``` will be prompted with a warning. See the full Abseil compatibility guidelines \ for more information. ### abseil-redundant-strcat-calls Suggests removal of unnecessary calls to **absl::StrCat** when the result is being passed to another call to **absl::StrCat** or **absl::StrAppend**. The extra calls cause unnecessary temporary strings to be constructed. Removing them makes the code smaller and faster. Examples: ``` std::string s = absl::StrCat("A", absl::StrCat("B", absl::StrCat("C", "D"))); //before std::string s = absl::StrCat("A", "B", "C", "D"); //after absl::StrAppend(&s, absl::StrCat("E", "F", "G")); //before absl::StrAppend(&s, "E", "F", "G"); //after ``` ### abseil-str-cat-append Flags uses of **absl::StrCat()** to append to a **std::string**. Suggests **absl::StrAppend()** should be used instead. The extra calls cause unnecessary temporary strings to be constructed. Removing them makes the code smaller and faster. ``` a = absl::StrCat(a, b); // Use absl::StrAppend(&a, b) instead. ``` Does not diagnose cases where **absl::StrCat()** is used as a template argument for a functor. ### abseil-string-find-startswith Checks whether a **std::string::find()** or **std::string::rfind()** (and corresponding **std::string\_view** methods) result is compared with 0, and suggests replacing with **absl::StartsWith()**. This is both a readability and performance issue. **starts\_with** was added as a built-in function on those types in C++20. If available, prefer enabling modernize-use-starts-ends-with \<\> instead of this check. ``` string s = "..."; if (s.find("Hello World") == 0) { /* do something */ } if (s.rfind("Hello World", 0) == 0) { /* do something */ } ``` becomes ``` string s = "..."; if (absl::StartsWith(s, "Hello World")) { /* do something */ } if (absl::StartsWith(s, "Hello World")) { /* do something */ } ``` ### Options - **StringLikeClasses** Semicolon-separated list of names of string-like classes. By default both **std::basic\_string** and **std::basic\_string\_view** are considered. The list of methods to be considered is fixed. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **AbseilStringsMatchHeader** The location of Abseil's **strings/match.h**. Defaults to **absl/strings/match.h**. ### abseil-string-find-str-contains Finds **s.find(...) == string::npos** comparisons (for various string-like types) and suggests replacing with **absl::StrContains()**. This improves readability and reduces the likelihood of accidentally mixing **find()** and **npos** from different string-like types. By default, "string-like types" includes **::std::basic\_string**, **::std::basic\_string\_view**, and **::absl::string\_view**. See the StringLikeClasses option to change this. ``` std::string s = "..."; if (s.find("Hello World") == std::string::npos) { /* do something */ } absl::string_view a = "..."; if (absl::string_view::npos != a.find("Hello World")) { /* do something */ } ``` becomes ``` std::string s = "..."; if (!absl::StrContains(s, "Hello World")) { /* do something */ } absl::string_view a = "..."; if (absl::StrContains(a, "Hello World")) { /* do something */ } ``` ### Options - **StringLikeClasses** Semicolon-separated list of names of string-like classes. By default includes **::std::basic\_string**, **::std::basic\_string\_view**, and **::absl::string\_view**. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **AbseilStringsMatchHeader** The location of Abseil's **strings/match.h**. Defaults to **absl/strings/match.h**. ### abseil-time-comparison Prefer comparisons in the **absl::Time** domain instead of the integer domain. N.B.: In cases where an **absl::Time** is being converted to an integer, alignment may occur. If the comparison depends on this alignment, doing the comparison in the **absl::Time** domain may yield a different result. In practice this is very rare, and still indicates a bug which should be fixed. Examples: ``` // Original - Comparison in the integer domain int x; absl::Time t; if (x < absl::ToUnixSeconds(t)) ... // Suggested - Compare in the absl::Time domain instead if (absl::FromUnixSeconds(x) < t) ... ``` ### abseil-time-subtraction Finds and fixes **absl::Time** subtraction expressions to do subtraction in the Time domain instead of the numeric domain. There are two cases of Time subtraction in which deduce additional type information: - • When the result is an **absl::Duration** and the first argument is an **absl::Time**. - • When the second argument is a **absl::Time**. In the first case, we must know the result of the operation, since without that the second operand could be either an **absl::Time** or an **absl::Duration**. In the second case, the first operand *must* be an **absl::Time**, because subtracting an **absl::Time** from an **absl::Duration** is not defined. Examples: ``` int x; absl::Time t; // Original - absl::Duration result and first operand is an absl::Time. absl::Duration d = absl::Seconds(absl::ToUnixSeconds(t) - x); // Suggestion - Perform subtraction in the Time domain instead. absl::Duration d = t - absl::FromUnixSeconds(x); // Original - Second operand is an absl::Time. int i = x - absl::ToUnixSeconds(t); // Suggestion - Perform subtraction in the Time domain instead. int i = absl::ToInt64Seconds(absl::FromUnixSeconds(x) - t); ``` ### abseil-unchecked-statusor-access This check identifies unsafe accesses to values contained in **absl::StatusOr\** objects. Below we will refer to this type as **StatusOr\**. An access to the value of an **StatusOr\** occurs when one of its **value**, **operator\***, or **operator-\>** member functions is invoked. To align with common misconceptions, the check considers these member functions as equivalent, even though there are subtle differences related to exceptions vs. undefined behavior. An access to the value of a **StatusOr\** is considered safe if and only if code in the local scope (e.g. function body) ensures that the status of the **StatusOr\** is ok in all possible execution paths that can reach the access. That should happen either through an explicit check, using the **StatusOr\::ok** member function, or by constructing the **StatusOr\** in a way that shows that its status is unambiguously ok (e.g. by passing a value to its constructor). Below we list some examples of safe and unsafe **StatusOr\** access patterns. Note: If the check isn't behaving as you would have expected on a code snippet, please report it \. ### False negatives This check generally does **not** generate false negatives. That means that if an access is not marked as unsafe, it is provably safe. If it cannot prove an access safe, it is assumed to be unsafe. In some cases, the static analysis cannot prove an access safe even though it is, for a variety of reasons (e.g. unmodelled invariants of functions called). In these cases, the analysis does produce false positive reports. That being said, there are some heuristics used that in very rare cases might be incorrect: - • a const method accessor (without arguments) that returns different values when called multiple times \<#functionstability\>. If you think the check generated a false negative, please report it \. ### Known limitations This is a non-exhaustive list of constructs that are currently not modelled in the check and will lead to false positives: - • Checking a StatusOr and then capturing it in a lambda \<#lambdas\> - • Indexing into a container with the same index \<#containers\> - • Project specific helper-functions \<#uncommonapi\>, - • Functions with a stable return value \<#functionstability\> - • **Any** cross-function reasoning \<#crossfunction\>. This is by design and will not change in the future. ### Checking if the status is ok, then accessing the value The check recognizes all straightforward ways for checking the status and accessing the value contained in a **StatusOr\** object. For example: ``` void f(absl::StatusOr x) { if (x.ok()) { use(*x); } } ``` ### Checking if the status is ok, then accessing the value from a copy The criteria that the check uses is semantic, not syntactic. It recognizes when a copy of the **StatusOr\** object being accessed is known to have ok status. For example: ``` void f(absl::StatusOr x1) { if (x1.ok()) { absl::optional x2 = x1; use(*x2); } } ``` ### Ensuring that the status is ok using common macros The check is aware of common macros like **ABSL\_CHECK** or **ABSL\_CHECK\_OK**. Those can be used to ensure that the status of a **StatusOr\** object is ok. For example: ``` void f(absl::StatusOr x) { ABSL_CHECK_OK(x); use(*x); } ``` ### Ensuring that the status is ok using googletest macros The check is aware of **googletest** (or **gtest**) macros and matchers. Accessing the value of a **StatusOr\** object is considered safe if it is preceded by an **ASSERT\_** macro that ensures the status is ok. For example: ``` TEST(MySuite, MyTest) { absl::StatusOr x = foo(); ASSERT_OK(x); use(*x); } TEST(MySuite, MyOtherTest) { absl::StatusOr x = foo(); ASSERT_THAT(x, absl_testing::IsOk()); use(*x); } ``` The following **googletest** macros are supported: - • **ASSERT\_OK(...)** - • **ASSERT\_TRUE(...)** - • **ASSERT\_FALSE(...)** - • **ASSERT\_THAT(...)** The following matchers are supported: - • **IsOk()** - • **StatusIs(...)** - • **IsOkAndHolds(...)** - • **CanonicalStatusIs(...)** **Note**: **EXPECT\_** macros (like **EXPECT\_OK** or **EXPECT\_TRUE(x.ok())**) do **not** make subsequent accesses safe because they do not terminate the test execution. ### Ensuring that the status is ok, then accessing the value in a correlated branch The check is aware of correlated branches in the code and can figure out when a **StatusOr\** object is ensured to have ok status on all execution paths that lead to an access. For example: ``` void f(absl::StatusOr x) { bool safe = false; if (x.ok() && SomeOtherCondition()) { safe = true; } // ... more code... if (safe) { use(*x); } } ``` ### Accessing the value without checking the status The check flags accesses to the value that are not locally guarded by a status check: ``` void f1(absl::StatusOr x) { use(*x); // unsafe: it is unclear whether the status of `x` is ok. } void f2(absl::StatusOr x) { use(x->member); // unsafe: it is unclear whether the status of `x` is ok. } void f3(absl::StatusOr x) { use(x.value()); // unsafe: it is unclear whether the status of `x` is ok. } ``` Use **ABSL\_CHECK\_OK** to signal that you knowingly want to crash on non-OK values. NOTE: Even though using **.value()** on a non-**ok()** **StatusOr** is defined to crash, it is often unintentional. That is why our checker flags those as well. ### Accessing the value in the wrong branch The check is aware of the state of a **StatusOr\** object in different branches of the code. For example: ``` void f(absl::StatusOr x) { if (x.ok()) { } else { use(*x); // unsafe: it is clear that the status of `x` is *not* ok. } } ``` ### Assuming a function result to be stable The check is aware that function results might not be stable. That is, consecutive calls to the same function might return different values. For example: ``` void f(Foo foo) { if (foo.x().ok()) { use(*foo.x()); // unsafe: it is unclear whether the status of `foo.x()` is ok. } } ``` In such cases it is best to store the result of the function call in a local variable and use it to access the value. For example: ``` void f(Foo foo) { if (const auto& x = foo.x(); x.ok()) { use(*x); } } ``` The check **does** assume that **const**-qualified accessor functions return a stable value if no non-const function was called between the two calls: ``` class Foo { const absl::StatusOr& get() const { [...]; } } void f(Foo foo) { if (foo.get().ok()) { use(*foo.get()); } } ``` If there is a call to a non-**const**-qualified function, the check assumes the return value of the accessor was mutated. ``` class Foo { const absl::StatusOr& get() const { [...]; } void mutate(); } void f(Foo foo) { if (foo.get().ok()) { foo.mutate(); use(*foo.get()); // unsafe: `mutate()` might have changed the state of the object } } ``` ### Relying on invariants of uncommon APIs The check is unaware of invariants of uncommon APIs. For example: ``` void f(Foo foo) { if (foo.HasProperty("bar")) { use(*foo.GetProperty("bar")); // unsafe: it is unclear whether the status of `foo.GetProperty("bar")` is ok. } } ``` In such cases it is best to check explicitly that the status of the **StatusOr\** object is ok. For example: ``` void f(Foo foo) { if (const auto& property = foo.GetProperty("bar"); property.ok()) { use(*property); } } ``` ### Checking if the StatusOr\ is ok, then passing it to another function The check relies on local reasoning. The check and value access must both happen in the same function. An access is considered unsafe even if the caller of the function performing the access ensures that the status of the **StatusOr\** is ok. For example: ``` void g(absl::StatusOr x) { use(*x); // unsafe: it is unclear whether the status of `x` is ok. } void f(absl::StatusOr x) { if (x.ok()) { g(x); } } ``` In such cases it is best to either pass the value directly when calling a function or check that the status of the **StatusOr\** is ok in the local scope of the callee. For example: ``` void g(int val) { use(val); } void f(absl::StatusOr x) { if (x.ok()) { g(*x); } } ``` ### Aliases created via using declarations The check is aware of aliases of **StatusOr\** types that are created via **using** declarations. For example: ``` using StatusOrInt = absl::StatusOr; void f(StatusOrInt x) { use(*x); // unsafe: it is unclear whether the status of `x` is ok. } ``` ### Containers The check is more strict than necessary when it comes to containers of **StatusOr\** values. Simply checking that the status of an element of a container is ok is not sufficient to deem accessing it safe. For example: ``` void f(std::vector> x) { if (x[0].ok()) { use(*x[0]); // unsafe: it is unclear whether the status of `x[0]` is ok. } } ``` One needs to grab a reference to a particular object and use that instead: ``` void f(std::vector> x) { absl::StatusOr& x0 = x[0]; if (x0.ok()) { use(*x0); } } ``` A future version could improve the understanding of more safe usage patterns that involve containers. ### Lambdas The check is capable of reporting unsafe **StatusOr\** accesses in lambdas, but isn’t smart enough to propagate information from the surrounding context through the lambda. This means that the following pattern will be reported as an unsafe access: ``` void f(absl::StatusOr x) { if (x.ok()) { [&x]() { use(*x); // unsafe: it is unclear whether the status of `x` is ok. } } } ``` To avoid the issue, you should instead capture the contained object, either by value or by reference. An init-capture is useful for this, here capturing by reference: ``` void f(absl::StatusOr x) { if (x.ok()) { [&x = *x]() { use(x); } } } ``` Alternatively you could add a check inside the lambda where the value is accessed: ``` void f(absl::StatusOr x) { [&x]() { if (x.ok()) { use(*x); } } } ``` ### Reasoning about integers Because it uses a simple SAT solver, the check cannot reason about integer inequalities. For instance, the following will result in a false positive: ``` void f(int n, absl::StatusOr x) { if (n > 0) CHECK_OK(x); if (n > 1) return *x; // false positive return 0; } ``` In fact, currently this is also the case if the two conditions are identical. ### abseil-upgrade-duration-conversions Finds calls to **absl::Duration** arithmetic operators and factories whose argument needs an explicit cast to continue compiling after upcoming API changes. The operators **\*=**, **/=**, **\***, and **/** for **absl::Duration** currently accept an argument of class type that is convertible to an arithmetic type. Such a call currently converts the value to an **int64\_t**, even in a case such as **std::atomic\** that would result in lossy conversion. Additionally, the **absl::Duration** factory functions (**absl::Hours**, **absl::Minutes**, etc) currently accept an **int64\_t** or a floating-point type. Similar to the arithmetic operators, calls with an argument of class type that is convertible to an arithmetic type go through the **int64\_t** path. These operators and factories will be changed to only accept arithmetic types to prevent unintended behavior. After these changes are released, passing an argument of class type will no longer compile, even if the type is implicitly convertible to an arithmetic type. Here are example fixes created by this check: ``` std::atomic a; absl::Duration d = absl::Milliseconds(a); d *= a; ``` becomes ``` std::atomic a; absl::Duration d = absl::Milliseconds(static_cast(a)); d *= static_cast(a); ``` Note that this check always adds a cast to **int64\_t** in order to preserve the current behavior of user code. It is possible that this uncovers unintended behavior due to types implicitly convertible to a floating-point type. ### altera-id-dependent-backward-branch Finds ID-dependent variables and fields that are used within loops. This causes branches to occur inside the loops, and thus leads to performance degradation. ``` // The following code will produce a warning because this ID-dependent // variable is used in a loop condition statement. int ThreadID = get_local_id(0); // The following loop will produce a warning because the loop condition // statement depends on an ID-dependent variable. for (int i = 0; i < ThreadID; ++i) { std::cout << i << std::endl; } // The following loop will not produce a warning, because the ID-dependent // variable is not used in the loop condition statement. for (int i = 0; i < 100; ++i) { std::cout << ThreadID << std::endl; } ``` Based on the Altera SDK for OpenCL: Best Practices Guide \. ### altera-kernel-name-restriction Finds kernel files and include directives whose filename is *kernel.cl*, *Verilog.cl*, or *VHDL.cl*. The check is case insensitive. Such kernel file names cause the offline compiler to generate intermediate design files that have the same names as certain internal files, which leads to a compilation error. Based on the *Guidelines for Naming the Kernel* section in the Intel FPGA SDK for OpenCL Pro Edition: Programming Guide \. ### altera-single-work-item-barrier Finds OpenCL kernel functions that call a barrier function but do not call an ID function (**get\_local\_id**, **get\_local\_id**, **get\_group\_id**, or **get\_local\_linear\_id**). These kernels may be viable single work-item kernels, but will be forced to execute as NDRange kernels if using a newer version of the Altera Offline Compiler (\>= v17.01). If using an older version of the Altera Offline Compiler, these kernel functions will be treated as single work-item kernels, which could be inefficient or lead to errors if NDRange semantics were intended. Based on the Altera SDK for OpenCL: Best Practices Guide \. Examples: ``` // error: function calls barrier but does not call an ID function. void __kernel barrier_no_id(__global int * foo, int size) { for (int i = 0; i < 100; i++) { foo[i] += 5; } barrier(CLK_GLOBAL_MEM_FENCE); } // ok: function calls barrier and an ID function. void __kernel barrier_with_id(__global int * foo, int size) { for (int i = 0; i < 100; i++) { int tid = get_global_id(0); foo[tid] += 5; } barrier(CLK_GLOBAL_MEM_FENCE); } // ok with AOC Version 17.01: the reqd_work_group_size turns this into // an NDRange. __attribute__((reqd_work_group_size(2,2,2))) void __kernel barrier_with_id(__global int * foo, int size) { for (int i = 0; i < 100; i++) { foo[tid] += 5; } barrier(CLK_GLOBAL_MEM_FENCE); } ``` ### Options - **AOCVersion** Defines the version of the Altera Offline Compiler. Defaults to **1600** (corresponding to version 16.00). ### altera-struct-pack-align Finds structs that are inefficiently packed or aligned, and recommends packing and/or aligning of said structs as needed. Structs that are not packed take up more space than they should, and accessing structs that are not well aligned is inefficient. Fix-its are provided to fix both of these issues by inserting and/or amending relevant struct attributes. Based on the Altera SDK for OpenCL: Best Practices Guide \. ``` // The following struct is originally aligned to 4 bytes, and thus takes up // 12 bytes of memory instead of 10. Packing the struct will make it use // only 10 bytes of memory, and aligning it to 16 bytes will make it // efficient to access. struct example { char a; // 1 byte double b; // 8 bytes char c; // 1 byte }; // The following struct is arranged in such a way that packing is not needed. // However, it is aligned to 4 bytes instead of 8, and thus needs to be // explicitly aligned. struct implicitly_packed_example { char a; // 1 byte char b; // 1 byte char c; // 1 byte char d; // 1 byte int e; // 4 bytes }; // The following struct is explicitly aligned and packed. struct good_example { char a; // 1 byte double b; // 8 bytes char c; // 1 byte } __attribute__((packed)) __attribute__((aligned(16)); // Explicitly aligning a struct to the wrong value will result in a warning. // The following example should be aligned to 16 bytes, not 32. struct badly_aligned_example { char a; // 1 byte double b; // 8 bytes char c; // 1 byte } __attribute__((packed)) __attribute__((aligned(32))); ``` ### altera-unroll-loops Finds inner loops that have not been unrolled, as well as fully unrolled loops with unknown loop bounds or a large number of iterations. Unrolling inner loops could improve the performance of OpenCL kernels. However, if they have unknown loop bounds or a large number of iterations, they cannot be fully unrolled, and should be partially unrolled. Notes: - • This check is unable to determine the number of iterations in a **while** or **do..while** loop; hence if such a loop is fully unrolled, a note is emitted advising the user to partially unroll instead. - • In **for** loops, our check only works with simple arithmetic increments ( **+**, **-**, **\***, **/**). For all other increments, partial unrolling is advised. - • Depending on the exit condition, the calculations for determining if the number of iterations is large may be off by 1. This should not be an issue since the cut-off is generally arbitrary. Based on the Altera SDK for OpenCL: Best Practices Guide \. ``` for (int i = 0; i < 10; i++) { // ok: outer loops should not be unrolled int j = 0; do { // warning: this inner do..while loop should be unrolled j++; } while (j < 15); int k = 0; #pragma unroll while (k < 20) { // ok: this inner loop is already unrolled k++; } } int A[1000]; #pragma unroll // warning: this loop is large and should be partially unrolled for (int a : A) { printf("%d", a); } #pragma unroll 5 // ok: this loop is large, but is partially unrolled for (int a : A) { printf("%d", a); } #pragma unroll // warning: this loop is large and should be partially unrolled for (int i = 0; i < 1000; ++i) { printf("%d", i); } #pragma unroll 5 // ok: this loop is large, but is partially unrolled for (int i = 0; i < 1000; ++i) { printf("%d", i); } #pragma unroll // warning: << operator not supported, recommend partial unrolling for (int i = 0; i < 1000; i<<1) { printf("%d", i); } std::vector someVector (100, 0); int i = 0; #pragma unroll // note: loop may be large, recommend partial unrolling while (i < someVector.size()) { someVector[i]++; } #pragma unroll // note: loop may be large, recommend partial unrolling while (true) { printf("In loop"); } #pragma unroll 5 // ok: loop may be large, but is partially unrolled while (i < someVector.size()) { someVector[i]++; } ``` ### Options - **MaxLoopIterations** Defines the maximum number of loop iterations that a fully unrolled loop can have. By default, it is set to *100*. In practice, this refers to the integer value of the upper bound within the loop statement's condition expression. ### android-cloexec-accept The usage of **accept()** is not recommended, it's better to use **accept4()**. Without this flag, an opened sensitive file descriptor would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` accept(sockfd, addr, addrlen); // becomes accept4(sockfd, addr, addrlen, SOCK_CLOEXEC); ``` ### android-cloexec-accept4 **accept4()** should include **SOCK\_CLOEXEC** in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` accept4(sockfd, addr, addrlen, SOCK_NONBLOCK); // becomes accept4(sockfd, addr, addrlen, SOCK_NONBLOCK | SOCK_CLOEXEC); ``` ### android-cloexec-creat The usage of **creat()** is not recommended, it's better to use **open()**. Examples: ``` int fd = creat(path, mode); // becomes int fd = open(path, O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC, mode); ``` ### android-cloexec-dup The usage of **dup()** is not recommended, it's better to use **fcntl()**, which can set the close-on-exec flag. Otherwise, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` int fd = dup(oldfd); // becomes int fd = fcntl(oldfd, F_DUPFD_CLOEXEC); ``` ### android-cloexec-epoll-create The usage of **epoll\_create()** is not recommended, it's better to use **epoll\_create1()**, which allows close-on-exec. Examples: ``` epoll_create(size); // becomes epoll_create1(EPOLL_CLOEXEC); ``` ### android-cloexec-epoll-create1 **epoll\_create1()** should include **EPOLL\_CLOEXEC** in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` epoll_create1(0); // becomes epoll_create1(EPOLL_CLOEXEC); ``` ### android-cloexec-fopen **fopen()** should include **e** in their mode string; so **re** would be valid. This is equivalent to having set **FD\_CLOEXEC on** that descriptor. Examples: ``` fopen("fn", "r"); // becomes fopen("fn", "re"); ``` ### android-cloexec-inotify-init The usage of **inotify\_init()** is not recommended, it's better to use **inotify\_init1()**. Examples: ``` inotify_init(); // becomes inotify_init1(IN_CLOEXEC); ``` ### android-cloexec-inotify-init1 **inotify\_init1()** should include **IN\_CLOEXEC** in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` inotify_init1(IN_NONBLOCK); // becomes inotify_init1(IN_NONBLOCK | IN_CLOEXEC); ``` ### android-cloexec-memfd-create **memfd\_create()** should include **MFD\_CLOEXEC** in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` memfd_create(name, MFD_ALLOW_SEALING); // becomes memfd_create(name, MFD_ALLOW_SEALING | MFD_CLOEXEC); ``` ### android-cloexec-open A common source of security bugs is code that opens a file without using the **O\_CLOEXEC** flag. Without that flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain, leaking that sensitive data. Open-like functions including **open()**, **openat()**, and **open64()** should include **O\_CLOEXEC** in their flags argument. Examples: ``` open("filename", O_RDWR); open64("filename", O_RDWR); openat(0, "filename", O_RDWR); // becomes open("filename", O_RDWR | O_CLOEXEC); open64("filename", O_RDWR | O_CLOEXEC); openat(0, "filename", O_RDWR | O_CLOEXEC); ``` ### android-cloexec-pipe This check detects usage of **pipe()**. Using **pipe()** is not recommended, **pipe2()** is the suggested replacement. The check also adds the **O\_CLOEXEC** flag that marks the file descriptor to be closed in child processes. Without this flag a sensitive file descriptor can be leaked to a child process, potentially into a lower-privileged SELinux domain. Examples: ``` pipe(pipefd); ``` Suggested replacement: ``` pipe2(pipefd, O_CLOEXEC); ``` ### android-cloexec-pipe2 This check ensures that **pipe2()** is called with the **O\_CLOEXEC** flag. The check also adds the **O\_CLOEXEC** flag that marks the file descriptor to be closed in child processes. Without this flag a sensitive file descriptor can be leaked to a child process, potentially into a lower-privileged SELinux domain. Examples: ``` pipe2(pipefd, O_NONBLOCK); ``` Suggested replacement: ``` pipe2(pipefd, O_NONBLOCK | O_CLOEXEC); ``` ### android-cloexec-socket **socket()** should include **SOCK\_CLOEXEC** in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: ``` socket(domain, type, SOCK_STREAM); // becomes socket(domain, type, SOCK_STREAM | SOCK_CLOEXEC); ``` ### android-comparison-in-temp-failure-retry Diagnoses comparisons that appear to be incorrectly placed in the argument to the **TEMP\_FAILURE\_RETRY** macro. Having such a use is incorrect in the vast majority of cases, and will often silently defeat the purpose of the **TEMP\_FAILURE\_RETRY** macro. For context, **TEMP\_FAILURE\_RETRY** is a convenience macro \ provided by both glibc and Bionic. Its purpose is to repeatedly run a syscall until it either succeeds, or fails for reasons other than being interrupted. Example buggy usage looks like: ``` char cs[1]; while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs)) != 0)) { // Do something with cs. } ``` Because **TEMP\_FAILURE\_RETRY** will check for whether the result *of the comparison* is **-1**, and retry if so. If you encounter this, the fix is simple: lift the comparison out of the **TEMP\_FAILURE\_RETRY** argument, like so: ``` char cs[1]; while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs))) != 0) { // Do something with cs. } ``` ### Options - **RetryMacros** A comma-separated list of the names of retry macros to be checked. Default is *TEMP\_FAILURE\_RETRY*. ### boost-use-ranges Detects calls to standard library iterator algorithms that could be replaced with a Boost ranges version instead. ### Example ``` auto Iter1 = std::find(Items.begin(), Items.end(), 0); auto AreSame = std::equal(Items1.cbegin(), Items1.cend(), std::begin(Items2), std::end(Items2)); ``` Transforms to: ``` auto Iter1 = boost::range::find(Items, 0); auto AreSame = boost::range::equal(Items1, Items2); ``` ### Supported algorithms Calls to the following std library algorithms are checked: **std::accumulate**, **std::adjacent\_difference**, **std::adjacent\_find**, **std::all\_of**, **std::any\_of**, **std::binary\_search**, **std::copy\_backward**, **std::copy\_if**, **std::copy**, **std::count\_if**, **std::count**, **std::equal\_range**, **std::equal**, **std::fill**, **std::find\_end**, **std::find\_first\_of**, **std::find\_if\_not**, **std::find\_if**, **std::find**, **std::for\_each**, **std::generate**, **std::includes**, **std::iota**, **std::is\_partitioned**, **std::is\_permutation**, **std::is\_sorted\_until**, **std::is\_sorted**, **std::lexicographical\_compare**, **std::lower\_bound**, **std::make\_heap**, **std::max\_element**, **std::merge**, **std::min\_element**, **std::mismatch**, **std::next\_permutation**, **std::none\_of**, **std::partial\_sum**, **std::partial\_sort\_copy**, **std::partition\_copy**, **std::partition\_point**, **std::partition**, **std::pop\_heap**, **std::prev\_permutation**, **std::push\_heap**, **std::random\_shuffle**, **std::reduce**, **std::remove\_copy\_if**, **std::remove\_copy**, **std::remove\_if**, **std::remove**, **std::replace\_copy\_if**, **std::replace\_copy**, **std::replace\_if**, **std::replace**, **std::reverse\_copy**, **std::reverse**, **std::search**, **std::set\_difference**, **std::set\_intersection**, **std::set\_symmetric\_difference**, **std::set\_union**, **std::sort\_heap**, **std::sort**, **std::stable\_partition**, **std::stable\_sort**, **std::transform**, **std::unique\_copy**, **std::unique**, **std::upper\_bound**. The check will also look for the following functions from the **boost::algorithm** namespace: **all\_of\_equal**, **any\_of\_equal**, **any\_of**, **apply\_permutation**, **apply\_reverse\_permutation**, **clamp\_range**, **copy\_if\_until**, **copy\_if\_while**, **copy\_if**, **copy\_until**, **copy\_while**, **find\_backward**, **find\_if\_backward**, **find\_if\_not\_backward**, **find\_if\_not**, **find\_not\_backward**, **hex\_lower**, **hex**, **iota**, **all\_of**, **is\_decreasing**, **is\_increasing**, **is\_palindrome**, **is\_partitioned\_until**, **is\_partitioned**, **is\_permutation**, **is\_sorted\_until**, **is\_sorted**, **is\_strictly\_decreasing**, **is\_strictly\_increasing**, **none\_of\_equal**, **none\_of**, **one\_of\_equal**, **one\_of**, **partition\_copy**, **partition\_point**, **reduce**, **unhex**. ### Reverse Iteration If calls are made using reverse iterators on containers, The code will be fixed using the **boost::adaptors::reverse** adaptor. ``` auto AreSame = std::equal(Items1.rbegin(), Items1.rend(), std::crbegin(Items2), std::crend(Items2)); ``` Transforms to: ``` auto AreSame = boost::range::equal(boost::adaptors::reverse(Items1), boost::adaptors::reverse(Items2)); ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **IncludeBoostSystem** If *true* (default value) the boost headers are included as system headers with angle brackets (*#include \*), otherwise quotes are used (*#include "boost.hpp"*). - **UseReversePipe** When *true* (default *false*), fixes which involve reverse ranges will use the pipe adaptor syntax instead of the function syntax. ``` std::find(Items.rbegin(), Items.rend(), 0); ``` Transforms to: ``` boost::range::find(Items | boost::adaptors::reversed, 0); ``` ### boost-use-to-string This check finds conversion from integer type like **int** to **std::string** or **std::wstring** using **boost::lexical\_cast**, and replace it with calls to **std::to\_string** and **std::to\_wstring**. It doesn't replace conversion from floating points despite the **to\_string** overloads, because it would change the behavior. ``` auto str = boost::lexical_cast(42); auto wstr = boost::lexical_cast(2137LL); // Will be changed to auto str = std::to_string(42); auto wstr = std::to_wstring(2137LL); ``` ### bugprone-argument-comment Checks that argument comments match parameter names and can optionally add missing comments for literals, init-lists, and constructed temporaries. The check understands argument comments in the form **/\*parameter\_name=\*/** that are placed right before the argument. ``` void f(bool foo); ... f(/*bar=*/true); // warning: argument name 'bar' in comment does not match parameter name 'foo' ``` The check tries to detect typos and suggest automated fixes for them. It can also insert missing comments for configured argument kinds. ### Options - **StrictMode** When *false*, the check will ignore leading and trailing underscores and case when comparing names -- otherwise they are taken into account. Default is *false*. - **IgnoreSingleArgument** When *true*, the check will ignore the single argument. Default is *false*. - **CommentAnonymousInitLists** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before anonymous braced-init list arguments such as **{}** and **{1, 2, 3}**. Default is *false*. Before: ``` void foo(const std::vector &Dims); foo({}); ``` After: ``` void foo(const std::vector &Dims); foo(/*Dims=*/{}); ``` - **CommentBoolLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the boolean literal argument. Default is *false*. Before: ``` void foo(bool TurnKey, bool PressButton); foo(true, false); ``` After: ``` void foo(bool TurnKey, bool PressButton); foo(/*TurnKey=*/true, /*PressButton=*/false); ``` - **CommentCharacterLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the character literal argument. Default is *false*. Before: ``` void foo(char *Character); foo('A'); ``` After: ``` void foo(char *Character); foo(/*Character=*/'A'); ``` - **CommentFloatLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the float/double literal argument. Default is *false*. Before: ``` void foo(float Pi); foo(3.14159); ``` After: ``` void foo(float Pi); foo(/*Pi=*/3.14159); ``` - **CommentIntegerLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the integer literal argument. Default is *false*. Before: ``` void foo(int MeaningOfLife); foo(42); ``` After: ``` void foo(int MeaningOfLife); foo(/*MeaningOfLife=*/42); ``` - **CommentNullPtrs** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the nullptr literal argument. Default is *false*. Before: ``` void foo(A* Value); foo(nullptr); ``` After: ``` void foo(A* Value); foo(/*Value=*/nullptr); ``` - **CommentParenthesizedTemporaries** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before explicit temporary constructions such as **Type()** and **Type(1, 2, 3)**. Default is *false*. Before: ``` struct Dims { Dims(); Dims(int, int, int); }; void foo(const Dims &DimsValue); foo(Dims()); foo(Dims(1, 2, 3)); ``` After: ``` struct Dims { Dims(); Dims(int, int, int); }; void foo(const Dims &DimsValue); foo(/*DimsValue=*/Dims()); foo(/*DimsValue=*/Dims(1, 2, 3)); ``` - **CommentStringLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the string literal argument. Default is *false*. Before: ``` void foo(const char *String); void foo(const wchar_t *WideString); foo("Hello World"); foo(L"Hello World"); ``` After: ``` void foo(const char *String); void foo(const wchar_t *WideString); foo(/*String=*/"Hello World"); foo(/*WideString=*/L"Hello World"); ``` - **CommentTypedInitLists** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before typed braced-init list arguments such as **Type{}**. Default is *false*. Before: ``` void foo(const std::vector &Dims); foo(std::vector{}); ``` After: ``` void foo(const std::vector &Dims); foo(/*Dims=*/std::vector{}); ``` - **CommentUserDefinedLiterals** When *true*, the check will add argument comments in the format **/\*ParameterName=\*/** right before the user defined literal argument. Default is *false*. Before: ``` void foo(double Distance); double operator"" _km(long double); foo(402.0_km); ``` After: ``` void foo(double Distance); double operator"" _km(long double); foo(/*Distance=*/402.0_km); ``` ### bugprone-assert-side-effect Finds **assert()** with side effect. The condition of **assert()** is evaluated only in debug builds so a condition with side effect can cause different behavior in debug / release builds. ### Options - **AssertMacros** A comma-separated list of the names of assert macros to be checked. Default is *assert,NSAssert,NSCAssert*. - **CheckFunctionCalls** Whether to treat non-const member and non-member functions as they produce side effects. Disabled by default because it can increase the number of false positive warnings. - **IgnoredFunctions** A semicolon-separated list of the names of functions or methods to be considered as not having side-effects. Regular expressions are accepted, e.g. **\[Rr\]ef(erence)?$** matches every type with suffix **Ref**, **ref**, **Reference** and **reference**. The default is empty. If a name in the list contains the sequence *::* it is matched against the qualified type name (i.e. **namespace::Type**), otherwise it is matched against only the type name (i.e. **Type**). ### bugprone-assignment-in-if-condition Finds assignments within conditions of *if* statements. Such assignments are bug-prone because they may have been intended as equality tests. This check finds all assignments within *if* conditions, including ones that are not flagged by *-Wparentheses* due to an extra set of parentheses, and including assignments that call an overloaded **operator=()**. The identified assignments violate BARR group "Rule 8.2.c" \. ``` int f = 3; if(f = 4) { // This is identified by both `Wparentheses` and this check - should it have been: `if (f == 4)` ? f = f + 1; } if((f == 5) || (f = 6)) { // the assignment here `(f = 6)` is identified by this check, but not by `-Wparentheses`. Should it have been `(f == 6)` ? f = f + 2; } ``` ### bugprone-assignment-in-selection-statement Finds assignments within selection statements. Such assignments may indicate programmer error because they may have been intended as equality tests. The selection statements are conditions of **if** and loop (**for**, **while**, **do**) statements, condition of conditional operator (**?:**) and any operand of a binary logical operator (**&&**, **\|\|**). The check finds assignments within these contexts if the single expression is an assignment or the assignment is contained (recursively) in last operand of a comma (**,**) operator or true and false expressions in a conditional operator. The warning is suppressed if the assignment is placed in extra parentheses, but only if the assignment is the single expression of a condition (of **if** or a loop statement). This check corresponds to the CERT rule EXP45-C. Do not perform assignments in selection statements \. ### Examples The check emits a warning in the following cases at the indicated locations: ``` int x = 3; if (x = 4) // should it be `x == 4` instead of 'x = 4' ? x = x + 1; while ((x <= 11) || (x = 22)) // assignment appears as operand of a logical operator x += 2; do { x += 5; } while ((x > 10) ? (x = 11) : (x > 5)); // assignment in loop condition (from `x = 11`) for (int i = 0; i == 2, x = 5; ++i) // assignment in loop condition (from last operand of comma) foo1(i, x); for (int i = 0; i == 2, (x = 5); ++i) // assignment is not a single expression, parentheses do not prevent the warning foo1(i, x); int a = (x == 2) || (x = 3); // assignment appears in the operand a logical operator ``` The following cases do not produce a warning: ``` if ((x = 1)) { // a single assignment between parentheses x += 10; if ((x = 1) != 0) { // assignment appears in a complex expression and without a logical operator ++x; if (foo(x = 9) && array[x = 8]) { // assignment appears in argument of function call or array index ++x; for (int i = 0; i = 2, x == 5; ++i) // assignment does not take part in the condition of the loop foo1(i, x); ``` ### bugprone-bad-signal-to-kill-thread Finds **pthread\_kill** function calls when a thread is terminated by raising **SIGTERM** signal and the signal kills the entire process, not just the individual thread. Use any signal except **SIGTERM**. ``` pthread_kill(thread, SIGTERM); ``` This check corresponds to the CERT C Coding Standard rule POS44-C. Do not use signals to terminate threads \. *cert-pos44-c* redirects here as an alias of this check. ### bugprone-bitwise-pointer-cast Warns about code that tries to cast between pointers by means of **std::bit\_cast** or **memcpy**. The motivation is that **std::bit\_cast** is advertised as the safe alternative to type punning via **reinterpret\_cast** in modern C++. However, one should not blindly replace **reinterpret\_cast** with **std::bit\_cast**, as follows: ``` int x{}; -float y = *reinterpret_cast(&x); +float y = *std::bit_cast(&x); ``` The drop-in replacement behaves exactly the same as **reinterpret\_cast**, and Undefined Behavior is still invoked. **std::bit\_cast** is copying the bytes of the input pointer, not the pointee, into an output pointer of a different type, which may violate the strict aliasing rules. However, simply looking at the code, it looks "safe", because it uses **std::bit\_cast** which is advertised as safe. The solution to safe type punning is to apply **std::bit\_cast** on value types, not on pointer types: ``` int x{}; float y = std::bit_cast(x); ``` This way, the bytes of the input object are copied into the output object, which is much safer. Do note that Undefined Behavior can still occur, if there is no value of type **To** corresponding to the value representation produced. Compilers may be able to optimize this copy and generate identical assembly to the original **reinterpret\_cast** version. Code before C++20 may backport **std::bit\_cast** by means of **memcpy**, or simply call **memcpy** directly, which is equally problematic. This is also detected by this check: ``` int* x{}; float* y{}; std::memcpy(&y, &x, sizeof(x)); ``` Alternatively, if a cast between pointers is truly wanted, **reinterpret\_cast** should be used, to clearly convey the intent and enable warnings from compilers and linters, which should be addressed accordingly. ### bugprone-bool-pointer-implicit-conversion Checks for conditions based on implicit conversion from a **bool** pointer to **bool**. Example: ``` bool *p; if (p) { // Never used in a pointer-specific way. } ``` ### bugprone-branch-clone Checks for repeated branches in **if/else if/else** chains, consecutive repeated branches in **switch** statements and identical true and false branches in conditional operators. ``` if (test_value(x)) { y++; do_something(x, y); } else { y++; do_something(x, y); } ``` In this simple example (which could arise e.g. as a copy-paste error) the **then** and **else** branches are identical and the code is equivalent the following shorter and cleaner code: ``` test_value(x); // can be omitted unless it has side effects y++; do_something(x, y); ``` If this is the intended behavior, then there is no reason to use a conditional statement; otherwise the issue can be solved by fixing the branch that is handled incorrectly. The check detects repeated branches in longer **if/else if/else** chains where it would be even harder to notice the problem. The check also detects repeated inner and outer **if** statements that may be a result of a copy-paste error. This check cannot currently detect identical inner and outer **if** statements if code is between the **if** conditions. An example is as follows. ``` void test_warn_inner_if_1(int x) { if (x == 1) { // warns, if with identical inner if if (x == 1) // inner if is here ; if (x == 1) { // does not warn, cannot detect int y = x; if (x == 1) ; } } ``` In **switch** statements the check only reports repeated branches when they are consecutive, because it is relatively common that the **case:** labels have some natural ordering and rearranging them would decrease the readability of the code. For example: ``` switch (ch) { case 'a': return 10; case 'A': return 10; case 'b': return 11; case 'B': return 11; default: return 10; } ``` Here the check reports that the **'a'** and **'A'** branches are identical (and that the **'b'** and **'B'** branches are also identical), but does not report that the **default:** branch is also identical to the first two branches. If this is indeed the correct behavior, then it could be implemented as: ``` switch (ch) { case 'a': case 'A': return 10; case 'b': case 'B': return 11; default: return 10; } ``` Here the check does not warn for the repeated **return 10;**, which is good if we want to preserve that **'a'** is before **'b'** and **default:** is the last branch. Switch cases marked with the **\[\[fallthrough\]\]** attribute are ignored. Finally, the check also examines conditional operators and reports code like: ``` return test_value(x) ? x : x; ``` Unlike if statements, the check does not detect chains of conditional operators. Note: This check also reports situations where branches become identical only after preprocessing. ### bugprone-capturing-this-in-member-variable Finds lambda captures that capture the **this** pointer and store it as class members without handle the copy and move constructors and the assignments. Capture this in a lambda and store it as a class member is dangerous because the lambda can outlive the object it captures. Especially when the object is copied or moved, the captured **this** pointer will be implicitly propagated to the new object. Most of the time, people will believe that the captured **this** pointer points to the new object, which will lead to bugs. ``` struct C { C() : Captured([this]() -> C const * { return this; }) {} std::function Captured; }; void foo() { C v1{}; C v2 = v1; // v2.Captured capture v1's 'this' pointer assert(v2.Captured() == v1.Captured()); // v2.Captured capture v1's 'this' pointer assert(v2.Captured() == &v2); // assertion failed. } ``` - **Possible fixes:** - • marking copy and move constructors and assignment operators deleted. - • using class member method instead of class member variable with function object types. - • passing **this** pointer as parameter. ### Options - **FunctionWrapperTypes** A semicolon-separated list of names of types. Used to specify function wrapper that can hold lambda expressions. Default is *::std::function;::std::move\_only\_function;::boost::function*. - **BindFunctions** A semicolon-separated list of fully qualified names of functions that can capture **this** pointer. Default is *::std::bind;::boost::bind;::std::bind\_front;::std::bind\_back;* *::boost::compat::bind\_front;::boost::compat::bind\_back*. ### bugprone-casting-through-void Detects unsafe or redundant two-step casting operations involving **void\***, which is equivalent to **reinterpret\_cast** as per the C++ Standard \. Two-step type conversions via **void\*** are discouraged for several reasons. - • They obscure code and impede its understandability, complicating maintenance. - • These conversions bypass valuable compiler support, erasing warnings related to pointer alignment. It may violate strict aliasing rule and leading to undefined behavior. - • In scenarios involving multiple inheritance, ambiguity and unexpected outcomes can arise due to the loss of type information, posing runtime issues. In summary, avoiding two-step type conversions through **void\*** ensures clearer code, maintains essential compiler warnings, and prevents ambiguity and potential runtime errors, particularly in complex inheritance scenarios. If such a cast is wanted, it shall be done via **reinterpret\_cast**, to express the intent more clearly. Note: it is expected that, after applying the suggested fix and using **reinterpret\_cast**, the check cppcoreguidelines-pro-type-reinterpret-cast \<\> will emit a warning. This is intentional: **reinterpret\_cast** is a dangerous operation that can easily break the strict aliasing rules when dereferencing the casted pointer, invoking Undefined Behavior. The warning is there to prompt users to carefully analyze whether the usage of **reinterpret\_cast** is safe, in which case the warning may be suppressed. Examples: ``` using IntegerPointer = int *; double *ptr; static_cast(static_cast(ptr)); // WRONG reinterpret_cast(reinterpret_cast(ptr)); // WRONG (IntegerPointer)(void *)ptr; // WRONG IntegerPointer(static_cast(ptr)); // WRONG reinterpret_cast(ptr); // OK, clearly expresses intent. // NOTE: dereferencing this pointer violates // the strict aliasing rules, invoking // Undefined Behavior. ``` ### bugprone-chained-comparison Check detects chained comparison operators that can lead to unintended behavior or logical errors. Chained comparisons are expressions that use multiple comparison operators to compare three or more values. For example, the expression **a \< b \< c** compares the values of **a**, **b**, and **c**. However, this expression does not evaluate as **(a \< b) && (b \< c)**, which is probably what the developer intended. Instead, it evaluates as **(a \< b) \< c**, which may produce unintended results, especially when the types of **a**, **b**, and **c** are different. To avoid such errors, the check will issue a warning when a chained comparison operator is detected, suggesting to use parentheses to specify the order of evaluation or to use a logical operator to separate comparison expressions. Consider the following examples: ``` int a = 2, b = 6, c = 4; if (a < b < c) { // This block will be executed } ``` In this example, the developer intended to check if **a** is less than **b** and **b** is less than **c**. However, the expression **a \< b \< c** is equivalent to **(a \< b) \< c**. Since **a \< b** is **true**, the expression **(a \< b) \< c** is evaluated as **1 \< c**, which is equivalent to **true \< c** and is invalid in this case as **b \< c** is **false**. Even that above issue could be detected as comparison of **int** to **bool**, there is more dangerous example: ``` bool a = false, b = false, c = true; if (a == b == c) { // This block will be executed } ``` In this example, the developer intended to check if **a**, **b**, and **c** are all equal. However, the expression **a == b == c** is evaluated as **(a == b) == c**. Since **a == b** is true, the expression **(a == b) == c** is evaluated as **true == c**, which is equivalent to **true == true**. This comparison yields **true**, even though **a** and **b** are **false**, and are not equal to **c**. To avoid this issue, the developer can use a logical operator to separate the comparison expressions, like this: ``` if (a == b && b == c) { // This block will not be executed } ``` Alternatively, use of parentheses in the comparison expressions can make the developer's intention more explicit and help avoid misunderstanding. ``` if ((a == b) == c) { // This block will be executed } ``` ### Options - **IgnoreMacros** If *true*, the check will not warn on chained comparisons inside macros. Default is *false*. ### bugprone-command-processor Flags calls to **system()**, **popen()**, and **\_popen()**, which execute a command processor. It does not flag calls to **system()** with a null pointer argument, as such a call checks for the presence of a command processor but does not actually attempt to execute a command. ### References This check corresponds to the CERT C Coding Standard rule ENV33-C. Do not call system() \. ### bugprone-compare-pointer-to-member-virtual-function Detects unspecified behavior about equality comparison between pointer to member virtual function and anything other than null-pointer-constant. ``` struct A { void f1(); void f2(); virtual void f3(); virtual void f4(); void g1(int); }; void fn() { bool r1 = (&A::f1 == &A::f2); // ok bool r2 = (&A::f1 == &A::f3); // bugprone bool r3 = (&A::f1 != &A::f3); // bugprone bool r4 = (&A::f3 == nullptr); // ok bool r5 = (&A::f3 == &A::f4); // bugprone void (A::*v1)() = &A::f3; bool r6 = (v1 == &A::f1); // bugprone bool r6 = (v1 == nullptr); // ok void (A::*v2)() = &A::f2; bool r7 = (v2 == &A::f1); // false positive, but potential risk if assigning other value to v2. void (A::*v3)(int) = &A::g1; bool r8 = (v3 == &A::g1); // ok, no virtual function match void(A::*)(int) signature. } ``` Provide warnings on equality comparisons involve pointers to member virtual function or variables which is potential pointer to member virtual function and any entity other than a null-pointer constant. In certain compilers, virtual function addresses are not conventional pointers but instead consist of offsets and indexes within a virtual function table (vtable). Consequently, these pointers may vary between base and derived classes, leading to unpredictable behavior when compared directly. This issue becomes particularly challenging when dealing with pointers to pure virtual functions, as they may not even have a valid address, further complicating comparisons. Instead, it is recommended to utilize the **typeid** operator or other appropriate mechanisms for comparing objects to ensure robust and predictable behavior in your codebase. By heeding this detection and adopting a more reliable comparison method, you can mitigate potential issues related to unspecified behavior, especially when dealing with pointers to member virtual functions or pure virtual functions, thereby improving the overall stability and maintainability of your code. In scenarios involving pointers to member virtual functions, it's only advisable to employ **nullptr** for comparisons. ### Limitations Does not analyze values stored in a variable. For variable, only analyze all virtual methods in the same **class** or **struct** and diagnose when assigning a pointer to member virtual function to this variable is possible. ### bugprone-copy-constructor-init Finds copy constructors where the constructor doesn't call the copy constructor of the base class. ``` class Copyable { public: Copyable() = default; Copyable(const Copyable &) = default; int memberToBeCopied = 0; }; class X2 : public Copyable { X2(const X2 &other) {} // Copyable(other) is missing }; ``` Also finds copy constructors where the constructor of the base class don't have parameter. ``` class X3 : public Copyable { X3(const X3 &other) : Copyable() {} // other is missing }; ``` Failure to properly initialize base class sub-objects during copy construction can result in undefined behavior, crashes, data corruption, or other unexpected outcomes. The check ensures that the copy constructor of a derived class properly calls the copy constructor of the base class, helping to prevent bugs and improve code quality. ### Limitations - • It won't generate warnings for empty classes, as there are no class members (including base class sub-objects) to worry about. - • It won't generate warnings for base classes that have copy constructor private or deleted. - • It won't generate warnings for base classes that are initialized using other non-default constructor, as this could be intentional. The check also suggests a fix-its in some cases. ### bugprone-copy-constructor-mutates-argument Finds assignments to the copied object and its direct or indirect members in copy constructors and copy assignment operators. This check corresponds to the CERT C Coding Standard rule OOP58-CPP. Copy operations must not mutate the source object \. ### bugprone-crtp-constructor-accessibility Detects error-prone Curiously Recurring Template Pattern usage, when the CRTP can be constructed outside itself and the derived class. The CRTP is an idiom, in which a class derives from a template class, where itself is the template argument. It should be ensured that if a class is intended to be a base class in this idiom, it can only be instantiated if the derived class is its template argument. Example: ``` template class CRTP { private: CRTP() = default; friend T; }; class Derived : CRTP {}; ``` Below can be seen some common mistakes that will allow the breaking of the idiom. If the constructor of a class intended to be used in a CRTP is public, then it allows users to construct that class on its own. Example: ``` template class CRTP { public: CRTP() = default; }; class Good : CRTP {}; Good GoodInstance; CRTP BadInstance; ``` If the constructor is protected, the possibility of an accidental instantiation is prevented, however it can fade an error, when a different class is used as the template parameter instead of the derived one. Example: ``` template class CRTP { protected: CRTP() = default; }; class Good : CRTP {}; Good GoodInstance; class Bad : CRTP {}; Bad BadInstance; ``` To ensure that no accidental instantiation happens, the best practice is to make the constructor private and declare the derived class as friend. Note that as a tradeoff, this also gives the derived class access to every other private members of the CRTP. However, constructors can still be public or protected if they are deleted. Example: ``` template class CRTP { CRTP() = default; friend T; }; class Good : CRTP {}; Good GoodInstance; class Bad : CRTP {}; Bad CompileTimeError; CRTP AlsoCompileTimeError; ``` ### Limitations - • The check is not supported below C++11 - • The check does not handle when the derived class is passed as a variadic template argument - • Accessible functions that can construct the CRTP, like factory functions are not checked The check also suggests a fix-its in some cases. ### bugprone-dangling-handle Detect dangling references in value handles like **std::string\_view**. These dangling references can be a result of constructing handles from temporary values, where the temporary is destroyed soon after the handle is created. Examples: ``` string_view View = string(); // View will dangle. string A; View = A + "A"; // still dangle. vector V; V.push_back(string()); // V[0] is dangling. V.resize(3, string()); // V[1] and V[2] will also dangle. string_view f() { // All these return values will dangle. return string(); string S; return S; char Array[10]{}; return Array; } span g() { array V; return {V}; int Array[10]{}; return {Array}; } ``` ### Options - **HandleClasses** A semicolon-separated list of class names that should be treated as handles. By default only **std::basic\_string\_view**, **std::experimental::basic\_string\_view** and **std::span** are considered. ### bugprone-default-operator-new-on-overaligned-type Flags uses of default **operator new** where the type has extended alignment (an alignment greater than the fundamental alignment). The default **operator new** is guaranteed to provide the correct alignment if the requested alignment is less or equal to the fundamental alignment. Only cases are detected (by design) where the **operator new** is not user-defined and is not a placement new (the reason is that in these cases we assume that the user provided the correct memory allocation). ### References This check corresponds to the CERT C++ Coding Standard rule MEM57-CPP. Avoid using default operator new for over-aligned types \. ### bugprone-derived-method-shadowing-base-method Finds derived class methods that shadow a (non-virtual) base class method. In order to be considered "shadowing", methods must have the same signature (i.e. the same name, same number of parameters, same parameter types, etc). Only checks public, non-templated methods. The below example is bugprone because consumers of the **Derived** class will expect the **reset** method to do the work of **Base::reset()** in addition to extra work required to reset the **Derived** class. Common fixes include: - • Making the **reset** method polymorphic - • Re-naming **Derived::reset** if it's not meant to intersect with **Base::reset** - • Using **using Base::reset** to change the access specifier This is also a violation of the Liskov Substitution Principle. ``` struct Base { void reset() {/* reset the base class */}; }; struct Derived : public Base { void reset() {/* reset the derived class, but not the base class */}; }; ``` ### bugprone-dynamic-static-initializers Finds instances of static variables that are dynamically initialized in header files. This can pose problems in certain multithreaded contexts. For example, when disabling compiler generated synchronization instructions for static variables initialized at runtime (e.g. by **-fno-threadsafe-statics**), even if a particular project takes the necessary precautions to prevent race conditions during initialization by providing their own synchronization, header files included from other projects may not. Therefore, such a check is helpful for ensuring that disabling compiler generated synchronization for static variable initialization will not cause problems. Consider the following code: ``` int foo() { static int k = bar(); return k; } ``` When synchronization of static initialization is disabled, if two threads both call *foo* for the first time, there is the possibility that *k* will be double initialized, creating a race condition. ### bugprone-easily-swappable-parameters Finds function definitions where parameters of convertible types follow each other directly, making call sites prone to calling the function with swapped (or badly ordered) arguments. ``` void drawPoint(int X, int Y) { /* ... */ } FILE *open(const char *Dir, const char *Name, Flags Mode) { /* ... */ } ``` A potential call like **drawPoint(-2, 5)** or **openPath("a.txt", "tmp", Read)** is perfectly legal from the language's perspective, but might not be what the developer of the function intended. More elaborate and type-safe constructs, such as opaque typedefs or strong types should be used instead, to prevent a mistaken order of arguments. ``` struct Coord2D { int X; int Y; }; void drawPoint(const Coord2D Pos) { /* ... */ } FILE *open(const Path &Dir, const Filename &Name, Flags Mode) { /* ... */ } ``` Due to the potentially elaborate refactoring and API-breaking that is necessary to strengthen the type safety of a project, no automatic fix-its are offered. ### Options ### Extension/relaxation options Relaxation (or extension) options can be used to broaden the scope of the analysis and fine-tune the enabling of more mixes between types. Some mixes may depend on coding style or preference specific to a project, however, it should be noted that enabling *all* of these relaxations model the way of mixing at call sites the most. These options are expected to make the check report for more functions, and report longer mixable ranges. - **QualifiersMix** Whether to consider parameters of some *cvr-qualified* **T** and a differently *cvr-qualified* **T** (i.e. **T** and **const T**, **const T** and **volatile T**, etc.) mixable between one another. If *false*, the check will consider differently qualified types unmixable. *True* turns the warnings on. Defaults to *false*. The following example produces a diagnostic only if *QualifiersMix* is enabled: ``` void *memcpy(const void *Destination, void *Source, std::size_t N) { /* ... */ } ``` - **ModelImplicitConversions** Whether to consider parameters of type **T** and **U** mixable if there exists an implicit conversion from **T** to **U** and **U** to **T**. If *false*, the check will not consider implicitly convertible types for mixability. *True* turns warnings for implicit conversions on. Defaults to *true*. The following examples produce a diagnostic only if *ModelImplicitConversions* is enabled: ``` void fun(int Int, double Double) { /* ... */ } void compare(const char *CharBuf, std::string String) { /* ... */ } ``` **Note:** Changing the qualifiers of an expression's type (e.g. from **int** to **const int**) is defined as an *implicit conversion* in the C++ Standard. However, the check separates this decision-making on the mixability of differently qualified types based on whether *QualifiersMix* was enabled. For example, the following code snippet will only produce a diagnostic if **both** *QualifiersMix* and *ModelImplicitConversions* are enabled: ``` void fun2(int Int, const double Double) { /* ... */ } ``` ### Filtering options Filtering options can be used to lessen the size of the diagnostics emitted by the checker, whether the aim is to ignore certain constructs or dampen the noisiness. - **MinimumLength** The minimum length required from an adjacent parameter sequence to be diagnosed. Defaults to *2*. Might be any positive integer greater or equal to *2*. If *0* or *1* is given, the default value *2* will be used instead. For example, if *3* is specified, the examples above will not be matched. - **IgnoredParameterNames** The list of parameter **names** that should never be considered part of a swappable adjacent parameter sequence. The value is a *;*-separated list of names. To ignore unnamed parameters, add *""* to the list verbatim (not the empty string, but the two quotes, potentially escaped!). **This option is case-sensitive!** By default, the following parameter names, and their Uppercase-initial variants are ignored: *""* (unnamed parameters), *iterator*, *begin*, *end*, *first*, *last*, *lhs*, *rhs*. - **IgnoredParameterTypeSuffixes** The list of parameter **type name suffixes** that should never be considered part of a swappable adjacent parameter sequence. Parameters which type, as written in the source code, end with an element of this option will be ignored. The value is a *;*-separated list of names. **This option is case-sensitive!** By default, the following, and their lowercase-initial variants are ignored: *bool*, *It*, *Iterator*, *InputIt*, *ForwardIt*, *BidirIt*, *RandomIt*, *random\_iterator*, *ReverseIt*, *reverse\_iterator*, *reverse\_const\_iterator*, *RandomIt*, *random\_iterator*, *ReverseIt*, *reverse\_iterator*, *reverse\_const\_iterator*, *Const\_Iterator*, *ConstIterator*, *const\_reverse\_iterator*, *ConstReverseIterator*. In addition, *\_Bool* (but not *\_bool*) is also part of the default value. - **SuppressParametersUsedTogether** Suppresses diagnostics about parameters that are used together or in a similar fashion inside the function's body. Defaults to *true*. Specifying *false* will turn off the heuristics. Currently, the following heuristics are implemented which will suppress the warning about the parameter pair involved: - • The parameters are used in the same expression, e.g. **f(a, b)** or **a \< b**. - • The parameters are further passed to the same function to the same parameter of that function, of the same overload. E.g. **f(a, 1)** and **f(b, 2)** to some **f(T, int)**. **Note:** The check does not perform path-sensitive analysis, and as such, "same function" in this context means the same function declaration. If the same member function of a type on two distinct instances are called with the parameters, it will still be regarded as "same function". - • The same member field is accessed, or member method is called of the two parameters, e.g. **a.foo()** and **b.foo()**. - • Separate **return** statements return either of the parameters on different code paths. - **NamePrefixSuffixSilenceDissimilarityThreshold** The number of characters two parameter names might be different on *either* the head or the tail end with the rest of the name the same so that the warning about the two parameters are silenced. Defaults to *1*. Might be any positive integer. If *0*, the filtering heuristic based on the parameters' names is turned off. This option can be used to silence warnings about parameters where the naming scheme indicates that the order of those parameters do not matter. For example, the parameters **LHS** and **RHS** are 1-dissimilar suffixes of each other: **L** and **R** is the different character, while **HS** is the common suffix. Similarly, parameters **text1, text2, text3** are 1-dissimilar prefixes of each other, with the numbers at the end being the dissimilar part. If the value is at least *1*, such cases will not be reported. ### Limitations **This check is designed to check function signatures!** The check does not investigate functions that are generated by the compiler in a context that is only determined from a call site. These cases include variadic functions, functions in C code that do not have an argument list, and C++ template instantiations. Most of these cases, which are otherwise swappable from a caller's standpoint, have no way of getting "fixed" at the definition point. In the case of C++ templates, only primary template definitions and explicit specializations are matched and analyzed. None of the following cases produce a diagnostic: ``` int printf(const char *Format, ...) { /* ... */ } int someOldCFunction() { /* ... */ } template int add(T X, U Y) { return X + Y }; void theseAreNotWarnedAbout() { printf("%d %d\n", 1, 2); // Two ints passed, they could be swapped. someOldCFunction(1, 2, 3); // Similarly, multiple ints passed. add(1, 2); // Instantiates 'add', but that's not a user-defined function. } ``` Due to the limitation above, parameters which type are further dependent upon template instantiations to *prove* that they mix with another parameter's is not diagnosed. ``` template struct Vector { typedef T element_type; }; // Diagnosed: Explicit instantiation was done by the user, we can prove it // is the same type. void instantiated(int A, Vector::element_type B) { /* ... */ } // Diagnosed: The two parameter types are exactly the same. template void exact(typename Vector::element_type A, typename Vector::element_type B) { /* ... */ } // Skipped: The two parameters are both 'T' but we cannot prove this // without actually instantiating. template void falseNegative(T A, typename Vector::element_type B) { /* ... */ } ``` In the context of *implicit conversions* (when *ModelImplicitConversions* is enabled), the modelling performed by the check warns if the parameters are swappable and the swapped order matches implicit conversions. It does not model whether there exists an unrelated third type from which *both* parameters can be given in a function call. This means that in the following example, even while **strs()** clearly carries the possibility to be called with swapped arguments (as long as the arguments are string literals), will not be warned about. ``` struct String { String(const char *Buf); }; struct StringView { StringView(const char *Buf); operator const char *() const; }; // Skipped: Directly swapping expressions of the two type cannot mix. // (Note: StringView -> const char * -> String would be **two** // user-defined conversions, which is disallowed by the language.) void strs(String Str, StringView SV) { /* ... */ } // Diagnosed: StringView implicitly converts to and from a buffer. void cStr(StringView SV, const char *Buf() { /* ... */ } ``` ### bugprone-empty-catch Detects and suggests addressing issues with empty catch statements. ``` try { // Some code that can throw an exception } catch(const std::exception&) { } ``` Having empty catch statements in a codebase can be a serious problem that developers should be aware of. Catch statements are used to handle exceptions that are thrown during program execution. When an exception is thrown, the program jumps to the nearest catch statement that matches the type of the exception. Empty catch statements, also known as "swallowing" exceptions, catch the exception but do nothing with it. This means that the exception is not handled properly, and the program continues to run as if nothing happened. This can lead to several issues, such as: - • *Hidden Bugs*: If an exception is caught and ignored, it can lead to hidden bugs that are difficult to diagnose and fix. The root cause of the problem may not be apparent, and the program may continue to behave in unexpected ways. - • *Security Issues*: Ignoring exceptions can lead to security issues, such as buffer overflows or null pointer dereferences. Hackers can exploit these vulnerabilities to gain access to sensitive data or execute malicious code. - • *Poor Code Quality*: Empty catch statements can indicate poor code quality and a lack of attention to detail. This can make the codebase difficult to maintain and update, leading to longer development cycles and increased costs. - • *Unreliable Code*: Code that ignores exceptions is often unreliable and can lead to unpredictable behavior. This can cause frustration for users and erode trust in the software. To avoid these issues, developers should always handle exceptions properly. This means either fixing the underlying issue that caused the exception or propagating the exception up the call stack to a higher-level handler. If an exception is not important, it should still be logged or reported in some way so that it can be tracked and addressed later. If the exception is something that can be handled locally, then it should be handled within the catch block. This could involve logging the exception or taking other appropriate action to ensure that the exception is not ignored. Here is an example: ``` try { // Some code that can throw an exception } catch (const std::exception& ex) { // Properly handle the exception, e.g.: std::cerr << "Exception caught: " << ex.what() << std::endl; } ``` If the exception cannot be handled locally and needs to be propagated up the call stack, it should be re-thrown or new exception should be thrown. Here is an example: ``` try { // Some code that can throw an exception } catch (const std::exception& ex) { // Re-throw the exception throw; } ``` In some cases, catching the exception at this level may not be necessary, and it may be appropriate to let the exception propagate up the call stack. This can be done simply by not using **try/catch** block. Here is an example: ``` void function() { // Some code that can throw an exception } void callerFunction() { try { function(); } catch (const std::exception& ex) { // Handling exception on higher level std::cerr << "Exception caught: " << ex.what() << std::endl; } } ``` Other potential solution to avoid empty catch statements is to modify the code to avoid throwing the exception in the first place. This can be achieved by using a different API, checking for error conditions beforehand, or handling errors in a different way that does not involve exceptions. By eliminating the need for try-catch blocks, the code becomes simpler and less error-prone. Here is an example: ``` // Old code: try { mapContainer["Key"].callFunction(); } catch(const std::out_of_range&) { } // New code if (auto it = mapContainer.find("Key"); it != mapContainer.end()) { it->second.callFunction(); } ``` In conclusion, empty catch statements are a bad practice that can lead to hidden bugs, security issues, poor code quality, and unreliable code. By handling exceptions properly, developers can ensure that their code is robust, secure, and maintainable. ### Options - **IgnoreCatchWithKeywords** This option can be used to ignore specific catch statements containing certain keywords. If a **catch** statement body contains (case-insensitive) any of the keywords listed in this semicolon-separated option, then the catch will be ignored, and no warning will be raised. Default value: *@TODO;@FIXME*. - **AllowEmptyCatchForExceptions** This option can be used to ignore empty catch statements for specific exception types. By default, the check will raise a warning if an empty catch statement is detected, regardless of the type of exception being caught. However, in certain situations, such as when a developer wants to intentionally ignore certain exceptions or handle them in a different way, it may be desirable to allow empty catch statements for specific exception types. To configure this option, a semicolon-separated list of exception type names should be provided. If an exception type name in the list is caught in an empty catch statement, no warning will be raised. Default value: empty string. ### bugprone-exception-copy-constructor-throws Checks whether a thrown object's copy constructor can throw. Exception objects are required to be copy constructible in C++. However, an exception's copy constructor should not throw to avoid potential issues when unwinding the stack. If an exception is thrown during stack unwinding (such as from a copy constructor of an exception object), the program will terminate via **std::terminate**. ``` class SomeException { public: SomeException() = default; SomeException(const SomeException&) { /* may throw */ } }; void f() { throw SomeException(); // warning: thrown exception type's copy constructor can throw } ``` ### References This check corresponds to the CERT C++ Coding Standard rule ERR60-CPP. Exception objects must be nothrow copy constructible \. ### bugprone-exception-escape Finds functions which may throw an exception directly or indirectly, but they should not. The functions which should not throw exceptions are the following: - • Destructors - • Move constructors - • Move assignment operators - • The **main()** functions - • **swap()** functions - • **iter\_swap()** functions - • **iter\_move()** functions - • Functions marked with **throw()** or **noexcept** - • Other functions given as option A destructor throwing an exception may result in undefined behavior, resource leaks or unexpected termination of the program. Throwing move constructor or move assignment also may result in undefined behavior or resource leak. The **swap()** operations expected to be non throwing most of the cases and they are always possible to implement in a non throwing way. Non throwing **swap()** operations are also used to create move operations. A throwing **main()** function also results in unexpected termination. Functions declared explicitly with **noexcept(false)** or **throw(exception)** will be excluded from the analysis, as even though it is not recommended for functions like **swap()**, **main()**, move constructors, move assignment operators and destructors, it is a clear indication of the developer's intention and should be respected. To check if these special functions are marked as potentially throwing, the check bugprone-unsafe-to-allow-exceptions \<\> can be used. WARNING! This check may be expensive on large source files. ### Options - **CheckDestructors** When *true*, destructors are analyzed to not throw exceptions. Default value is *true*. - **CheckMoveMemberFunctions** When *true*, move constructors and move assignment operators are analyzed to not throw exceptions. Default value is *true*. - **CheckMain** When *true*, the **main()** function is analyzed to not throw exceptions. Default value is *true*. - **CheckNothrowFunctions** When *true*, functions marked with **noexcept** or **throw()** exception specifications are analyzed to not throw exceptions. Default value is *true*. - **CheckedSwapFunctions** Comma-separated list of swap function names which should not throw exceptions. Default value is *swap,iter\_swap,iter\_move*. - **FunctionsThatShouldNotThrow** Comma separated list containing function names which should not throw. An example value for this parameter can be **WinMain** which adds function **WinMain()** in the Windows API to the list of the functions which should not throw. Default value is an empty string. - **IgnoredExceptions** Comma separated list containing type names which are not counted as thrown exceptions in the check. Default value is an empty string. - **TreatFunctionsWithoutSpecificationAsThrowing** Determines which functions are considered as throwing if they do not have an explicit exception specification. It can be set to the following values: - • - ***None*** The check will consider functions without an explicit exception specification as throwing only if they have a visible definition which can be deduced to throw. - • - ***OnlyUndefined*** The check will consider functions with only a declaration available and no visible definition as throwing. - • - ***All*** The check will consider all functions without an explicit exception specification (such as **noexcept**) as throwing, even if they have a visible definition and do not contain any throwing statements. Default value is *None*. ### bugprone-float-loop-counter Flags **for** loops where the induction expression has a floating-point type. ### References This check corresponds to the CERT C Coding Standard rule FLP30-C. Do not use floating-point variables as loop counters \. ### bugprone-fold-init-type The check flags type mismatches in folds \ that might result in loss of precision. The check supports the following functions: - • **std::accumulate** - • **std::reduce** - • **std::inner\_product** These functions fold an input range into an initial value using the type of the latter. By default, **std::accumulate** and **std::reduce** use **operator+** while **std::inner\_product** uses **operator+** and **operator\***. This can cause loss of precision through: - • Truncation: The following code uses a floating point range and an int initial value, so truncation will happen at every application of **operator+** and the result will be *0*, which might not be what the user expected. ``` auto a = {0.5f, 0.5f, 0.5f, 0.5f}; return std::accumulate(std::begin(a), std::end(a), 0); ``` - • Overflow: The following code also returns *0*. ``` auto a = {65536LL * 65536 * 65536}; return std::accumulate(std::begin(a), std::end(a), 0); ``` The check handles overloads with the following transparent standard functors: - • **std::plus** - • **std::minus** - • **std::multiplies** - • **std::divides** - • **std::bit\_and** - • **std::bit\_or** - • **std::bit\_xor** ### bugprone-forward-declaration-namespace Checks if an unused forward declaration is in a wrong namespace. The check inspects all unused forward declarations and checks if there is any declaration/definition with the same name existing, which could indicate that the forward declaration is in a potentially wrong namespace. ``` namespace na { struct A; } namespace nb { struct A {}; } nb::A a; // warning : no definition found for 'A', but a definition with the same name // 'A' found in another namespace 'nb::' ``` This check can only generate warnings, but it can't suggest a fix at this point. ### bugprone-forwarding-reference-overload The check looks for perfect forwarding constructors that can hide copy or move constructors. If a non const lvalue reference is passed to the constructor, the forwarding reference parameter will be a better match than the const reference parameter of the copy constructor, so the perfect forwarding constructor will be called, which can be confusing. For detailed description of this issue see: Scott Meyers, Effective Modern C++, Item 26. Consider the following example: ``` class Person { public: // C1: perfect forwarding ctor template explicit Person(T&& n) {} // C2: perfect forwarding ctor with parameter default value template explicit Person(T&& n, int x = 1) {} // C3: perfect forwarding ctor guarded with enable_if template, void>> explicit Person(T&& n) {} // C4: variadic perfect forwarding ctor guarded with enable_if template, A&&...>, int> = 0> explicit Person(A&&... a) {} // C5: perfect forwarding ctor guarded with requires expression template requires requires { is_special; } explicit Person(T&& n) {} // C6: perfect forwarding ctor guarded with concept requirement template explicit Person(T&& n) {} // (possibly compiler generated) copy ctor Person(const Person& rhs); }; ``` The check warns for constructors C1 and C2, because those can hide copy and move constructors. We suppress warnings if the copy and the move constructors are both disabled (deleted or private), because there is nothing the perfect forwarding constructor could hide in this case. We also suppress warnings for constructors like C3-C6 that are guarded with an **enable\_if** or a concept, assuming the programmer was aware of the possible hiding. ### Background For deciding whether a constructor is guarded with enable\_if, we consider the types of the constructor parameters, the default values of template type parameters and the types of non-type template parameters with a default literal value. If any part of these types is **std::enable\_if** or **std::enable\_if\_t**, we assume the constructor is guarded. ### bugprone-implicit-widening-of-multiplication-result The check diagnoses instances where a result of a multiplication is implicitly widened, and suggests (with fix-it) to either silence the code by making widening explicit, or to perform the multiplication in a wider type, to avoid the widening afterwards. This is mainly useful when operating on very large buffers. For example, consider: ``` void zeroinit(char* base, unsigned width, unsigned height) { for(unsigned row = 0; row != height; ++row) { for(unsigned col = 0; col != width; ++col) { char* ptr = base + row * width + col; *ptr = 0; } } } ``` This is fine in general, but if **width \* height** overflows, you end up wrapping back to the beginning of **base** instead of processing the entire requested buffer. Indeed, this only matters for pretty large buffers (4GB+), but that can happen very easily for example in image processing, where for that to happen you "only" need a ~269MPix image. ### Options - **UseCXXStaticCastsInCppSources** When suggesting fix-its for C++ code, should C++-style **static\_cast\<\>()**'s be suggested, or C-style casts. Defaults to *true*. - **UseCXXHeadersInCppSources** When suggesting to include the appropriate header in C++ code, should **\** header be suggested, or **\**. Defaults to *true*. - **IgnoreConstantIntExpr** If the multiplication operands are compile-time constants (like literals or are **constexpr**) and fit within the source expression type, do not emit a diagnostic or suggested fix. Only considers expressions where the source expression is a signed integer type. Defaults to *false*. Examples: ``` long mul(int a, int b) { return a * b; // warning: performing an implicit widening conversion to type 'long' of a multiplication performed in type 'int' } char* ptr_add(char *base, int a, int b) { return base + a * b; // warning: result of multiplication in type 'int' is used as a pointer offset after an implicit widening conversion to type 'ssize_t' } char ptr_subscript(char *base, int a, int b) { return base[a * b]; // warning: result of multiplication in type 'int' is used as a pointer offset after an implicit widening conversion to type 'ssize_t' } ``` ### bugprone-inaccurate-erase Checks for inaccurate use of the **erase()** method. Algorithms like **remove()** do not actually remove any element from the container but return an iterator to the first redundant element at the end of the container. These redundant elements must be removed using the **erase()** method. This check warns when not all of the elements will be removed due to using an inappropriate overload. For example, the following code erases only one element: ``` std::vector xs; ... xs.erase(std::remove(xs.begin(), xs.end(), 10)); ``` Call the two-argument overload of **erase()** to remove the subrange: ``` std::vector xs; ... xs.erase(std::remove(xs.begin(), xs.end(), 10), xs.end()); ``` ### bugprone-inc-dec-in-conditions Detects when a variable is both incremented/decremented and referenced inside a complex condition and suggests moving them outside to avoid ambiguity in the variable's value. When a variable is modified and also used in a complex condition, it can lead to unexpected behavior. The side-effect of changing the variable's value within the condition can make the code difficult to reason about. Additionally, the developer's intended timing for the modification of the variable may not be clear, leading to misunderstandings and errors. This can be particularly problematic when the condition involves logical operators like **&&** and **\|\|**, where the order of evaluation can further complicate the situation. Consider the following example: ``` int i = 0; // ... if (i++ < 5 && i > 0) { // do something } ``` In this example, the result of the expression may not be what the developer intended. The original intention of the developer could be to increment **i** after the entire condition is evaluated, but in reality, i will be incremented before **i \> 0** is executed. This can lead to unexpected behavior and bugs in the code. To fix this issue, the developer should separate the increment operation from the condition and perform it separately. For example, they can increment **i** in a separate statement before or after the condition is evaluated. This ensures that the value of **i** is predictable and consistent throughout the code. ``` int i = 0; // ... i++; if (i <= 5 && i > 0) { // do something } ``` Another common issue occurs when multiple increments or decrements are performed on the same variable inside a complex condition. For example: ``` int i = 4; // ... if (i++ < 5 || --i > 2) { // do something } ``` There is a potential issue with this code due to the order of evaluation in C++. The **\|\|** operator used in the condition statement guarantees that if the first operand evaluates to **true**, the second operand will not be evaluated. This means that if **i** were initially **4**, the first operand **i \< 5** would evaluate to **true** and the second operand **i \> 2** would not be evaluated. As a result, the decrement operation **--i** would not be executed and **i** would hold value **5**, which may not be the intended behavior for the developer. To avoid this potential issue, the both increment and decrement operation on **i** should be moved outside the condition statement. ### bugprone-incorrect-enable-if Detects incorrect usages of **std::enable\_if** that don't name the nested **type** type. In C++11 introduced **std::enable\_if** as a convenient way to leverage SFINAE. One form of using **std::enable\_if** is to declare an unnamed template type parameter with a default type equal to **typename std::enable\_if\::type**. If the author forgets to name the nested type **type**, then the code will always consider the candidate template even if the condition is not met. Below are some examples of code using **std::enable\_if** correctly and incorrect examples that this check flags. ``` template ::type> void valid_usage() { ... } template > void valid_usage_with_trait_helpers() { ... } // The below code is not a correct application of SFINAE. Even if // T::some_trait is not true, the function will still be considered in the // set of function candidates. It can either incorrectly select the function // when it should not be a candidates, and/or lead to hard compile errors // if the body of the template does not compile if the condition is not // satisfied. template > void invalid_usage() { ... } // The tool suggests the following replacement for 'invalid_usage': template ::type> void fixed_invalid_usage() { ... } ``` C++14 introduced the trait helper **std::enable\_if\_t** which reduces the likelihood of this error. C++20 introduces constraints, which generally supersede the use of **std::enable\_if**. See modernize-type-traits \<\> for another tool that will replace **std::enable\_if** with **std::enable\_if\_t**, and see modernize-use-constraints \<\> for another tool that replaces **std::enable\_if** with C++20 constraints. Consider these newer mechanisms where possible. ### bugprone-incorrect-enable-shared-from-this Detect classes or structs that do not publicly inherit from **std::enable\_shared\_from\_this**, because unintended behavior will otherwise occur when calling **shared\_from\_this**. Consider the following code: ```` #include // private inheritance class BadExample : std::enable_shared_from_this { // ``shared_from_this``` unintended behaviour // `libstdc++` implementation returns uninitialized ``weak_ptr`` public: BadExample* foo() { return shared_from_this().get(); } void bar() { return; } }; void using_not_public() { auto bad_example = std::make_shared(); auto* b_ex = bad_example->foo(); b_ex->bar(); } ```` Using *libstdc++* implementation, **shared\_from\_this** will throw **std::bad\_weak\_ptr**. When **using\_not\_public()** is called, this code will crash without exception handling. ### bugprone-incorrect-roundings Checks the usage of patterns known to produce incorrect rounding. Programmers often use: ``` (int)(double_expression + 0.5) ``` to round the double expression to an integer. The problem with this: - 1\. It is unnecessarily slow. - 2\. It is incorrect. The number 0.499999975 (smallest representable float number below 0.5) rounds to 1.0. Even worse behavior for negative numbers where both -0.5f and -1.4f both round to 0.0. ### bugprone-infinite-loop Finds obvious infinite loops (loops where the condition variable is not changed at all). Finding infinite loops is well-known to be impossible (halting problem). However, it is possible to detect some obvious infinite loops, for example, if the loop condition is not changed. This check detects such loops. A loop is considered infinite if it does not have any loop exit statement (**break**, **continue**, **goto**, **return**, **throw** or a call to a function called as **\[\[noreturn\]\]**) and all of the following conditions hold for every variable in the condition: - • It is a local variable. - • It has no reference or pointer aliases. - • It is not a structure or class member. Furthermore, the condition must not contain a function call to consider the loop infinite since functions may return different values for different calls. For example, the following loop is considered infinite *i* is not changed in the body: ``` int i = 0, j = 0; while (i < 10) { ++j; } ``` ### bugprone-integer-division Finds cases where integer division in a floating point context is likely to cause unintended loss of precision. No reports are made if divisions are part of the following expressions: - • operands of operators expecting integral or bool types, - • call expressions of integral or bool types, and - • explicit cast expressions to integral or bool types, as these are interpreted as signs of deliberateness from the programmer. Examples: ``` float floatFunc(float); int intFunc(int); double d; int i = 42; // Warn, floating-point values expected. d = 32 * 8 / (2 + i); d = 8 * floatFunc(1 + 7 / 2); d = i / (1 << 4); // OK, no integer division. d = 32 * 8.0 / (2 + i); d = 8 * floatFunc(1 + 7.0 / 2); d = (double)i / (1 << 4); // OK, there are signs of deliberateness. d = 1 << (i / 2); d = 9 + intFunc(6 * i / 32); d = (int)(i / 32) - 8; ``` ### bugprone-invalid-enum-default-initialization Detects default initialization (to 0) of variables with **enum** type where the enum has no enumerator with value of 0. In C++ a default initialization is performed if a variable is initialized with initializer list or in other implicit ways, and no value is specified at the initialization. In such cases the value 0 is used for the initialization. This also applies to enumerations even if it does not have an enumerator with value 0. In this way a variable with the **enum** type may contain initially an invalid value (if the program expects that it contains only the listed enumerator values). The check emits a warning only if an **enum** variable is default-initialized (contrary to not initialized) and the **enum** does not have an enumerator with value of 0. The type can be a scoped or non-scoped **enum**. Unions are not handled by the check (if it contains a member of enumeration type). Note that the **enum** **std::errc** is always ignored because it is expected to be default initialized, despite not defining an enumerator with the value 0. ``` enum class Enum1: int { A = 1, B }; enum class Enum0: int { A = 0, B }; void f() { Enum1 X1{}; // warn: 'X1' is initialized to 0 Enum1 X2 = Enum1(); // warn: 'X2' is initialized to 0 Enum1 X3; // no warning: 'X3' is not initialized Enum0 X4{}; // no warning: type has an enumerator with value of 0 } struct S1 { Enum1 A; S(): A() {} // warn: 'A' is initialized to 0 }; struct S2 { int A; Enum1 B; }; S2 VarS2{}; // warn: member 'B' is initialized to 0 ``` The check applies to initialization of arrays or structures with initialization lists in C code too. In these cases elements not specified in the list (and have enum type) are set to 0. ``` enum Enum1 { Enum1_A = 1, Enum1_B }; struct Struct1 { int a; enum Enum1 b; }; enum Enum1 Array1[2] = {Enum1_A}; // warn: omitted elements are initialized to 0 enum Enum1 Array2[2][2] = {{Enum1_A}, {Enum1_A}}; // warn: last element of both nested arrays is initialized to 0 enum Enum1 Array3[2][2] = {{Enum1_A, Enum1_A}}; // warn: elements of second array are initialized to 0 struct Struct1 S1 = {1}; // warn: element 'b' is initialized to 0 ``` ### Options - **IgnoredEnums** Semicolon-separated list of regexes specifying enums for which this check won't be enforced. Default is *::std::errc*. ### bugprone-lambda-function-name Checks for attempts to get the name of a function from within a lambda expression. The name of a lambda is always something like **operator()**, which is almost never what was intended. Example: ``` void FancyFunction() { [] { printf("Called from %s\n", __func__); }(); [] { printf("Now called from %s\n", __FUNCTION__); }(); } ``` Output: ``` Called from operator() Now called from operator() ``` Likely intended output: ``` Called from FancyFunction Now called from FancyFunction ``` ### Options - **IgnoreMacros** The value *true* specifies that attempting to get the name of a function from within a macro should not be diagnosed. The default value is *false*. ### bugprone-macro-parentheses Finds macros that can have unexpected behavior due to missing parentheses. Macros are expanded by the preprocessor as-is. As a result, there can be unexpected behavior; operators may be evaluated in unexpected order and unary operators may become binary operators, etc. When the replacement list has an expression, it is recommended to surround it with parentheses. This ensures that the macro result is evaluated completely before it is used. It is also recommended to surround macro arguments in the replacement list with parentheses. This ensures that the argument value is calculated properly. This check corresponds to the CERT C Coding Standard rule PRE02-C. Macro replacement lists should be parenthesized. \ ### bugprone-macro-repeated-side-effects Checks for repeated argument with side effects in macros. ### bugprone-misleading-setter-of-reference Finds setter-like member functions that take a pointer parameter and set a reference member of the same class with the pointed value. The check detects member functions that take a single pointer parameter, and contain a single expression statement that dereferences the parameter and assigns the result to a data member with a reference type. The fact that a setter function takes a pointer might cause the belief that an internal reference (if it would be a pointer) is changed instead of the pointed-to (or referenced) value. Example: ``` class MyClass { int &InternalRef; // non-const reference member public: MyClass(int &Value) : InternalRef(Value) {} // Warning: This setter could lead to unintended behaviour. void setRef(int *Value) { InternalRef = *Value; // This assigns to the referenced value, not changing what InternalRef references. } }; int main() { int Value1 = 42; int Value2 = 100; MyClass X(Value1); // This might look like it changes what InternalRef references to, // but it actually modifies Value1 to be 100. X.setRef(&Value2); } ``` - **Possible fixes:** - • Change the parameter type of the "set" function to non-pointer type (for example, a const reference). - • Change the type of the member variable to a pointer and in the "set" function assign a value to the pointer (without dereference). ### bugprone-misplaced-operator-in-strlen-in-alloc Finds cases where **1** is added to the string in the argument to **strlen()**, **strnlen()**, **strnlen\_s()**, **wcslen()**, **wcsnlen()**, and **wcsnlen\_s()** instead of the result and the value is used as an argument to a memory allocation function (**malloc()**, **calloc()**, **realloc()**, **alloca()**) or the **new\[\]** operator in *C++*. The check detects error cases even if one of these functions (except the **new\[\]** operator) is called by a constant function pointer. Cases where **1** is added both to the parameter and the result of the **strlen()**-like function are ignored, as are cases where the whole addition is surrounded by extra parentheses. *C* example code: ``` void bad_malloc(char *str) { char *c = (char*) malloc(strlen(str + 1)); } ``` The suggested fix is to add **1** to the return value of **strlen()** and not to its argument. In the example above the fix would be ``` char *c = (char*) malloc(strlen(str) + 1); ``` *C++* example code: ``` void bad_new(char *str) { char *c = new char[strlen(str + 1)]; } ``` As in the *C* code with the **malloc()** function, the suggested fix is to add **1** to the return value of **strlen()** and not to its argument. In the example above the fix would be ``` char *c = new char[strlen(str) + 1]; ``` Example for silencing the diagnostic: ``` void bad_malloc(char *str) { char *c = (char*) malloc(strlen((str + 1))); } ``` ### bugprone-misplaced-pointer-arithmetic-in-alloc Finds cases where an integer expression is added to or subtracted from the result of a memory allocation function (**malloc()**, **calloc()**, **realloc()**, **alloca()**) instead of its argument. The check detects error cases even if one of these functions is called by a constant function pointer. Example code: ``` void bad_malloc(int n) { char *p = (char*) malloc(n) + 10; } ``` The suggested fix is to add the integer expression to the argument of **malloc** and not to its result. In the example above the fix would be ``` char *p = (char*) malloc(n + 10); ``` ### bugprone-misplaced-widening-cast This check will warn when there is a cast of a calculation result to a bigger type. If the intention of the cast is to avoid loss of precision then the cast is misplaced, and there can be loss of precision. Otherwise the cast is ineffective. Example code: ``` long f(int x) { return (long)(x * 1000); } ``` The result **x \* 1000** is first calculated using **int** precision. If the result exceeds **int** precision there is loss of precision. Then the result is casted to **long**. If there is no loss of precision then the cast can be removed or you can explicitly cast to **int** instead. If you want to avoid loss of precision then put the cast in a proper location, for instance: ``` long f(int x) { return (long)x * 1000; } ``` ### Implicit casts Forgetting to place the cast at all is at least as dangerous and at least as common as misplacing it. If **CheckImplicitCasts** is enabled the check also detects these cases, for instance: ``` long f(int x) { return x * 1000; } ``` ### Floating point Currently warnings are only written for integer conversion. No warning is written for this code: ``` double f(float x) { return (double)(x * 10.0f); } ``` ### Options - **CheckImplicitCasts** If *true*, enables detection of implicit casts. Default is *false*. ### bugprone-missing-end-comparison Finds instances where the result of a standard algorithm is used in a Boolean context without being compared to the end iterator. Standard algorithms such as **std::find**, **std::search**, and **std::lower\_bound** return an iterator to the element if found, or the end iterator otherwise. Using the result directly in a Boolean context (like an **if** statement) is almost always a bug, as it only checks if the iterator itself evaluates to **true**, which may always be true for many iterator types. Examples: ``` void example() { int arr[] = {1, 2, 3}; int* begin = std::begin(arr); int* end = std::end(arr); if (std::find(begin, end, 2)) { // ... } // Fixed by the check: if ((std::find(begin, end, 2) != end)) { // ... } // C++20 ranges: int v[] = {1, 2, 3}; if (std::ranges::find(v, 2)) { // ... } // Fixed by the check: if ((std::ranges::find(v, 2) != std::ranges::end(v))) { // ... } } ``` The check also handles range-based algorithms introduced in C++20. Supported algorithms: - • **std::adjacent\_find** - • **std::find** - • **std::find\_end** - • **std::find\_first\_of** - • **std::find\_if** - • **std::find\_if\_not** - • **std::is\_sorted\_until** - • **std::lower\_bound** - • **std::max\_element** - • **std::min\_element** - • **std::partition\_point** - • **std::search** - • **std::search\_n** - • **std::upper\_bound** - • **std::ranges::adjacent\_find** - • **std::ranges::find** - • **std::ranges::find\_first\_of** - • **std::ranges::find\_if** - • **std::ranges::find\_if\_not** - • **std::ranges::is\_sorted\_until** - • **std::ranges::lower\_bound** - • **std::ranges::max\_element** - • **std::ranges::min\_element** - • **std::ranges::upper\_bound** ### Options - **ExtraAlgorithms** A semicolon-separated list of extra algorithms to check. The list can contain: - • Iterator-based algorithms. These should follow the standard iterator pattern: **func(Iter, Iter, ...)**. - • Range-based algorithms. These are heuristically detected if they take exactly two arguments and the first argument is a container or range. The fix will insert **std::end(Container)**. Default is an empty string. ### bugprone-move-forwarding-reference Warns if **std::move** is called on a forwarding reference, for example: ``` template void foo(T&& t) { bar(std::move(t)); } ``` Forwarding references \ should typically be passed to **std::forward** instead of **std::move**, and this is the fix that will be suggested. (A forwarding reference is an rvalue reference of a type that is a deduced function template argument.) In this example, the suggested fix would be ``` bar(std::forward(t)); ``` ### Background Code like the example above is sometimes written with the expectation that **T&&** will always end up being an rvalue reference, no matter what type is deduced for **T**, and that it is therefore not possible to pass an lvalue to **foo()**. However, this is not true. Consider this example: ``` std::string s = "Hello, world"; foo(s); ``` This code compiles and, after the call to **foo()**, **s** is left in an indeterminate state because it has been moved from. This may be surprising to the caller of **foo()** because no **std::move** was used when calling **foo()**. The reason for this behavior lies in the special rule for template argument deduction on function templates like **foo()** -- i.e. on function templates that take an rvalue reference argument of a type that is a deduced function template argument. (See section \[temp.deduct.call\]/3 in the C++11 standard.) If **foo()** is called on an lvalue (as in the example above), then **T** is deduced to be an lvalue reference. In the example, **T** is deduced to be **std::string &**. The type of the argument **t** therefore becomes **std::string& &&**; by the reference collapsing rules, this collapses to **std::string&**. This means that the **foo(s)** call passes **s** as an lvalue reference, and **foo()** ends up moving **s** and thereby placing it into an indeterminate state. ### bugprone-multi-level-implicit-pointer-conversion Detects implicit conversions between pointers of different levels of indirection. Conversions between pointer types of different levels of indirection can be dangerous and may lead to undefined behavior, particularly if the converted pointer is later cast to a type with a different level of indirection. For example, converting a pointer to a pointer to an **int** (**int\*\***) to a **void\*** can result in the loss of information about the original level of indirection, which can cause problems when attempting to use the converted pointer. If the converted pointer is later cast to a type with a different level of indirection and dereferenced, it may lead to access violations, memory corruption, or other undefined behavior. Consider the following example: ``` void foo(void* ptr); int main() { int x = 42; int* ptr = &x; int** ptr_ptr = &ptr; foo(ptr_ptr); // warning will trigger here return 0; } ``` In this example, **foo()** is called with **ptr\_ptr** as its argument. However, **ptr\_ptr** is a **int\*\*** pointer, while **foo()** expects a **void\*** pointer. This results in an implicit pointer level conversion, which could cause issues if **foo()** dereferences the pointer assuming it's a **int\*** pointer. Using an explicit cast is a recommended solution to prevent issues caused by implicit pointer level conversion, as it allows the developer to explicitly state their intention and show their reasoning for the type conversion. Additionally, it is recommended that developers thoroughly check and verify the safety of the conversion before using an explicit cast. This extra level of caution can help catch potential issues early on in the development process, improving the overall reliability and maintainability of the code. ### Options - **EnableInC** If *true*, enables the check in C code (it is always enabled in C++ code). Default is *true*. ### bugprone-multiple-new-in-one-expression Finds multiple **new** operator calls in a single expression, where the allocated memory by the first **new** may leak if the second allocation fails and throws exception. C++ does often not specify the exact order of evaluation of the operands of an operator or arguments of a function. Therefore if a first allocation succeeds and a second fails, in an exception handler it is not possible to tell which allocation has failed and free the memory. Even if the order is fixed the result of a first **new** may be stored in a temporary location that is not reachable at the time when a second allocation fails. It is best to avoid any expression that contains more than one **operator new** call, if exception handling is used to check for allocation errors. Different rules apply for are the short-circuit operators **\|\|** and **&&** and the **,** operator, where evaluation of one side must be completed before the other starts. Expressions of a list-initialization (initialization or construction using **{** and **}** characters) are evaluated in fixed order. Similarly, condition of a **?** operator is evaluated before the branches are evaluated. The check reports warning if two **new** calls appear in one expression at different sides of an operator, or if **new** calls appear in different arguments of a function call (that can be an object construction with **()** syntax). These **new** calls can be nested at any level. For any warning to be emitted the **new** calls should be in a code block where exception handling is used with catch for **std::bad\_alloc** or **std::exception**. At **\|\|**, **&&**, **,**, **?** (condition and one branch) operators no warning is emitted. No warning is emitted if both of the memory allocations are not assigned to a variable or not passed directly to a function. The reason is that in this case the memory may be intentionally not freed or the allocated objects can be self-destructing objects. Examples: ``` struct A { int Var; }; struct B { B(); B(A *); int Var; }; struct C { int *X1; int *X2; }; void f(A *, B *); int f1(A *); int f1(B *); bool f2(A *); void foo() { A *PtrA; B *PtrB; try { // Allocation of 'B'/'A' may fail after memory for 'A'/'B' was allocated. f(new A, new B); // warning: memory allocation may leak if an other allocation is sequenced after it and throws an exception; order of these allocations is undefined // List (aggregate) initialization is used. C C1{new int, new int}; // no warning // Allocation of 'B'/'A' may fail after memory for 'A'/'B' was allocated but not yet passed to function 'f1'. int X = f1(new A) + f1(new B); // warning: memory allocation may leak if an other allocation is sequenced after it and throws an exception; order of these allocations is undefined // Allocation of 'B' may fail after memory for 'A' was allocated. // From C++17 on memory for 'B' is allocated first but still may leak if allocation of 'A' fails. PtrB = new B(new A); // warning: memory allocation may leak if an other allocation is sequenced after it and throws an exception // 'new A' and 'new B' may be performed in any order. // 'new B'/'new A' may fail after memory for 'A'/'B' was allocated but not assigned to 'PtrA'/'PtrB'. (PtrA = new A)->Var = (PtrB = new B)->Var; // warning: memory allocation may leak if an other allocation is sequenced after it and throws an exception; order of these allocations is undefined // Evaluation of 'f2(new A)' must be finished before 'f1(new B)' starts. // If 'new B' fails the allocated memory for 'A' is supposedly handled correctly because function 'f2' could take the ownership. bool Z = f2(new A) || f1(new B); // no warning X = (f2(new A) ? f1(new A) : f1(new B)); // no warning // No warning if the result of both allocations is not passed to a function // or stored in a variable. (new A)->Var = (new B)->Var; // no warning // No warning if at least one non-throwing allocation is used. f(new(std::nothrow) A, new B); // no warning } catch(std::bad_alloc) { } // No warning if the allocation is outside a try block (or no catch handler exists for std::bad_alloc). // (The fact if exceptions can escape from 'foo' is not taken into account.) f(new A, new B); // no warning } ``` ### bugprone-multiple-statement-macro Detect multiple statement macros that are used in unbraced conditionals. Only the first statement of the macro will be inside the conditional and the other ones will be executed unconditionally. Example: ``` #define INCREMENT_TWO(x, y) (x)++; (y)++ if (do_increment) INCREMENT_TWO(a, b); // (b)++ will be executed unconditionally. ``` ### bugprone-narrowing-conversions *cppcoreguidelines-narrowing-conversions* redirects here as an alias for this check. Checks for silent narrowing conversions, e.g: **int i = 0; i += 0.1;**. While the issue is obvious in this former example, it might not be so in the following: **void MyClass::f(double d) { int\_member\_ += d; }**. - **We flag narrowing conversions from:** - • an integer to a narrower integer (e.g. **char** to **unsigned char**) if WarnOnIntegerNarrowingConversion Option is set, - • an integer to a narrower floating-point (e.g. **uint64\_t** to **float**) if WarnOnIntegerToFloatingPointNarrowingConversion Option is set, - • a floating-point to an integer (e.g. **double** to **int**), - • a floating-point to a narrower floating-point (e.g. **double** to **float**) if WarnOnFloatingPointNarrowingConversion Option is set. - **This check will flag:** - • All narrowing conversions that are not marked by an explicit cast (c-style or **static\_cast**). For example: **int i = 0; i += 0.1;**, **void f(int); f(0.1);**, - • All applications of binary operators with a narrowing conversions. For example: **int i; i+= 0.1;**. Arithmetic with smaller integer types than **int** trigger implicit conversions, as explained under "Integral Promotion" on cppreference.com \. This check diagnoses more instances of narrowing than the compiler warning *-Wconversion* does. The example below demonstrates this behavior. ``` // The following function definition demonstrates usage of arithmetic with // integer types smaller than `int` and how the narrowing conversion happens // implicitly. void computation(short argument1, short argument2) { // Arithmetic written by humans: short result = argument1 + argument2; // Arithmetic actually performed by C++: short result = static_cast(static_cast(argument1) + static_cast(argument2)); } void recommended_resolution(short argument1, short argument2) { short result = argument1 + argument2; // ^ warning: narrowing conversion from 'int' to signed type 'short' is implementation-defined // The cppcoreguidelines recommend to resolve this issue by using the GSL // in one of two ways. Either by a cast that throws if a loss of precision // would occur. short result = gsl::narrow(argument1 + argument2); // Or it can be resolved without checking the result risking invalid results. short result = gsl::narrow_cast(argument1 + argument2); // A classical `static_cast` will silence the warning as well if the GSL // is not available. short result = static_cast(argument1 + argument2); } ``` ### Options - **WarnOnIntegerNarrowingConversion** When *true*, the check will warn on narrowing integer conversion (e.g. **int** to **size\_t**). *true* by default. - **WarnOnIntegerToFloatingPointNarrowingConversion** When *true*, the check will warn on narrowing integer to floating-point conversion (e.g. **size\_t** to **double**). *true* by default. - **WarnOnFloatingPointNarrowingConversion** When *true*, the check will warn on narrowing floating point conversion (e.g. **double** to **float**). *true* by default. - **WarnWithinTemplateInstantiation** When *true*, the check will warn on narrowing conversions within template instantiations. *false* by default. - **WarnOnEquivalentBitWidth** When *true*, the check will warn on narrowing conversions that arise from casting between types of equivalent bit width. (e.g. *int n = uint(0);* or *long long n = double(0);*) *true* by default. - **IgnoreConversionFromTypes** Narrowing conversions from any type in this semicolon-separated list will be ignored. This may be useful to weed out commonly occurring, but less commonly problematic assignments such as *int n = std::vector\().size();* or *int n = std::difference(it1, it2);*. The default list is empty, but one suggested list for a legacy codebase would be *size\_t;ptrdiff\_t;size\_type;difference\_type*. - **PedanticMode** When *true*, the check will warn on assigning a floating point constant to an integer value even if the floating point value is exactly representable in the destination type (e.g. **int i = 1.0;**). *false* by default. ### FAQ - • What does "narrowing conversion from 'int' to 'float'" mean? An IEEE754 Floating Point number can represent all integer values in the range \[-2^PrecisionBits, 2^PrecisionBits\] where PrecisionBits is the number of bits in the mantissa. For **float** this would be \[-2^23, 2^23\], where **int** can represent values in the range \[-2^31, 2^31-1\]. - • What does "implementation-defined" mean? You may have encountered messages like "narrowing conversion from 'unsigned int' to signed type 'int' is implementation-defined". The C/C++ standard does not mandate two's complement for signed integers, and so the compiler is free to define what the semantics are for converting an unsigned integer to signed integer. Clang's implementation uses the two's complement format. ### bugprone-no-escape Finds pointers with the **noescape** attribute that are captured by an asynchronously-executed block. The block arguments in **dispatch\_async()** and **dispatch\_after()** are guaranteed to escape, so it is an error if a pointer with the **noescape** attribute is captured by one of these blocks. The following is an example of an invalid use of the **noescape** attribute. ``` void foo(__attribute__((noescape)) int *p) { dispatch_async(queue, ^{ *p = 123; }); }); ``` ### bugprone-non-zero-enum-to-bool-conversion Detect implicit and explicit casts of **enum** type into **bool** where **enum** type doesn't have a zero-value enumerator. If the **enum** is used only to hold values equal to its enumerators, then conversion to **bool** will always result in **true** value. This can lead to unnecessary code that reduces readability and maintainability and can result in bugs. May produce false positives if the **enum** is used to store other values (used as a bit-mask or zero-initialized on purpose). To deal with them, **// NOLINT** or casting first to the underlying type before casting to **bool** can be used. It is important to note that this check will not generate warnings if the definition of the enumeration type is not available. Additionally, C++11 enumeration classes are supported by this check. Overall, this check serves to improve code quality and readability by identifying and flagging instances where implicit or explicit casts from enumeration types to boolean could cause potential issues. ### Example ``` enum EStatus { OK = 1, NOT_OK, UNKNOWN }; void process(EStatus status) { if (!status) { // this true-branch won't be executed return; } // proceed with "valid data" } ``` ### Options - **EnumIgnoreList** Option is used to ignore certain enum types when checking for implicit/explicit casts to bool. It accepts a semicolon-separated list of (fully qualified) enum type names or regular expressions that match the enum type names. The default value is an empty string, which means no enums will be ignored. ### bugprone-nondeterministic-pointer-iteration-order Finds nondeterministic usages of pointers in unordered containers. One canonical example is iteration across a container of pointers. ``` { int a = 1, b = 2; std::unordered_set UnorderedPtrSet = {&a, &b}; for (auto i : UnorderedPtrSet) f(i); } ``` Another such example is sorting a container of pointers. ``` { int a = 1, b = 2; std::vector VectorOfPtr = {&a, &b}; std::sort(VectorOfPtr.begin(), VectorOfPtr.end()); } ``` Iteration of a containers of pointers may present the order of different pointers differently across different runs of a program. In some cases this may be acceptable behavior, in others this may be unexpected behavior. This check is advisory for this reason. This check only detects range-based for loops over unordered sets and maps. It also detects calls sorting-like algorithms on containers holding pointers. Other similar usages will not be found and are false negatives. ### Limitations - • This check currently does not check if a nondeterministic iteration order is likely to be a mistake, and instead marks all such iterations as bugprone. - • std::reference\_wrapper is not considered yet. - • Only for loops are considered, other iterators can be included in improvements. ### bugprone-not-null-terminated-result Finds function calls where it is possible to cause a not null-terminated result. Usually the proper length of a string is **strlen(src) + 1** or equal length of this expression, because the null terminator needs an extra space. Without the null terminator it can result in undefined behavior when the string is read. The following and their respective **wchar\_t** based functions are checked: **memcpy**, **memcpy\_s**, **memchr**, **memmove**, **memmove\_s**, **strerror\_s**, **strncmp**, **strxfrm** The following is a real-world example where the programmer forgot to increase the passed third argument, which is **size\_t length**. That is why the length of the allocated memory is not enough to hold the null terminator. ``` static char *stringCpy(const std::string &str) { char *result = reinterpret_cast(malloc(str.size())); memcpy(result, str.data(), str.size()); return result; } ``` In addition to issuing warnings, fix-it rewrites all the necessary code. It also tries to adjust the capacity of the destination array: ``` static char *stringCpy(const std::string &str) { char *result = reinterpret_cast(malloc(str.size() + 1)); strcpy(result, str.data()); return result; } ``` Note: It cannot guarantee to rewrite every of the path-sensitive memory allocations. ### Transformation rules of 'memcpy()' It is possible to rewrite the **memcpy()** and **memcpy\_s()** calls as the following four functions: **strcpy()**, **strncpy()**, **strcpy\_s()**, **strncpy\_s()**, where the latter two are the safer versions of the former two. It rewrites the **wchar\_t** based memory handler functions respectively. ### Rewrite based on the destination array - • If copy to the destination array cannot overflow \[1\] the new function should be the older copy function (ending with **cpy**), because it is more efficient than the safe version. - • If copy to the destination array can overflow \[1\] and **WantToUseSafeFunctions** is set to *true* and it is possible to obtain the capacity of the destination array then the new function could be the safe version (ending with **cpy\_s**). - • If the new function is could be safe version and C++ files are analyzed and the destination array is plain **char**/**wchar\_t** without **un/signed** then the length of the destination array can be omitted. - • If the new function is could be safe version and the destination array is **un/signed** it needs to be casted to plain **char \***/**wchar\_t \***. - **\[1\] It is possible to overflow:** - • If the capacity of the destination array is unknown. - • If the given length is equal to the destination array's capacity. ### Rewrite based on the length of the source string - • If the given length is **strlen(source)** or equal length of this expression then the new function should be the older copy function (ending with **cpy**), as it is more efficient than the safe version (ending with **cpy\_s**). - • Otherwise we assume that the programmer wanted to copy 'N' characters, so the new function is **ncpy**-like which copies 'N' characters. ### Transformations with 'strlen()' or equal length of this expression It transforms the **wchar\_t** based memory and string handler functions respectively (where only **strerror\_s** does not have **wchar\_t** based alias). ### Memory handler functions **memcpy** Please visit the Transformation rules of 'memcpy()' section. **memchr** Usually there is a C-style cast and it is needed to be removed, because the new function **strchr**'s return type is correct. The given length is going to be removed. **memmove** If safe functions are available the new function is **memmove\_s**, which has a new second argument which is the length of the destination array, it is adjusted, and the length of the source string is incremented by one. If safe functions are not available the given length is incremented by one. **memmove\_s** The given length is incremented by one. ### String handler functions **strerror\_s** The given length is incremented by one. **strncmp** If the third argument is the first or the second argument's **length + 1** it has to be truncated without the **+ 1** operation. **strxfrm** The given length is incremented by one. ### Options - **WantToUseSafeFunctions** The value *true* specifies that the target environment is considered to implement '\_s' suffixed memory and string handler functions which are safer than older versions (e.g. 'memcpy\_s()'). The default value is *true*. ### bugprone-optional-value-conversion Detects potentially unintentional and redundant conversions where a value is extracted from an optional-like type and then used to create a new instance of the same optional-like type. These conversions might be the result of developer oversight, leftovers from code refactoring, or other situations that could lead to unintended exceptions or cases where the resulting optional is always initialized, which might be unexpected behavior. To illustrate, consider the following problematic code snippet: ``` #include void print(std::optional); int main() { std::optional opt; // ... // Unintentional conversion from std::optional to int and back to // std::optional: print(opt.value()); // ... } ``` A better approach would be to directly pass **opt** to the **print** function without extracting its value: ``` #include void print(std::optional); int main() { std::optional opt; // ... // Proposed code: Directly pass the std::optional to the print // function. print(opt); // ... } ``` By passing **opt** directly to the print function, unnecessary conversions are avoided, and potential unintended behavior or exceptions are minimized. Value extraction using **operator \*** is matched by default. The support for non-standard optional types such as **boost::optional** or **absl::optional** may be limited. ### Options: - **OptionalTypes** Semicolon-separated list of (fully qualified) optional type names or regular expressions that match the optional types. Default value is *::std::optional;::absl::optional;::boost::optional*. - **ValueMethods** Semicolon-separated list of (fully qualified) method names or regular expressions that match the methods. Default value is *::value$;::get$*. ### bugprone-parent-virtual-call Detects and fixes calls to grand-...parent virtual methods instead of calls to overridden parent's virtual methods. ``` struct A { int virtual foo() {...} }; struct B: public A { int foo() override {...} }; struct C: public B { int foo() override { A::foo(); } // ^^^^^^^^ // warning: qualified name A::foo refers to a member overridden in subclass; did you mean 'B'? [bugprone-parent-virtual-call] }; ``` ### bugprone-pointer-arithmetic-on-polymorphic-object Finds pointer arithmetic performed on classes that contain a virtual function. Pointer arithmetic on polymorphic objects where the pointer's static type is different from its dynamic type is undefined behavior, as the two types could have different sizes, and thus the vtable pointer could point to an invalid address. Finding pointers where the static type contains a virtual member function is a good heuristic, as the pointer is likely to point to a different, derived object. Example: ``` struct Base { virtual ~Base(); int i; }; struct Derived : public Base {}; void foo(Base* b) { b += 1; // warning: pointer arithmetic on class that declares a virtual function can // result in undefined behavior if the dynamic type differs from the // pointer type } int bar(const Derived d[]) { return d[1].i; // warning due to pointer arithmetic on polymorphic object } // Making Derived final suppresses the warning struct FinalDerived final : public Base {}; int baz(const FinalDerived d[]) { return d[1].i; // no warning as FinalDerived is final } ``` ### Options - **IgnoreInheritedVirtualFunctions** When *true*, objects that only inherit a virtual function are not checked. Classes that do not declare a new virtual function are excluded by default, as they make up the majority of false positives. Default: *false*. ``` void bar(Base b[], Derived d[]) { b += 1; // warning, as Base declares a virtual destructor d += 1; // warning only if IgnoreVirtualDeclarationsOnly is set to false } ``` ### References This check corresponds to the SEI Cert rule CTR56-CPP. Do not use pointer arithmetic on polymorphic objects \. ### bugprone-posix-return Checks if any calls to **pthread\_\*** or **posix\_\*** functions (except **posix\_openpt**) expect negative return values. These functions return either **0** on success or an **errno** on failure, which is positive only. Example buggy usage looks like: ``` if (posix_fadvise(...) < 0) { ``` This will never happen as the return value is always non-negative. A simple fix could be: ``` if (posix_fadvise(...) > 0) { ``` ### bugprone-random-generator-seed Flags all pseudo-random number engines, engine adaptor instantiations and **srand()** when initialized or seeded with default argument, constant expression or any user-configurable type. Pseudo-random number engines seeded with a predictable value may cause vulnerabilities e.g. in security protocols. Examples: ``` void foo() { std::mt19937 engine1; // Diagnose, always generate the same sequence std::mt19937 engine2(1); // Diagnose engine1.seed(); // Diagnose engine2.seed(1); // Diagnose std::time_t t; engine1.seed(std::time(&t)); // Diagnose, system time might be controlled by user int x = atoi(argv[1]); std::mt19937 engine3(x); // Will not warn } ``` ### Options - **DisallowedSeedTypes** A comma-separated list of the type names which are disallowed. Default value is *time\_t,std::time\_t*. ### References This check corresponds to the CERT C++ Coding Standard rules MSC51-CPP. Ensure your random number generator is properly seeded \ and MSC32-C. Properly seed pseudorandom number generators \. ### bugprone-raw-memory-call-on-non-trivial-type Flags use of the C standard library functions **memset**, **memcpy** and **memcmp** and similar derivatives on non-trivial types. The check will detect the following functions: **memset**, **std::memset**, **std::memcpy**, **memcpy**, **std::memmove**, **memmove**, **std::strcpy**, **strcpy**, **memccpy**, **stpncpy**, **strncpy**, **std::memcmp**, **memcmp**, **std::strcmp**, **strcmp**, **strncmp**. ### Options - **MemSetNames** Specify extra functions to flag that act similarly to **memset**. Specify names in a semicolon-delimited list. Default is an empty string. - **MemCpyNames** Specify extra functions to flag that act similarly to **memcpy**. Specify names in a semicolon-delimited list. Default is an empty string. - **MemCmpNames** Specify extra functions to flag that act similarly to **memcmp**. Specify names in a semicolon-delimited list. Default is an empty string. This check corresponds to the CERT C++ Coding Standard rule OOP57-CPP. Prefer special member functions and overloaded operators to C Standard Library functions \. ### bugprone-redundant-branch-condition Finds condition variables in nested **if** statements that were also checked in the outer **if** statement and were not changed. Simple example: ``` bool onFire = isBurning(); if (onFire) { if (onFire) scream(); } ``` Here *onFire* is checked both in the outer **if** and the inner **if** statement without a possible change between the two checks. The check warns for this code and suggests removal of the second checking of variable *onFire*. The checker also detects redundant condition checks if the condition variable is an operand of a logical "and" (**&&**) or a logical "or" (**\|\|**) operator: ``` bool onFire = isBurning(); if (onFire) { if (onFire && peopleInTheBuilding > 0) scream(); } ``` ``` bool onFire = isBurning(); if (onFire) { if (onFire || isCollapsing()) scream(); } ``` In the first case (logical "and") the suggested fix is to remove the redundant condition variable and keep the other side of the **&&**. In the second case (logical "or") the whole **if** is removed similarly to the simple case on the top. The condition of the outer **if** statement may also be a logical "and" (**&&**) expression: ``` bool onFire = isBurning(); if (onFire && fireFighters < 10) { if (someOtherCondition()) { if (onFire) scream(); } } ``` The error is also detected if both the outer statement is a logical "and" (**&&**) and the inner statement is a logical "and" (**&&**) or "or" (**\|\|**). The inner **if** statement does not have to be a direct descendant of the outer one. No error is detected if the condition variable may have been changed between the two checks: ``` bool onFire = isBurning(); if (onFire) { tryToExtinguish(onFire); if (onFire && peopleInTheBuilding > 0) scream(); } ``` Every possible change is considered, thus if the condition variable is not a local variable of the function, it is a volatile or it has an alias (pointer or reference) then no warning is issued. ### Limitations The **else** branch is not checked currently for negated condition variable: ``` bool onFire = isBurning(); if (onFire) { scream(); } else { if (!onFire) { continueWork(); } } ``` The checker currently only detects redundant checking of single condition variables. More complex expressions are not checked: ``` if (peopleInTheBuilding == 1) { if (peopleInTheBuilding == 1) { doSomething(); } } ``` ### bugprone-reserved-identifier *cert-dcl37-c* and *cert-dcl51-cpp* redirect here as an alias for this check. Checks for usages of identifiers reserved for use by the implementation. The C and C++ standards both reserve the following names for such use: - • identifiers that begin with an underscore followed by an uppercase letter; - • identifiers in the global namespace that begin with an underscore. The C standard additionally reserves names beginning with a double underscore, while the C++ standard strengthens this to reserve names with a double underscore occurring anywhere. Violating the naming rules above results in undefined behavior. ``` namespace NS { void __f(); // name is not allowed in user code using _Int = int; // same with this #define cool__macro // also this } int _g(); // disallowed in global namespace only ``` The check can also be inverted, i.e. it can be configured to flag any identifier that is *not* a reserved identifier. This mode is for use by e.g. standard library implementors, to ensure they don't infringe on the user namespace. This check does not (yet) check for other reserved names, e.g. macro names identical to language keywords, and names specifically reserved by language standards, e.g. C++ 'zombie names' and C future library directions. This check corresponds to CERT C Coding Standard rule DCL37-C. Do not declare or define a reserved identifier \ as well as its C++ counterpart, DCL51-CPP. Do not declare or define a reserved identifier \. ### Options - **Invert** If *true*, inverts the check, i.e. flags names that are not reserved. Default is *false*. - **AllowedIdentifiers** Semicolon-separated list of regular expressions that the check ignores. Default is an empty list. ### bugprone-return-const-ref-from-parameter Detects return statements that return a constant reference parameter as constant reference. This may cause use-after-free errors if the caller uses xvalues as arguments. In C++, constant reference parameters can accept xvalues which will be destructed after the call. When the function returns such a parameter also as constant reference, then the returned reference can be used after the object it refers to has been destroyed. ### Example ``` struct S { int v; S(int); ~S(); }; const S &fn(const S &a) { return a; } const S& s = fn(S{1}); s.v; // use after free ``` This issue can be resolved by declaring an overload of the problematic function where the **const &** parameter is instead declared as **&&**. The developer has to ensure that the implementation of that function does not produce a use-after-free, the exact error that this check is warning against. Marking such an **&&** overload as **deleted**, will silence the warning as well. In the case of different **const &** parameters being returned depending on the control flow of the function, an overload where all problematic **const &** parameters have been declared as **&&** will resolve the issue. This issue can also be resolved by adding **\[\[clang::lifetimebound\]\]**. Clang enable **-Wdangling** warning by default which can detect mis-uses of the annotated function. See lifetimebound attribute \ for details. ``` const int &f(const int &a [[clang::lifetimebound]]) { return a; } // no warning const int &v = f(1); // warning: temporary bound to local reference 'v' will be destroyed at the end of the full-expression [-Wdangling] ``` ### bugprone-shared-ptr-array-mismatch Finds initializations of C++ shared pointers to non-array type that are initialized with an array. If a shared pointer **std::shared\_ptr\** is initialized with a new-expression **new T\[\]** the memory is not deallocated correctly. The pointer uses plain **delete** in this case to deallocate the target memory. Instead a **delete\[\]** call is needed. A **std::shared\_ptr\** calls the correct delete operator. The check offers replacement of **shared\_ptr\** to **shared\_ptr\** if it is used at a single variable declaration (one variable in one statement). Example: ``` std::shared_ptr x(new Foo[10]); // -> std::shared_ptr x(new Foo[10]); // ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch] std::shared_ptr x1(new Foo), x2(new Foo[10]); // no replacement // ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch] std::shared_ptr x3(new Foo[10], [](const Foo *ptr) { delete[] ptr; }); // no warning struct S { std::shared_ptr x(new Foo[10]); // no replacement in this case // ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch] }; ``` This check partially covers the CERT C++ Coding Standard rule MEM51-CPP. Properly deallocate dynamically allocated resources \ However, only the **std::shared\_ptr** case is detected by this check. ### bugprone-signal-handler Finds specific constructs in signal handler functions that can cause undefined behavior. The rules for what is allowed differ between C++ language versions. Checked signal handler rules for C: - • Calls to non-asynchronous-safe functions are not allowed. Checked signal handler rules for up to and including C++14: - • Calls to non-asynchronous-safe functions are not allowed. - • C++-specific code constructs are not allowed in signal handlers. In other words, only the common subset of C and C++ is allowed to be used. - • Calls to functions with non-C linkage are not allowed (including the signal handler itself). The check is disabled on C++17 and later. Asynchronous-safety is determined by comparing the function's name against a set of known functions. In addition, the function must come from a system header include and in a global namespace. The (possible) arguments passed to the function are not checked. Any function that cannot be determined to be asynchronous-safe is assumed to be non-asynchronous-safe by the check, including user functions for which only the declaration is visible. Calls to user-defined functions with visible definitions are checked recursively. This check implements the CERT C Coding Standard rule SIG30-C. Call only asynchronous-safe functions within signal handlers \ and the rule MSC54-CPP. A signal handler must be a plain old function \. It has the alias names **cert-sig30-c** and **cert-msc54-cpp**. ### Options - **AsyncSafeFunctionSet** Selects which set of functions is considered as asynchronous-safe (and therefore allowed in signal handlers). It can be set to the following values: - • - ***minimal*** Selects a minimal set that is defined in the CERT SIG30-C rule. and includes functions **abort()**, **\_Exit()**, **quick\_exit()** and **signal()**. - • - ***POSIX*** Selects a larger set of functions that is listed in POSIX.1-2017 (see this link \ for more information). The following functions are included: **\_Exit**, **\_exit**, **abort**, **accept**, **access**, **aio\_error**, **aio\_return**, **aio\_suspend**, **alarm**, **bind**, **cfgetispeed**, **cfgetospeed**, **cfsetispeed**, **cfsetospeed**, **chdir**, **chmod**, **chown**, **clock\_gettime**, **close**, **connect**, **creat**, **dup**, **dup2**, **execl**, **execle**, **execv**, **execve**, **faccessat**, **fchdir**, **fchmod**, **fchmodat**, **fchown**, **fchownat**, **fcntl**, **fdatasync**, **fexecve**, **ffs**, **fork**, **fstat**, **fstatat**, **fsync**, **ftruncate**, **futimens**, **getegid**, **geteuid**, **getgid**, **getgroups**, **getpeername**, **getpgrp**, **getpid**, **getppid**, **getsockname**, **getsockopt**, **getuid**, **htonl**, **htons**, **kill**, **link**, **linkat**, **listen**, **longjmp**, **lseek**, **lstat**, **memccpy**, **memchr**, **memcmp**, **memcpy**, **memmove**, **memset**, **mkdir**, **mkdirat**, **mkfifo**, **mkfifoat**, **mknod**, **mknodat**, **ntohl**, **ntohs**, **open**, **openat**, **pause**, **pipe**, **poll**, **posix\_trace\_event**, **pselect**, **pthread\_kill**, **pthread\_self**, **pthread\_sigmask**, **quick\_exit**, **raise**, **read**, **readlink**, **readlinkat**, **recv**, **recvfrom**, **recvmsg**, **rename**, **renameat**, **rmdir**, **select**, **sem\_post**, **send**, **sendmsg**, **sendto**, **setgid**, **setpgid**, **setsid**, **setsockopt**, **setuid**, **shutdown**, **sigaction**, **sigaddset**, **sigdelset**, **sigemptyset**, **sigfillset**, **sigismember**, **siglongjmp**, **signal**, **sigpause**, **sigpending**, **sigprocmask**, **sigqueue**, **sigset**, **sigsuspend**, **sleep**, **sockatmark**, **socket**, **socketpair**, **stat**, **stpcpy**, **stpncpy**, **strcat**, **strchr**, **strcmp**, **strcpy**, **strcspn**, **strlen**, **strncat**, **strncmp**, **strncpy**, **strnlen**, **strpbrk**, **strrchr**, **strspn**, **strstr**, **strtok\_r**, **symlink**, **symlinkat**, **tcdrain**, **tcflow**, **tcflush**, **tcgetattr**, **tcgetpgrp**, **tcsendbreak**, **tcsetattr**, **tcsetpgrp**, **time**, **timer\_getoverrun**, **timer\_gettime**, **timer\_settime**, **times**, **umask**, **uname**, **unlink**, **unlinkat**, **utime**, **utimensat**, **utimes**, **wait**, **waitpid**, **wcpcpy**, **wcpncpy**, **wcscat**, **wcschr**, **wcscmp**, **wcscpy**, **wcscspn**, **wcslen**, **wcsncat**, **wcsncmp**, **wcsncpy**, **wcsnlen**, **wcspbrk**, **wcsrchr**, **wcsspn**, **wcsstr**, **wcstok**, **wmemchr**, **wmemcmp**, **wmemcpy**, **wmemmove**, **wmemset**, **write** The function **quick\_exit** is not included in the POSIX list but it is included here in the set of safe functions. The default value is *POSIX*. ### bugprone-signed-bitwise Finds uses of bitwise operations on signed integer types, which may lead to undefined or implementation defined behavior. Performing bitwise operations on signed integers can be confusing and may lead to undefined or implementation dependent behavior. In particular, right shift a signed integer is implementation dependent, while left shift a signed integer may result in undefined behavior. ``` int main(){ int x = -4; int y = x >> 1; // y can be -2 or 2147483646 } ``` ### Options - **IgnorePositiveIntegerLiterals** If this option is set to *true*, the check will not warn on bitwise operations with positive integer literals, e.g. **~0**, **2 \<\< 1**, etc. Default value is *false*. ### bugprone-signed-char-misuse *cert-str34-c* redirects here as an alias for this check. For the CERT alias, the *DiagnoseSignedUnsignedCharComparisons* option is set to *false*. Finds those **signed char** -\> integer conversions which might indicate a programming error. The basic problem with the **signed char**, that it might store the non-ASCII characters as negative values. This behavior can cause a misunderstanding of the written code both when an explicit and when an implicit conversion happens. When the code contains an explicit **signed char** -\> integer conversion, the human programmer probably expects that the converted value matches with the character code (a value from \[0..255\]), however, the actual value is in \[-128..127\] interval. To avoid this kind of misinterpretation, the desired way of converting from a **signed char** to an integer value is converting to **unsigned char** first, which stores all the characters in the positive \[0..255\] interval which matches the known character codes. In case of implicit conversion, the programmer might not actually be aware that a conversion happened and char value is used as an integer. There are some use cases when this unawareness might lead to a functionally imperfect code. For example, checking the equality of a **signed char** and an **unsigned char** variable is something we should avoid in C++ code. During this comparison, the two variables are converted to integers which have different value ranges. For **signed char**, the non-ASCII characters are stored as a value in \[-128..-1\] interval, while the same characters are stored in the \[128..255\] interval for an **unsigned char**. It depends on the actual platform whether plain **char** is handled as **signed char** by default and so it is caught by this check or not. To change the default behavior you can use **-funsigned-char** and **-fsigned-char** compilation options. Currently, this check warns in the following cases: - • **signed char** is assigned to an integer variable - • **signed char** and **unsigned char** are compared with equality/inequality operator - • **signed char** is converted to an integer in the array subscript See also: STR34-C. Cast characters to unsigned char before converting to larger integer sizes \ A good example from the CERT description when a **char** variable is used to read from a file that might contain non-ASCII characters. The problem comes up when the code uses the **-1** integer value as EOF, while the 255 character code is also stored as **-1** in two's complement form of char type. See a simple example of this below. This code stops not only when it reaches the end of the file, but also when it gets a character with the 255 code. ``` #define EOF (-1) int read(void) { char CChar; int IChar = EOF; if (readChar(CChar)) { IChar = CChar; } return IChar; } ``` A proper way to fix the code above is converting the **char** variable to an **unsigned char** value first. ``` #define EOF (-1) int read(void) { char CChar; int IChar = EOF; if (readChar(CChar)) { IChar = static_cast(CChar); } return IChar; } ``` Another use case is checking the equality of two **char** variables with different signedness. Inside the non-ASCII value range this comparison between a **signed char** and an **unsigned char** always returns **false**. ``` bool compare(signed char SChar, unsigned char USChar) { if (SChar == USChar) return true; return false; } ``` The easiest way to fix this kind of comparison is casting one of the arguments, so both arguments will have the same type. ``` bool compare(signed char SChar, unsigned char USChar) { if (static_cast(SChar) == USChar) return true; return false; } ``` ### Options - **CharTypedefsToIgnore** A semicolon-separated list of typedef names. In this list, we can list typedefs for **char** or **signed char**, which will be ignored by the check. This is useful when a typedef introduces an integer alias like **sal\_Int8** or **int8\_t**. In this case, human misinterpretation is not an issue. Default is an empty string. - **DiagnoseSignedUnsignedCharComparisons** When *true*, the check will warn on **signed char**/**unsigned char** comparisons, otherwise these comparisons are ignored. By default, this option is set to *true*. ### bugprone-sizeof-container The check finds usages of **sizeof** on expressions of STL container types. Most likely the user wanted to use **.size()** instead. All class/struct types declared in namespace **std::** having a const **size()** method are considered containers, with the exception of **std::bitset** and **std::array**. Examples: ``` std::string s; int a = 47 + sizeof(s); // warning: sizeof() doesn't return the size of the container. Did you mean .size()? int b = sizeof(std::string); // no warning, probably intended. std::string array_of_strings[10]; int c = sizeof(array_of_strings) / sizeof(array_of_strings[0]); // no warning, definitely intended. std::array std_array; int d = sizeof(std_array); // no warning, probably intended. ``` ### bugprone-sizeof-expression The check finds usages of **sizeof** expressions which are most likely errors. The **sizeof** operator yields the size (in bytes) of its operand, which may be an expression or the parenthesized name of a type. Misuse of this operator may be leading to errors and possible software vulnerabilities. ### Suspicious usage of 'sizeof(K)' A common mistake is to query the **sizeof** of an integer literal. This is equivalent to query the size of its type (probably **int**). The intent of the programmer was probably to simply get the integer and not its size. ``` #define BUFLEN 42 char buf[BUFLEN]; memset(buf, 0, sizeof(BUFLEN)); // sizeof(42) ==> sizeof(int) ``` ### Suspicious usage of 'sizeof(expr)' In cases, where there is an enum or integer to represent a type, a common mistake is to query the **sizeof** on the integer or enum that represents the type that should be used by **sizeof**. This results in the size of the integer and not of the type the integer represents: ``` enum data_type { FLOAT_TYPE, DOUBLE_TYPE }; struct data { data_type type; void* buffer; data_type get_type() { return type; } }; void f(data d, int numElements) { // should be sizeof(float) or sizeof(double), depending on d.get_type() int numBytes = numElements * sizeof(d.get_type()); ... } ``` ### Suspicious usage of 'sizeof(this)' The **this** keyword is evaluated to a pointer to an object of a given type. The expression **sizeof(this)** is returning the size of a pointer. The programmer most likely wanted the size of the object and not the size of the pointer. ``` class Point { [...] size_t size() { return sizeof(this); } // should probably be sizeof(*this) [...] }; ``` ### Suspicious usage of 'sizeof(char\*)' There is a subtle difference between declaring a string literal with **char\* A = ""** and **char A\[\] = ""**. The first case has the type **char\*** instead of the aggregate type **char\[\]**. Using **sizeof** on an object declared with **char\*** type is returning the size of a pointer instead of the number of characters (bytes) in the string literal. ``` const char* kMessage = "Hello World!"; // const char kMessage[] = "..."; void getMessage(char* buf) { memcpy(buf, kMessage, sizeof(kMessage)); // sizeof(char*) } ``` ### Suspicious usage of 'sizeof(A\*)' A common mistake is to compute the size of a pointer instead of its pointee. These cases may occur because of explicit cast or implicit conversion. ``` int A[10]; memset(A, 0, sizeof(A + 0)); struct Point point; memset(point, 0, sizeof(&point)); ``` ### Suspicious usage of 'sizeof(...)/sizeof(...)' Dividing **sizeof** expressions is typically used to retrieve the number of elements of an aggregate. This check warns on incompatible or suspicious cases. In the following example, the entity has 10-bytes and is incompatible with the type **int** which has 4 bytes. ``` char buf[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; // sizeof(buf) => 10 void getMessage(char* dst) { memcpy(dst, buf, sizeof(buf) / sizeof(int)); // sizeof(int) => 4 [incompatible sizes] } ``` In the following example, the expression **sizeof(Values)** is returning the size of **char\***. One can easily be fooled by its declaration, but in parameter declaration the size '10' is ignored and the function is receiving a **char\***. ``` char OrderedValues[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; return CompareArray(char Values[10]) { return memcmp(OrderedValues, Values, sizeof(Values)) == 0; // sizeof(Values) ==> sizeof(char*) [implicit cast to char*] } ``` ### Suspicious 'sizeof' by 'sizeof' expression Multiplying **sizeof** expressions typically makes no sense and is probably a logic error. In the following example, the programmer used **\*** instead of **/**. ``` const char kMessage[] = "Hello World!"; void getMessage(char* buf) { memcpy(buf, kMessage, sizeof(kMessage) * sizeof(char)); // sizeof(kMessage) / sizeof(char) } ``` This check may trigger on code using the arraysize macro. The following code is working correctly but should be simplified by using only the **sizeof** operator. ``` extern Object objects[100]; void InitializeObjects() { memset(objects, 0, arraysize(objects) * sizeof(Object)); // sizeof(objects) } ``` ### Suspicious usage of 'sizeof(sizeof(...))' Getting the **sizeof** of a **sizeof** makes no sense and is typically an error hidden through macros. ``` #define INT_SZ sizeof(int) int buf[] = { 42 }; void getInt(int* dst) { memcpy(dst, buf, sizeof(INT_SZ)); // sizeof(sizeof(int)) is suspicious. } ``` ### Suspicious usages of 'sizeof(...)' in pointer arithmetic Arithmetic operators on pointers automatically scale the result with the size of the pointed typed. Further use of **sizeof** around pointer arithmetic will typically result in an unintended result. ### Scaling the result of pointer difference Subtracting two pointers results in an integer expression (of type **ptrdiff\_t**) which expresses the distance between the two pointed objects in "number of objects between". A common mistake is to think that the result is "number of bytes between", and scale the difference with **sizeof**, such as **P1 - P2 == N \* sizeof(T)** (instead of **P1 - P2 == N**) or **(P1 - P2) / sizeof(T)** instead of **P1 - P2**. ``` void splitFour(const Obj* Objs, size_t N, Obj Delimiter) { const Obj *P = Objs; while (P < Objs + N) { if (*P == Delimiter) { break; } } if (P - Objs != 4 * sizeof(Obj)) { // Expecting a distance multiplied by sizeof is suspicious. error(); } } ``` ``` void iterateIfEvenLength(int *Begin, int *End) { auto N = (Begin - End) / sizeof(int); // Dividing by sizeof() is suspicious. if (N % 2) return; // ... } ``` ### Stepping a pointer with a scaled integer Conversely, when performing pointer arithmetics to add or subtract from a pointer, the arithmetic operator implicitly scales the value actually added to the pointer with the size of the pointee, as **Ptr + N** expects **N** to be "number of objects to step", and not "number of bytes to step". Seeing the calculation of a pointer where **sizeof** appears is suspicious, and the result is typically unintended, often out of bounds. **Ptr + sizeof(T)** will offset the pointer by **sizeof(T)** elements, effectively exponentiating the scaling factor to the power of 2. Similarly, multiplying or dividing a numeric value with the **sizeof** of an element or the whole buffer is suspicious, because the dimensional connection between the numeric value and the actual **sizeof** result can not always be deduced. While scaling an integer up (multiplying) with **sizeof** is likely **always** an issue, a scaling down (division) is not always inherently dangerous, in case the developer is aware that the division happens between an appropriate number of \_bytes\_ and a **sizeof** value. Turning **WarnOnOffsetDividedBySizeOf** off will restrict the warnings to the multiplication case. This case also checks suspicious **alignof** and **offsetof** usages in pointer arithmetic, as both return the "size" in bytes and not elements, potentially resulting in doubly-scaled offsets. ``` void printEveryEvenIndexElement(int *Array, size_t N) { int *P = Array; while (P <= Array + N * sizeof(int)) { // Suspicious pointer arithmetic using sizeof()! printf("%d ", *P); P += 2 * sizeof(int); // Suspicious pointer arithmetic using sizeof()! } } ``` ``` struct Message { /* ... */; char Flags[8]; }; void clearFlags(Message *Array, size_t N) { const Message *End = Array + N; while (Array < End) { memset(Array + offsetof(Message, Flags), // Suspicious pointer arithmetic using offsetof()! 0, sizeof(Message::Flags)); ++Array; } } ``` For this checked bogus pattern, *cert-arr39-c* redirects here as an alias of this check. This check corresponds to the CERT C Coding Standard rule ARR39-C. Do not add or subtract a scaled integer to a pointer \. ### Limitations Cases where the pointee type has a size of *1* byte (such as, and most importantly, **char**) are excluded. ### Options - **WarnOnSizeOfConstant** When *true*, the check will warn on an expression like **sizeof(CONSTANT)**. Default is *true*. - **WarnOnSizeOfIntegerExpression** When *true*, the check will warn on an expression like **sizeof(expr)** where the expression results in an integer. Default is *false*. - **WarnOnSizeOfThis** When *true*, the check will warn on an expression like **sizeof(this)**. Default is *true*. - **WarnOnSizeOfCompareToConstant** When *true*, the check will warn on an expression like **sizeof(expr) \<= k** for a suspicious constant *k* while *k* is *0* or greater than *0x8000*. Default is *true*. - **WarnOnSizeOfPointerToAggregate** When *true*, the check will warn when the argument of **sizeof** is either a pointer-to-aggregate type, an expression returning a pointer-to-aggregate value or an expression that returns a pointer from an array-to-pointer conversion (that may be implicit or explicit, for example **array + 2** or **(int \*)array**). Default is *true*. - **WarnOnSizeOfPointer** When *true*, the check will report all expressions where the argument of **sizeof** is an expression that produces a pointer (except for a few idiomatic expressions that are probably intentional and correct). This detects occurrences of CWE 467. Default is *false*. - **WarnOnOffsetDividedBySizeOf** When *true*, the check will warn on pointer arithmetic where the element count is obtained from a division with **sizeof(...)**, e.g., **Ptr + Bytes / sizeof(\*T)**. Default is *true*. - **WarnOnSizeOfInLoopTermination** When *true*, the check will warn about incorrect use of sizeof expression in loop termination condition. The warning triggers if the **sizeof** expression appears to be incorrectly used to determine the number of array/buffer elements. e.g, **long arr\[10\]; for(int i = 0; i \< sizeof(arr); i++) { ... }**. Default is *true*. ### bugprone-spuriously-wake-up-functions Finds **cnd\_wait**, **cnd\_timedwait**, **wait**, **wait\_for**, or **wait\_until** function calls when the function is not invoked from a loop that checks whether a condition predicate holds or the function has a condition parameter. ``` if (condition_predicate) { condition.wait(lk); } ``` ``` if (condition_predicate) { if (thrd_success != cnd_wait(&condition, &lock)) { } } ``` This check corresponds to the CERT C++ Coding Standard rule CON54-CPP. Wrap functions that can spuriously wake up in a loop \. and CERT C Coding Standard rule CON36-C. Wrap functions that can spuriously wake up in a loop \. ### bugprone-standalone-empty Warns when **empty()** is used on a range and the result is ignored. Suggests **clear()** if it is an existing member function. The **empty()** method on several common ranges returns a Boolean indicating whether or not the range is empty, but is often mistakenly interpreted as a way to clear the contents of a range. Some ranges offer a **clear()** method for this purpose. This check warns when a call to empty returns a result that is ignored, and suggests replacing it with a call to **clear()** if it is available as a member function of the range. For example, the following code could be used to indicate whether a range is empty or not, but the result is ignored: ``` std::vector v; ... v.empty(); ``` A call to **clear()** would appropriately clear the contents of the range: ``` std::vector v; ... v.clear(); ``` ### Limitations - • Doesn't warn if **empty()** is defined and used with the ignore result in the class template definition (for example in the library implementation). These error cases can be caught with **\[\[nodiscard\]\]** attribute. ### bugprone-std-exception-baseclass Ensure that every value that in a **throw** expression is an instance of **std::exception**. Deriving all exceptions from **std::exception** allows callers to catch all exceptions with a single catch block and provides access to the **what()** method for diagnostics. Throwing arbitrary types creates hidden contracts, reduces interoperability with the standard library, and may result in program termination. ``` class custom_exception {}; void throwing() noexcept(false) { // Problematic throw expressions. throw int(42); throw custom_exception(); } class mathematical_error : public std::exception {}; void throwing2() noexcept(false) { // These kind of throws are ok. throw mathematical_error(); throw std::runtime_error(); throw std::exception(); } ``` ### bugprone-std-namespace-modification Warns on modifications of the **std** or **posix** namespaces which can result in undefined behavior. The **std** (or **posix**) namespace is allowed to be extended with (class or function) template specializations that depend on an user-defined type (a type that is not defined in the standard system headers). The check detects the following (user provided) declarations in namespace **std** or **posix**: - • Anything that is not a template specialization. - • Explicit specializations of any standard library function template or class template, if it does not have any user-defined type as template argument. - • Explicit specializations of any member function of a standard library class template. - • Explicit specializations of any member function template of a standard library class or class template. - • Explicit or partial specialization of any member class template of a standard library class or class template. Examples: ``` namespace std { int x; // warning: modification of 'std' namespace can result in undefined behavior [bugprone-dont-modify-std-namespace] } namespace posix::a { // warning: modification of 'posix' namespace can result in undefined behavior } template <> struct ::std::hash { // warning: modification of 'std' namespace can result in undefined behavior unsigned long operator()(const long &K) const { return K; } }; struct MyData { long data; }; template <> struct ::std::hash { // no warning: specialization with user-defined type unsigned long operator()(const MyData &K) const { return K.data; } }; namespace std { template <> void swap(bool &a, bool &b); // warning: modification of 'std' namespace can result in undefined behavior template <> bool less::operator()(MyData &&, MyData &&) const { // warning: modification of 'std' namespace can result in undefined behavior return true; } } ``` ### References This check corresponds to the CERT C++ Coding Standard rule DCL58-CPP. Do not modify the standard namespaces \. ### bugprone-string-constructor Finds string constructors that are suspicious and probably errors. A common mistake is to swap parameters to the 'fill' string-constructor. Examples: ``` std::string str('x', 50); // should be str(50, 'x') ``` Calling the string-literal constructor with a length bigger than the literal is suspicious and adds extra random characters to the string. Examples: ``` std::string("test", 200); // Will include random characters after "test". std::string("test", 2, 5); // Will include random characters after "st". std::string_view("test", 200); ``` Creating an empty string from constructors with parameters is considered suspicious. The programmer should use the empty constructor instead. Examples: ``` std::string("test", 0); // Creation of an empty string. std::string("test", 1, 0); std::string_view("test", 0); ``` Passing an invalid first character position parameter to constructor will cause **std::out\_of\_range** exception at runtime. Examples: ``` std::string("test", -1, 10); // Negative first character position. std::string("test", 10, 10); // First character position is bigger than string literal character range". ``` ### Options - **WarnOnLargeLength** When *true*, the check will warn on a string with a length greater than **LargeLengthThreshold**. Default is *true*. - **LargeLengthThreshold** An integer specifying the large length threshold. Default is *0x800000*. - **StringNames** Default is *::std::basic\_string;::std::basic\_string\_view*. Semicolon-delimited list of class names to apply this check to. By default *::std::basic\_string* applies to **std::string** and **std::wstring**. Set to e.g. *::std::basic\_string;llvm::StringRef;QString* to perform this check on custom classes. ### bugprone-string-integer-assignment The check finds assignments of an integer to **std::basic\_string\** (**std::string**, **std::wstring**, etc.). The source of the problem is the following assignment operator of **std::basic\_string\**: ``` basic_string& operator=( CharT ch ); ``` Numeric types can be implicitly casted to character types. ``` std::string s; int x = 5965; s = 6; s = x; ``` Use the appropriate conversion functions or character literals. ``` std::string s; int x = 5965; s = '6'; s = std::to_string(x); ``` In order to suppress false positives, use an explicit cast. ``` std::string s; s = static_cast(6); ``` ### bugprone-string-literal-with-embedded-nul Finds occurrences of string literal with embedded NUL character and validates their usage. ### Invalid escaping Special characters can be escaped within a string literal by using their hexadecimal encoding like **\\x42**. A common mistake is to escape them like this **\\0x42** where the **\\0** stands for the NUL character. ``` const char* Example[] = "Invalid character: \0x12 should be \x12"; const char* Bytes[] = "\x03\0x02\0x01\0x00\0xFF\0xFF\0xFF"; ``` ### Truncated literal String-like classes can manipulate strings with embedded NUL as they are keeping track of the bytes and the length. This is not the case for a **char\*** (NUL-terminated) string. A common mistake is to pass a string-literal with embedded NUL to a string constructor expecting a NUL-terminated string. The bytes after the first NUL character are truncated. ``` std::string str("abc\0def"); // "def" is truncated str += "\0"; // This statement is doing nothing if (str == "\0abc") return; // This expression is always true ``` ### bugprone-stringview-nullptr Checks for various ways that the **const CharT\*** constructor of **std::basic\_string\_view** can be passed a null argument and replaces them with the default constructor in most cases. For the comparison operators, braced initializer list does not compile so instead a call to **.empty()** or the empty string literal are used, where appropriate. This prevents code from invoking behavior which is unconditionally undefined. The single-argument **const CharT\*** constructor does not check for the null case before dereferencing its input. The standard is slated to add an explicitly-deleted overload to catch some of these cases: wg21.link/p2166 To catch the additional cases of **NULL** (which expands to **\_\_null**) and **0**, first run the **modernize-use-nullptr** check to convert the callers to **nullptr**. ``` std::string_view sv = nullptr; sv = nullptr; bool is_empty = sv == nullptr; bool isnt_empty = sv != nullptr; accepts_sv(nullptr); accepts_sv({{}}); // A accepts_sv({nullptr, 0}); // B ``` is translated into... ``` std::string_view sv = {}; sv = {}; bool is_empty = sv.empty(); bool isnt_empty = !sv.empty(); accepts_sv(""); accepts_sv(""); // A accepts_sv({nullptr, 0}); // B ``` **Note:** The source pattern with trailing comment "A" selects the **(const CharT\*)** constructor overload and then value-initializes the pointer, causing a null dereference. It happens to not include the **nullptr** literal, but it is still within the scope of this ClangTidy check. **Note:** The source pattern with trailing comment "B" selects the **(const CharT\*, size\_type)** constructor which is perfectly valid, since the length argument is **0**. It is not changed by this ClangTidy check. ### bugprone-suspicious-enum-usage The checker detects various cases when an enum is probably misused (as a bitmask). - 1\. When "ADD" or "bitwise OR" is used between two enum which come from different types and these types value ranges are not disjoint. The following cases will be investigated only using **StrictMode** \<#cmdoption-arg-StrictMode\>. We regard the enum as a (suspicious) bitmask if the three conditions below are true at the same time: - • at most half of the elements of the enum are non pow-of-2 numbers (because of short enumerations) - • there is another non pow-of-2 number than the enum constant representing all choices (the result "bitwise OR" operation of all enum elements) - • enum type variable/enumconstant is used as an argument of a *+* or "bitwise OR" operator So whenever the non pow-of-2 element is used as a bitmask element we diagnose a misuse and give a warning. - 2\. Investigating the right hand side of **+=** and **\|=** operator. - 3\. Check only the enum value side of a **\|** and **+** operator if one of them is not enum val. - 4\. Check both side of **\|** or **+** operator where the enum values are from the same enum type. Examples: ``` enum { A, B, C }; enum { D, E, F = 5 }; enum { G = 10, H = 11, I = 12 }; unsigned flag; flag = A | H; // OK, disjoint value intervals in the enum types ->probably good use. flag = B | F; // Warning, have common values so they are probably misused. // Case 2: enum Bitmask { A = 0, B = 1, C = 2, D = 4, E = 8, F = 16, G = 31 // OK, real bitmask. }; enum Almostbitmask { AA = 0, BB = 1, CC = 2, DD = 4, EE = 8, FF = 16, GG // Problem, forgot to initialize. }; unsigned flag = 0; flag |= E; // OK. flag |= EE; // Warning at the decl, and note that it was used here as a bitmask. ``` ### Options - **StrictMode** Default value: 0. When non-null the suspicious bitmask usage will be investigated additionally to the different enum usage check. ### bugprone-suspicious-include The check detects various cases when an include refers to what appears to be an implementation file, which often leads to hard-to-track-down ODR violations. Examples: ``` #include "Dinosaur.hpp" // OK, .hpp files tend not to have definitions. #include "Pterodactyl.h" // OK, .h files tend not to have definitions. #include "Velociraptor.cpp" // Warning, filename is suspicious. #include_next // Warning, filename is suspicious. ``` ### Options - **IgnoredRegex** A regular expression for the file name to be ignored by the check. Default is empty string. ### bugprone-suspicious-memory-comparison Finds potentially incorrect calls to **memcmp()** based on properties of the arguments. The following cases are covered: **Case 1: Non-standard-layout type** Comparing the object representations of non-standard-layout objects may not properly compare the value representations. **Case 2: Types with no unique object representation** Objects with the same value may not have the same object representation. This may be caused by padding or floating-point types. See also: EXP42-C. Do not compare padding data \ and FLP37-C. Do not use object representations to compare floating-point values \ This check is also related to and partially overlaps the CERT C++ Coding Standard rules OOP57-CPP. Prefer special member functions and overloaded operators to C Standard Library functions \ and EXP62-CPP. Do not access the bits of an object representation that are not part of the object's value representation \ *cert-exp42-c* redirects here as an alias of this check. ### bugprone-suspicious-memset-usage This check finds **memset()** calls with potential mistakes in their arguments. Considering the function as **void\* memset(void\* destination, int fill\_value,** **size\_t byte\_count)**, the following cases are covered: **Case 1: Fill value is a character \`\`'0'\`\`** Filling up a memory area with ASCII code 48 characters is not customary, possibly integer zeroes were intended instead. The check offers a replacement of **'0'** with **0**. Memsetting character pointers with **'0'** is allowed. **Case 2: Fill value is truncated** Memset converts **fill\_value** to **unsigned char** before using it. If **fill\_value** is out of unsigned character range, it gets truncated and memory will not contain the desired pattern. **Case 3: Byte count is zero** Calling memset with a literal zero in its **byte\_count** argument is likely to be unintended and swapped with **fill\_value**. The check offers to swap these two arguments. Corresponding cpplint.py check name: **runtime/memset**. Examples: ``` void foo() { int i[5] = {1, 2, 3, 4, 5}; int *ip = i; char c = '1'; char *cp = &c; int v = 0; // Case 1 memset(ip, '0', 1); // suspicious memset(cp, '0', 1); // OK // Case 2 memset(ip, 0xabcd, 1); // fill value gets truncated memset(ip, 0x00, 1); // OK // Case 3 memset(ip, sizeof(int), v); // zero length, potentially swapped memset(ip, 0, 1); // OK } ``` ### bugprone-suspicious-missing-comma String literals placed side-by-side are concatenated at translation phase 6 (after the preprocessor). This feature is used to represent long string literal on multiple lines. For instance, the following declarations are equivalent: ``` const char* A[] = "This is a test"; const char* B[] = "This" " is a " "test"; ``` A common mistake done by programmers is to forget a comma between two string literals in an array initializer list. ``` const char* Test[] = { "line 1", "line 2" // Missing comma! "line 3", "line 4", "line 5" }; ``` The array contains the string "line 2line3" at offset 1 (i.e. Test\[1\]). Clang won't generate warnings at compile time. This check may warn incorrectly on cases like: ``` const char* SupportedFormat[] = { "Error %s", "Code " PRIu64, // May warn here. "Warning %s", }; ``` ### Options - **SizeThreshold** An unsigned integer specifying the minimum size of a string literal to be considered by the check. Default is **5U**. - **RatioThreshold** A string specifying the maximum threshold ratio \[0, 1.0\] of suspicious string literals to be considered. Default is **".2"**. - **MaxConcatenatedTokens** An unsigned integer specifying the maximum number of concatenated tokens. Default is **5U**. ### bugprone-suspicious-realloc-usage This check finds usages of **realloc** where the return value is assigned to the same expression as passed to the first argument: **p = realloc(p, size);** The problem with this construct is that if **realloc** fails it returns a null pointer but does not deallocate the original memory. If no other variable is pointing to it, the original memory block is not available any more for the program to use or free. In either case **p = realloc(p, size);** indicates bad coding style and can be replaced by **q = realloc(p, size);**. The pointer expression (used at **realloc**) can be a variable or a field member of a data structure, but can not contain function calls or unresolved types. In obvious cases when the pointer used at realloc is assigned to another variable before the **realloc** call, no warning is emitted. This happens only if a simple expression in form of **q = p** or **void \*q = p** is found in the same function where **p = realloc(p, ...)** is found. The assignment has to be before the call to realloc (but otherwise at any place) in the same function. This suppression works only if **p** is a single variable. Examples: ``` struct A { void *p; }; A &getA(); void foo(void *p, A *a, int new_size) { p = realloc(p, new_size); // warning: 'p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer a->p = realloc(a->p, new_size); // warning: 'a->p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer getA().p = realloc(getA().p, new_size); // no warning } void foo1(void *p, int new_size) { void *p1 = p; p = realloc(p, new_size); // no warning } ``` ### bugprone-suspicious-semicolon Finds most instances of stray semicolons that unexpectedly alter the meaning of the code. More specifically, it looks for **if**, **while**, **for** and **for-range** statements whose body is a single semicolon, and then analyzes the context of the code (e.g. indentation) in an attempt to determine whether that is intentional. ``` if (x < y); { x++; } ``` Here the body of the **if** statement consists of only the semicolon at the end of the first line, and *x* will be incremented regardless of the condition. ``` while ((line = readLine(file)) != NULL); processLine(line); ``` As a result of this code, *processLine()* will only be called once, when the **while** loop with the empty body exits with **line == NULL**. The indentation of the code indicates the intention of the programmer. ``` if (x >= y); x -= y; ``` While the indentation does not imply any nesting, there is simply no valid reason to have an *if* statement with an empty body (but it can make sense for a loop). So this check issues a warning for the code above. To solve the issue remove the stray semicolon or in case the empty body is intentional, reflect this using code indentation or put the semicolon in a new line. For example: ``` while (readWhitespace()); Token t = readNextToken(); ``` Here the second line is indented in a way that suggests that it is meant to be the body of the *while* loop - whose body is in fact empty, because of the semicolon at the end of the first line. Either remove the indentation from the second line: ``` while (readWhitespace()); Token t = readNextToken(); ``` ... or move the semicolon from the end of the first line to a new line: ``` while (readWhitespace()) ; Token t = readNextToken(); ``` In this case the check will assume that you know what you are doing, and will not raise a warning. ### bugprone-suspicious-string-compare Find suspicious usage of runtime string comparison functions. This check is valid in C and C++. Checks for calls with implicit comparator and proposed to explicitly add it. ``` if (strcmp(...)) // Implicitly compare to zero if (!strcmp(...)) // Won't warn if (strcmp(...) != 0) // Won't warn ``` Checks that compare function results (i.e., **strcmp**) are compared to valid constant. The resulting value is ``` < 0 when lower than, > 0 when greater than, == 0 when equals. ``` A common mistake is to compare the result to *1* or *-1*. ``` if (strcmp(...) == -1) // Incorrect usage of the returned value. ``` Additionally, the check warns if the results value is implicitly cast to a *suspicious* non-integer type. It's happening when the returned value is used in a wrong context. ``` if (strcmp(...) < 0.) // Incorrect usage of the returned value. ``` ### Options - **WarnOnImplicitComparison** When *true*, the check will warn on implicit comparison. *true* by default. - **WarnOnLogicalNotComparison** When *true*, the check will warn on logical not comparison. *false* by default. - **StringCompareLikeFunctions** A string specifying the comma-separated names of the extra string comparison functions. Default is an empty string. The check will detect the following string comparison functions: *\_\_builtin\_memcmp*, *\_\_builtin\_strcasecmp*, *\_\_builtin\_strcmp*, *\_\_builtin\_strncasecmp*, *\_\_builtin\_strncmp*, *\_mbscmp*, *\_mbscmp\_l*, *\_mbsicmp*, *\_mbsicmp\_l*, *\_mbsnbcmp*, *\_mbsnbcmp\_l*, *\_mbsnbicmp*, *\_mbsnbicmp\_l*, *\_mbsncmp*, *\_mbsncmp\_l*, *\_mbsnicmp*, *\_mbsnicmp\_l*, *\_memicmp*, *\_memicmp\_l*, *\_stricmp*, *\_stricmp\_l*, *\_strnicmp*, *\_strnicmp\_l*, *\_wcsicmp*, *\_wcsicmp\_l*, *\_wcsnicmp*, *\_wcsnicmp\_l*, *lstrcmp*, *lstrcmpi*, *memcmp*, *memicmp*, *strcasecmp*, *strcmp*, *strcmpi*, *stricmp*, *strncasecmp*, *strncmp*, *strnicmp*, *wcscasecmp*, *wcscmp*, *wcsicmp*, *wcsncmp*, *wcsnicmp*, *wmemcmp*. ### bugprone-suspicious-stringview-data-usage Identifies suspicious usages of **std::string\_view::data()** that could lead to reading out-of-bounds data due to inadequate or incorrect string null termination. It warns when the result of **data()** is passed to a constructor or function without also passing the corresponding result of **size()** or **length()** member function. Such usage can lead to unintended behavior, particularly when assuming the data pointed to by **data()** is null-terminated. The absence of a **c\_str()** method in **std::string\_view** often leads developers to use **data()** as a substitute, especially when interfacing with C APIs that expect null-terminated strings. However, since **data()** does not guarantee null termination, this can result in unintended behavior if the API relies on proper null termination for correct string interpretation. In today's programming landscape, this scenario can occur when implicitly converting an **std::string\_view** to an **std::string**. Since the constructor in **std::string** designed for string-view-like objects is **explicit**, attempting to pass an **std::string\_view** to a function expecting an **std::string** will result in a compilation error. As a workaround, developers may be tempted to utilize the **.data()** method to achieve compilation, introducing potential risks. For instance: ``` void printString(const std::string& str) { std::cout << "String: " << str << std::endl; } void something(std::string_view sv) { printString(sv.data()); } ``` In this example, directly passing **sv** to the **printString** function would lead to a compilation error due to the explicit nature of the **std::string** constructor. Consequently, developers might opt for **sv.data()** to resolve the compilation error, albeit introducing potential hazards as discussed. ### Options - **StringViewTypes** Option allows users to specify custom string view-like types for analysis. It accepts a semicolon-separated list of type names or regular expressions matching these types. Default value is: *::std::basic\_string\_view;::llvm::StringRef*. - **AllowedCallees** Specifies methods, functions, or classes where the result of **.data()** is passed to. Allows to exclude such calls from the analysis. Accepts a semicolon-separated list of names or regular expressions matching these entities. Default value is: empty string. ### bugprone-swapped-arguments Finds potentially swapped arguments by examining implicit conversions. It analyzes the types of the arguments being passed to a function and compares them to the expected types of the corresponding parameters. If there is a mismatch or an implicit conversion that indicates a potential swap, a warning is raised. ``` void printNumbers(int a, float b); int main() { // Swapped arguments: float passed as int, int as float) printNumbers(10.0f, 5); return 0; } ``` Covers a wide range of implicit conversions, including: - User-defined conversions - Conversions from floating-point types to boolean or integral types - Conversions from integral types to boolean or floating-point types - Conversions from boolean to integer types or floating-point types - Conversions from (member) pointers to boolean It is important to note that for most argument swaps, the types need to match exactly. However, there are exceptions to this rule. Specifically, when the swapped argument is of integral type, an exact match is not always necessary. Implicit casts from other integral types are also accepted. Similarly, when dealing with floating-point arguments, implicit casts between different floating-point types are considered acceptable. To avoid confusion, swaps where both swapped arguments are of integral types or both are of floating-point types do not trigger the warning. In such cases, it's assumed that the developer intentionally used different integral or floating-point types and does not raise a warning. This approach prevents false positives and provides flexibility in handling situations where varying integral or floating-point types are intentionally utilized. ### bugprone-switch-missing-default-case Ensures that switch statements without default cases are flagged, focuses only on covering cases with non-enums where the compiler may not issue warnings. Switch statements without a default case can lead to unexpected behavior and incomplete handling of all possible cases. When a switch statement lacks a default case, if a value is encountered that does not match any of the specified cases, the switch statement will do nothing and the program will continue execution without handling the value. This check helps identify switch statements that are missing a default case, allowing developers to ensure that all possible cases are handled properly. Adding a default case allows for graceful handling of unexpected or unmatched values, reducing the risk of program errors and unexpected behavior. Example: ``` // Example 1: // warning: switching on non-enum value without default case may not cover all cases switch (i) { case 0: break; } // Example 2: enum E { eE1 }; E e = eE1; switch (e) { // no-warning case eE1: break; } // Example 3: int i = 0; switch (i) { // no-warning case 0: break; default: break; } ``` **Note:** Enum types are already covered by compiler warnings (comes under -Wswitch) when a switch statement does not handle all enum values. This check focuses on non-enum types where the compiler warnings may not be present. **See also:** The CppCoreGuideline ES.79 \ provide guidelines on switch statements, including the recommendation to always provide a default case. ### bugprone-tagged-union-member-count Gives warnings for tagged unions, where the number of tags is different from the number of data members inside the union. A struct or a class is considered to be a tagged union if it has exactly one union data member and exactly one enum data member and any number of other data members that are neither unions or enums. Furthermore, the types of the union and the enum members must not come from system header files nor the **std** namespace. Example: ``` enum Tags { Tag1, Tag2, }; struct TaggedUnion { // warning: tagged union has more data members (3) than tags (2) enum Tags Kind; union { int I; float F; char *Str; } Data; }; ``` The following example illustrates the exception for unions and enums from system header files and the **std** namespace. ``` #include struct NotTaggedUnion { enum MyEnum { MyEnumConstant1, MyEnumConstant2 } En; pthread_mutex_t Mutex; }; ``` The **pthread\_mutex\_t** type may be defined as a union behind a **typedef**, in which case the check could mistake this type as a user-defined tagged union. After all, it has exactly one enum data member and exactly one union data member. To avoid false-positive cases originating from this, unions and enums from system headers and the **std** namespace are ignored when pinpointing the union part and the enum part of a potential user-defined tagged union. ### How enum constants are counted The main complicating factor when counting the number of enum constants is that some of them might be auxiliary values that purposefully don't have a corresponding union data member and are used for something else. For example the last enum constant sometimes explicitly "points to" the last declared valid enum constant or tracks how many enum constants have been declared. For an illustration: ``` enum TagWithLast { Tag1 = 0, Tag2 = 1, Tag3 = 2, LastTag = 2 }; enum TagWithCounter { Tag1, // is 0 Tag2, // is 1 Tag3, // is 2 TagCount, // is 3 }; ``` The check counts the number of distinct values among the enum constants and not the enum constants themselves. This way the enum constants that are essentially just aliases of other enum constants are not included in the final count. Handling of counting enum constants (ones like **TagCount** in the previous code example) is done by decreasing the number of enum values by one if the name of the last enum constant starts with a prefix or ends with a suffix specified in **CountingEnumPrefixes**, **CountingEnumSuffixes** and it's value is one less than the total number of distinct values in the enum. When the final count is adjusted based on this heuristic then a diagnostic note is emitted that shows which enum constant matched the criteria. The heuristic can be disabled entirely (**EnableCountingEnumHeuristic**) or configured to follow your naming convention (**CountingEnumPrefixes**, **CountingEnumSuffixes**). The strings specified in **CountingEnumPrefixes**, **CountingEnumSuffixes** are matched case insensitively. Example counts: ``` // Enum count is 3, because the value 2 is counted only once enum TagWithLast { Tag1 = 0, Tag2 = 1, Tag3 = 2, LastTag = 2 }; // Enum count is 3, because TagCount is heuristically excluded enum TagWithCounter { Tag1, // is 0 Tag2, // is 1 Tag3, // is 2 TagCount, // is 3 }; ``` ### Options - **EnableCountingEnumHeuristic** This option enables or disables the counting enum heuristic. It uses the prefixes and suffixes specified in the options **CountingEnumPrefixes**, **CountingEnumSuffixes** to find counting enum constants by using them for prefix and suffix matching. This option is enabled by default. When **EnableCountingEnumHeuristic** is *false*: ``` enum TagWithCounter { Tag1, Tag2, Tag3, TagCount, }; struct TaggedUnion { TagWithCounter Kind; union { int A; long B; char *Str; float F; } Data; }; ``` When **EnableCountingEnumHeuristic** is *true*: ``` enum TagWithCounter { Tag1, Tag2, Tag3, TagCount, }; struct TaggedUnion { // warning: tagged union has more data members (4) than tags (3) TagWithCounter Kind; union { int A; long B; char *Str; float F; } Data; }; ``` - **CountingEnumPrefixes** See **CountingEnumSuffixes** below. - **CountingEnumSuffixes** CountingEnumPrefixes and CountingEnumSuffixes are lists of semicolon separated strings that are used to search for possible counting enum constants. These strings are matched case insensitively as prefixes and suffixes respectively on the names of the enum constants. If **EnableCountingEnumHeuristic** is *false* then these options do nothing. The default value of **CountingEnumSuffixes** is *count* and of **CountingEnumPrefixes** is the empty string. When **EnableCountingEnumHeuristic** is *true* and **CountingEnumSuffixes** is *count;size*: ``` enum TagWithCounterCount { Tag1, Tag2, Tag3, TagCount, }; struct TaggedUnionCount { // warning: tagged union has more data members (4) than tags (3) TagWithCounterCount Kind; union { int A; long B; char *Str; float F; } Data; }; enum TagWithCounterSize { Tag11, Tag22, Tag33, TagSize, }; struct TaggedUnionSize { // warning: tagged union has more data members (4) than tags (3) TagWithCounterSize Kind; union { int A; long B; char *Str; float F; } Data; }; ``` When **EnableCountingEnumHeuristic** is *true* and **CountingEnumPrefixes** is *maxsize;last\_* ``` enum TagWithCounterLast { Tag1, Tag2, Tag3, last_tag, }; struct TaggedUnionLast { // warning: tagged union has more data members (4) than tags (3) TagWithCounterLast tag; union { int I; short S; char *C; float F; } Data; }; enum TagWithCounterMaxSize { Tag1, Tag2, Tag3, MaxSizeTag, }; struct TaggedUnionMaxSize { // warning: tagged union has more data members (4) than tags (3) TagWithCounterMaxSize tag; union { int I; short S; char *C; float F; } Data; }; ``` - **StrictMode** When enabled, the check will also give a warning, when the number of tags is greater than the number of union data members. This option is disabled by default. When **StrictMode** \<#cmdoption-arg-StrictMode\> is *false*: ``` struct TaggedUnion { enum { Tag1, Tag2, Tag3, } Tags; union { int I; float F; } Data; }; ``` When **StrictMode** \<#cmdoption-arg-StrictMode\> is *true*: ``` struct TaggedUnion { // warning: tagged union has fewer data members (2) than tags (3) enum { Tag1, Tag2, Tag3, } Tags; union { int I; float F; } Data; }; ``` ### bugprone-terminating-continue Detects **do while** loops with a condition always evaluating to false that have a **continue** statement, as this **continue** terminates the loop effectively. ``` void f() { do { // some code continue; // terminating continue // some other code } while(false); ``` ### bugprone-throw-keyword-missing Warns about a potentially missing **throw** keyword. If a temporary object is created, but the object's type derives from (or is the same as) a class that has 'EXCEPTION', 'Exception' or 'exception' in its name, we can assume that the programmer's intention was to throw that object. Example: ``` void f(int i) { if (i < 0) { // Exception is created but is not thrown. std::runtime_error("Unexpected argument"); } } ``` ### bugprone-throwing-static-initialization Finds all **static** or **thread\_local** variable declarations where the initializer for the object may throw an exception. ### Options - **AllowedTypes** A semicolon-separated list of names of types that will be excluded from this check (declarations with matching type will be excluded). Regular expressions are accepted, e.g. **\[Rr\]ef(erence)?$** matches every type with suffix **Ref**, **ref**, **Reference** and **reference**. If a name in the list contains the sequence *::*, it is matched against the qualified type name (i.e. **namespace::Type**), otherwise it is matched against only the type name (i.e. **Type**). Default is an empty string. ### References This check corresponds to the CERT C++ Coding Standard rule ERR58-CPP. Handle all exceptions thrown before main() begins executing \. ### bugprone-too-small-loop-variable Detects those **for** loops that have a loop variable with a "too small" type which means this type can't represent all values which are part of the iteration range. ``` int main() { long size = 294967296l; for (short i = 0; i < size; ++i) {} } ``` This **for** loop is an infinite loop because the **short** type can't represent all values in the **\[0..size\]** interval. In a real use case size means a container's size which depends on the user input. ``` int doSomething(const std::vector& items) { for (short i = 0; i < items.size(); ++i) {} } ``` This algorithm works for a small amount of objects, but will lead to freeze for a larger user input. It's recommended to enable the compiler warning *-Wtautological-constant-out-of-range-compare* as well, since check does not inspect compile-time constant loop boundaries to avoid overlaps with the warning. ### Options - **MagnitudeBitsUpperLimit** Upper limit for the magnitude bits of the loop variable. If it's set the check filters out those catches in which the loop variable's type has more magnitude bits as the specified upper limit. The default value is 16. For example, if the user sets this option to 31 (bits), then a 32-bit **unsigned int** is ignored by the check, however a 32-bit **int** is not (A 32-bit **signed int** has 31 magnitude bits). ``` int main() { long size = 294967296l; for (unsigned i = 0; i < size; ++i) {} // no warning with MagnitudeBitsUpperLimit = 31 on a system where unsigned is 32-bit for (int i = 0; i < size; ++i) {} // warning with MagnitudeBitsUpperLimit = 31 on a system where int is 32-bit } ``` ### bugprone-unchecked-optional-access *Note*: This check uses a flow-sensitive static analysis to produce its results. Therefore, it may be more resource intensive (RAM, CPU) than the average clang-tidy check. This check identifies unsafe accesses to values contained in **std::optional\**, **absl::optional\**, **base::Optional\**, **folly::Optional\**, **bsl::optional**, or **BloombergLP::bdlb::NullableValue** objects. Below we will refer to all these types collectively as **optional\**. An access to the value of an **optional\** occurs when one of its **value**, **operator\***, or **operator-\>** member functions is invoked. To align with common misconceptions, the check considers these member functions as equivalent, even though there are subtle differences related to exceptions versus undefined behavior. See *Additional notes*, below, for more information on this topic. An access to the value of an **optional\** is considered safe if and only if code in the local scope (for example, a function body) ensures that the **optional\** has a value in all possible execution paths that can reach the access. That should happen either through an explicit check, using the **optional\::has\_value** member function, or by constructing the **optional\** in a way that shows that it unambiguously holds a value (e.g using **std::make\_optional** which always returns a populated **std::optional\**). Below we list some examples, starting with unsafe optional access patterns, followed by safe access patterns. ### Unsafe access patterns ### Access the value without checking if it exists The check flags accesses to the value that are not locally guarded by existence check: ``` void f(std::optional opt) { use(*opt); // unsafe: it is unclear whether `opt` has a value. } ``` ### Access the value in the wrong branch The check is aware of the state of an optional object in different branches of the code. For example: ``` void f(std::optional opt) { if (opt.has_value()) { } else { use(opt.value()); // unsafe: it is clear that `opt` does *not* have a value. } } ``` ### Assume a function result to be stable The check is aware that function results might not be stable. That is, consecutive calls to the same function might return different values. For example: ``` void f(Foo foo) { if (foo.take().has_value()) { use(*foo.take()); // unsafe: it is unclear whether `foo.take()` has a value. } } ``` ### Exception: accessor methods The check assumes *accessor* methods of a class are stable, with a heuristic to determine which methods are accessors. Specifically, parameter-free **const** methods and smart pointer-like APIs (non **const** overloads of **\*** when there is a parallel **const** overload) are treated as accessors. Note that this is not guaranteed to be safe -- but, it is widely used (safely) in practice. Calls to non **const** methods are assumed to modify the state of the object and affect the stability of earlier accessor calls. ### Rely on invariants of uncommon APIs The check is unaware of invariants of uncommon APIs. For example: ``` void f(Foo foo) { if (foo.HasProperty("bar")) { use(*foo.GetProperty("bar")); // unsafe: it is unclear whether `foo.GetProperty("bar")` has a value. } } ``` ### Check if a value exists, then pass the optional to another function The check relies on local reasoning. The check and value access must both happen in the same function. An access is considered unsafe even if the caller of the function performing the access ensures that the optional has a value. For example: ``` void g(std::optional opt) { use(*opt); // unsafe: it is unclear whether `opt` has a value. } void f(std::optional opt) { if (opt.has_value()) { g(opt); } } ``` ### Safe access patterns ### Check if a value exists, then access the value The check recognizes all straightforward ways for checking if a value exists and accessing the value contained in an optional object. For example: ``` void f(std::optional opt) { if (opt.has_value()) { use(*opt); } } ``` ### Check if a value exists, then access the value from a copy The criteria that the check uses is semantic, not syntactic. It recognizes when a copy of the optional object being accessed is known to have a value. For example: ``` void f(std::optional opt1) { if (opt1.has_value()) { std::optional opt2 = opt1; use(*opt2); } } ``` ### Ensure that a value exists using common macros The check is aware of common macros like **CHECK** and **DCHECK**. Those can be used to ensure that an optional object has a value. For example: ``` void f(std::optional opt) { DCHECK(opt.has_value()); use(*opt); } ``` ### Ensure that a value exists, then access the value in a correlated branch The check is aware of correlated branches in the code and can figure out when an optional object is ensured to have a value on all execution paths that lead to an access. For example: ``` void f(std::optional opt) { bool safe = false; if (opt.has_value() && SomeOtherCondition()) { safe = true; } // ... more code... if (safe) { use(*opt); } } ``` ### Stabilize function results Function results are not assumed to be stable across calls, except for const accessor methods. For more complex accessors (non-const, or depend on multiple params) it is best to store the result of the function call in a local variable and use that variable to access the value. For example: ``` void f(Foo foo) { if (const auto& foo_opt = foo.take(); foo_opt.has_value()) { use(*foo_opt); } } ``` ### Do not rely on uncommon-API invariants When uncommon APIs guarantee that an optional has contents, do not rely on it -- instead, check explicitly that the optional object has a value. For example: ``` void f(Foo foo) { if (const auto& property = foo.GetProperty("bar")) { use(*property); } } ``` instead of the *HasProperty*, *GetProperty* pairing we saw above. ### Do not rely on caller-performed checks If you know that all of a function's callers have checked that an optional argument has a value, either change the function to take the value directly or check the optional again in the local scope of the callee. For example: ``` void g(int val) { use(val); } void f(std::optional opt) { if (opt.has_value()) { g(*opt); } } ``` and ``` struct S { std::optional opt; int x; }; void g(const S &s) { if (s.opt.has_value() && s.x > 10) { use(*s.opt); } void f(S s) { if (s.opt.has_value()) { g(s); } } ``` ### Additional notes ### Aliases created via using declarations The check is aware of aliases of optional types that are created via **using** declarations. For example: ``` using OptionalInt = std::optional; void f(OptionalInt opt) { use(opt.value()); // unsafe: it is unclear whether `opt` has a value. } ``` ### Lambdas The check does not currently report unsafe optional accesses in lambdas. A future version will expand the scope to lambdas, following the rules outlined above. It is best to follow the same principles when using optionals in lambdas. ### Access with operator\*() vs. value() Given that **value()** has well-defined behavior (either throwing an exception or terminating the program), why treat it the same as **operator\*()** which causes undefined behavior (UB)? That is, why is it considered unsafe to access an optional with **value()**, if it's not provably populated with a value? For that matter, why is **CHECK()** followed by **operator\*()** any better than **value()**, given that they are semantically equivalent (on configurations that disable exceptions)? The answer is that we assume most users do not realize the difference between **value()** and **operator\*()**. Shifting to **operator\*()** and some form of explicit value-presence check or explicit program termination has two advantages: - • Readability. The check, and any potential side effects like program shutdown, are very clear in the code. Separating access from checks can actually make the checks more obvious. - • Performance. A single check can cover many or even all accesses within scope. This gives the user the best of both worlds -- the safety of a dynamic check, but without incurring redundant costs. ### GoogleTest awareness The check recognizes common macros like **ASSERT\_TRUE** and **ASSERT\_FALSE**: ``` TEST(OptionalTest, CheckValue) { std::optional opt; EXPECT_TRUE(opt.has_value()); EXPECT_EQ(opt.value(), 42); // unsafe: EXPECT_TRUE doesn't terminate test. ASSERT_TRUE(opt.has_value()); EXPECT_EQ(opt.value(), 42); // safe: ASSERT_TRUE terminates if no value. } ``` Less common macros such as **ASSERT\_NE(..., nullopt)** and **ASSERT\_THAT** are not currently supported and are ignored, which may result in false positives. ### Options - **IgnoreSmartPointerDereference** If set to *true*, the check ignores optionals that are reached through overloaded smart-pointer-like dereference (**operator\***, **operator-\>**) on classes other than the optional type itself. This helps avoid false positives where the analysis cannot equate results across such calls. This does not cover access through **operator\[\]**. Default is *false*. - **IgnoreValueCalls** If set to *true*, the check does not diagnose calls to **optional::value()**. Diagnostics for **operator\*()** and **operator-\>()** remain enabled. This is useful for codebases that intentionally rely on **value()** for defined, guarded access while still flagging UB-prone operator dereferences. Default is *false*. ### bugprone-unchecked-string-to-number-conversion This check flags calls to string-to-number conversion functions that do not verify the validity of the conversion, such as **atoi()** or **scanf()**. It does not flag calls to **strtol()**, or other, related conversion functions that do perform better error checking. ``` #include void func(const char *buff) { int si; if (buff) { si = atoi(buff); /* 'atoi' used to convert a string to an integer, but function will not report conversion errors; consider using 'strtol' instead. */ } else { /* Handle error */ } } ``` ### References This check corresponds to the CERT C Coding Standard rule ERR34-C. Detect errors when converting a string to a number \. ### bugprone-undefined-memory-manipulation Finds calls of memory manipulation functions **memset()**, **memcpy()** and **memmove()** on non-TriviallyCopyable objects resulting in undefined behavior. Using memory manipulation functions on non-TriviallyCopyable objects can lead to a range of subtle and challenging issues in C++ code. The most immediate concern is the potential for undefined behavior, where the state of the object may become corrupted or invalid. This can manifest as crashes, data corruption, or unexpected behavior at runtime, making it challenging to identify and diagnose the root cause. Additionally, misuse of memory manipulation functions can bypass essential object-specific operations, such as constructors and destructors, leading to resource leaks or improper initialization. For example, when using **memcpy** to copy **std::string**, pointer data is being copied, and it can result in a double free issue. ``` #include #include int main() { std::string source = "Hello"; std::string destination; std::memcpy(&destination, &source, sizeof(std::string)); // Undefined behavior may occur here, during std::string destructor call. return 0; } ``` ### bugprone-undelegated-constructor Finds creation of temporary objects in constructors that look like a function call to another constructor of the same class. The user most likely meant to use a delegating constructor or base class initializer. ### bugprone-unhandled-code-paths This check discovers situations where code paths are not fully-covered. **if-else if** chains that miss a final **else** branch might lead to unexpected program execution and be the result of a logical error. If the missing **else** branch is intended you can leave it empty with a clarifying comment. This warning can be noisy on some code bases, so it is disabled by default. ``` void f1() { int i = determineTheNumber(); if(i > 0) { // Some Calculation } else if (i < 0) { // Precondition violated or something else. } // ... } ``` Similar arguments hold for **switch** statements which do not cover all possible code paths. ``` // The missing default branch might be a logical error. It can be kept empty // if there is nothing to do, making it explicit. void f2(int i) { switch (i) { case 0: // something break; case 1: // something else break; } // All other numbers? } // Violates this rule as well, but already emits a compiler warning (-Wswitch). enum Color { Red, Green, Blue, Yellow }; void f3(enum Color c) { switch (c) { case Red: // We can't drive for now. break; case Green: // We are allowed to drive. break; } // Other cases missing } ``` ### Options - **WarnOnMissingElse** Boolean flag that activates a warning for missing **else** branches. Default is *false*. ### bugprone-unhandled-exception-at-new Finds calls to **new** with missing exception handler for **std::bad\_alloc**. Calls to **new** may throw exceptions of type **std::bad\_alloc** that should be handled. Alternatively, the nonthrowing form of **new** can be used. The check verifies that the exception is handled in the function that calls **new**. If a nonthrowing version is used or the exception is allowed to propagate out of the function no warning is generated. The exception handler is checked if it catches a **std::bad\_alloc** or **std::exception** exception type, or all exceptions (catch-all). The check assumes that any user-defined **operator new** is either **noexcept** or may throw an exception of type **std::bad\_alloc** (or one derived from it). Other exception class types are not taken into account. ``` int *f() noexcept { int *p = new int[1000]; // warning: missing exception handler for allocation failure at 'new' // ... return p; } ``` ``` int *f1() { // not 'noexcept' int *p = new int[1000]; // no warning: exception can be handled outside // of this function // ... return p; } int *f2() noexcept { try { int *p = new int[1000]; // no warning: exception is handled // ... return p; } catch (std::bad_alloc &) { // ... } // ... } int *f3() noexcept { int *p = new (std::nothrow) int[1000]; // no warning: "nothrow" is used // ... return p; } ``` ### bugprone-unhandled-self-assignment *cert-oop54-cpp* redirects here as an alias for this check. For the CERT alias, the *WarnOnlyIfThisHasSuspiciousField* option is set to *false*. Finds user-defined copy assignment operators which do not protect the code against self-assignment either by checking self-assignment explicitly or using the copy-and-swap or the copy-and-move method. By default, this check searches only those classes which have any pointer or C array field to avoid false positives. In case of a pointer or a C array, it's likely that self-copy assignment breaks the object if the copy assignment operator was not written with care. See also: OOP54-CPP. Gracefully handle self-copy assignment \ A copy assignment operator must prevent that self-copy assignment ruins the object state. A typical use case is when the class has a pointer field and the copy assignment operator first releases the pointed object and then tries to assign it: ``` class T { int* p; public: T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {} ~T() { delete p; } // ... T& operator=(const T &rhs) { delete p; p = new int(*rhs.p); return *this; } }; ``` There are two common C++ patterns to avoid this problem. The first is the self-assignment check: ``` class T { int* p; public: T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {} ~T() { delete p; } // ... T& operator=(const T &rhs) { if(this == &rhs) return *this; delete p; p = new int(*rhs.p); return *this; } }; ``` The second one is the copy-and-swap method when we create a temporary copy (using the copy constructor) and then swap this temporary object with **this**: ``` class T { int* p; public: T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {} ~T() { delete p; } // ... void swap(T &rhs) { using std::swap; swap(p, rhs.p); } T& operator=(const T &rhs) { T(rhs).swap(*this); return *this; } }; ``` There is a third pattern which is less common. Let's call it the copy-and-move method when we create a temporary copy (using the copy constructor) and then move this temporary object into **this** (needs a move assignment operator): ``` class T { int* p; public: T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {} ~T() { delete p; } // ... T& operator=(const T &rhs) { T t = rhs; *this = std::move(t); return *this; } T& operator=(T &&rhs) { p = rhs.p; rhs.p = nullptr; return *this; } }; ``` ### Options - **WarnOnlyIfThisHasSuspiciousField** When *true*, the check will warn only if the container class of the copy assignment operator has any suspicious fields (pointer, C array and C++ smart pointer). This option is set to *true* by default. ### bugprone-unintended-char-ostream-output Finds unintended character output from **unsigned char** and **signed char** to an **ostream**. Normally, when **unsigned char (uint8\_t)** or **signed char (int8\_t)** is used, it is more likely a number than a character. However, when it is passed directly to **std::ostream**'s **operator\<\<**, the result is the character output instead of the numeric value. This often contradicts the developer's intent to print integer values. ``` uint8_t v = 65; std::cout << v; // output 'A' instead of '65' ``` The check will suggest casting the value to an appropriate type to indicate the intent, by default, it will cast to **unsigned int** for **unsigned char** and **int** for **signed char**. ``` std::cout << static_cast(v); // when v is unsigned char std::cout << static_cast(v); // when v is signed char ``` To avoid lengthy cast statements, add prefix **+** to the variable can also suppress warnings because unary expression will promote the value to an **int**. ``` std::cout << +v; ``` Or cast to char to explicitly indicate that output should be a character. ``` std::cout << static_cast(v); ``` ### Options - **AllowedTypes** A semicolon-separated list of type names that will be treated like the **char** type: the check will not report variables declared with with these types or explicit cast expressions to these types. Note that this distinguishes type aliases from the original type, so specifying e.g. **unsigned char** here will not suppress reports about **uint8\_t** even if it is defined as a **typedef** alias for **unsigned char**. Default is *unsigned char;signed char*. - **CastTypeName** When *CastTypeName* is specified, the fix-it will use *CastTypeName* as the cast target type. Otherwise, fix-it will automatically infer the type. ### bugprone-unique-ptr-array-mismatch Finds initializations of C++ unique pointers to non-array type that are initialized with an array. If a pointer **std::unique\_ptr\** is initialized with a new-expression **new T\[\]** the memory is not deallocated correctly. A plain **delete** is used in this case to deallocate the target memory. Instead a **delete\[\]** call is needed. A **std::unique\_ptr\** uses the correct delete operator. The check does not emit warning if an **unique\_ptr** with user-specified deleter type is used. The check offers replacement of **unique\_ptr\** to **unique\_ptr\** if it is used at a single variable declaration (one variable in one statement). Example: ``` std::unique_ptr x(new Foo[10]); // -> std::unique_ptr x(new Foo[10]); // ^ warning: unique pointer to non-array is initialized with array std::unique_ptr x1(new Foo), x2(new Foo[10]); // no replacement // ^ warning: unique pointer to non-array is initialized with array D d; std::unique_ptr x3(new Foo[10], d); // no warning (custom deleter used) struct S { std::unique_ptr x(new Foo[10]); // no replacement in this case // ^ warning: unique pointer to non-array is initialized with array }; ``` This check partially covers the CERT C++ Coding Standard rule MEM51-CPP. Properly deallocate dynamically allocated resources \ However, only the **std::unique\_ptr** case is detected by this check. ### bugprone-unsafe-functions Checks for functions that have safer, more secure replacements available, or are considered deprecated due to design flaws. The check heavily relies on the functions from the **Annex K.** "Bounds-checking interfaces" of C11. - **The check implements the following rules from the CERT C Coding Standard:** - • Recommendation MSC24-C. Do not use deprecated or obsolescent functions \. - • Rule MSC33-C. Do not pass invalid data to the asctime() function \. *cert-msc24-c* and *cert-msc33-c* redirect here as aliases of this check. ### Unsafe functions The following functions are reported if **ReportDefaultFunctions** is enabled. If *Annex K.* is available, a replacement from *Annex K.* is suggested for the following functions: **asctime**, **asctime\_r**, **bsearch**, **ctime**, **fopen**, **fprintf**, **freopen**, **fscanf**, **fwprintf**, **fwscanf**, **getenv**, **gets**, **gmtime**, **localtime**, **mbsrtowcs**, **mbstowcs**, **memcpy**, **memmove**, **memset**, **printf**, **qsort**, **scanf**, **snprintf**, **sprintf**, **sscanf**, **strcat**, **strcpy**, **strerror**, **strlen**, **strncat**, **strncpy**, **strtok**, **swprintf**, **swscanf**, **vfprintf**, **vfscanf**, **vfwprintf**, **vfwscanf**, **vprintf**, **vscanf**, **vsnprintf**, **vsprintf**, **vsscanf**, **vswprintf**, **vswscanf**, **vwprintf**, **vwscanf**, **wcrtomb**, **wcscat**, **wcscpy**, **wcslen**, **wcsncat**, **wcsncpy**, **wcsrtombs**, **wcstok**, **wcstombs**, **wctomb**, **wmemcpy**, **wmemmove**, **wprintf**, **wscanf**. If *Annex K.* is not available, replacements are suggested only for the following functions from the previous list: - • **asctime**, **asctime\_r**, suggested replacement: **strftime** - • **gets**, suggested replacement: **fgets** The following functions are always checked, regardless of *Annex K* availability: - • **rewind**, suggested replacement: **fseek** - • **setbuf**, suggested replacement: **setvbuf** - • **std::get\_temporary\_buffer**, suggested replacement: "plain" allocation with **operator new\[\]** If **ReportMoreUnsafeFunctions** is enabled, the following functions are also checked: - • **bcmp**, suggested replacement: **memcmp** - • **bcopy**, suggested replacement: **memcpy\_s** if *Annex K* is available, or **memcpy** - • **bzero**, suggested replacement: **memset\_s** if *Annex K* is available, or **memset** - • **getpw**, suggested replacement: **getpwuid** - • **vfork**, suggested replacement: **posix\_spawn** Although mentioned in the associated CERT rules, the following functions are **ignored** by the check: **atof**, **atoi**, **atol**, **atoll**, **tmpfile**. The availability of *Annex K* is determined based on the following macros: - • **\_\_STDC\_LIB\_EXT1\_\_**: feature macro, which indicates the presence of *Annex K. "Bounds-checking interfaces"* in the library implementation - • **\_\_STDC\_WANT\_LIB\_EXT1\_\_**: user-defined macro, which indicates that the user requests the functions from *Annex K.* to be defined. Both macros have to be defined to suggest replacement functions from *Annex K.* **\_\_STDC\_LIB\_EXT1\_\_** is defined by the library implementation, and **\_\_STDC\_WANT\_LIB\_EXT1\_\_** must be defined to **1** by the user **before** including any system headers. ### Custom functions The option **CustomFunctions** allows the user to define custom functions to be checked. The format is the following, without newlines: ``` bugprone-unsafe-functions.CustomFunctions=" functionRegex1[, replacement1[, reason1]]; functionRegex2[, replacement2[, reason2]]; ... " ``` The functions are matched using POSIX extended regular expressions. *(Note: The regular expressions do not support negative* **(?!)** *matches.)* The *reason* is optional and is used to provide additional information about the reasoning behind the replacement. The default reason is *is marked as unsafe*. If *replacement* is empty, the default text *it should not be used* will be shown instead of the suggestion for a replacement. If the *reason* starts with the character *\>*, the reason becomes fully custom. The default suffix is disabled even if a *replacement* is present, and only the reason message is shown after the matched function, to allow better control over the suggestions. (The starting *\>* and whitespace directly after it are trimmed from the message.) As an example, the following configuration matches only the function **original** in the default namespace. A similar diagnostic can also be printed using a fully custom reason. ``` // bugprone-unsafe-functions.CustomFunctions: // ^original$, replacement, is deprecated; // Using the fully custom message syntax: // ^suspicious$,,> should be avoided if possible. original(); // warning: function 'original' is deprecated; 'replacement' should be used instead. suspicious(); // warning: function 'suspicious' should be avoided if possible. ::std::original(); // no-warning original_function(); // no-warning ``` If the regular expression contains the character *:*, it is matched against the qualified name (i.e. **std::original**), otherwise the regex is matched against the unqualified name (**original**). If the regular expression starts with *::* (or *^::*), it is matched against the fully qualified name (**::std::original**). One of the use cases for fully custom messages is suggesting compiler options and warning flags: ``` // bugprone-unsafe-functions.CustomFunctions: // ^memcpy$,,>is recommended to have compiler hardening using '_FORTIFY_SOURCE'; // ^printf$,,>is recommended to have the '-Werror=format-security' compiler warning flag; memcpy(dest, src, 999'999); // warning: function 'memcpy' is recommended to have compiler hardening using '_FORTIFY_SOURCE' printf(raw_str); // warning: function 'printf' is recommended to have the '-Werror=format-security' compiler warning flag ``` **Note:** Fully qualified names can contain template parameters on certain C++ classes, but not on C++ functions. Type aliases are resolved before matching. As an example, the member function **open** in the class **std::ifstream** has a fully qualified name of **::std::basic\_ifstream\::open**. The example could also be matched with the regex **::std::basic\_ifstream\<\[^\>\]\*\>::open**, which matches all potential template parameters, but does not match nested template classes. ### Options - **ReportMoreUnsafeFunctions** When *true*, additional functions from widely used APIs (such as POSIX) are added to the list of reported functions. See the main documentation of the check for the complete list as to what this option enables. Default is *true*. - **ReportDefaultFunctions** When *true*, the check reports the default set of functions. Consider changing the setting to false if you only want to see custom functions matched via custom functions. Default is *true*. - **CustomFunctions** A semicolon-separated list of custom functions to be matched. A matched function contains a regular expression, an optional name of the replacement function, and an optional reason, separated by comma. For more information, see Custom functions. ### Examples ``` #ifndef __STDC_LIB_EXT1__ #error "Annex K is not supported by the current standard library implementation." #endif #define __STDC_WANT_LIB_EXT1__ 1 #include // Defines functions from Annex K. #include enum { BUFSIZE = 32 }; void Unsafe(const char *Msg) { static const char Prefix[] = "Error: "; static const char Suffix[] = "\n"; char Buf[BUFSIZE] = {0}; strcpy(Buf, Prefix); // warning: function 'strcpy' is not bounds-checking; 'strcpy_s' should be used instead. strcat(Buf, Msg); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead. strcat(Buf, Suffix); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead. if (fputs(buf, stderr) < 0) { // error handling return; } } void UsingSafeFunctions(const char *Msg) { static const char Prefix[] = "Error: "; static const char Suffix[] = "\n"; char Buf[BUFSIZE] = {0}; if (strcpy_s(Buf, BUFSIZE, Prefix) != 0) { // error handling return; } if (strcat_s(Buf, BUFSIZE, Msg) != 0) { // error handling return; } if (strcat_s(Buf, BUFSIZE, Suffix) != 0) { // error handling return; } if (fputs(Buf, stderr) < 0) { // error handling return; } } ``` ### bugprone-unsafe-to-allow-exceptions Finds functions where throwing exceptions is unsafe but the function is still marked as potentially throwing. Throwing exceptions from the following functions can be problematic: - • Destructors - • Move constructors - • Move assignment operators - • The **main()** functions - • **swap()** functions - • **iter\_swap()** functions - • **iter\_move()** functions A destructor throwing an exception may result in undefined behavior, resource leaks or unexpected termination of the program. Throwing move constructor or move assignment also may result in undefined behavior or resource leak. The **swap()** operations expected to be non throwing most of the cases and they are always possible to implement in a non throwing way. Non throwing **swap()** operations are also used to create move operations. A throwing **main()** function also results in unexpected termination. The check finds any of these functions if it is marked with **noexcept(false)** or **throw(exception)**. This would indicate that the function is expected to throw exceptions. Only the presence of these keywords is checked, not if the function actually throws any exception. To check if the function actually throws exception, the check bugprone-exception-escape \<\> can be used (but it does not warn if a function is explicitly marked as throwing). ### Options - **CheckedSwapFunctions** Semicolon-separated list of checked swap function names (where throwing exceptions is unsafe). These functions are checked if the parameter count is at least 1. Default value is *swap;iter\_swap;iter\_move*. ### bugprone-unused-local-non-trivial-variable Warns when a local non trivial variable is unused within a function. The following types of variables are excluded from this check: - • trivial and trivially copyable - • references and pointers - • exception variables in catch clauses - • static or thread local - • structured bindings - • variables with **\[\[maybe\_unused\]\]** attribute - • name-independent variables This check can be configured to warn on all non-trivial variables by setting *IncludeTypes* to *.\**, and excluding specific types using *ExcludeTypes*. In the this example, *my\_lock* would generate a warning that it is unused. ``` std::mutex my_lock; // my_lock local variable is never used ``` In the next example, *future2* would generate a warning that it is unused. ``` std::future future1; std::future future2; // ... MyObject foo = future1.get(); // future2 is not used. ``` ### Options - **IncludeTypes** Semicolon-separated list of regular expressions matching types of variables to check. By default the following types are checked: - • *::std::.\*mutex* - • *::std::future* - • *::std::basic\_string* - • *::std::basic\_regex* - • *::std::basic\_istringstream* - • *::std::basic\_stringstream* - • *::std::bitset* - • *::std::filesystem::path* - **ExcludeTypes** A semicolon-separated list of regular expressions matching types that are excluded from the *IncludeTypes* matches. By default it is an empty list. ### bugprone-unused-raii Finds temporaries that look like RAII objects. The canonical example for this is a scoped lock. ``` { scoped_lock(&global_mutex); critical_section(); } ``` The destructor of the scoped\_lock is called before the **critical\_section** is entered, leaving it unprotected. We apply a number of heuristics to reduce the false positive count of this check: - • Ignore code expanded from macros. Testing frameworks make heavy use of this. - • Ignore types with trivial destructors. They are very unlikely to be RAII objects and there's no difference when they are deleted. - • Ignore objects at the end of a compound statement (doesn't change behavior). - • Ignore objects returned from a call. ### bugprone-unused-return-value Warns on unused function return values. The checked functions can be configured. Operator overloading with assignment semantics are ignored. ### Options - **CheckedFunctions** Semicolon-separated list of functions to check. This parameter supports regexp. The function is checked if the name and scope matches, with any arguments. By default the following functions are checked: **^::std::async$, ^::std::launder$, ^::std::remove$, ^::std::remove\_if$,** **^::std::unique$, ^::std::unique\_ptr::release$, ^::std::basic\_string::empty$,** **^::std::vector::empty$, ^::std::back\_inserter$, ^::std::distance$,** **^::std::find$, ^::std::find\_if$, ^::std::inserter$, ^::std::lower\_bound$,** **^::std::make\_pair$, ^::std::map::count$, ^::std::map::find$,** **^::std::map::lower\_bound$, ^::std::multimap::equal\_range$,** **^::std::multimap::upper\_bound$, ^::std::set::count$, ^::std::set::find$,** **^::std::setfill$, ^::std::setprecision$, ^::std::setw$, ^::std::upper\_bound$,** **^::std::vector::at$, ^::bsearch$, ^::ferror$, ^::feof$, ^::isalnum$,** **^::isalpha$, ^::isblank$, ^::iscntrl$, ^::isdigit$, ^::isgraph$, ^::islower$,** **^::isprint$, ^::ispunct$, ^::isspace$, ^::isupper$, ^::iswalnum$,** **^::iswprint$, ^::iswspace$, ^::isxdigit$, ^::memchr$, ^::memcmp$, ^::strcmp$,** **^::strcoll$, ^::strncmp$, ^::strpbrk$, ^::strrchr$, ^::strspn$, ^::strstr$,** **^::wcscmp$, ^::access$, ^::bind$, ^::connect$, ^::difftime$, ^::dlsym$,** **^::fnmatch$, ^::getaddrinfo$, ^::getopt$, ^::htonl$, ^::htons$,** **^::iconv\_open$, ^::inet\_addr$, isascii$, isatty$, ^::mmap$, ^::newlocale$,** **^::openat$, ^::pathconf$, ^::pthread\_equal$, ^::pthread\_getspecific$,** **^::pthread\_mutex\_trylock$, ^::readdir$, ^::readlink$, ^::recvmsg$,** **^::regexec$, ^::scandir$, ^::semget$, ^::setjmp$, ^::shm\_open$, ^::shmget$,** **^::sigismember$, ^::strcasecmp$, ^::strsignal$, ^::ttyname$** - • **std::async()**. Not using the return value makes the call synchronous. - • **std::launder()**. Not using the return value usually means that the function interface was misunderstood by the programmer. Only the returned pointer is "laundered", not the argument. - • **std::remove()**, **std::remove\_if()** and **std::unique()**. The returned iterator indicates the boundary between elements to keep and elements to be removed. Not using the return value means that the information about which elements to remove is lost. - • **std::unique\_ptr::release()**. Not using the return value can lead to resource leaks if the same pointer isn't stored anywhere else. Often, ignoring the **release()** return value indicates that the programmer confused the function with **reset()**. - • **std::basic\_string::empty()** and **std::vector::empty()**. Not using the return value often indicates that the programmer confused the function with **clear()**. - **CheckedReturnTypes** Semicolon-separated list of function return types to check. By default the following function return types are checked: *^::std::error\_code$*, *^::std::error\_condition$*, *^::std::errc$*, *^::std::expected$*, *^::boost::system::error\_code$* - **AllowCastToVoid** Controls whether casting return values to **void** is permitted. Default: *false*. cert-err33-c \<\> is an alias of this check that checks a fixed and large set of standard library functions. ### bugprone-use-after-move Warns if an object is used after it has been moved, for example: ``` std::string str = "Hello, world!\n"; std::vector messages; messages.emplace_back(std::move(str)); std::cout << str; ``` The last line will trigger a warning that **str** is used after it has been moved. The check does not trigger a warning if the object is reinitialized after the move and before the use. For example, no warning will be output for this code: ``` messages.emplace_back(std::move(str)); str = "Greetings, stranger!\n"; std::cout << str; ``` Subsections below explain more precisely what exactly the check considers to be a move, use, and reinitialization. The check takes control flow into account. A warning is only emitted if the use can be reached from the move. This means that the following code does not produce a warning: ``` if (condition) { messages.emplace_back(std::move(str)); } else { std::cout << str; } ``` On the other hand, the following code does produce a warning: ``` for (int i = 0; i < 10; ++i) { std::cout << str; messages.emplace_back(std::move(str)); } ``` (The use-after-move happens on the second iteration of the loop.) In some cases, the check may not be able to detect that two branches are mutually exclusive. For example (assuming that **i** is an int): ``` if (i == 1) { messages.emplace_back(std::move(str)); } if (i == 2) { std::cout << str; } ``` In this case, the check will erroneously produce a warning, even though it is not possible for both the move and the use to be executed. More formally, the analysis is flow-sensitive but not path-sensitive \. ### Silencing erroneous warnings An erroneous warning can be silenced by reinitializing the object after the move: ``` if (i == 1) { messages.emplace_back(std::move(str)); str = ""; } if (i == 2) { std::cout << str; } ``` If you want to avoid the overhead of actually reinitializing the object, you can create a dummy function that causes the check to assume the object was reinitialized: ``` template void IS_INITIALIZED(T&) {} ``` You can use this as follows: ``` if (i == 1) { messages.emplace_back(std::move(str)); } if (i == 2) { IS_INITIALIZED(str); std::cout << str; } ``` The check will not output a warning in this case because passing the object to a function as a non-const pointer or reference counts as a reinitialization (see section Reinitialization below). ### Unsequenced moves, uses, and reinitializations In many cases, C++ does not make any guarantees about the order in which sub-expressions of a statement are evaluated. This means that in code like the following, it is not guaranteed whether the use will happen before or after the move: ``` void f(int i, std::vector v); std::vector v = { 1, 2, 3 }; f(v[1], std::move(v)); ``` In this kind of situation, the check will note that the use and move are unsequenced. The check will also take sequencing rules into account when reinitializations occur in the same statement as moves or uses. A reinitialization is only considered to reinitialize a variable if it is guaranteed to be evaluated after the move and before the use. ### Move The check currently only considers calls of **std::move** on local variables or function parameters. It does not check moves of member variables or global variables. Any call of **std::move** on a variable is considered to cause a move of that variable, even if the result of **std::move** is not passed to an rvalue reference parameter. This means that the check will flag a use-after-move even on a type that does not define a move constructor or move assignment operator. This is intentional. Developers may use **std::move** on such a type in the expectation that the type will add move semantics in the future. If such a **std::move** has the potential to cause a use-after-move, we want to warn about it even if the type does not implement move semantics yet. Furthermore, if the result of **std::move** *is* passed to an rvalue reference parameter, this will always be considered to cause a move, even if the function that consumes this parameter does not move from it, or if it does so only conditionally. For example, in the following situation, the check will assume that a move always takes place: ``` std::vector messages; void f(std::string &&str) { // Only remember the message if it isn't empty. if (!str.empty()) { messages.emplace_back(std::move(str)); } } std::string str = ""; f(std::move(str)); ``` The check will assume that the last line causes a move, even though, in this particular case, it does not. Again, this is intentional. There is one special case: A call to **std::move** inside a **try\_emplace** call is conservatively assumed not to move. This is to avoid spurious warnings, as the check has no way to reason about the **bool** returned by **try\_emplace**. When analyzing the order in which moves, uses and reinitializations happen (see section Unsequenced moves, uses, and reinitializations), the move is assumed to occur in whichever function the result of the **std::move** is passed to. The check also handles perfect-forwarding with **std::forward** so the following code will also trigger a use-after-move warning. ``` void consume(int); void f(int&& i) { consume(std::forward(i)); consume(std::forward(i)); // use-after-move } ``` ### Use Any occurrence of the moved variable that is not a reinitialization (see below) or an explicit call to the variable destructor is considered to be a use. An exception to this are objects of type **std::unique\_ptr**, **std::shared\_ptr**, **std::weak\_ptr**, **std::optional**, and **std::any**, which can be reinitialized via **reset**. For smart pointers specifically, the moved-from objects have a well-defined state of being **nullptr\`\`s, and only** **\`\`operator\***, **operator-\>** and **operator\[\]** are considered bad accesses as they would be dereferencing a **nullptr**. User-defined types can be annotated as having the same semantics as standard smart pointers with **\[\[clang::annotate("clang-tidy",** **"bugprone-use-after-move", "null\_after\_move")\]\]**. This expresses that a moved-from object of this type is a null pointer. If multiple uses occur after a move, only the first of these is flagged. ### Reinitialization The check considers a variable to be reinitialized in the following cases: - • The variable occurs on the left-hand side of an assignment. - • The variable is passed to a function as a non-const pointer or non-const lvalue reference. (It is assumed that the variable may be an out-parameter for the function.) - • **clear()** or **assign()** is called on the variable and the variable is of one of the standard container types **basic\_string**, **vector**, **deque**, **forward\_list**, **list**, **set**, **map**, **multiset**, **multimap**, **unordered\_set**, **unordered\_map**, **unordered\_multiset**, **unordered\_multimap**. - • **reset()** is called on the variable and the variable is of type **std::unique\_ptr**, **std::shared\_ptr**, **std::weak\_ptr**, **std::optional**, or **std::any**. - • A member function marked with the **\[\[clang::reinitializes\]\]** attribute is called on the variable. - • The variable is passed as an argument to **std::tie** on the left-hand side of an assignment (e.g. **std::tie(a, b) = f(...)**). The tuple assignment operator writes back through the stored references, which reinitializes each named variable. If the variable in question is a struct and an individual member variable of that struct is written to, the check does not consider this to be a reinitialization -- even if, eventually, all member variables of the struct are written to. For example: ``` struct S { std::string str; int i; }; S s = { "Hello, world!\n", 42 }; S s_other = std::move(s); s.str = "Lorem ipsum"; s.i = 99; ``` The check will not consider **s** to be reinitialized after the last line; instead, the line that assigns to **s.str** will be flagged as a use-after-move. This is intentional as this pattern of reinitializing a struct is error-prone. For example, if an additional member variable is added to **S**, it is easy to forget to add the reinitialization for this additional member. Instead, it is safer to assign to the entire struct in one go, and this will also avoid the use-after-move warning. ### Options - **InvalidationFunctions** A semicolon-separated list of regular expressions matching names of functions that cause their first arguments to be invalidated (e.g., closing a handle). For member functions, the first argument is considered to be the implicit object argument (**this**). Default value is an empty string. - **ReinitializationFunctions** A semicolon-separated list of regular expressions matching names of functions that reinitialize the object. For member functions, the implicit object argument (**\*this**) is considered to be reinitialized. For non-member or static member functions, the first argument is considered to be reinitialized. Default value is an empty string. ### bugprone-virtual-near-miss Warn if a function is a near miss (i.e. the name is very similar and the function signature is the same) to a virtual function from a base class. Example: ``` struct Base { virtual void func(); }; struct Derived : Base { virtual void funk(); // warning: 'Derived::funk' has a similar name and the same signature as virtual method 'Base::func'; did you mean to override it? }; ``` ### cert-arr39-c The *cert-arr39-c* check is an alias, please see bugprone-sizeof-expression \<\> for more information. ### cert-con36-c The *cert-con36-c* check is an alias, please see bugprone-spuriously-wake-up-functions \<\> for more information. ### cert-con54-cpp The *cert-con54-cpp* check is an alias, please see bugprone-spuriously-wake-up-functions \<\> for more information. ### cert-ctr56-cpp The *cert-ctr56-cpp* check is an alias, please see bugprone-pointer-arithmetic-on-polymorphic-object \<\> for more information. ### cert-dcl03-c The *cert-dcl03-c* check is an alias, please see misc-static-assert \<\> for more information. ### cert-dcl16-c The *cert-dcl16-c* check is an alias, please see readability-uppercase-literal-suffix \<\> for more information. ### cert-dcl37-c The *cert-dcl37-c* check is an alias, please see bugprone-reserved-identifier \<\> for more information. ### cert-dcl50-cpp The *cert-dcl50-cpp* check is an alias, please see modernize-avoid-variadic-functions \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule DCL50-CPP. Do not define a C-style variadic function \. ### cert-dcl51-cpp The *cert-dcl51-cpp* check is an alias, please see bugprone-reserved-identifier \<\> for more information. ### cert-dcl54-cpp The *cert-dcl54-cpp* check is an alias, please see misc-new-delete-overloads \<\> for more information. ### cert-dcl58-cpp The *cert-dcl58-cpp* is an alias, please see bugprone-std-namespace-modification \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule DCL58-CPP. Do not modify the standard namespaces \. ### cert-dcl59-cpp The *cert-dcl59-cpp* check is an alias, please see misc-anonymous-namespace-in-header \<\> for more information. ### cert-env33-c The *cert-env33-c* check is an alias, please see bugprone-command-processor \<\> for more information. This check corresponds to the CERT C Coding Standard rule ENV33-C. Do not call system() \. ### cert-err09-cpp The *cert-err09-cpp* check is an alias, please see misc-throw-by-value-catch-by-reference \<\> for more information. This check corresponds to the CERT C++ Coding Standard recommendation ERR09-CPP. Throw anonymous temporaries. However, all of the CERT recommendations have been removed from public view, and so their justification for the behavior of this check requires an account on their wiki to view. ### cert-err33-c Warns on unused function return values. Many of the standard library functions return a value that indicates if the call was successful. Ignoring the returned value can cause unexpected behavior if an error has occurred. The following functions are checked: - • aligned\_alloc() - • asctime\_s() - • at\_quick\_exit() - • atexit() - • bsearch() - • bsearch\_s() - • btowc() - • c16rtomb() - • c32rtomb() - • calloc() - • clock() - • cnd\_broadcast() - • cnd\_init() - • cnd\_signal() - • cnd\_timedwait() - • cnd\_wait() - • ctime\_s() - • fclose() - • fflush() - • fgetc() - • fgetpos() - • fgets() - • fgetwc() - • fopen() - • fopen\_s() - • fprintf() - • fprintf\_s() - • fputc() - • fputs() - • fputwc() - • fputws() - • fread() - • freopen() - • freopen\_s() - • fscanf() - • fscanf\_s() - • fseek() - • fsetpos() - • ftell() - • fwprintf() - • fwprintf\_s() - • fwrite() - • fwscanf() - • fwscanf\_s() - • getc() - • getchar() - • getenv() - • getenv\_s() - • gets\_s() - • getwc() - • getwchar() - • gmtime() - • gmtime\_s() - • localtime() - • localtime\_s() - • malloc() - • mbrtoc16() - • mbrtoc32() - • mbsrtowcs() - • mbsrtowcs\_s() - • mbstowcs() - • mbstowcs\_s() - • memchr() - • mktime() - • mtx\_init() - • mtx\_lock() - • mtx\_timedlock() - • mtx\_trylock() - • mtx\_unlock() - • printf\_s() - • putc() - • putwc() - • raise() - • realloc() - • remove() - • rename() - • setlocale() - • setvbuf() - • scanf() - • scanf\_s() - • signal() - • snprintf() - • snprintf\_s() - • sprintf() - • sprintf\_s() - • sscanf() - • sscanf\_s() - • strchr() - • strerror\_s() - • strftime() - • strpbrk() - • strrchr() - • strstr() - • strtod() - • strtof() - • strtoimax() - • strtok() - • strtok\_s() - • strtol() - • strtold() - • strtoll() - • strtoumax() - • strtoul() - • strtoull() - • strxfrm() - • swprintf() - • swprintf\_s() - • swscanf() - • swscanf\_s() - • thrd\_create() - • thrd\_detach() - • thrd\_join() - • thrd\_sleep() - • time() - • timespec\_get() - • tmpfile() - • tmpfile\_s() - • tmpnam() - • tmpnam\_s() - • tss\_create() - • tss\_get() - • tss\_set() - • ungetc() - • ungetwc() - • vfprintf() - • vfprintf\_s() - • vfscanf() - • vfscanf\_s() - • vfwprintf() - • vfwprintf\_s() - • vfwscanf() - • vfwscanf\_s() - • vprintf\_s() - • vscanf() - • vscanf\_s() - • vsnprintf() - • vsnprintf\_s() - • vsprintf() - • vsprintf\_s() - • vsscanf() - • vsscanf\_s() - • vswprintf() - • vswprintf\_s() - • vswscanf() - • vswscanf\_s() - • vwprintf\_s() - • vwscanf() - • vwscanf\_s() - • wcrtomb() - • wcschr() - • wcsftime() - • wcspbrk() - • wcsrchr() - • wcsrtombs() - • wcsrtombs\_s() - • wcsstr() - • wcstod() - • wcstof() - • wcstoimax() - • wcstok() - • wcstok\_s() - • wcstol() - • wcstold() - • wcstoll() - • wcstombs() - • wcstombs\_s() - • wcstoumax() - • wcstoul() - • wcstoull() - • wcsxfrm() - • wctob() - • wctrans() - • wctype() - • wmemchr() - • wprintf\_s() - • wscanf() - • wscanf\_s() This check is an alias of check bugprone-unused-return-value \<\> with a fixed set of functions. Suppressing issues by casting to **void** is enabled by default and can be disabled by setting *AllowCastToVoid* option to *false*. The check corresponds to a part of CERT C Coding Standard rule ERR33-C. Detect and handle standard library errors \. The list of checked functions is taken from the rule, with following exception: - • The check can not differentiate if a function is called with **NULL** argument. Therefore the following functions are not checked: **mblen**, **mbrlen**, **mbrtowc**, **mbtowc**, **wctomb**, **wctomb\_s** ### cert-err34-c The cert-err34-c check is an alias, please see bugprone-unchecked-string-to-number-conversion \<\> for more information. ### cert-err52-cpp The *cert-err52-cpp* check is an alias, please see modernize-avoid-setjmp-longjmp \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule ERR52-CPP. Do not use setjmp() or longjmp() \. ### cert-err58-cpp The *cert-err58-cpp* check is an alias, please see bugprone-throwing-static-initialization \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule ERR58-CPP. Handle all exceptions thrown before main() begins executing \. ### cert-err60-cpp The *cert-err60-cpp* check is an alias, please see bugprone-exception-copy-constructor-throws \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule ERR60-CPP. Exception objects must be nothrow copy constructible \. ### cert-err61-cpp The *cert-err61-cpp* check is an alias, please see misc-throw-by-value-catch-by-reference \<\> for more information. ### cert-exp42-c The *cert-exp42-c* check is an alias, please see bugprone-suspicious-memory-comparison \<\> for more information. ### cert-exp45-c The *cert-exp45-c* check is an alias, please see bugprone-assignment-in-selection-statement \<\> for more information. ### cert-fio38-c The *cert-fio38-c* check is an alias, please see misc-non-copyable-objects \<\> for more information. This check corresponds to CERT C++ Coding Standard rule FIO38-C. Do not copy a FILE object \. ### cert-flp30-c The *cert-flp30-c* check is an alias, please see bugprone-float-loop-counter \<\> for more information This check corresponds to the CERT C Coding Standard rule FLP30-C. Do not use floating-point variables as loop counters \. ### cert-flp37-c The *cert-flp37-c* check is an alias, please see bugprone-suspicious-memory-comparison \<\> for more information. ### cert-int09-c The *cert-int09-c* check is an alias, please see readability-enum-initial-value \<\> for more information. ### cert-mem57-cpp The *cert-mem57-cpp* is an alias, please see bugprone-default-operator-new-on-overaligned-type \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule MEM57-CPP. Avoid using default operator new for over-aligned types \. ### cert-msc24-c The *cert-msc24-c* check is an alias, please see bugprone-unsafe-functions \<\> for more information. ### cert-msc30-c The *cert-msc30-c* check is an alias, please see misc-predictable-rand \<\> for more information. This check corresponds to the CERT C Coding Standard rule MSC30-C. Do not use the rand() function for generating pseudorandom numbers \. ### cert-msc32-c The *cert-msc32-c* check is an alias, please see bugprone-random-generator-seed \<\> for more information. This check corresponds to the CERT C Coding Standard rule MSC32-C. Properly seed pseudorandom number generators \. ### cert-msc33-c The *cert-msc33-c* check is an alias, please see bugprone-unsafe-functions \<\> for more information. ### cert-msc50-cpp The *cert-msc50-cpp* check is an alias, please see misc-predictable-rand \<\> for more information. This check corresponds to the CERT C Coding Standard rule MSC50-CPP. Do not use std::rand() for generating pseudorandom numbers \. ### cert-msc51-cpp The *cert-msc51-cpp* check is an alias, please see bugprone-random-generator-seed \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule MSC51-CPP. Ensure your random number generator is properly seeded \. ### cert-msc54-cpp The *cert-msc54-cpp* check is an alias, please see bugprone-signal-handler \<\> for more information. ### cert-oop11-cpp The *cert-oop11-cpp check* is an alias, please see performance-move-constructor-init \<\> for more information. This check corresponds to the CERT C++ Coding Standard recommendation OOP11-CPP. Do not copy-initialize members or base classes from a move constructor. However, all of the CERT recommendations have been removed from public view, and so their justification for the behavior of this check requires an account on their wiki to view. ### cert-oop54-cpp The *cert-oop54-cpp* check is an alias, please see bugprone-unhandled-self-assignment \<\> for more information. ### cert-oop57-cpp The *cert-oop57-cpp* check is an alias, please see bugprone-raw-memory-call-on-non-trivial-type \<\> for more information. This check corresponds to the CERT C++ Coding Standard rule OOP57-CPP. Prefer special member functions and overloaded operators to C Standard Library functions \. ### cert-oop58-cpp The *cert-oop58-cpp* check is an alias, please see bugprone-copy-constructor-mutates-argument \<\> for more information. ### cert-pos44-c The *cert-pos44-c* check is an alias, please see bugprone-bad-signal-to-kill-thread \<\> for more information. ### cert-pos47-c The *cert-pos47-c* check is an alias, please see concurrency-thread-canceltype-asynchronous \<\> for more information. ### cert-sig30-c The *cert-sig30-c* check is an alias, please see bugprone-signal-handler \<\> for more information. ### cert-str34-c The *cert-str34-c* check is an alias, please see bugprone-signed-char-misuse \<\> for more information. ### clang-analyzer-core.BitwiseShift Finds cases where bitwise shift operation causes undefined behaviour. The *clang-analyzer-core.BitwiseShift* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.CallAndMessage Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers). The *clang-analyzer-core.CallAndMessage* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.DivideZero Check for division by zero. The *clang-analyzer-core.DivideZero* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.NonNullParamChecker Check for null pointers passed as arguments to a function whose arguments are references or marked with the 'nonnull' attribute. The *clang-analyzer-core.NonNullParamChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.NullDereference Check for dereferences of null pointers. The *clang-analyzer-core.NullDereference* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.StackAddressEscape Check that addresses to stack memory do not escape the function. The *clang-analyzer-core.StackAddressEscape* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.UndefinedBinaryOperatorResult Check for undefined results of binary operators. The *clang-analyzer-core.UndefinedBinaryOperatorResult* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.VLASize Check for declarations of VLA of undefined or zero size. The *clang-analyzer-core.VLASize* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.ArraySubscript Check for uninitialized values used as array subscripts. The *clang-analyzer-core.uninitialized.ArraySubscript* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.Assign Check for assigning uninitialized values. The *clang-analyzer-core.uninitialized.Assign* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.Branch Check for uninitialized values used as branch conditions. The *clang-analyzer-core.uninitialized.Branch* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.CapturedBlockVariable Check for blocks that capture uninitialized values. The *clang-analyzer-core.uninitialized.CapturedBlockVariable* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.NewArraySize Check if the size of the array in a new\[\] expression is undefined. The *clang-analyzer-core.uninitialized.NewArraySize* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-core.uninitialized.UndefReturn Check for uninitialized values being returned to the caller. The *clang-analyzer-core.uninitialized.UndefReturn* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.ArrayDelete Reports destructions of arrays of polymorphic objects that are destructed as their base class. The *clang-analyzer-cplusplus.ArrayDelete* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.InnerPointer Check for inner pointers of C++ containers used after re/deallocation. The *clang-analyzer-cplusplus.InnerPointer* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.Move Find use-after-move bugs in C++. The *clang-analyzer-cplusplus.Move* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.NewDelete Check for double-free and use-after-free problems. Traces memory managed by new/delete. The *clang-analyzer-cplusplus.NewDelete* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.NewDeleteLeaks Check for memory leaks. Traces memory managed by new/delete. The *clang-analyzer-cplusplus.NewDeleteLeaks* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.PlacementNew Check if default placement new is provided with pointers to sufficient storage capacity. The *clang-analyzer-cplusplus.PlacementNew* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.SelfAssignment Checks C++ copy and move assignment operators for self assignment. The *clang-analyzer-cplusplus.SelfAssignment* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-cplusplus.StringChecker Checks C++ std::string bugs. The *clang-analyzer-cplusplus.StringChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-deadcode.DeadStores Check for values stored to variables that are never read afterwards. The *clang-analyzer-deadcode.DeadStores* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-fuchsia.HandleChecker A Checker that detect leaks related to Fuchsia handles. The *clang-analyzer-fuchsia.HandleChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-nullability.NullPassedToNonnull Warns when a null pointer is passed to a pointer which has a \_Nonnull type. The *clang-analyzer-nullability.NullPassedToNonnull* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-nullability.NullReturnedFromNonnull Warns when a null pointer is returned from a function that has \_Nonnull return type. The *clang-analyzer-nullability.NullReturnedFromNonnull* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-nullability.NullableDereferenced Warns when a nullable pointer is dereferenced. The *clang-analyzer-nullability.NullableDereferenced* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-nullability.NullablePassedToNonnull Warns when a nullable pointer is passed to a pointer which has a \_Nonnull type. The *clang-analyzer-nullability.NullablePassedToNonnull* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-nullability.NullableReturnedFromNonnull Warns when a nullable pointer is returned from a function that has \_Nonnull return type. The *clang-analyzer-nullability.NullableReturnedFromNonnull* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.core.EnumCastOutOfRange Check integer to enumeration casts for out of range values. The *clang-analyzer-optin.core.EnumCastOutOfRange* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.cplusplus.UninitializedObject Reports uninitialized fields after object construction. The *clang-analyzer-optin.cplusplus.UninitializedObject* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.cplusplus.VirtualCall Check virtual function calls during construction/destruction. The *clang-analyzer-optin.cplusplus.VirtualCall* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.mpi.MPI-Checker Checks MPI code. The *clang-analyzer-optin.mpi.MPI-Checker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.osx.cocoa.localizability.EmptyLocalizationContextChecker Check that NSLocalizedString macros include a comment for context. The *clang-analyzer-optin.osx.cocoa.localizability.EmptyLocalizationContextChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.osx.cocoa.localizability.NonLocalizedStringChecker Warns about uses of non-localized NSStrings passed to UI methods expecting localized NSStrings. The *clang-analyzer-optin.osx.cocoa.localizability.NonLocalizedStringChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.performance.GCDAntipattern Check for performance anti-patterns when using Grand Central Dispatch. The *clang-analyzer-optin.performance.GCDAntipattern* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.performance.Padding Check for excessively padded structs. The *clang-analyzer-optin.performance.Padding* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.portability.UnixAPI Finds implementation-defined behavior in UNIX/Posix functions. The *clang-analyzer-optin.portability.UnixAPI* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-optin.taint.TaintedAlloc Check for memory allocations, where the size parameter might be a tainted (attacker controlled) value. The *clang-analyzer-optin.taint.TaintedAlloc* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.API Check for proper uses of various Apple APIs. The *clang-analyzer-osx.API* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.NumberObjectConversion Check for erroneous conversions of objects representing numbers into numbers. The *clang-analyzer-osx.NumberObjectConversion* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.ObjCProperty Check for proper uses of Objective-C properties. The *clang-analyzer-osx.ObjCProperty* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.SecKeychainAPI Check for proper uses of Secure Keychain APIs. The *clang-analyzer-osx.SecKeychainAPI* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.AtSync Check for nil pointers used as mutexes for @synchronized. The *clang-analyzer-osx.cocoa.AtSync* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.AutoreleaseWrite Warn about potentially crashing writes to autoreleasing objects from different autoreleasing pools in Objective-C. The *clang-analyzer-osx.cocoa.AutoreleaseWrite* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.ClassRelease Check for sending 'retain', 'release', or 'autorelease' directly to a Class. The *clang-analyzer-osx.cocoa.ClassRelease* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.Dealloc Warn about Objective-C classes that lack a correct implementation of -dealloc. The *clang-analyzer-osx.cocoa.Dealloc* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.IncompatibleMethodTypes Warn about Objective-C method signatures with type incompatibilities. The *clang-analyzer-osx.cocoa.IncompatibleMethodTypes* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.Loops Improved modeling of loops using Cocoa collection types. The *clang-analyzer-osx.cocoa.Loops* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.MissingSuperCall Warn about Objective-C methods that lack a necessary call to super. The *clang-analyzer-osx.cocoa.MissingSuperCall* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.NSAutoreleasePool Warn for suboptimal uses of NSAutoreleasePool in Objective-C GC mode. The *clang-analyzer-osx.cocoa.NSAutoreleasePool* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.NSError Check usage of NSError\*\* parameters. The *clang-analyzer-osx.cocoa.NSError* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.NilArg Check for prohibited nil arguments to ObjC method calls. The *clang-analyzer-osx.cocoa.NilArg* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.NonNilReturnValue Model the APIs that are guaranteed to return a non-nil value. The *clang-analyzer-osx.cocoa.NonNilReturnValue* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.ObjCGenerics Check for type errors when using Objective-C generics. The *clang-analyzer-osx.cocoa.ObjCGenerics* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.RetainCount Check for leaks and improper reference count management. The *clang-analyzer-osx.cocoa.RetainCount* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.RunLoopAutoreleaseLeak Check for leaked memory in autorelease pools that will never be drained. The *clang-analyzer-osx.cocoa.RunLoopAutoreleaseLeak* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.SelfInit Check that 'self' is properly initialized inside an initializer method. The *clang-analyzer-osx.cocoa.SelfInit* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.SuperDealloc Warn about improper use of '\[super dealloc\]' in Objective-C. The *clang-analyzer-osx.cocoa.SuperDealloc* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.UnusedIvars Warn about private ivars that are never used. The *clang-analyzer-osx.cocoa.UnusedIvars* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.cocoa.VariadicMethodTypes Check for passing non-Objective-C types to variadic collection initialization methods that expect only Objective-C types. The *clang-analyzer-osx.cocoa.VariadicMethodTypes* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.coreFoundation.CFError Check usage of CFErrorRef\* parameters. The *clang-analyzer-osx.coreFoundation.CFError* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.coreFoundation.CFNumber Check for proper uses of CFNumber APIs. The *clang-analyzer-osx.coreFoundation.CFNumber* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.coreFoundation.CFRetainRelease Check for null arguments to CFRetain/CFRelease/CFMakeCollectable. The *clang-analyzer-osx.coreFoundation.CFRetainRelease* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.coreFoundation.containers.OutOfBounds Checks for index out-of-bounds when using 'CFArray' API. The *clang-analyzer-osx.coreFoundation.containers.OutOfBounds* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-osx.coreFoundation.containers.PointerSizedValues Warns if 'CFArray', 'CFDictionary', 'CFSet' are created with non-pointer-size values. The *clang-analyzer-osx.coreFoundation.containers.PointerSizedValues* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.FloatLoopCounter Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP). The *clang-analyzer-security.FloatLoopCounter* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.PutenvStackArray Finds calls to the putenv function which pass a pointer to a stack-allocated (automatic) array as the argument. Function putenv does not copy the passed string, only a pointer to the data is stored and this data can be read even by other threads. Content of a stack-allocated array is likely to be overwritten after exiting from the function. The *clang-analyzer-security.PutenvStackArray* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.SetgidSetuidOrder The checker checks for sequences of **setuid(getuid())** and **setgid(getgid())** calls (in this order). If such a sequence is found and there is no other privilege-changing function call (**seteuid**, **setreuid**, **setresuid** and the GID versions of these) in between, a warning is generated. The checker finds only exactly **setuid(getuid())** calls (and the GID versions), not for example if the result of **getuid()** is stored in a variable. The *clang-analyzer-security.SetgidSetuidOrder* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.cert.env.InvalidPtr Finds usages of possibly invalidated pointers. The *clang-analyzer-security.cert.env.InvalidPtr* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling Warn on uses of unsecure or deprecated buffer manipulating functions. The *clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.UncheckedReturn Warn on uses of functions whose return values must be always checked. The *clang-analyzer-security.insecureAPI.UncheckedReturn* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.bcmp Warn on uses of the 'bcmp' function. The *clang-analyzer-security.insecureAPI.bcmp* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.bcopy Warn on uses of the 'bcopy' function. The *clang-analyzer-security.insecureAPI.bcopy* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.bzero Warn on uses of the 'bzero' function. The *clang-analyzer-security.insecureAPI.bzero* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.decodeValueOfObjCType Warn on uses of the '-decodeValueOfObjCType:at:' method. The *clang-analyzer-security.insecureAPI.decodeValueOfObjCType* check is an alias, please see Clang Static Analyzer security.insecureAPI.decodeValueOfObjCType \ for more information. ### clang-analyzer-security.insecureAPI.getpw Warn on uses of the 'getpw' function. The *clang-analyzer-security.insecureAPI.getpw* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.gets Warn on uses of the 'gets' function. The *clang-analyzer-security.insecureAPI.gets* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.mkstemp Warn when 'mkstemp' is passed fewer than 6 X's in the format string. The *clang-analyzer-security.insecureAPI.mkstemp* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.mktemp Warn on uses of the 'mktemp' function. The *clang-analyzer-security.insecureAPI.mktemp* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.rand Warn on uses of the 'rand', 'random', and related functions. The *clang-analyzer-security.insecureAPI.rand* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.strcpy Warn on uses of the 'strcpy' and 'strcat' functions. The *clang-analyzer-security.insecureAPI.strcpy* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-security.insecureAPI.vfork Warn on uses of the 'vfork' function. The *clang-analyzer-security.insecureAPI.vfork* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.API Check calls to various UNIX/Posix functions. The *clang-analyzer-unix.API* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.BlockInCriticalSection Check for calls to blocking functions inside a critical section. The *clang-analyzer-unix.BlockInCriticalSection* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.Errno Check for improper use of 'errno'. The *clang-analyzer-unix.Errno* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.Malloc Check for memory leaks, double free, and use-after-free problems. Traces memory managed by malloc()/free(). The *clang-analyzer-unix.Malloc* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.MallocSizeof Check for dubious malloc arguments involving sizeof. The *clang-analyzer-unix.MallocSizeof* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.MismatchedDeallocator Check for mismatched deallocators. The *clang-analyzer-unix.MismatchedDeallocator* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.StdCLibraryFunctions Check for invalid arguments of C standard library functions, and apply relations between arguments and return value. The *clang-analyzer-unix.StdCLibraryFunctions* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.Stream Check stream handling functions. The *clang-analyzer-unix.Stream* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.Vfork Check for proper usage of vfork. The *clang-analyzer-unix.Vfork* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.cstring.BadSizeArg Check the size argument passed into C string functions for common erroneous patterns. The *clang-analyzer-unix.cstring.BadSizeArg* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-unix.cstring.NullArg Check for null pointers being passed as arguments to C string functions. The *clang-analyzer-unix.cstring.NullArg* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-webkit.NoUncountedMemberChecker Check for no uncounted member variables. The *clang-analyzer-webkit.NoUncountedMemberChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-webkit.RefCntblBaseVirtualDtor Check for any ref-countable base class having virtual destructor. The *clang-analyzer-webkit.RefCntblBaseVirtualDtor* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### clang-analyzer-webkit.UncountedLambdaCapturesChecker Check uncounted lambda captures. The *clang-analyzer-webkit.UncountedLambdaCapturesChecker* check is an alias, please see Clang Static Analyzer Available Checkers \ for more information. ### concurrency-mt-unsafe Checks for some thread-unsafe functions against a black list of known-to-be-unsafe functions. Usually they access static variables without synchronization (e.g. [gmtime(3)](/gmtime/3.md)) or utilize signals in a racy way. The set of functions to check is specified with the *FunctionSet* option. Note that using some thread-unsafe functions may be still valid in concurrent programming if only a single thread is used (e.g. [setenv(3)](/setenv/3.md)), however, some functions may track a state in global variables which would be clobbered by subsequent (non-parallel, but concurrent) calls to a related function. E.g. the following code suffers from unprotected accesses to a global state: ``` // getnetent(3) maintains global state with DB connection, etc. // If a concurrent green thread calls getnetent(3), the global state is corrupted. netent = getnetent(); yield(); netent = getnetent(); ``` Examples: ``` tm = gmtime(timep); // uses a global buffer sleep(1); // implementation may use SIGALRM ``` ### Options - **FunctionSet** Specifies which functions in libc should be considered thread-safe, possible values are *posix*, *glibc*, or *any*. *posix* means POSIX defined thread-unsafe functions. POSIX.1-2001 in "2.9.1 Thread-Safety" defines that all functions specified in the standard are thread-safe except a predefined list of thread-unsafe functions. Glibc defines some of them as thread-safe (e.g. [dirname(3)](/dirname/3.md)), but adds non-POSIX thread-unsafe ones (e.g. [getopt\_long(3)](/getopt_long/3.md)). Glibc's list is compiled from GNU web documentation with a search for MT-Safe tag: \ If you want to identify thread-unsafe API for at least one libc or unsure which libc will be used, use *any* (default). ### concurrency-thread-canceltype-asynchronous Finds **pthread\_setcanceltype** function calls where a thread's cancellation type is set to asynchronous. Asynchronous cancellation type (**PTHREAD\_CANCEL\_ASYNCHRONOUS**) is generally unsafe, use type **PTHREAD\_CANCEL\_DEFERRED** instead which is the default. Even with deferred cancellation, a cancellation point in an asynchronous signal handler may still be acted upon and the effect is as if it was an asynchronous cancellation. ``` pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldtype); ``` This check corresponds to the CERT C Coding Standard rule POS47-C. Do not use threads that can be canceled asynchronously \. *cert-pos47-c* redirects here as an alias of this check. ### cppcoreguidelines-avoid-c-arrays The *cppcoreguidelines-avoid-c-arrays* check is an alias, please see modernize-avoid-c-arrays \<\> for more information. ### cppcoreguidelines-avoid-capturing-lambda-coroutines Flags C++20 coroutine lambdas with non-empty capture lists that may cause use-after-free errors and suggests avoiding captures or ensuring the lambda closure object has a guaranteed lifetime. This check implements CP.51 \ from the C++ Core Guidelines. Using coroutine lambdas with non-empty capture lists can be risky, as capturing variables can lead to accessing freed memory after the first suspension point. This issue can occur even with refcounted smart pointers and copyable types. When a lambda expression creates a coroutine, it results in a closure object with storage, which is often on the stack and will eventually go out of scope. When the closure object goes out of scope, its captures also go out of scope. While normal lambdas finish executing before this happens, coroutine lambdas may resume from suspension after the closure object has been destructed, resulting in use-after-free memory access for all captures. Consider the following example: ``` int value = get_value(); std::shared_ptr sharedFoo = get_foo(); { const auto lambda = [value, sharedFoo]() -> std::future { co_await something(); // "sharedFoo" and "value" have already been destroyed // the "shared" pointer didn't accomplish anything }; lambda(); } // the lambda closure object has now gone out of scope ``` In this example, the lambda object is defined with two captures: value and **sharedFoo**. When **lambda()** is called, the lambda object is created on the stack, and the captures are copied into the closure object. When the coroutine is suspended, the lambda object goes out of scope, and the closure object is destroyed. When the coroutine is resumed, the captured variables may have been destroyed, resulting in use-after-free bugs. In conclusion, the use of coroutine lambdas with non-empty capture lists can lead to use-after-free errors when resuming the coroutine after the closure object has been destroyed. This check helps prevent such errors by flagging C++20 coroutine lambdas with non-empty capture lists and suggesting avoiding captures or ensuring the lambda closure object has a guaranteed lifetime. Following these guidelines can help ensure the safe and reliable use of coroutine lambdas in C++ code. ### Options - **AllowExplicitObjectParameters** When set to *true*, lambda coroutines that use C++23 "deducing this" (explicit object parameter, e.g. **this auto**) are not flagged by this check, because the captures are moved into the coroutine frame, decoupling their lifetime from the lambda object. Default is *false*. The example from above can be made safe and will pass this check with the following change: ``` int value = get_value(); std::shared_ptr sharedFoo = get_foo(); { // Pass "this auto" as the first argument to the lambda const auto lambda = [value, sharedFoo](this auto) -> std::future { co_await something(); }; lambda(); } // the lambda closure object has now gone out of scope, but captures are // no longer coupled to its lifetime ``` ### cppcoreguidelines-avoid-const-or-ref-data-members This check warns when structs or classes that are copyable or movable, and have const-qualified or reference (lvalue or rvalue) data members. Having such members is rarely useful, and makes the class only copy-constructible but not copy-assignable. Examples: ``` // Bad, const-qualified member struct Const { const int x; } // Good: class Foo { public: int get() const { return x; } private: int x; }; // Bad, lvalue reference member struct Ref { int& x; }; // Good: struct Foo { int* x; std::unique_ptr x; std::shared_ptr x; gsl::not_null x; }; // Bad, rvalue reference member struct RefRef { int&& x; }; ``` This check implements C.12 \ from the C++ Core Guidelines. Further reading: Data members: Never const \. ### cppcoreguidelines-avoid-do-while Warns when using **do-while** loops. They are less readable than plain **while** loops, since the termination condition is at the end and the condition is not checked prior to the first iteration. This can lead to subtle bugs. This check implements ES.75 \ from the C++ Core Guidelines. Examples: ``` int x; do { std::cin >> x; // ... } while (x < 0); ``` ### Options - **IgnoreMacros** Ignore the check when analyzing macros. This is useful for safely defining function-like macros: ``` #define FOO_BAR(x) \ do { \ foo(x); \ bar(x); \ } while(0) ``` Defaults to *false*. ### cppcoreguidelines-avoid-goto The usage of **goto** for control flow is error prone and should be replaced with looping constructs. Only forward jumps in nested loops are accepted. This check implements ES.76 \ from the C++ Core Guidelines. For more information on why to avoid programming with **goto** you can read the famous paper A Case against the GO TO Statement. \. The check diagnoses **goto** for backward jumps in every language mode. These should be replaced with *C/C++* looping constructs. ``` // Bad, handwritten for loop. int i = 0; // Jump label for the loop loop_start: do_some_operation(); if (i < 100) { ++i; goto loop_start; } // Better for(int i = 0; i < 100; ++i) do_some_operation(); ``` Modern C++ needs **goto** only to jump out of nested loops. ``` for(int i = 0; i < 100; ++i) { for(int j = 0; j < 100; ++j) { if (i * j > 500) goto early_exit; } } early_exit: some_operation(); ``` All other uses of **goto** are diagnosed in *C++*. ### Options - **IgnoreMacros** If set to *true*, the check will not warn if a **goto** statement is expanded from a macro. Default is *false*. ### cppcoreguidelines-avoid-magic-numbers The *cppcoreguidelines-avoid-magic-numbers* check is an alias, please see readability-magic-numbers \<\> for more information. ### cppcoreguidelines-avoid-non-const-global-variables Finds non-const global variables as described in I.2 \ of C++ Core Guidelines. As R.6 \ of C++ Core Guidelines is a duplicate of rule I.2 \ it also covers that rule. ``` char a; // Warns! const char b = 0; namespace some_namespace { char c; // Warns! const char d = 0; } char * c_ptr1 = &some_namespace::c; // Warns! char *const c_const_ptr = &some_namespace::c; // Warns! char & c_reference = some_namespace::c; // Warns! class Foo // No Warnings inside Foo, only namespace scope is covered { public: char e = 0; const char f = 0; protected: char g = 0; private: char h = 0; }; ``` The variables **a**, **c**, **c\_ptr1**, **c\_const\_ptr** and **c\_reference** will all generate warnings since they are either a non-const globally accessible variable, a pointer or a reference providing global access to non-const data or both. ### Options - **AllowInternalLinkage** When set to *true*, static non-const variables and variables in anonymous namespaces will not generate a warning. The default value is *false*. - **AllowThreadLocal** When set to *true*, non-const global variables with thread-local storage duration will not generate a warning. The default value is *false*. - **IgnoreMacros** When set to *true*, non-const global variables defined in macros will not generate a warning. The default value is *false*. ### cppcoreguidelines-avoid-reference-coroutine-parameters Warns when a coroutine accepts reference parameters. After a coroutine suspend point, references could be dangling and no longer valid. Instead, pass parameters as values. Examples: ``` std::future someCoroutine(int& val) { co_await ...; // When the coroutine is resumed, 'val' might no longer be valid. if (val) ... } ``` This check implements CP.53 \ from the C++ Core Guidelines. ### cppcoreguidelines-c-copy-assignment-signature The *cppcoreguidelines-c-copy-assignment-signature* check is an alias, please see misc-unconventional-assign-operator \<\> for more information. ### cppcoreguidelines-explicit-constructor This check is an alias for misc-explicit-constructor \<\>. ### cppcoreguidelines-explicit-virtual-functions The *cppcoreguidelines-explicit-virtual-functions* check is an alias, please see modernize-use-override \<\> for more information. ### cppcoreguidelines-init-variables Checks whether there are local variables that are declared without an initial value. These may lead to unexpected behavior if there is a code path that reads the variable before assigning to it. This rule is part of the Type safety (Type.5) \ profile and ES.20 \ from the C++ Core Guidelines. Only integers, booleans, floats, doubles and pointers are checked. The fix option initializes all detected values with the value of zero. An exception is float and double types, which are initialized to NaN. As an example a function that looks like this: ``` void function() { int x; char *txt; double d; // Rest of the function. } ``` Would be rewritten to look like this: ``` #include void function() { int x = 0; char *txt = nullptr; double d = NAN; // Rest of the function. } ``` It warns for the uninitialized enum case, but without a FixIt: ``` enum A {A1, A2, A3}; enum A_c : char { A_c1, A_c2, A_c3 }; enum class B { B1, B2, B3 }; enum class B_i : int { B_i1, B_i2, B_i3 }; void function() { A a; // Warning: variable 'a' is not initialized A_c a_c; // Warning: variable 'a_c' is not initialized B b; // Warning: variable 'b' is not initialized B_i b_i; // Warning: variable 'b_i' is not initialized } ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **MathHeader** A string specifying the header to include to get the definition of *NAN*. Default is *\*. ### cppcoreguidelines-interfaces-global-init This check flags initializers of globals that access extern objects, and therefore can lead to order-of-initialization problems. This check implements I.22 \ from the C++ Core Guidelines. Note that currently this does not flag calls to non-constexpr functions, and therefore globals could still be accessed from functions themselves. ### cppcoreguidelines-macro-to-enum The *cppcoreguidelines-macro-to-enum* check is an alias, please see modernize-macro-to-enum \<\> for more information. ### cppcoreguidelines-macro-usage Finds macro usage that is considered problematic because better language constructs exist for the task. The relevant sections in the C++ Core Guidelines are ES.31 \, and ES.32 \. Examples: ``` #define C 0 #define F1(x, y) ((a) > (b) ? (a) : (b)) #define F2(...) (__VA_ARGS__) #define F3(x, y) x##y #define COMMA , #define NORETURN [[noreturn]] #define DEPRECATED attribute((deprecated)) #if LIB_EXPORTS #define DLLEXPORTS __declspec(dllexport) #else #define DLLEXPORTS __declspec(dllimport) #endif ``` results in the following warnings: ``` 4 warnings generated. test.cpp:1:9: warning: macro 'C' used to declare a constant; consider using a 'constexpr' constant [cppcoreguidelines-macro-usage] #define C 0 ^ test.cpp:2:9: warning: function-like macro 'F1' used; consider a 'constexpr' template function [cppcoreguidelines-macro-usage] #define F1(x, y) ((a) > (b) ? (a) : (b)) ^ test.cpp:3:9: warning: variadic macro 'F2' used; consider using a 'constexpr' variadic template function [cppcoreguidelines-macro-usage] #define F2(...) (__VA_ARGS__) ^ ``` ### Options - **AllowedRegexp** A regular expression to filter allowed macros. For example *DEBUG\*\|LIBTORRENT\*\|TORRENT\*\|UNI\** could be applied to filter *libtorrent*. Default value is *^DEBUG\_\**. - **CheckCapsOnly** Boolean flag to warn on all macros except those with CAPS\_ONLY names. This option is intended to ease introduction of this check into older code bases. Default value is *false*. - **IgnoreCommandLineMacros** Boolean flag to toggle ignoring command-line-defined macros. Default value is *true*. ### cppcoreguidelines-misleading-capture-default-by-value Warns when lambda specify a by-value capture default and capture **this**. By-value capture defaults in member functions can be misleading about whether data members are captured by value or reference. This occurs because specifying the capture default **\[=\]** actually captures the **this** pointer by value, not the data members themselves. As a result, data members are still indirectly accessed via the captured **this** pointer, which essentially means they are being accessed by reference. Therefore, even when using **\[=\]**, data members are effectively captured by reference, which might not align with the user's expectations. Examples: ``` struct AClass { int member; void misleadingLogic() { int local = 0; member = 0; auto f = [=]() mutable { local += 1; member += 1; }; f(); // Here, local is 0 but member is 1 } void clearLogic() { int local = 0; member = 0; auto f = [this, local]() mutable { local += 1; member += 1; }; f(); // Here, local is 0 but member is 1 } }; ``` This check implements F.54 \ from the C++ Core Guidelines. ### cppcoreguidelines-missing-std-forward Warns when a forwarding reference parameter is not forwarded inside the function body. Example: ``` template void wrapper(T&& t) { impl(std::forward(t), 1, 2); // Correct } template void wrapper2(T&& t) { impl(t, 1, 2); // Oops - should use std::forward(t) } template void wrapper3(T&& t) { impl(std::move(t), 1, 2); // Also buggy - should use std::forward(t) } template void wrapper_function(F&& f) { std::forward(f)(1, 2); // Correct } template void wrapper_function2(F&& f) { f(1, 2); // Incorrect - may not invoke the desired qualified function operator } ``` ### Options - **ForwardFunction** Specify the function used for forwarding. Default is *::std::forward*. This check implements F.19 \ from the C++ Core Guidelines. ### Limitations Explicit object parameters (**this Self&&**) with a type constraint are not checked to avoid false positives. Such parameters are rarely intended to be perfectly forwarded. ### cppcoreguidelines-narrowing-conversions This check implements part of ES.46 \ from the C++ Core Guidelines. The *cppcoreguidelines-narrowing-conversions* check is an alias, please see bugprone-narrowing-conversions \<\> for more information. ### cppcoreguidelines-no-malloc This check handles C-Style memory management using **malloc()**, **realloc()**, **calloc()** and **free()**. It warns about its use and tries to suggest the use of an appropriate RAII object. Furthermore, it can be configured to check against a user-specified list of functions that are used for memory management (e.g. **posix\_memalign()**). This check implements R.10 \ from the C++ Core Guidelines. There is no attempt made to provide fix-it hints, since manual resource management isn't easily transformed automatically into RAII. ``` // Warns each of the following lines. // Containers like std::vector or std::string should be used. char* some_string = (char*) malloc(sizeof(char) * 20); char* some_string = (char*) realloc(sizeof(char) * 30); free(some_string); int* int_array = (int*) calloc(30, sizeof(int)); // Rather use a smartpointer or stack variable. struct some_struct* s = (struct some_struct*) malloc(sizeof(struct some_struct)); ``` ### Options - **Allocations** Semicolon-separated list of fully qualified names of memory allocation functions. Defaults to *::malloc;::calloc*. - **Deallocations** Semicolon-separated list of fully qualified names of memory allocation functions. Defaults to *::free*. - **Reallocations** Semicolon-separated list of fully qualified names of memory allocation functions. Defaults to *::realloc*. ### cppcoreguidelines-no-suspend-with-lock Flags coroutines that suspend while a lock guard is in scope at the suspension point. When a coroutine suspends, any mutexes held by the coroutine will remain locked until the coroutine resumes and eventually destructs the lock guard. This can lead to long periods with a mutex held and runs the risk of deadlock. Instead, locks should be released before suspending a coroutine. This check only checks suspending coroutines while a lock\_guard is in scope; it does not consider manual locking or unlocking of mutexes, e.g., through calls to **std::mutex::lock()**. Examples: ``` future bad_coro() { std::lock_guard lock{mtx}; ++some_counter; co_await something(); // Suspending while holding a mutex } future good_coro() { { std::lock_guard lock{mtx}; ++some_counter; } // Destroy the lock_guard to release the mutex before suspending the coroutine co_await something(); // Suspending while holding a mutex } ``` This check implements CP.52 \ from the C++ Core Guidelines. ### cppcoreguidelines-noexcept-destructor This check implements C.37 \ from the C++ Core Guidelines. The *cppcoreguidelines-noexcept-destructor* check is an alias, please see performance-noexcept-destructor \<\> for more information. ### cppcoreguidelines-noexcept-move-operations This check implements C.66 \ from the C++ Core Guidelines. The *cppcoreguidelines-noexcept-move-operations* check is an alias, please see performance-noexcept-move-constructor \<\> for more information. ### cppcoreguidelines-noexcept-swap This check implements C.83 \ , C.84 \ and C.85 \ from the C++ Core Guidelines. The *cppcoreguidelines-noexcept-swap check* is an alias, please see performance-noexcept-swap \<\> for more information. ### cppcoreguidelines-non-private-member-variables-in-classes The *cppcoreguidelines-non-private-member-variables-in-classes* check is an alias, please see misc-non-private-member-variables-in-classes \<\> for more information. ### cppcoreguidelines-owning-memory This check implements the type-based semantics of **gsl::owner\**, which allows static analysis on code, that uses raw pointers to handle resources like dynamic memory, but won't introduce RAII concepts. This check implements I.11 \, C.33 \, R.3 \ and GSL.Views \ from the C++ Core Guidelines. The definition of a **gsl::owner\** is straight forward ``` namespace gsl { template owner = T; } ``` It is therefore simple to introduce the owner even without using an implementation of the Guideline Support Library \. All checks are purely type based and not (yet) flow sensitive. The following examples will demonstrate the correct and incorrect initializations of owners, assignment is handled the same way. Note that both **new** and **malloc()**-like resource functions are considered to produce resources. ``` // Creating an owner with factory functions is checked. gsl::owner function_that_returns_owner() { return gsl::owner(new int(42)); } // Dynamic memory must be assigned to an owner int* Something = new int(42); // BAD, will be caught gsl::owner Owner = new int(42); // Good gsl::owner Owner = new int[42]; // Good as well // Returned owner must be assigned to an owner int* Something = function_that_returns_owner(); // Bad, factory function gsl::owner Owner = function_that_returns_owner(); // Good, result lands in owner // Something not a resource or owner should not be assigned to owners int Stack = 42; gsl::owner Owned = &Stack; // Bad, not a resource assigned ``` In the case of dynamic memory as resource, only **gsl::owner\** variables are allowed to be deleted. ``` // Example Bad, non-owner as resource handle, will be caught. int* NonOwner = new int(42); // First warning here, since new must land in an owner delete NonOwner; // Second warning here, since only owners are allowed to be deleted // Example Good, Ownership correctly stated gsl::owner Owner = new int(42); // Good delete Owner; // Good as well, statically enforced, that only owners get deleted ``` The check will furthermore ensure, that functions, that expect a **gsl::owner\** as argument get called with either a **gsl::owner\** or a newly created resource. ``` void expects_owner(gsl::owner o) { delete o; } // Bad Code int NonOwner = 42; expects_owner(&NonOwner); // Bad, will get caught // Good Code gsl::owner Owner = new int(42); expects_owner(Owner); // Good expects_owner(new int(42)); // Good as well, recognized created resource // Port legacy code for better resource-safety gsl::owner File = fopen("my_file.txt", "rw+"); FILE* BadFile = fopen("another_file.txt", "w"); // Bad, warned // ... use the file fclose(File); // Ok, File is annotated as 'owner<>' fclose(BadFile); // BadFile is not an 'owner<>', will be warned ``` ### Options - **LegacyResourceProducers** Semicolon-separated list of fully qualified names of legacy functions that create resources but cannot introduce **gsl::owner\<\>**. Defaults to *::malloc;::aligned\_alloc;::realloc;::calloc;::fopen;::freopen;::tmpfile*. - **LegacyResourceConsumers** Semicolon-separated list of fully qualified names of legacy functions expecting resource owners as pointer arguments but cannot introduce **gsl::owner\<\>**. Defaults to *::free;::realloc;::freopen;::fclose*. ### Limitations Using **gsl::owner\** in a typedef or alias is not handled correctly. ``` using heap_int = gsl::owner; heap_int allocated = new int(42); // False positive! ``` The **gsl::owner\** is declared as a templated type alias. In template functions and classes, like in the example below, the information of the type aliases gets lost. Therefore using **gsl::owner\** in a heavy templated code base might lead to false positives. Known code constructs that do not get diagnosed correctly are: - • **std::exchange** - • **std::vector\\>** ``` // This template function works as expected. Type information doesn't get lost. template void delete_owner(gsl::owner owned_object) { delete owned_object; // Everything alright } gsl::owner function_that_returns_owner() { return gsl::owner(new int(42)); } // Type deduction does not work for auto variables. // This is caught by the check and will be noted accordingly. auto OwnedObject = function_that_returns_owner(); // Type of OwnedObject will be int* // Problematic function template that looses the typeinformation on owner template void bad_template_function(T some_object) { // This line will trigger the warning, that a non-owner is assigned to an owner gsl::owner new_owner = some_object; } // Calling the function with an owner still yields a false positive. bad_template_function(gsl::owner(new int(42))); // The same issue occurs with templated classes like the following. template class OwnedValue { public: const T getValue() const { return _val; } private: T _val; }; // Code, that yields a false positive. OwnedValue> Owner(new int(42)); // Type deduction yield T -> int * // False positive, getValue returns int* and not gsl::owner gsl::owner OwnedInt = Owner.getValue(); ``` Another limitation of the current implementation is only the type based checking. Suppose you have code like the following: ``` // Two owners with assigned resources gsl::owner Owner1 = new int(42); gsl::owner Owner2 = new int(42); Owner2 = Owner1; // Conceptual Leak of initial resource of Owner2! Owner1 = nullptr; ``` The semantic of a **gsl::owner\** is mostly like a **std::unique\_ptr\**, therefore assignment of two **gsl::owner\** is considered a move, which requires that the resource **Owner2** must have been released before the assignment. This kind of condition could be caught in later improvements of this check with flowsensitive analysis. Currently, the *Clang Static Analyzer* catches this bug for dynamic memory, but not for general types of resources. ### cppcoreguidelines-prefer-member-initializer Finds member initializations in the constructor body which can be converted into member initializers of the constructor instead. This not only improves the readability of the code but also positively affects its performance. Class-member assignments inside a control statement or following the first control statement are ignored. This check implements C.49 \ from the C++ Core Guidelines. Please note, that this check does not enforce rule C.48 \ from the C++ Core Guidelines. For that purpose see check modernize-use-default-member-init \<\>. ### Example 1 ``` class C { int n; int m; public: C() { n = 1; // Literal in default constructor if (dice()) return; m = 1; } }; ``` Here **n** can be initialized in the constructor initializer list, unlike **m**, as **m**'s initialization follows a control statement (**if**): ``` class C { int n; int m; public: C(): n(1) { if (dice()) return; m = 1; } }; ``` ### Example 2 ``` class C { int n; int m; public: C(int nn, int mm) { n = nn; // Neither default constructor nor literal if (dice()) return; m = mm; } }; ``` Here **n** can be initialized in the constructor initializer list, unlike **m**, as **m**'s initialization follows a control statement (**if**): ``` C(int nn, int mm) : n(nn) { if (dice()) return; m = mm; } ``` ### cppcoreguidelines-pro-bounds-array-to-pointer-decay This check flags all array to pointer decays. Pointers should not be used as arrays. **span\** is a bounds-checked, safe alternative to using pointers to access arrays. This rule is part of the Bounds safety (Bounds 3) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-pro-bounds-avoid-unchecked-container-access Finds calls to **operator\[\]** in STL containers and suggests replacing them with safe alternatives. Safe alternatives include STL **at** or GSL **at** functions, **begin()** or **end()** functions, **range-for** loops, **std::span**, or an appropriate function from **\**. For example, both ``` std::vector a; int b = a[4]; ``` and ``` std::unique_ptr a; int b = a[0]; ``` will generate a warning. STL containers for which **operator\[\]** is well-defined for all inputs are excluded from this check (e.g.: **std::map::operator\[\]**). This check enforces part of the SL.con.3 \ guideline and is part of the Bounds Safety (Bounds 4) \ profile from the C++ Core Guidelines. ### Options - **ExcludeClasses** Semicolon-separated list of regular expressions matching class names that overwrites the default exclusion list. The default is: *::std::map;::std::unordered\_map;::std::flat\_map*. - **FixMode** Determines what fixes are suggested. Either *none*, *at* (use **a.at(index)** if a fitting function exists) or *function* (use a function **f(a, index)**). The default is *none*. - **FixFunction** The function to use in the *function* mode. For C++23 and beyond, the passed function must support the empty subscript operator, i.e., the case where **a\[\]** becomes **f(a)**. **FixFunctionEmptyArgs** can be used to override the suggested function in that case. The default is *gsl::at*. - **FixFunctionEmptyArgs** The function to use in the *function* mode for the empty subscript operator case in C++23 and beyond only. If no fixes should be made for empty subscript operators, pass an empty string. In that case, only the warnings will be printed. The default is the value of **FixFunction**. ### cppcoreguidelines-pro-bounds-constant-array-index This check flags all array subscript expressions on static arrays and **std::arrays** that either do not have a constant integer expression index or are out of bounds (for **std::array**). For out-of-bounds checking of static arrays, see the *-Warray-bounds* Clang diagnostic. This rule is part of the Bounds safety (Bounds 2) \ profile from the C++ Core Guidelines. Optionally, this check can generate fixes using **gsl::at** for indexing. ### Options - **GslHeader** The check can generate fixes after this option has been set to the name of the include file that contains **gsl::at()**, e.g. *"gsl/gsl.h"*. Default is an empty string. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. ### cppcoreguidelines-pro-bounds-pointer-arithmetic This check flags all usage of pointer arithmetic, because it could lead to an invalid pointer. Subtraction of two pointers is not flagged by this check. Pointers should only refer to single objects, and pointer arithmetic is fragile and easy to get wrong. **span\** is a bounds-checked, safe type for accessing arrays of data. This rule is part of the Bounds safety (Bounds 1) \ profile from the C++ Core Guidelines. ### Options - **AllowIncrementDecrementOperators** When enabled, the check will allow using the prefix/postfix increment or decrement operators on pointers. Default is **false**. ### cppcoreguidelines-pro-type-const-cast Imposes limitations on the use of **const\_cast** within C++ code. It depends on the **StrictMode** \<#cmdoption-arg-StrictMode\> option setting to determine whether it should flag all instances of **const\_cast** or only those that remove either **const** or **volatile** qualifier. Modifying a variable that has been declared as **const** in C++ is generally considered undefined behavior, and this remains true even when using **const\_cast**. In C++, the **const** qualifier indicates that a variable is intended to be read-only, and the compiler enforces this by disallowing any attempts to change the value of that variable. Removing the **volatile** qualifier in C++ can have serious consequences. This qualifier indicates that a variable's value can change unpredictably, and removing it may lead to undefined behavior, optimization problems, and debugging challenges. It's essential to retain the **volatile** qualifier in situations where the variable's volatility is a crucial aspect of program correctness and reliability. This rule is part of the Type safety (Type 3) \ profile and ES.50: Don’t cast away const \ rule from the C++ Core Guidelines. ### Options - **StrictMode** When this setting is set to *true*, it means that any usage of **const\_cast** is not allowed. On the other hand, when it's set to *false*, it permits casting to **const** or **volatile** types. Default value is *false*. ### cppcoreguidelines-pro-type-cstyle-cast This check flags all use of C-style casts that perform a **static\_cast** downcast, **const\_cast**, or **reinterpret\_cast**. Use of these casts can violate type safety and cause the program to access a variable that is actually of type X to be accessed as if it were of an unrelated type Z. Note that a C-style **(T)expression** cast means to perform the first of the following that is possible: a **const\_cast**, a **static\_cast**, a **static\_cast** followed by a **const\_cast**, a **reinterpret\_cast**, or a **reinterpret\_cast** followed by a **const\_cast**. This rule bans **(T)expression** only when used to perform an unsafe cast. This rule is part of the Type safety (Type.4) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-pro-type-member-init The check flags user-provided constructor definitions that do not initialize all fields that would be left in an undefined state by default construction, e.g. builtins, pointers and record types without user-provided default constructors containing at least one such type. If these fields aren't initialized, the constructor will leave some of the memory in an undefined state. For C++11 it suggests fixes to add in-class field initializers. For older versions it inserts the field initializers into the constructor initializer list. It will also initialize any direct base classes that need to be zeroed in the constructor initializer list. The check takes assignment of fields in the constructor body into account but generates false positives for fields initialized in methods invoked in the constructor body. The check also flags variables with automatic storage duration that have record types without a user-provided constructor and are not initialized. The suggested fix is to zero initialize the variable via **{}** for C++11 and beyond or **= {}** for older language versions. ### Options - **IgnoreArrays** If set to *true*, the check will not warn about array members that are not zero-initialized during construction. For performance critical code, it may be important to not initialize fixed-size array members. Default is *false*. - **UseAssignment** If set to *true*, the check will provide fix-its with literal initializers ( **int i = 0;** ) instead of curly braces ( **int i{};** ). Default is *false*. This rule is part of the Type safety (Type.6) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-pro-type-reinterpret-cast This check flags all uses of **reinterpret\_cast** in C++ code. Use of these casts can violate type safety and cause the program to access a variable that is actually of type **X** to be accessed as if it were of an unrelated type **Z**. This rule is part of the Type safety (Type.1.1) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-pro-type-static-cast-downcast This check flags all usages of **static\_cast**, where a base class is casted to a derived class. In those cases, a fix-it is provided to convert the cast to a **dynamic\_cast**. Use of these casts can violate type safety and cause the program to access a variable that is actually of type **X** to be accessed as if it were of an unrelated type **Z**. This rule is part of the Type safety (Type.2) \ profile from the C++ Core Guidelines. ### Options - **StrictMode** When set to *false*, no warnings are emitted for casts on non-polymorphic types. Default is *true*. ### cppcoreguidelines-pro-type-union-access This check flags all access to members of unions. Passing unions as a whole is not flagged. Reading from a union member assumes that member was the last one written, and writing to a union member assumes another member with a nontrivial destructor had its destructor called. This is fragile because it cannot generally be enforced to be safe in the language and so relies on programmer discipline to get it right. This rule is part of the Type safety (Type.7) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-pro-type-vararg This check flags all calls to c-style vararg functions and all use of **va\_arg**. To allow for SFINAE use of vararg functions, a call is not flagged if a literal 0 is passed as the only vararg argument or function is used in unevaluated context. Passing to varargs assumes the correct type will be read. This is fragile because it cannot generally be enforced to be safe in the language and so relies on programmer discipline to get it right. This rule is part of the Type safety (Type.8) \ profile from the C++ Core Guidelines. ### cppcoreguidelines-rvalue-reference-param-not-moved Warns when an rvalue reference function parameter is never moved within the function body. Rvalue reference parameters indicate a parameter that should be moved with **std::move** from within the function body. Any such parameter that is never moved is confusing and potentially indicative of a buggy program. Example: ``` void logic(std::string&& Input) { std::string Copy(Input); // Oops - forgot to std::move } ``` Note that parameters that are unused and marked as such will not be diagnosed. Example: ``` void conditional_use([[maybe_unused]] std::string&& Input) { // No diagnostic here since Input is unused and marked as such } ``` ### Options - **AllowPartialMove** If set to *true*, the check accepts **std::move** calls containing any subexpression containing the parameter. CppCoreGuideline F.18 officially mandates that the parameter itself must be moved. Default is *false*. ``` // 'p' is flagged by this check if and only if AllowPartialMove is false void move_members_of(pair&& p) { pair other; other.first = std::move(p.first); other.second = std::move(p.second); } // 'p' is never flagged by this check void move_whole_pair(pair&& p) { pair other = std::move(p); } ``` - **AllowImplicitMove** If set to *true*, the check recognizes implicit move **return param;** where **param** is a rvalue reference parameter. Default is *false*. ``` A f(A&& a) { return a; // no warning with AllowImplicitMove = true } ``` - **IgnoreUnnamedParams** If set to *true*, the check ignores unnamed rvalue reference parameters. Default is *false*. - **IgnoreNonDeducedTemplateTypes** If set to *true*, the check ignores non-deduced template type rvalue reference parameters. Default is *false*. ``` template struct SomeClass { // Below, 'T' is not deduced and 'T&&' is an rvalue reference type. // This will be flagged if and only if IgnoreNonDeducedTemplateTypes is // false. One suggested fix would be to specialize the class for 'T' and // 'T&' separately (e.g., see std::future), or allow only one of 'T' or // 'T&' instantiations of SomeClass (e.g., see std::optional). SomeClass(T&& t) { } }; // Never flagged, since 'T' is a forwarding reference in a deduced context template void forwarding_ref(T&& t) { T other = std::forward(t); } ``` - **MoveFunction** Specify the function used for moving. Default is *::std::move*. This check implements F.18 \ from the C++ Core Guidelines. ### cppcoreguidelines-slicing Flags slicing of member variables or vtable. Slicing happens when copying a derived object into a base object: the members of the derived object (both member variables and virtual member functions) will be discarded. This can be misleading especially for member function slicing, for example: ``` struct B { int a; virtual int f(); }; struct D : B { int b; int f() override; }; void use(B b) { // Missing reference, intended? b.f(); // Calls B::f. } D d; use(d); // Slice. ``` This check implements ES.63 \ and C.145 \ from the C++ Core Guidelines. ### cppcoreguidelines-special-member-functions The check finds classes where some but not all of the special member functions are defined. By default the compiler defines a copy constructor, copy assignment operator, move constructor, move assignment operator and destructor. The default can be suppressed by explicit user-definitions. The relationship between which functions will be suppressed by definitions of other functions is complicated and it is advised that all five are defaulted or explicitly defined. Note that defining a function with **= delete** is considered to be a definition. This check implements C.21 \ from the C++ Core Guidelines. ### Options - **AllowSoleDefaultDtor** When set to *true* (default is *false*), this check will only trigger on destructors if they are defined and not defaulted. ``` struct A { // This is fine. virtual ~A() = default; }; struct B { // This is not fine. ~B() {} }; struct C { // This is not checked, because the destructor might be defaulted in // another translation unit. ~C(); }; ``` - **AllowMissingMoveFunctions** When set to *true* (default is *false*), this check doesn't flag classes which define no move operations at all. It still flags classes which define only one of either move constructor or move assignment operator. With this option enabled, the following class won't be flagged: ``` struct A { A(const A&); A& operator=(const A&); ~A(); }; ``` - **AllowMissingMoveFunctionsWhenCopyIsDeleted** When set to *true* (default is *false*), this check doesn't flag classes which define deleted copy operations but don't define move operations. This flag is related to Google C++ Style Guide Copyable and Movable Types \. With this option enabled, the following class won't be flagged: ``` struct A { A(const A&) = delete; A& operator=(const A&) = delete; ~A(); }; ``` - **AllowImplicitlyDeletedCopyOrMove** When set to *true* (default is *false*), this check doesn't flag classes which implicitly delete copy or move operations. With this option enabled, the following class won't be flagged: ``` struct A : boost::noncopyable { ~A() { std::cout << "dtor\n"; } }; ``` - **IgnoreMacros** If set to *true*, the check will not give warnings for classes defined inside macros. Default is *true*. ### cppcoreguidelines-use-default-member-init This check implements C.48 \ from the C++ Core Guidelines. The *cppcoreguidelines-use-default-member-init* check is an alias, please see modernize-use-default-member-init \<\> for more information. ### cppcoreguidelines-use-enum-class Finds unscoped (non-class) **enum** declarations and suggests using **enum class** instead. This check implements Enum.3 \ from the C++ Core Guidelines." Example: ``` enum E {}; // use "enum class E {};" instead enum class E {}; // OK struct S { enum E {}; // use "enum class E {};" instead // OK with option IgnoreUnscopedEnumsInClasses }; namespace N { enum E {}; // use "enum class E {};" instead } ``` ### Options - **IgnoreUnscopedEnumsInClasses** When *true*, ignores unscoped **enum** declarations in classes. Default is *false*. - **IgnoreMacros** When *true*, ignores unscoped **enum** declarations within macros. Default is *false*. ### cppcoreguidelines-virtual-class-destructor Finds virtual classes whose destructor is neither public and virtual nor protected and non-virtual. A virtual class's destructor should be specified in one of these ways to prevent undefined behavior. This check implements C.35 \ from the C++ Core Guidelines. Note that this check will diagnose a class with a virtual method regardless of whether the class is used as a base class or not. Fixes are available for user-declared and implicit destructors that are either public and non-virtual or protected and virtual. No fixes are offered for private destructors. There, the decision whether to make them private and virtual or protected and non-virtual depends on the use case and is thus left to the user. ### Example For example, the following classes/structs get flagged by the check since they violate guideline **C.35**: ``` struct Foo { // NOK, protected destructor should not be virtual virtual void f(); protected: virtual ~Foo(){} }; class Bar { // NOK, public destructor should be virtual virtual void f(); public: ~Bar(){} }; ``` This would be rewritten to look like this: ``` struct Foo { // OK, destructor is not virtual anymore virtual void f(); protected: ~Foo(){} }; class Bar { // OK, destructor is now virtual virtual void f(); public: virtual ~Bar(){} }; ``` ### darwin-avoid-spinlock Finds usages of **OSSpinlock**, which is deprecated due to potential livelock problems. This check will detect following function invocations: - • **OSSpinlockLock** - • **OSSpinlockTry** - • **OSSpinlockUnlock** The corresponding information about the problem of **OSSpinlock**: \ ### darwin-dispatch-once-nonstatic Finds declarations of **dispatch\_once\_t** variables without static or global storage. The behavior of using **dispatch\_once\_t** predicates with automatic or dynamic storage is undefined by libdispatch, and should be avoided. It is a common pattern to have functions initialize internal static or global data once when the function runs, but programmers have been known to miss the static on the **dispatch\_once\_t** predicate, leading to an uninitialized flag value at the mercy of the stack. Programmers have also been known to make **dispatch\_once\_t** variables be members of structs or classes, with the intent to lazily perform some expensive struct or class member initialization only once; however, this violates the libdispatch requirements. See the discussion section of Apple's dispatch\_once documentation \ for more information. ### fuchsia-default-arguments-calls Warns if a function or method is called with default arguments. For example, given the declaration: ``` int foo(int value = 5) { return value; } ``` A function call expression that uses a default argument will be diagnosed. Calling it without defaults will not cause a warning: ``` foo(); // warning foo(0); // no warning ``` See the features disallowed in Fuchsia at \ ### fuchsia-default-arguments-declarations Warns if a function or method is declared with default parameters. For example, the declaration: ``` int foo(int value = 5) { return value; } ``` will cause a warning. See the features disallowed in Fuchsia at \ ### fuchsia-header-anon-namespaces The *fuchsia-header-anon-namespaces* check is an alias, please see misc-anonymous-namespace-in-header \<\> for more information. ### fuchsia-multiple-inheritance The *fuchsia-multiple-inheritance* check is an alias, please See misc-multiple-inheritance \<\> for details. See the features disallowed in Fuchsia at \ ### fuchsia-overloaded-operator Warns if an operator is overloaded, except for the assignment (copy and move) operators. For example: ``` int operator+(int); // Warning B &operator=(const B &Other); // No warning B &operator=(B &&Other) // No warning ``` See the features disallowed in Fuchsia at \ ### fuchsia-statically-constructed-objects Warns if global, non-trivial objects with static storage are constructed, unless the object is statically initialized with a **constexpr** constructor or has no explicit constructor. For example: ``` class A {}; class B { public: B(int Val) : Val(Val) {} private: int Val; }; class C { public: constexpr C(int Val) : Val(Val) {} C(int Val1, int Val2) : Val(Val1+Val2) {} private: int Val; }; static A a; // No warning, as there is no explicit constructor static C c(0); // No warning, as constructor is constexpr static B b(0); // Warning, as constructor is not constexpr static C c2(0, 1); // Warning, as constructor is not constexpr static int i; // No warning, as it is trivial extern int get_i(); static C c3(get_i());// Warning, as the constructor is dynamically initialized ``` See the features disallowed in Fuchsia at \ ### fuchsia-temporary-objects Warns on construction of specific temporary objects in the Zircon kernel. If the object should be flagged, the fully qualified type name must be explicitly passed to the check. For example, given the list of classes "Foo" and "NS::Bar", all of the following will trigger the warning: ``` Foo(); Foo F = Foo(); func(Foo()); namespace NS { Bar(); } ``` With the same list, the following will not trigger the warning: ``` Foo F; // Non-temporary construction okay Foo F(param); // Non-temporary construction okay Foo *F = new Foo(); // New construction okay Bar(); // Not NS::Bar, so okay NS::Bar B; // Non-temporary construction okay ``` Note that objects must be explicitly specified in order to be flagged, and so objects that inherit a specified object will not be flagged. This check matches temporary objects without regard for inheritance and so a prohibited base class type does not similarly prohibit derived class types. ``` class Derived : Foo {} // Derived is not explicitly disallowed Derived(); // and so temporary construction is okay ``` ### Options - **Names** A semi-colon-separated list of fully-qualified names of C++ classes that should not be constructed as temporaries. Default is empty string. ### fuchsia-trailing-return Functions that have trailing returns are disallowed, except for those using **decltype** specifiers and lambda with otherwise unutterable return types. For example: ``` // No warning int add_one(const int arg) { return arg; } // Warning auto get_add_one() -> int (*)(const int) { return add_one; } ``` Exceptions are made for lambdas and **decltype** specifiers: ``` // No warning auto lambda = [](double x, double y) -> double {return x + y;}; // No warning template auto fn(const T1 &lhs, const T2 &rhs) -> decltype(lhs + rhs) { return lhs + rhs; } ``` See the features disallowed in Fuchsia at \ ### fuchsia-virtual-inheritance Warns if classes are defined with virtual inheritance. For example, classes should not be defined with virtual inheritance: ``` class B : public virtual A {}; // warning ``` See the features disallowed in Fuchsia at \ ### google-build-explicit-make-pair Check that **make\_pair**'s template arguments are deduced. G++ 4.6 in C++11 mode fails badly if **make\_pair**'s template arguments are specified explicitly, and such use isn't intended in any case. Corresponding cpplint.py check name: *build/explicit\_make\_pair*. ### google-build-namespaces The *google-build-namespaces* check is an alias, please see misc-anonymous-namespace-in-header \<\> for more information. Finds anonymous namespaces in headers. \ Corresponding cpplint.py check name: *build/namespaces*. ### google-build-using-namespace Finds **using namespace** directives. The check implements the following rule of the Google C++ Style Guide \: You may not use a using-directive to make all names from a namespace available. ``` // Forbidden -- This pollutes the namespace. using namespace foo; ``` Corresponding cpplint.py check name: *build/namespaces*. ### google-default-arguments Checks that default arguments are not given for virtual methods. See \ ### google-explicit-constructor This check is an alias for misc-explicit-constructor \<\>. See \ ### google-global-names-in-headers Flag global namespace pollution in header files. Right now it only triggers on **using** declarations and directives. The relevant style guide section is \. ### google-objc-avoid-nsobject-new Finds calls to **+new** or overrides of it, which are prohibited by the Google Objective-C style guide. The Google Objective-C style guide forbids calling **+new** or overriding it in class implementations, preferring **+alloc** and **-init** methods to instantiate objects. An example: ``` NSDate *now = [NSDate new]; Foo *bar = [Foo new]; ``` Instead, code should use **+alloc**/**-init** or class factory methods. ``` NSDate *now = [NSDate date]; Foo *bar = [[Foo alloc] init]; ``` This check corresponds to the Google Objective-C Style Guide rule Do Not Use +new \. ### google-objc-avoid-throwing-exception Finds uses of throwing exceptions usages in Objective-C files. For the same reason as the Google C++ style guide, we prefer not throwing exceptions from Objective-C code. The corresponding C++ style guide rule: \ Instead, prefer passing in **NSError \*\*** and return **BOOL** to indicate success or failure. A counterexample: ``` - (void)readFile { if ([self isError]) { @throw [NSException exceptionWithName:...]; } } ``` Instead, returning an error via **NSError \*\*** is preferred: ``` - (BOOL)readFileWithError:(NSError **)error { if ([self isError]) { *error = [NSError errorWithDomain:...]; return NO; } return YES; } ``` The corresponding style guide rule: \ ### google-objc-function-naming Finds function declarations in Objective-C files that do not follow the pattern described in the Google Objective-C Style Guide. The corresponding style guide rule can be found here: \ All function names should be in Pascal case. Functions whose storage class is not static should have an appropriate prefix. The following code sample does not follow this pattern: ``` static bool is_positive(int i) { return i > 0; } bool IsNegative(int i) { return i < 0; } ``` The sample above might be corrected to the following code: ``` static bool IsPositive(int i) { return i > 0; } bool *ABCIsNegative(int i) { return i < 0; } ``` ### google-objc-global-variable-declaration Finds global variable declarations in Objective-C files that do not follow the pattern of variable names in Google's Objective-C Style Guide. The corresponding style guide rule: \ All the global variables should follow the pattern of **g\[A-Z\].\*** (variables) or **k\[A-Z\].\*** (constants). The check will suggest a variable name that follows the pattern if it can be inferred from the original name. For code: ``` static NSString* myString = @"hello"; ``` The fix will be: ``` static NSString* gMyString = @"hello"; ``` Another example of constant: ``` static NSString* const myConstString = @"hello"; ``` The fix will be: ``` static NSString* const kMyConstString = @"hello"; ``` However for code that prefixed with non-alphabetical characters like: ``` static NSString* __anotherString = @"world"; ``` The check will give a warning message but will not be able to suggest a fix. The user needs to fix it on their own. ### google-readability-avoid-underscore-in-googletest-name Checks whether there are underscores in googletest test suite names and test names in test macros: - • **TEST** - • **TEST\_F** - • **TEST\_P** - • **TYPED\_TEST** - • **TYPED\_TEST\_P** The **FRIEND\_TEST** macro is not included. For example: ``` TEST(TestSuiteName, Illegal_TestName) {} TEST(Illegal_TestSuiteName, TestName) {} ``` would trigger the check. Underscores are not allowed \ in test suite name nor test names. The **DISABLED\_** prefix, which may be used to disable test suites and individual tests \, is removed from the test suite name and test name before checking for underscores. This check does not propose any fixes. ### google-readability-braces-around-statements The *google-readability-braces-around-statements* check is an alias, please see readability-braces-around-statements \<\> for more information. ### google-readability-casting The *google-readability-casting* check is an alias, please see modernize-avoid-c-style-cast \<\> for more information. Finds usages of C-style casts. \ Corresponding cpplint.py check name: *readability/casting*. ### google-readability-function-size The *google-readability-function-size* check is an alias, please see readability-function-size \<\> for more information. ### google-readability-namespace-comments The *google-readability-namespace-comments check* is an alias, please see llvm-namespace-comment \<\> for more information. ### google-readability-todo Finds TODO comments without a username or bug number. The relevant style guide section is \. Corresponding cpplint.py check: *readability/todo* ### Options - **Style** A string specifying the TODO style for fix-it hints. Accepted values are *Hyphen* and *Parentheses*. Default is *Hyphen*. - • *Hyphen* will format the fix-it as: **// TODO: username - details**. - • *Parentheses* will format the fix-it as: **// TODO(username): details**. ### google-runtime-float Finds uses of **long double** and suggests against their use due to lack of portability. The corresponding style guide rule: \ ### google-runtime-int Finds uses of **short**, **long** and **long long** and suggest replacing them with **u?intXX(\_t)?**. The corresponding style guide rule: \. Corresponding cpplint.py check: *runtime/int*. ### Options - **UnsignedTypePrefix** A string specifying the unsigned type prefix. Default is *uint*. - **SignedTypePrefix** A string specifying the signed type prefix. Default is *int*. - **TypeSuffix** A string specifying the type suffix. Default is an empty string. ### google-runtime-operator Finds overloads of unary **operator &**. \ Corresponding cpplint.py check name: *runtime/operator*. ### google-upgrade-googletest-case Finds uses of deprecated Google Test version 1.9 APIs with names containing **case** and replaces them with equivalent APIs with **suite**. All names containing **case** are being replaced to be consistent with the meanings of "test case" and "test suite" as used by the International Software Testing Qualifications Board and ISO 29119. The new names are a part of Google Test version 1.9 (release pending). It is recommended that users update their dependency to version 1.9 and then use this check to remove deprecated names. The affected APIs are: - • Member functions of **testing::Test**, **testing::TestInfo**, **testing::TestEventListener**, **testing::UnitTest**, and any type inheriting from these types - • The macros **TYPED\_TEST\_CASE**, **TYPED\_TEST\_CASE\_P**, **REGISTER\_TYPED\_TEST\_CASE\_P**, and **INSTANTIATE\_TYPED\_TEST\_CASE\_P** - • The type alias **testing::TestCase** Examples of fixes created by this check: ``` class FooTest : public testing::Test { public: static void SetUpTestCase(); static void TearDownTestCase(); }; TYPED_TEST_CASE(BarTest, BarTypes); ``` becomes ``` class FooTest : public testing::Test { public: static void SetUpTestSuite(); static void TearDownTestSuite(); }; TYPED_TEST_SUITE(BarTest, BarTypes); ``` For better consistency of user code, the check renames both virtual and non-virtual member functions with matching names in derived types. The check tries to provide only a warning when a fix cannot be made safely, as is the case with some template and macro uses. ### linuxkernel-must-check-errs Checks Linux kernel code to see if it uses the results from the functions in **linux/err.h**. Also checks to see if code uses the results from functions that directly return a value from one of these error functions. This is important in the Linux kernel because **ERR\_PTR**, **PTR\_ERR**, **IS\_ERR**, **IS\_ERR\_OR\_NULL**, **ERR\_CAST**, and **PTR\_ERR\_OR\_ZERO** return values must be checked, since positive pointers and negative error codes are being used in the same context. These functions are marked with **\_\_attribute\_\_((warn\_unused\_result))**, but some kernel versions do not have this warning enabled for clang. Examples: ``` /* Trivial unused call to an ERR function */ PTR_ERR_OR_ZERO(some_function_call()); /* A function that returns ERR_PTR. */ void *fn() { ERR_PTR(-EINVAL); } /* An invalid use of fn. */ fn(); ``` ### llvm-else-after-return The *llvm-else-after-return* check is an alias, please see readability-else-after-return \<\> for more information. ### llvm-formatv-string Validates **llvm::formatv** format strings against the provided arguments, diagnosing mismatched argument counts, unused arguments, and mixed index styles. This check diagnoses the following issues: - • The number of replacement indices in the format string does not match the number of arguments provided. - • A format string does not use one of the given arguments. - • Mixing of automatic and explicit indices (e.g. **{} {1}**). ``` // warning: format string requires 2 arguments, but 1 argument was provided llvm::formatv("{0} {1}", x); // warning: format string mixes automatic and explicit indices llvm::formatv("{} {1}", x, y); // warning: argument unused in format string llvm::formatv("{0} {2}", x, y, z); // OK. llvm::formatv("{0} {1}", x, y); llvm::formatv("{} {}", x, y); llvm::formatv("{0} {0}", x); ``` The check only operates on calls where the format string is a string literal. Dynamic format strings are not diagnosed. ### Options - **AdditionalFunctions** A semicolon-separated list of additional fully qualified function names to check, beyond **llvm::formatv** and **llvm::createStringErrorV**. Each function must be a variadic template whose last parameter is a parameter pack. The format string is assumed to be the parameter immediately preceding the pack. For example, to check **::mylib::log(Level, const char \*Fmt, Ts&&...)** set this option to *::mylib::log*. Default is the empty string. ### llvm-header-guard Finds and fixes header guards that do not adhere to LLVM style. ### llvm-include-order Checks the correct order of **#includes**. See \ ### llvm-namespace-comment *google-readability-namespace-comments* redirects here as an alias for this check. Checks that long namespaces have a closing comment. \ \ ``` namespace n1 { void f(); } // becomes namespace n1 { void f(); } // namespace n1 ``` ### Options - **ShortNamespaceLines** Requires the closing brace of the namespace definition to be followed by a closing comment if the body of the namespace has more than *ShortNamespaceLines* lines of code. The value is an unsigned integer that defaults to *1U*. - **SpacesBeforeComments** An unsigned integer specifying the number of spaces before the comment closing a namespace definition. Default is *1U*. - **AllowOmittingNamespaceComments** When *true*, the check will accept if no namespace comment is present. The check will only fail if the specified namespace comment is different than expected. Default is *false*. ### llvm-prefer-isa-or-dyn-cast-in-conditionals Looks at conditionals and finds and replaces cases of **cast\<\>**, which will assert rather than return a null pointer, and **dyn\_cast\<\>** where the return value is not captured. Additionally, finds and replaces cases that match the pattern **var &&** **isa\(var)**, where **var** is evaluated twice. ``` // Finds these: if (auto x = cast(y)) {} // is replaced by: if (auto x = dyn_cast(y)) {} if (cast(y)) {} // is replaced by: if (isa(y)) {} if (dyn_cast(y)) {} // is replaced by: if (isa(y)) {} if (var && isa(var)) {} // is replaced by: if (isa_and_nonnull(var.foo())) {} // Other cases are ignored, e.g.: if (auto f = cast(y)->foo()) {} if (cast(y)->foo()) {} if (X.cast(y)) {} ``` ### llvm-prefer-register-over-unsigned Finds historical use of **unsigned** to hold vregs and physregs and rewrites them to use **Register**. Currently this works by finding all variables of unsigned integer type whose initializer begins with an implicit cast from **Register** to **unsigned**. ``` void example(MachineOperand &MO) { unsigned Reg = MO.getReg(); ... } ``` becomes: ``` void example(MachineOperand &MO) { Register Reg = MO.getReg(); ... } ``` ### llvm-prefer-static-over-anonymous-namespace Finds function and variable declarations inside anonymous namespace and suggests replacing them with **static** declarations. The LLVM Coding Standards \ recommend keeping anonymous namespaces as small as possible and only use them for class declarations. For functions and variables the **static** specifier should be preferred for restricting visibility. For example non-compliant code: ``` namespace { class StringSort { public: StringSort(...) bool operator<(const char *RHS) const; }; // warning: place method definition outside of an anonymous namespace bool StringSort::operator<(const char *RHS) const {} // warning: prefer using 'static' for restricting visibility void runHelper() {} // warning: prefer using 'static' for restricting visibility int myVariable = 42; } ``` Should become: ``` // Small anonymous namespace for class declaration namespace { class StringSort { public: StringSort(...) bool operator<(const char *RHS) const; }; } // placed method definition outside of the anonymous namespace bool StringSort::operator<(const char *RHS) const {} // used 'static' instead of an anonymous namespace static void runHelper() {} // used 'static' instead of an anonymous namespace static int myVariable = 42; ``` ### Options - **AllowVariableDeclarations** When *true*, allow variable declarations to be in anonymous namespace. Default value is *true*. - **AllowMemberFunctionsInClass** When *true*, only methods defined in anonymous namespace outside of the corresponding class will be warned. Default value is *true*. ### llvm-qualified-auto The *llvm-qualified-auto check* is an alias, please see readability-qualified-auto \<\> for more information. ### llvm-redundant-casting Points out uses of **cast\<\>**, **dyn\_cast\<\>**, **isa\<\>** and their **or\_null** variants that are unnecessary because the argument already is of the target type, or a derived type thereof. ``` struct A {}; A a; // Finds: A x = cast(a); // replaced by: A x = a; struct B : public A {}; B b; // Finds: A y = cast(b); // replaced by: A y = b; struct C : public A {}; C c; // Finds: bool r1 = isa(a) // always true bool r2 = isa(b) // always true bool r3 = isa(c) // always true ``` - **Supported functions:** - • **llvm::cast** - • **llvm::cast\_or\_null** - • **llvm::cast\_if\_present** - • **llvm::dyn\_cast** - • **llvm::dyn\_cast\_or\_null** - • **llvm::dyn\_cast\_if\_present** - • **llvm::isa** - • **llvm::isa\_and\_nonnull** - • **llvm::isa\_and\_present** ### llvm-twine-local Looks for local **Twine** variables which are prone to use after frees and should be generally avoided. ``` static Twine Moo = Twine("bark") + "bah"; // becomes static std::string Moo = (Twine("bark") + "bah").str(); ``` The **Twine** does not own the memory of its contents, so it is not recommended to use **Twine** created from temporary strings or string literals. ``` static Twine getModuleIdentifier(StringRef moduleName) { return moduleName + "_module"; } void foo() { Twine result = getModuleIdentifier(std::string{"abc"} + "def"); // temporary std::string is destroyed here, result is dangling } ``` After applying this fix-it hints, the code will use **std::string** instead of **Twine** for local variables. However, **Twine** has lots of methods that are incompatible with **std::string**, so the user may need to adjust the code manually after applying the fix-it hints. ### llvm-type-switch-case-types Finds **llvm::TypeSwitch::Case** calls with redundant explicit template arguments that can be inferred from the lambda parameter type. This check identifies two patterns: - 1\. **Redundant explicit type**: When the lambda parameter type matches the **Case** template argument, the explicit type can be removed. - 2\. **Auto parameter with explicit type**: When a lambda uses **auto** but **Case** has an explicit template argument, suggests using an explicit type in the lambda instead. ### Example ``` llvm::TypeSwitch(base) .Case([](DerivedA *a) { return 1; }) // Redundant. .Case([](auto b) { return 2; }); // `auto` with explicit type. ``` Transforms to: ``` llvm::TypeSwitch(base) .Case([](DerivedA *a) { return 1; }) // Type inferred from lambda. .Case([](auto b) { return 2; }); // Warning only. ``` Note: The second case (**auto** parameter) only emits a warning without a fix-it, because the deduced type of **auto** depends on **dyn\_cast** behavior which varies between pointer types and MLIR handle types. ### llvm-mlir-op-builder Checks for uses of MLIR's old/to be deprecated **OpBuilder::create\** form and suggests using **T::create** instead. ### Example ``` builder.create(builder.getUnknownLoc(), "baz"); ``` Transforms to: ``` FooOp::create(builder, builder.getUnknownLoc(), "baz"); ``` ### llvm-use-ranges Finds calls to STL library iterator algorithms that could be replaced with LLVM range-based algorithms from **llvm/ADT/STLExtras.h**. ### Example ``` auto it = std::find(vec.begin(), vec.end(), value); bool all = std::all_of(vec.begin(), vec.end(), [](int x) { return x > 0; }); ``` Transforms to: ``` auto it = llvm::find(vec, value); bool all = llvm::all_of(vec, [](int x) { return x > 0; }); ``` ### Supported algorithms Calls to the following STL algorithms are checked: **std::accumulate**, **std::adjacent\_find**, **std::all\_of**, **std::any\_of**, **std::binary\_search**, **std::copy\_if**, **std::copy**, **std::count\_if**, **std::count**, **std::equal**, **std::fill**, **std::find\_if\_not**, **std::find\_if**, **std::find**, **std::for\_each**, **std::includes**, **std::is\_sorted**, **std::lower\_bound**, **std::max\_element**, **std::min\_element**, **std::mismatch**, **std::none\_of**, **std::partition\_point**, **std::partition**, **std::remove\_if**, **std::replace\_copy\_if**, **std::replace\_copy**, **std::replace**, **std::search**, **std::stable\_sort**, **std::transform**, **std::uninitialized\_copy**, **std::unique**, **std::upper\_bound**. The check will add the necessary **#include "llvm/ADT/STLExtras.h"** directive when applying fixes. ### llvm-use-vector-utils Finds calls to **llvm::to\_vector** with **llvm::map\_range** or **llvm::make\_filter\_range** that can be replaced with the more concise **llvm::map\_to\_vector** and **llvm::filter\_to\_vector** utilities from **llvm/ADT/SmallVectorExtras.h**. The check will add the necessary **#include "llvm/ADT/SmallVectorExtras.h"** directive when applying fixes. ### Example ``` auto v1 = llvm::to_vector(llvm::map_range(container, func)); auto v2 = llvm::to_vector(llvm::make_filter_range(container, pred)); auto v3 = llvm::to_vector<4>(llvm::map_range(container, func)); auto v4 = llvm::to_vector<4>(llvm::make_filter_range(container, pred)); ``` Transforms to: ``` auto v1 = llvm::map_to_vector(container, func); auto v2 = llvm::filter_to_vector(container, pred); auto v3 = llvm::map_to_vector<4>(container, func); auto v4 = llvm::filter_to_vector<4>(container, pred); ``` ### llvmlibc-callee-namespace Checks all calls resolve to functions within correct namespace. ``` // Implementation inside the LIBC_NAMESPACE namespace. // Correct if: // - LIBC_NAMESPACE is a macro // - LIBC_NAMESPACE expansion starts with `__llvm_libc` namespace LIBC_NAMESPACE { // Allow calls with the fully qualified name. LIBC_NAMESPACE::strlen("hello"); // Allow calls to compiler provided functions. (void)__builtin_abs(-1); // Bare calls are allowed as long as they resolve to the correct namespace. strlen("world"); // Disallow calling into functions in the global namespace. ::strlen("!"); } // namespace LIBC_NAMESPACE ``` ### llvmlibc-implementation-in-namespace Checks that all declarations in the llvm-libc implementation are within the correct namespace. ``` // Implementation inside the LIBC_NAMESPACE_DECL namespace. // Correct if: // - LIBC_NAMESPACE_DECL is a macro // - LIBC_NAMESPACE_DECL expansion starts with `[[gnu::visibility("hidden")]] __llvm_libc` namespace LIBC_NAMESPACE_DECL { LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {} // Namespaces within LIBC_NAMESPACE_DECL namespace are allowed. namespace inner { int localVar = 0; } // Functions with C linkage are allowed. extern "C" void str_fuzz() {} } // Incorrect: implementation not in the LIBC_NAMESPACE_DECL namespace. LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {} // Incorrect: outer most namespace is not the LIBC_NAMESPACE_DECL macro. namespace something_else { LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {} } // Incorrect: outer most namespace expansion does not start with `[[gnu::visibility("hidden")]] __llvm_libc`. #define LIBC_NAMESPACE_DECL custom_namespace namespace LIBC_NAMESPACE_DECL { LLVM_LIBC_FUNCTION(char *, strcpy, (char *dest, const char *src)) {} } ``` ### llvmlibc-inline-function-decl Checks that all implicitly and explicitly inline functions in header files are tagged with the **LIBC\_INLINE** macro, except for functions implicit to classes or deleted functions. See the libc style guide \ for more information about this macro. ### llvmlibc-restrict-system-libc-headers Finds includes of system libc headers not provided by the compiler within llvm-libc implementations. ``` #include // Not allowed because it is part of system libc. #include // Allowed because it is provided by the compiler. #include "internal/stdio.h" // Allowed because it is NOT part of system libc. ``` This check is necessary because accidentally including system libc headers can lead to subtle and hard to detect bugs. For example consider a system libc whose **dirent** struct has slightly different field ordering than llvm-libc. While this will compile successfully, this can cause issues during runtime because they are ABI incompatible. ### Options - **Includes** A string containing a comma separated glob list of allowed include filenames. Similar to the -checks glob list for running clang-tidy itself, the two wildcard characters are *\** and *-*, to include and exclude globs, respectively. The default is *-\**, which disallows all includes. This can be used to allow known safe includes such as Linux development headers. See portability-restrict-system-includes \<\> for more details. ### misc-anonymous-namespace-in-header Finds anonymous namespaces in headers. Anonymous namespaces in headers can lead to One Definition Rule (ODR) violations because each translation unit including the header will get its own unique version of the symbols. This increases binary size and can cause confusing link-time errors. ### References This check corresponds to the CERT C++ Coding Standard rule DCL59-CPP. Do not define an unnamed namespace in a header file \. Corresponding cpplint.py check name: *build/namespaces*. ### misc-confusable-identifiers Warn about confusable identifiers, i.e. identifiers that are visually close to each other, but use different Unicode characters. This detects a potential attack described in CVE-2021-42574 \. Example: ``` int fo; // Initial character is U+0066 (LATIN SMALL LETTER F). int 𝐟o; // Initial character is U+1D41F (MATHEMATICAL BOLD SMALL F) not U+0066 (LATIN SMALL LETTER F). ``` ### misc-const-correctness Finds local variables and function parameters which could be declared as **const** but are not. Declaring variables as **const** is required or recommended by many coding guidelines, such as: ES.25 \ from the C++ Core Guidelines. Please note that this check's analysis is type-based only. Variables that are not modified but used to create a non-const handle that might escape the scope are not diagnosed as potential **const**. ``` // Declare a variable, which is not ``const`` ... int i = 42; // but use it as read-only. This means that `i` can be declared ``const``. int result = i * i; // Before transformation int const result = i * i; // After transformation ``` The check can analyze values, pointers and references and pointees: ``` // Normal values like built-ins or objects. int potential_const_int = 42; // Before transformation int const potential_const_int = 42; // After transformation int copy_of_value = potential_const_int; MyClass could_be_const; // Before transformation MyClass const could_be_const; // After transformation could_be_const.const_qualified_method(); // References can be declared const as well. int &reference_value = potential_const_int; // Before transformation int const& reference_value = potential_const_int; // After transformation int another_copy = reference_value; // The similar semantics of pointers are analyzed. int *pointer_variable = &potential_const_int; // Before transformation int const*const pointer_variable = &potential_const_int; // After transformation, both pointer itself and pointee are supported. int last_copy = *pointer_variable; ``` The automatic code transformation is only applied to variables that are declared in single declarations. You may want to prepare your code base with readability-isolate-declaration \<\> first. Note that there is the check cppcoreguidelines-avoid-non-const-global-variables \<\> to enforce **const** correctness on all globals. ### Limitations The check does not run on *C* code. The check will not analyze templated variables, template functions or variables that are instantiation dependent. Different instantiations can result in different **const** correctness properties and in general it is not possible to find all instantiations of a template. The template might be used differently in an independent translation unit. ### Options - **AnalyzeValues** Enable or disable the analysis of ordinary value variables, like **int i = 42;**. Default is *true*. ``` // Warning int i = 42; // No warning int const i = 42; // Warning int a[] = {42, 42, 42}; // No warning int const a[] = {42, 42, 42}; ``` - **AnalyzeReferences** Enable or disable the analysis of reference variables, like **int &ref = i;**. Default is *true*. ``` int i = 42; // Warning int& ref = i; // No warning int const& ref = i; ``` - **AnalyzePointers** Enable or disable the analysis of pointers variables, like **int \*ptr = &i;**. For specific checks, see **WarnPointersAsValues** and **WarnPointersAsPointers**. Default is *true*. - **AnalyzeAutoVariables** Enable or disable the analysis of variables declared with **auto**, such as **auto i = 10;** or **auto \*ptr = &i**. Default is *true*. - **AnalyzeLambdas** Enable or disable the analysis of lambda variables, like **auto f = \[\] { return 10; };**. For this option to have any effect, *AnalyzeAutoVariables* must be *true* as well. Default is *true*. - **AnalyzeParameters** Enable or disable the analysis of function parameters, like **void foo(int\* ptr)**. Only reference and pointer parameters are analyzed. Unnamed parameters, member functions (including constructors) and lambdas are excluded from the analysis. Default is *true*. ``` // Warning void function(int& param) {} // No warning void function(const int& param, int&) {} ``` - **WarnPointersAsValues** This option enables the suggestion for **const** of the pointer itself. Pointer values have two possibilities to be **const**, the pointer and the value pointing to. Default is *false*. ``` int value = 42; // Warning const int * pointer_variable = &value; // No warning const int *const pointer_variable = &value; ``` - **WarnPointersAsPointers** This option enables the suggestion for **const** of the value pointing to. Default is *true*. Requires **AnalyzePointers** to be *true*. ``` int value = 42; // No warning const int *const pointer_variable = &value; // Warning int *const pointer_variable = &value; ``` - **TransformValues** Provides fixit-hints for value types that automatically add **const** if its a single declaration. Default is *true*. ``` // Before int value = 42; // After int const value = 42; // Before int a[] = {42, 42, 42}; // After int const a[] = {42, 42, 42}; // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted. int result = value * 3; result -= 10; ``` - **TransformReferences** Provides fixit-hints for reference types that automatically add **const** if its a single declaration. Default is *true*. ``` // This variable could still be a constant. But because there is a non-const reference to // it, it can not be transformed (yet). int value = 42; // The reference 'ref_value' is not modified and can be made 'const int &ref_value = value;' // Before int &ref_value = value; // After int const &ref_value = value; // Result is modified later in its life-time. No diagnostic and fixit hint will be emitted. int result = ref_value * 3; result -= 10; ``` - **TransformPointersAsValues** Provides fixit-hints for pointers if their pointee is not changed. This does not analyze if the value-pointed-to is unchanged! Default is *false*. Requires 'WarnPointersAsValues' to be 'true'. ``` int value = 42; // Before const int * pointer_variable = &value; // After const int *const pointer_variable = &value; // Before const int * a[] = {&value, &value}; // After const int *const a[] = {&value, &value}; // Before int *ptr_value = &value; // After int *const ptr_value = &value; int result = 100 * (*ptr_value); // Does not modify the pointer itself. // This modification of the pointee is still allowed and not diagnosed. *ptr_value = 0; // The following pointer may not become a 'int *const'. int *changing_pointee = &value; changing_pointee = &result; ``` - **TransformPointersAsPointers** Provides fix-it hints for pointers if the value it pointing to is not changed. Default is *false*. Requires **WarnPointersAsPointers** to be *true*. ``` int value = 42; // Before int * pointer_variable = &value; // After const int * pointer_variable = &value; // Before int * a[] = {&value, &value}; // After const int * a[] = {&value, &value}; ``` - **AllowedTypes** A semicolon-separated list of names of types that will be excluded from const-correctness checking. Regular expressions are accepted, e.g. **\[Rr\]ef(erence)?$** matches every type with suffix **Ref**, **ref**, **Reference** and **reference**. If a name in the list contains the sequence *::*, it is matched against the qualified type name (i.e. **namespace::Type**), otherwise it is matched against only the type name (i.e. **Type**). Default is empty string. ### misc-coroutine-hostile-raii Detects when objects of certain hostile RAII types persists across suspension points in a coroutine. Such hostile types include scoped-lockable types and types belonging to a configurable denylist. Some objects require that they be destroyed on the same thread that created them. Traditionally this requirement was often phrased as "must be a local variable", under the assumption that local variables always work this way. However this is incorrect with C++20 coroutines, since an intervening **co\_await** may cause the coroutine to suspend and later be resumed on another thread. The lifetime of an object that requires being destroyed on the same thread must not encompass a **co\_await** or **co\_yield** point. If you create/destroy an object, you must do so without allowing the coroutine to suspend in the meantime. Following types are considered as hostile: - • Scoped-lockable types: A scoped-lockable object persisting across a suspension point is problematic as the lock held by this object could be unlocked by a different thread. This would be undefined behaviour. This includes all types annotated with the **scoped\_lockable** attribute. - • Types belonging to a configurable denylist. ``` // Call some async API while holding a lock. task coro() { const std::lock_guard l(&mu_); // Oops! The async Bar function may finish on a different // thread from the one that created the lock_guard (and called // Mutex::Lock). After suspension, Mutex::Unlock will be called on the wrong thread. co_await Bar(); } ``` ### Options - **RAIITypesList** A semicolon-separated list of qualified types which should not be allowed to persist across suspension points. Eg: *my::lockable;a::b;::my::other::lockable* The default value of this option is *std::lock\_guard;std::scoped\_lock*. - **AllowedAwaitablesList** A semicolon-separated list of qualified types of awaitables types which can be safely awaited while having hostile RAII objects in scope. **co\_await**-ing an expression of **awaitable** type is considered safe if the **awaitable** type is part of this list. RAII objects persisting across such a **co\_await** expression are considered safe and hence are not flagged. Example usage: ``` // Consider option AllowedAwaitablesList = "safe_awaitable" struct safe_awaitable { bool await_ready() noexcept { return false; } void await_suspend(std::coroutine_handle<>) noexcept {} void await_resume() noexcept {} }; auto wait() { return safe_awaitable{}; } task coro() { // This persists across both the co_await's but is not flagged // because the awaitable is considered safe to await on. const std::lock_guard l(&mu_); co_await safe_awaitable{}; co_await wait(); } ``` Eg: *my::safe::awaitable;other::awaitable* Default is an empty string. - **AllowedCallees** A semicolon-separated list of callee function names which can be safely awaited while having hostile RAII objects in scope. Example usage: ``` // Consider option AllowedCallees = "noop" task noop() { co_return; } task coro() { // This persists across the co_await but is not flagged // because the awaitable is considered safe to await on. const std::lock_guard l(&mu_); co_await noop(); } ``` Eg: *my::safe::await;other::await* Default is an empty string. ### misc-definitions-in-headers Finds non-extern non-inline function and variable definitions in header files, which can lead to potential ODR violations in case these headers are included from multiple translation units. ``` // Foo.h int a = 1; // Warning: variable definition. extern int d; // OK: extern variable. namespace N { int e = 2; // Warning: variable definition. } // Warning: variable definition. const char* str = "foo"; // OK: internal linkage variable definitions are ignored for now. // Although these might also cause ODR violations, we can be less certain and // should try to keep the false-positive rate down. static int b = 1; const int c = 1; const char* const str2 = "foo"; constexpr int k = 1; namespace { int x = 1; } // Warning: function definition. int g() { return 1; } // OK: inline function definition is allowed to be defined multiple times. inline int e() { return 1; } class A { public: int f1() { return 1; } // OK: implicitly inline member function definition is allowed. int f2(); static int d; }; // Warning: not an inline member function definition. int A::f2() { return 1; } // OK: class static data member declaration is allowed. int A::d = 1; // OK: function template is allowed. template T f3() { T a = 1; return a; } // Warning: full specialization of a function template is not allowed. template <> int f3() { int a = 1; return a; } template struct B { void f1(); }; // OK: member function definition of a class template is allowed. template void B::f1() {} class CE { constexpr static int i = 5; // OK: inline variable definition. }; inline int i = 5; // OK: inline variable definition. constexpr int f10() { return 0; } // OK: constexpr function implies inline. // OK: C++14 variable templates are inline. template constexpr T pi = T(3.1415926L); ``` When **clang-tidy** is invoked with the *--fix-notes* option, this check provides fixes that automatically add the **inline** keyword to discovered functions. Please note that the addition of the **inline** keyword to variables is not currently supported by this check. ### misc-explicit-constructor Checks that constructors callable with a single argument and conversion operators are marked explicit to avoid the risk of unintentional implicit conversions. Consider this example: ``` struct S { int x; operator bool() const { return true; } }; bool f() { S a{1}; S b{2}; return a == b; } ``` The function will return **true**, since the objects are implicitly converted to **bool** before comparison, which is unlikely to be the intent. The check will suggest inserting **explicit** before the constructor or conversion operator declaration. However, copy and move constructors should not be explicit, as well as constructors taking a single **initializer\_list** argument. This code: ``` struct S { S(int a); explicit S(const S&); operator bool() const; ... ``` will become ``` struct S { explicit S(int a); S(const S&); explicit operator bool() const; ... ``` ### misc-header-include-cycle Check detects cyclic **#include** dependencies between user-defined headers. ``` // Header A.hpp #pragma once #include "B.hpp" // Header B.hpp #pragma once #include "C.hpp" // Header C.hpp #pragma once #include "A.hpp" // Include chain: A->B->C->A ``` Header files are a crucial part of many C++ programs as they provide a way to organize declarations and definitions shared across multiple source files. However, header files can also create problems when they become entangled in complex dependency cycles. Such cycles can cause issues with compilation times, unnecessary rebuilds, and make it harder to understand the overall structure of the code. To address these issues, a check has been developed to detect cyclic dependencies between header files, also known as "include cycles". An include cycle occurs when a header file *A* includes header file *B*, and *B* (or any subsequent included header file) includes back header file *A*, resulting in a circular dependency cycle. This check operates at the preprocessor level and specifically analyzes user-defined headers and their dependencies. It focuses solely on detecting include cycles while disregarding other types or function dependencies. This specialized analysis helps identify and prevent issues related to header file organization. By detecting include cycles early in the development process, developers can identify and resolve these issues before they become more difficult and time-consuming to fix. This can lead to faster compile times, improved code quality, and a more maintainable codebase overall. Additionally, by ensuring that header files are organized in a way that avoids cyclic dependencies, developers can make their code easier to understand and modify over time. It's worth noting that only user-defined headers their dependencies are analyzed, system includes such as standard library headers and third-party library headers are excluded. System includes are usually well-designed and free of include cycles, and ignoring them helps to focus on potential issues within the project's own codebase. This limitation doesn't diminish the ability to detect **#include** cycles within the analyzed code. Developers should carefully review any warnings or feedback provided by this solution. While the analysis aims to identify and prevent include cycles, there may be situations where exceptions or modifications are necessary. It's important to exercise judgment and consider the specific context of the codebase when making adjustments. ### Options - **IgnoredFilesList** Provides a way to exclude specific files/headers from the warnings raised by a check. This can be achieved by specifying a semicolon-separated list of regular expressions or filenames. This option can be used as an alternative to **//NOLINT** when using it is not possible. The default value of this option is an empty string, indicating that no files are ignored by default. ### misc-include-cleaner Checks for unused and missing includes. Generates findings only for the main file of a translation unit. Findings correspond to \. Example: ``` // foo.h class Foo{}; // bar.h #include "baz.h" class Bar{}; // baz.h class Baz{}; // main.cc #include "bar.h" // OK: uses class Bar from bar.h #include "foo.h" // warning: unused include "foo.h" Bar bar; Baz baz; // warning: missing include "baz.h" ``` ### Options - **IgnoreHeaders** A semicolon-separated list of regexes to disable insertion/removal of header files that match this regex as a suffix. E.g., *foo/.\** disables insertion/removal for all headers under the directory *foo*. Default is an empty string, no headers will be ignored. - **DeduplicateFindings** A boolean that controls whether the check should deduplicate findings for the same symbol. Defaults to *true*. - **UnusedIncludes** A boolean that controls whether the check should report unused includes (includes that are not used directly). Defaults to *true*. - **MissingIncludes** A boolean that controls whether the check should report missing includes (header files from which symbols are used but which are not directly included). Defaults to *true*. ### misc-misleading-bidirectional Warns about unterminated bidirectional unicode sequence, detecting potential attack as described in the Trojan Source \ attack. Example: ``` #include int main() { bool isAdmin = false; /*‮ } ⁦if (isAdmin)⁩ ⁦ begin admins only */ std::cout << "You are an admin.\n"; /* end admins only ‮ { ⁦*/ return 0; } ``` ### misc-misleading-identifier Finds identifiers that contain Unicode characters with right-to-left direction, which can be confusing as they may change the understanding of a whole statement line, as described in Trojan Source \. An example of such misleading code follows: ``` #include short int א = (short int)0; short int ג = (short int)12345; int main() { int א = ג; // a local variable, set to zero? printf("ג is %d\n", ג); printf("א is %d\n", א); } ``` ### misc-misplaced-const This check diagnoses when a **const** qualifier is applied to a **typedef**/ **using** to a pointer type rather than to the pointee, because such constructs are often misleading to developers because the **const** applies to the pointer rather than the pointee. For instance, in the following code, the resulting type is **int \* const** rather than **const int \***: ``` typedef int *int_ptr; void f(const int_ptr ptr) { *ptr = 0; // potentially quite unexpectedly the int can be modified here ptr = 0; // does not compile } ``` The check does not diagnose when the underlying **typedef**/**using** type is a pointer to a **const** type or a function pointer type. This is because the **const** qualifier is less likely to be mistaken because it would be redundant (or disallowed) on the underlying pointee type. ### misc-multiple-inheritance Warns if a class inherits from multiple classes that are not pure virtual. For example, declaring a class that inherits from multiple concrete classes is disallowed: ``` class Base_A { public: virtual int foo() { return 0; } }; class Base_B { public: virtual int bar() { return 0; } }; // Warning class Bad_Child1 : public Base_A, Base_B {}; ``` A class that inherits from a pure virtual is allowed: ``` class Interface_A { public: virtual int foo() = 0; }; class Interface_B { public: virtual int bar() = 0; }; // No warning class Good_Child1 : public Interface_A, Interface_B { virtual int foo() override { return 0; } virtual int bar() override { return 0; } }; ``` ### misc-new-delete-overloads *cert-dcl54-cpp* redirects here as an alias for this check. The check flags overloaded operator **new()** and operator **delete()** functions that do not have a corresponding free store function defined within the same scope. For instance, the check will flag a class implementation of a non-placement operator **new()** when the class does not also define a non-placement operator **delete()** function as well. The check does not flag implicitly-defined operators, deleted or private operators, or placement operators. This check corresponds to CERT C++ Coding Standard rule DCL54-CPP. Overload allocation and deallocation functions as a pair in the same scope \. ### misc-no-recursion Finds strongly connected functions (by analyzing the call graph for SCC's (Strongly Connected Components) that are loops), diagnoses each function in the cycle, and displays one example of a possible call graph loop (recursion). References: - • CERT C++ Coding Standard rule DCL56-CPP. Avoid cycles during initialization of static objects \. - • JPL Institutional Coding Standard for the C Programming Language (JPL DOCID D-60411) rule *2.4 Do not use direct or indirect recursion*. - • OpenCL Specification, Version 1.2 rule 6.9 Restrictions: i. Recursion is not supported. \. ### Limitations - • The check does not handle calls done through function pointers - • The check does not handle C++ destructors ### misc-non-copyable-objects *cert-fio38-c* redirects here as an alias for this check. Flags dereferences and non-pointer declarations of objects that are not meant to be passed by value, such as C FILE objects or POSIX **pthread\_mutex\_t** objects. ### References This check corresponds to CERT C++ Coding Standard rule FIO38-C. Do not copy a FILE object \. ### misc-non-private-member-variables-in-classes *cppcoreguidelines-non-private-member-variables-in-classes* redirects here as an alias for this check. Finds classes that contain non-static data members in addition to user-declared non-static member functions and diagnose all data members declared with a non-**public** access specifier. The data members should be declared as **private** and accessed through member functions instead of exposed to derived classes or class consumers. ### Options - **IgnoreClassesWithAllMemberVariablesBeingPublic** When *true*, allows to completely ignore classes if **all** the member variables in that class declared with a **public** access specifier. Default is *false*. - **IgnorePublicMemberVariables** When *true*, allows to ignore (not diagnose) **all** the member variables declared with a **public** access specifier. Default is *false*. ### misc-override-with-different-visibility Finds virtual function overrides with different visibility than the function in the base class. This includes for example if a virtual function declared as **private** is overridden and declared as **public** in a subclass. The detected change is the modification of visibility resulting from keywords **public**, **protected**, **private** at overridden virtual functions. The check applies to any normal virtual function and optionally to destructors or operators. Use of the **using** keyword is not considered as visibility change by this check. ``` class A { public: virtual void f_pub(); private: virtual void f_priv(); }; class B: public A { public: void f_priv(); // warning: changed visibility from private to public private: void f_pub(); // warning: changed visibility from public to private }; class C: private A { // no warning: f_pub becomes private in this case but this is from the // private inheritance }; class D: private A { public: void f_pub(); // warning: changed visibility from private to public // 'f_pub' would have private access but is forced to be // public }; ``` If the visibility is changed in this way, it can indicate bad design or programming error. If a virtual function is private in a subclass but public in the base class, it can still be accessed from a pointer to the subclass if the pointer is converted to the base type. Probably private inheritance can be used instead. A protected virtual function that is made public in a subclass may have valid use cases but similar (not exactly same) effect can be achieved with the **using** keyword. ### Options - **DisallowedVisibilityChange** Controls what kind of change to the visibility will be detected by the check. Possible values are *any*, *widening*, *narrowing*. For example the *widening* option will produce warning only if the visibility is changed from more restrictive (**private**) to less restrictive (**public**). Default value is *any*. - **CheckDestructors** If *true*, the check does apply to destructors too. Otherwise destructors are ignored by the check. Default value is *false*. - **CheckOperators** If *true*, the check does apply to overloaded C++ operators (as virtual member functions) too. This includes other special member functions (like conversions) too. This option is probably useful only in rare cases because operators and conversions are not often virtual functions. Default value is *false*. - **IgnoredFunctions** This option can be used to ignore the check at specific functions. To configure this option, a semicolon-separated list of function names should be provided. The list can contain regular expressions, in this way it is possible to select all functions of a specific class (like *MyClass::.\**) or a specific function of any class (like *my\_function* or *::.\*::my\_function*). The function names are matched at the base class. Default value is empty string. ### misc-predictable-rand Warns for the usage of **std::rand()**. Pseudorandom number generators use mathematical algorithms to produce a sequence of numbers with good statistical properties, but the numbers produced are not genuinely random. The **std::rand()** function takes a seed (number), runs a mathematical operation on it and returns the result. By manipulating the seed the result can be predictable. ### References This check corresponds to the CERT C Coding Standard rules MSC30-C. Do not use the rand() function for generating pseudorandom numbers \. MSC50-CPP. Do not use std::rand() for generating pseudorandom numbers \. ### misc-redundant-expression Detect redundant expressions which are typically errors due to copy-paste. Depending on the operator expressions may be - • redundant, - • always **true**, - • always **false**, - • always a constant (zero or one). Examples: ``` ((x+1) | (x+1)) // (x+1) is redundant (p->x == p->x) // always true (p->x < p->x) // always false (speed - speed + 1 == 12) // speed - speed is always zero int b = a | 4 | a // identical expr on both sides ((x=1) | (x=1)) // expression is identical (DEFINE_1 | DEFINE_1) // same macro on the both sides ((DEF_1 + DEF_2) | (DEF_1+DEF_2)) // expressions differ in spaces only ``` Floats are handled except in the case that NaNs are checked like so: ``` int TestFloat(float F) { if (F == F) // Identical float values used return 1; return 0; } int TestFloat(float F) { // Testing NaN. if (F != F && F == F) // does not warn return 1; return 0; } ``` ### misc-static-assert *cert-dcl03-c* redirects here as an alias for this check. Replaces **assert()** with **static\_assert()** if the condition is evaluable at compile time. The condition of **static\_assert()** is evaluated at compile time which is safer and more efficient. ### misc-static-initialization-cycle Finds cyclical initialization of static variables. The cycle can come from reference to static variables or from (static) function calls during initialization. Such cycles can cause undefined behavior. In this context "static" means C++ **static** class members, global variables, global functions, and **static** variables inside functions. For the purpose of this check, the initialization of a static variable *uses* another static variable or function if it appears in the initializer expression. A function *uses* a static variable or function if the variable or function appears at any place in the function code (except if the variable is assigned to). The check can detect cycles in this "usage graph". The check does not consider conditions in function code and does not follow the value of static variables (if assigned to another variable). For this reason it can produce false positives in some cases. ### Examples ``` struct S { static int A; }; int B = S::A; int S::A = B; ``` Cycle in variable initialization. ``` int f1(int X, int Y); struct S { static int A; }; int B = S::A + 1; int S::A = f1(B, 2); ``` Cyclical initialization: **B** uses value of **S::A**, and **S::A** may use value of **B** (the check gives always warning regardless of the code of **f1**). ``` struct S { static int A; }; int f1() { return S::A; } int S::A = f1(); ``` This code results in initialization of **S::A** with itself through a function call. The check would emit a warning in any case when **S::A** appears in **f1** (even if the return value is not affected by it). ### References - • CERT C++ Coding Standard rule DCL56-CPP. Avoid cycles during initialization of static objects \. ### misc-throw-by-value-catch-by-reference *cert-err09-cpp* and *cert-err61-cpp* redirect here as aliases of this check. Finds violations of the rule "Throw by value, catch by reference" presented for example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu, as well as the CERT C++ Coding Standard rule ERR61-CPP. Catch exceptions by lvalue reference \. - **Exceptions:** - • Throwing string literals will not be flagged despite being a pointer. They are not susceptible to slicing and the usage of string literals is idiomatic. - • Catching character pointers (**char**, **wchar\_t**, unicode character types) will not be flagged to allow catching string literals. - • Moved named values will not be flagged as not throwing an anonymous temporary. In this case we can be sure that the user knows that the object can't be accessed outside catch blocks handling the error. - • Throwing function parameters will not be flagged as not throwing an anonymous temporary. This allows helper functions for throwing. - • Re-throwing caught exception variables will not be flagged as not throwing an anonymous temporary. Although this can usually be done by just writing **throw;** it happens often enough in real code. ### Options - **CheckThrowTemporaries** Triggers detection of violations of the CERT recommendation ERR09-CPP. Throw anonymous temporaries. Default is *true*. - **WarnOnLargeObject** Also warns for any large, trivial object caught by value. Catching a large object by value is not dangerous but affects the performance negatively. The maximum size of an object allowed to be caught without warning can be set using the *MaxSize* option. Default is *false*. - **MaxSize** Determines the maximum size of an object allowed to be caught without warning. Only applicable if **WarnOnLargeObject** is set to *true*. If the option is set by the user to *std::numeric\_limits\::max()* then it reverts to the default value. Default is the size of *size\_t*. ### misc-unconventional-assign-operator Finds declarations of assign operators with the wrong return and/or argument types and definitions with good return type but wrong **return** statements. - • The return type must be **Class&**. - • The assignment may be from the class type by value, const lvalue reference, non-const rvalue reference, or from a completely different type (e.g. **int**). - • Private and deleted operators are ignored. - • The operator must always return **\*this**. ### misc-uniqueptr-reset-release Find and replace **unique\_ptr::reset(release())** with **std::move()**. Example: ``` std::unique_ptr x, y; x.reset(y.release()); -> x = std::move(y); ``` If **y** is already rvalue, **std::move()** is not added. **x** and **y** can also be **std::unique\_ptr\\***. ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. ### misc-unused-alias-decls Finds unused namespace alias declarations. ``` namespace my_namespace { class C {}; } namespace unused_alias = ::my_namespace; ``` ### misc-unused-parameters Finds unused function parameters. Unused parameters may signify a bug in the code (e.g. when a different parameter is used instead). The suggested fixes either comment parameter name out or remove the parameter completely, if all callers of the function are in the same translation unit and can be updated. The check is similar to the *-Wunused-parameter* compiler diagnostic and can be used to prepare a codebase to enabling of that diagnostic. By default the check is more permissive (see **StrictMode** \<#cmdoption-arg-StrictMode\>). ``` void a(int i) { /*some code that doesn't use `i`*/ } // becomes void a(int /*i*/) { /*some code that doesn't use `i`*/ } ``` ``` static void staticFunctionA(int i); static void staticFunctionA(int i) { /*some code that doesn't use `i`*/ } // becomes static void staticFunctionA() static void staticFunctionA() { /*some code that doesn't use `i`*/ } ``` ### Options - **StrictMode** When *false* (default value), the check will ignore trivially unused parameters, i.e. when the corresponding function has an empty body (and in case of constructors - no constructor initializers). When the function body is empty, an unused parameter is unlikely to be unnoticed by a human reader, and there's basically no place for a bug to hide. - **IgnoreVirtual** Determines whether virtual method parameters should be inspected. Set to *true* to ignore them. Default is *false*. - **IgnoreMacroParameters** When *true*, the check will not report unused parameters whose declarations originate from a macro expansion. This suppresses false positives in code that uses macros to define function signatures where parameters are structurally required by the macro but not used in every expansion. Default is *false*. ### misc-unused-using-decls Finds unused **using** declarations. Unused **using** declarations in header files will not be diagnosed since these using declarations are part of the header's public API. Allowed header file extensions can be configured via the global option *HeaderFileExtensions*. Example: ``` // main.cpp namespace n { class C; } using n::C; // Never actually used. ``` ### misc-use-anonymous-namespace Finds instances of **static** functions or variables declared at global scope that could instead be moved into an anonymous namespace. Anonymous namespaces are the "superior alternative" according to the C++ Standard. **static** was proposed for deprecation, but later un-deprecated to keep C compatibility \[1\]. **static** is an overloaded term with different meanings in different contexts, so it can create confusion. The following uses of **static** will *not* be diagnosed: - • Functions or variables in header files, since anonymous namespaces in headers is considered an antipattern. Allowed header file extensions can be configured via the global option *HeaderFileExtensions*. - • **const** or **constexpr** variables, since they already have implicit internal linkage in C++. Examples: ``` // Bad static void foo(); static int x; // Good namespace { void foo(); int x; } // namespace ``` \[1\] Undeprecating static \ ### misc-use-internal-linkage Detects variables, functions, and classes that can be marked as static or (in C++) moved into an anonymous namespace to enforce internal linkage. Any entity that's only used within a single file should be given internal linkage. Doing so gives the compiler more information, allowing it to better remove dead code and perform more aggressive optimizations. Example: ``` int v1; // can be marked as static void fn1() {} // can be marked as static // already declared as extern extern int v2; void fn3(); // without function body in all declaration, maybe external linkage void fn3(); // === C++-specific === struct S1 {}; // can be moved into anonymous namespace namespace { // already in anonymous namespace int v2; void fn2(); struct S2 {}; } // export declarations export void fn4() {} export namespace t { void fn5() {} } export int v2; export class C {}; ``` ### Options - **FixMode** Selects what kind of a fix the check should provide. The default is *UseStatic*. - • *None* Don't fix automatically. - • *UseStatic* Add **static** for internal linkage variable and function. - **AnalyzeFunctions** Whether to suggest giving functions internal linkage. Default is *true*. - **AnalyzeVariables** Whether to suggest giving variables internal linkage. Default is *true*. - **AnalyzeTypes** (C++ only) Whether to suggest giving user-defined types (structs, classes, unions, and enums) internal linkage. Default is *true*. ### modernize-avoid-bind The check finds uses of **std::bind** and **boost::bind** and replaces them with lambdas. Lambdas will use value-capture unless reference capture is explicitly requested with **std::ref** or **boost::ref**. It supports arbitrary callables including member functions, function objects, and free functions, and all variations thereof. Anything that you can pass to the first argument of **bind** should be diagnosable. Currently, the only known case where a fix-it is unsupported is when the same placeholder is specified multiple times in the parameter list. Given: ``` int add(int x, int y) { return x + y; } ``` Then: ``` void f() { int x = 2; auto clj = std::bind(add, x, _1); } ``` is replaced by: ``` void f() { int x = 2; auto clj = [=](auto && arg1) { return add(x, arg1); }; } ``` **std::bind** can be hard to read and can result in larger object files and binaries due to type information that will not be produced by equivalent lambdas. ### Options - **PermissiveParameterList** If the option is set to *true*, the check will append **auto&&...** to the end of every placeholder parameter list. Without this, it is possible for a fix-it to perform an incorrect transformation in the case where the result of the **bind** is used in the context of a type erased functor such as **std::function** which allows mismatched arguments. Default is *false*. For example: ``` int add(int x, int y) { return x + y; } int foo() { std::function ignore_args = std::bind(add, 2, 2); return ignore_args(3, 3); } ``` is valid code, and returns *4*. The actual values passed to **ignore\_args** are simply ignored. Without **PermissiveParameterList**, this would be transformed into ``` int add(int x, int y) { return x + y; } int foo() { std::function ignore_args = [] { return add(2, 2); } return ignore_args(3, 3); } ``` which will *not* compile, since the lambda does not contain an **operator()** that accepts 2 arguments. With permissive parameter list, it instead generates ``` int add(int x, int y) { return x + y; } int foo() { std::function ignore_args = [](auto&&...) { return add(2, 2); } return ignore_args(3, 3); } ``` which is correct. This check requires using C++14 or higher to run. ### modernize-avoid-c-arrays *cppcoreguidelines-avoid-c-arrays* redirects here as an alias for this check. Finds C-style array types and recommend to use **std::array\<\>** / **std::vector\<\>**. All types of C arrays are diagnosed. For parameters of incomplete C-style array type, it would be better to use **std::span** / **gsl::span** as replacement. However, fix-it are potentially dangerous in header files and are therefore not emitted right now. ``` int a[] = {1, 2}; // warning: do not declare C-style arrays, use 'std::array' instead int b[1]; // warning: do not declare C-style arrays, use 'std::array' instead void foo() { int c[b[0]]; // warning: do not declare C VLA arrays, use 'std::vector' instead } template class array { T d[Size]; // warning: do not declare C-style arrays, use 'std::array' instead int e[1]; // warning: do not declare C-style arrays, use 'std::array' instead }; array d; // warning: do not declare C-style arrays, use 'std::array' instead using k = int[4]; // warning: do not declare C-style arrays, use 'std::array' instead ``` However, the **extern "C"** code is ignored, since it is common to share such headers between C code, and C++ code. ``` // Some header extern "C" { int f[] = {1, 2}; // not diagnosed int j[1]; // not diagnosed inline void bar() { { int j[j[0]]; // not diagnosed } } } ``` Similarly, the **main()** function is ignored. Its second and third parameters can be either **char\* argv\[\]** or **char\*\* argv**, but cannot be **std::array\<\>**. ### Options - **AllowStringArrays** When set to *true* (default is *false*), variables of character array type with deduced length, initialized directly from string literals, will be ignored. This option doesn't affect cases where length can't be deduced, resembling pointers, as seen in class members and parameters. Example: ``` const char name[] = "Some name"; ``` ### modernize-avoid-c-style-cast Finds usages of C-style casts. C-style casts can perform a variety of different conversions (**const\_cast**, **static\_cast**, **reinterpret\_cast**, or a combination). This makes them dangerous as the intent is not clear, and they can silently perform unsafe conversions between incompatible types. This check is similar to *-Wold-style-cast*, but it suggests automated fixes in some cases. The reported locations should not be different from the ones generated by *-Wold-style-cast*. ### Examples ``` class A { public: std::string v; }; A a; double *num = (double*)(&a); // Compiles! Hides danger // num = static_cast(&a); // Won't compile (good!) num = reinterpret_cast(&a); // Compiles, danger is explicit ``` ### References Corresponding cpplint.py check name: *readability/casting*. ### modernize-avoid-setjmp-longjmp Flags all call expressions involving **setjmp()** and **longjmp()** in C++ code. Exception handling with **throw** and **catch** should be used instead. ### References This check corresponds to the CERT C++ Coding Standard rule ERR52-CPP. Do not use setjmp() or longjmp() \. ### modernize-avoid-variadic-functions Find all function definitions (but not declarations) of C-style variadic functions. Instead of C-style variadic functions, C++ function parameter pack should be used. ### References This check corresponds to the CERT C++ Coding Standard rule DCL50-CPP. Do not define a C-style variadic function \. ### modernize-concat-nested-namespaces Checks for use of nested namespaces such as **namespace a { namespace b { ... } }** and suggests changing to the more concise syntax introduced in C++17: **namespace a::b { ... }**. Inline namespaces are not modified. For example: ``` namespace n1 { namespace n2 { void t(); } } namespace n3 { namespace n4 { namespace n5 { void t(); } } namespace n6 { namespace n7 { void t(); } } } // in c++20 namespace n8 { inline namespace n9 { void t(); } } ``` Will be modified to: ``` namespace n1::n2 { void t(); } namespace n3 { namespace n4::n5 { void t(); } namespace n6::n7 { void t(); } } // in c++20 namespace n8::inline n9 { void t(); } ``` ### modernize-deprecated-headers Some headers from C library were deprecated in C++ and are no longer welcome in C++ codebases. Some have no effect in C++. For more details refer to the C++14 Standard \[depr.c.headers\] section. This check replaces C standard library headers with their C++ alternatives and removes redundant ones. ``` // C++ source file... #include #include // becomes #include // No 'stdbool.h' here. ``` Important note: the Standard doesn't guarantee that the C++ headers declare all the same functions in the global namespace. The check in its current form can break the code that uses library symbols from the global namespace. - • *\* - • *\* - • *\* - • *\* - • *\* // deprecated since C++11 - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* - • *\* // deprecated since C++11 - • *\* - • *\* // deprecated since C++11 - • *\* - • *\* If the specified standard is older than C++11 the check will only replace headers deprecated before C++11, otherwise -- every header that appeared in the previous list. These headers don't have effect in C++: - • *\* - • *\* - • *\* The checker ignores *include* directives within *extern "C" { ... }* blocks, since a library might want to expose some API for C and C++ libraries. ``` // C++ source file... extern "C" { #include // Left intact. #include // Left intact. } ``` ### Options - **CheckHeaderFile** *clang-tidy* cannot know if the header file included by the currently analyzed C++ source file is not included by any other C source files. Hence, to omit false-positives and wrong fixit-hints, we ignore emitting reports into header files. One can set this option to *true* if they know that the header files in the project are only used by C++ source files. Default is *false*. ### modernize-deprecated-ios-base-aliases Detects usage of the deprecated member types of **std::ios\_base** and replaces those that have a non-deprecated equivalent. | | | | --- | --- | | Deprecated member type | Replacement | | **std::ios\_base::io\_state** | **std::ios\_base::iostate** | | **std::ios\_base::open\_mode** | **std::ios\_base::openmode** | | **std::ios\_base::seek\_dir** | **std::ios\_base::seekdir** | | **std::ios\_base::streamoff** | | | **std::ios\_base::streampos** | | ### modernize-loop-convert This check converts **for(...; ...; ...)** loops to use the new range-based loops in C++11. Three kinds of loops can be converted: - • Loops over statically allocated arrays. - • Loops over containers, using iterators. - • Loops over array-like containers, using **operator\[\]** and **at()**. ### MinConfidence option ### risky In loops where the container expression is more complex than just a reference to a declared expression (a variable, function, enum, etc.), and some part of it appears elsewhere in the loop, we lower our confidence in the transformation due to the increased risk of changing semantics. Transformations for these loops are marked as *risky*, and thus will only be converted if the minimum required confidence level is set to *risky*. ``` int arr[10][20]; int l = 5; for (int j = 0; j < 20; ++j) int k = arr[l][j] + l; // using l outside arr[l] is considered risky for (int i = 0; i < obj.getVector().size(); ++i) obj.foo(10); // using 'obj' is considered risky ``` See Range-based loops evaluate end() only once for an example of an incorrect transformation when the minimum required confidence level is set to *risky*. ### reasonable (Default) If a loop calls **.end()** or **.size()** after each iteration, the transformation for that loop is marked as *reasonable*, and thus will be converted if the required confidence level is set to *reasonable* (default) or lower. ``` // using size() is considered reasonable for (int i = 0; i < container.size(); ++i) cout << container[i]; ``` ### safe Any other loops that do not match the above criteria to be marked as *risky* or *reasonable* are marked *safe*, and thus will be converted if the required confidence level is set to *safe* or lower. ``` int arr[] = {1,2,3}; for (int i = 0; i < 3; ++i) cout << arr[i]; ``` ### Example Original: ``` const int N = 5; int arr[] = {1,2,3,4,5}; vector v; v.push_back(1); v.push_back(2); v.push_back(3); // safe conversion for (int i = 0; i < N; ++i) cout << arr[i]; // reasonable conversion for (vector::iterator it = v.begin(); it != v.end(); ++it) cout << *it; // reasonable conversion for (vector::iterator it = begin(v); it != end(v); ++it) cout << *it; // reasonable conversion for (vector::iterator it = std::begin(v); it != std::end(v); ++it) cout << *it; // reasonable conversion for (int i = 0; i < v.size(); ++i) cout << v[i]; // reasonable conversion for (int i = 0; i < size(v); ++i) cout << v[i]; ``` After applying the check with minimum confidence level set to *reasonable* (default): ``` const int N = 5; int arr[] = {1,2,3,4,5}; vector v; v.push_back(1); v.push_back(2); v.push_back(3); // safe conversion for (auto & elem : arr) cout << elem; // reasonable conversion for (auto & elem : v) cout << elem; // reasonable conversion for (auto & elem : v) cout << elem; ``` ### Reverse Iterator Support The converter is also capable of transforming iterator loops which use **rbegin** and **rend** for looping backwards over a container. Out of the box this will automatically happen in C++20 mode using the **ranges** library, however the check can be configured to work without C++20 by specifying a function to reverse a range and optionally the header file where that function lives. ### Options - **UseCxx20ReverseRanges** When set to true convert loops when in C++20 or later mode using **std::views::reverse**. Default value is *true*. - **MakeReverseRangeFunction** Specify the function used to reverse an iterator pair, the function should accept a class with **rbegin** and **rend** methods and return a class with **begin** and **end** methods that call the **rbegin** and **rend** methods respectively. Common examples are **std::views::reverse** and **llvm::reverse**. Default value is an empty string. - **MakeReverseRangeHeader** Specifies the header file where **MakeReverseRangeFunction** is declared. For the previous examples this option would be set to **range/v3/view/reverse.hpp** and **llvm/ADT/STLExtras.h** respectively. If this is an empty string and **MakeReverseRangeFunction** is set, the check will proceed on the assumption that the function is already available in the translation unit. This can be wrapped in angle brackets to signify to add the include as a system include. Default value is an empty string. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. ### Limitations There are certain situations where the tool may erroneously perform transformations that remove information and change semantics. Users of the tool should be aware of the behavior and limitations of the check outlined by the cases below. ### Comments inside loop headers Comments inside the original loop header are ignored and deleted when transformed. ``` for (int i = 0; i < N; /* This will be deleted */ ++i) { } ``` ### Range-based loops evaluate end() only once The C++11 range-based for loop calls **.end()** only once during the initialization of the loop. If in the original loop **.end()** is called after each iteration the semantics of the transformed loop may differ. ``` // The following is semantically equivalent to the C++11 range-based for loop, // therefore the semantics of the header will not change. for (iterator it = container.begin(), e = container.end(); it != e; ++it) { } // Instead of calling .end() after each iteration, this loop will be // transformed to call .end() only once during the initialization of the loop, // which may affect semantics. for (iterator it = container.begin(); it != container.end(); ++it) { } ``` As explained above, calling member functions of the container in the body of the loop is considered *risky*. If the called member function modifies the container the semantics of the converted loop will differ due to **.end()** being called only once. ``` bool flag = false; for (vector::iterator it = vec.begin(); it != vec.end(); ++it) { // Add a copy of the first element to the end of the vector. if (!flag) { // This line makes this transformation 'risky'. vec.push_back(*it); flag = true; } cout << *it; } ``` The original code above prints out the contents of the container including the newly added element while the converted loop, shown below, will only print the original contents and not the newly added element. ``` bool flag = false; for (auto & elem : vec) { // Add a copy of the first element to the end of the vector. if (!flag) { // This line makes this transformation 'risky' vec.push_back(elem); flag = true; } cout << elem; } ``` Semantics will also be affected if **.end()** has side effects. For example, in the case where calls to **.end()** are logged the semantics will change in the transformed loop if **.end()** was originally called after each iteration. ``` iterator end() { num_of_end_calls++; return container.end(); } ``` ### Overloaded operator-\>() with side effects Similarly, if **operator-\>()** was overloaded to have side effects, such as logging, the semantics will change. If the iterator's **operator-\>()** was used in the original loop it will be replaced with **\.\** instead due to the implicit dereference as part of the range-based for loop. Therefore any side effect of the overloaded **operator-\>()** will no longer be performed. ``` for (iterator it = c.begin(); it != c.end(); ++it) { it->func(); // Using operator->() } // Will be transformed to: for (auto & elem : c) { elem.func(); // No longer using operator->() } ``` ### Pointers and references to containers While most of the check's risk analysis is dedicated to determining whether the iterator or container was modified within the loop, it is possible to circumvent the analysis by accessing and modifying the container through a pointer or reference. If the container were directly used instead of using the pointer or reference the following transformation would have only been applied at the *risky* level since calling a member function of the container is considered *risky*. The check cannot identify expressions associated with the container that are different than the one used in the loop header, therefore the transformation below ends up being performed at the *safe* level. ``` vector vec; vector *ptr = &vec; vector &ref = vec; for (vector::iterator it = vec.begin(), e = vec.end(); it != e; ++it) { if (!flag) { // Accessing and modifying the container is considered risky, but the risk // level is not raised here. ptr->push_back(*it); ref.push_back(*it); flag = true; } } ``` ### OpenMP As range-based for loops are only available since OpenMP 5, this check should not be used on code with a compatibility requirement of OpenMP prior to version 5. It is **intentional** that this check does not make any attempts to exclude incorrect diagnostics on OpenMP for loops prior to OpenMP 5. To prevent this check to be applied (and to break) OpenMP for loops but still be applied to non-OpenMP for loops the usage of **NOLINT** (see Suppressing Undesired Diagnostics \<#clang-tidy-nolint\>) on the specific for loops is recommended. ### modernize-macro-to-enum Replaces groups of adjacent macros with an unscoped anonymous enum. Using an unscoped anonymous enum ensures that everywhere the macro token was used previously, the enumerator name may be safely used. This check can be used to enforce the C++ core guideline Enum.1: Prefer enumerations over macros \, within the constraints outlined below. Potential macros for replacement must meet the following constraints: - • Macros must expand only to integral literal tokens or expressions of literal tokens. The expression may contain any of the unary operators **-**, **+**, **~** or **!**, any of the binary operators **,**, **-**, **+**, **\***, **/**, **%**, **&**, **\|**, **^**, **\<**, **\>**, **\<=**, **\>=**, **==**, **!=**, **\|\|**, **&&**, **\<\<**, **\>\>** or **\<=\>**, the ternary operator **?:** and its GNU extension \. Parenthesized expressions are also recognized. This recognizes most valid expressions. In particular, expressions with the **sizeof** operator are not recognized. - • Macros must be defined on sequential source file lines, or with only comment lines in between macro definitions. - • Macros must all be defined in the same source file. - • Macros must not be defined within a conditional compilation block. (Conditional include guards are exempt from this constraint.) - • Macros must not be defined adjacent to other preprocessor directives. - • Macros must not be used in any conditional preprocessing directive. - • Macros must not be used as arguments to other macros. - • Macros must not be undefined. - • Macros must be defined at the top-level, not inside any declaration or definition. Each cluster of macros meeting the above constraints is presumed to be a set of values suitable for replacement by an anonymous enum. From there, a developer can give the anonymous enum a name and continue refactoring to a scoped enum if desired. Comments on the same line as a macro definition or between subsequent macro definitions are preserved in the output. No formatting is assumed in the provided replacements, although clang-tidy can optionally format all fixes. **Warning:** Initializing expressions are assumed to be valid initializers for an enum. C requires that enum values fit into an **int**, but this may not be the case for some accepted constant expressions. For instance **1 \<\< 40** will not fit into an **int** when the size of an **int** is 32 bits. Examples: ``` #define RED 0xFF0000 #define GREEN 0x00FF00 #define BLUE 0x0000FF #define TM_NONE (-1) // No method selected. #define TM_ONE 1 // Use tailored method one. #define TM_TWO 2 // Use tailored method two. Method two // is preferable to method one. #define TM_THREE 3 // Use tailored method three. ``` becomes ``` enum { RED = 0xFF0000, GREEN = 0x00FF00, BLUE = 0x0000FF }; enum { TM_NONE = (-1), // No method selected. TM_ONE = 1, // Use tailored method one. TM_TWO = 2, // Use tailored method two. Method two // is preferable to method one. TM_THREE = 3 // Use tailored method three. }; ``` ### modernize-make-shared This check finds the creation of **std::shared\_ptr** objects by explicitly calling the constructor and a **new** expression, and replaces it with a call to **std::make\_shared**. ``` auto my_ptr = std::shared_ptr(new MyPair(1, 2)); // becomes auto my_ptr = std::make_shared(1, 2); ``` This check also finds calls to **std::shared\_ptr::reset()** with a **new** expression, and replaces it with a call to **std::make\_shared**. ``` my_ptr.reset(new MyPair(1, 2)); // becomes my_ptr = std::make_shared(1, 2); ``` ### Options - **MakeSmartPtrFunction** A string specifying the name of make-shared-ptr function. Default is *std::make\_shared*. - **MakeSmartPtrFunctionHeader** A string specifying the corresponding header of make-shared-ptr function. Default is *\*. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **IgnoreMacros** If set to *true*, the check will not give warnings inside macros. Default is *true*. - **IgnoreDefaultInitialization** If set to *false*, the check does not suggest edits that will transform default initialization into value initialization, as this can cause performance regressions. Default is *true*. ### modernize-make-unique This check finds the creation of **std::unique\_ptr** objects by explicitly calling the constructor and a **new** expression, and replaces it with a call to **std::make\_unique**, introduced in C++14. ``` auto my_ptr = std::unique_ptr(new MyPair(1, 2)); // becomes auto my_ptr = std::make_unique(1, 2); ``` This check also finds calls to **std::unique\_ptr::reset()** with a **new** expression, and replaces it with a call to **std::make\_unique**. ``` my_ptr.reset(new MyPair(1, 2)); // becomes my_ptr = std::make_unique(1, 2); ``` ### Options - **MakeSmartPtrFunction** A string specifying the name of make-unique-ptr function. Default is *std::make\_unique*. - **MakeSmartPtrFunctionHeader** A string specifying the corresponding header of make-unique-ptr function. Default is *\*. - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **IgnoreMacros** If set to *true*, the check will not give warnings inside macros. Default is *true*. - **IgnoreDefaultInitialization** If set to *false*, the check does not suggest edits that will transform default initialization into value initialization, as this can cause performance regressions. Default is *true*. ### modernize-min-max-use-initializer-list Replaces nested **std::min** and **std::max** calls with an initializer list where applicable. For instance, consider the following code: ``` int a = std::max(std::max(i, j), k); ``` The check will transform the above code to: ``` int a = std::max({i, j, k}); ``` ### Performance Considerations While this check simplifies the code and makes it more readable, it may cause performance degradation for non-trivial types due to the need to copy objects into the initializer list. To avoid this, it is recommended to use *std::ref* or *std::cref* for non-trivial types: ``` std::string b = std::max({std::ref(i), std::ref(j), std::ref(k)}); ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **IgnoreNonTrivialTypes** A boolean specifying whether to ignore non-trivial types. Default is *true*. - **IgnoreTrivialTypesOfSizeAbove** An integer specifying the size (in bytes) above which trivial types are ignored. Default is *32*. ### modernize-pass-by-value With move semantics added to the language and the standard library updated with move constructors added for many types it is now interesting to take an argument directly by value, instead of by const-reference, and then copy. This check allows the compiler to take care of choosing the best way to construct the copy. The transformation is usually beneficial when the calling code passes an *rvalue* and assumes the move construction is a cheap operation. This short example illustrates how the construction of the value happens: ``` void foo(std::string s); std::string get_str(); void f(const std::string &str) { foo(str); // lvalue -> copy construction foo(get_str()); // prvalue -> move construction } ``` **Note:** Currently, only constructors are transformed to make use of pass-by-value. Contributions that handle other situations are welcome! ### Pass-by-value in constructors Replaces the uses of const-references constructor parameters that are copied into class fields. The parameter is then moved with *std::move()*. Since **std::move()** is a library function declared in *\* it may be necessary to add this include. The check will add the include directive when necessary. ``` #include class Foo { public: - Foo(const std::string &Copied, const std::string &ReadOnly) - : Copied(Copied), ReadOnly(ReadOnly) + Foo(std::string Copied, const std::string &ReadOnly) + : Copied(std::move(Copied)), ReadOnly(ReadOnly) {} private: std::string Copied; const std::string &ReadOnly; }; std::string get_cwd(); void f(const std::string &Path) { // The parameter corresponding to 'get_cwd()' is move-constructed. By // using pass-by-value in the Foo constructor we managed to avoid a // copy-construction. Foo foo(get_cwd(), Path); } ``` If the parameter is used more than once no transformation is performed since moved objects have an undefined state. It means the following code will be left untouched: ``` #include void pass(const std::string &S); struct Foo { Foo(const std::string &S) : Str(S) { pass(S); } std::string Str; }; ``` ### Limitations A situation where the generated code can be wrong is when the object referenced is modified before the assignment in the init-list through a "hidden" reference. Example: ``` std::string s("foo"); struct Base { Base() { s = "bar"; } }; struct Derived : Base { - Derived(const std::string &S) : Field(S) + Derived(std::string S) : Field(std::move(S)) { } std::string Field; }; void f() { - Derived d(s); // d.Field holds "bar" + Derived d(s); // d.Field holds "foo" } ``` ### Note about delayed template parsing When delayed template parsing is enabled, constructors part of templated contexts; templated constructors, constructors in class templates, constructors of inner classes of template classes, etc., are not transformed. Delayed template parsing is enabled by default on Windows as a Microsoft extension: Clang Compiler User's Manual - Microsoft extensions \. Delayed template parsing can be enabled using the *-fdelayed-template-parsing* flag and disabled using *-fno-delayed-template-parsing*. Example: ``` template class C { std::string S; public: = // using -fdelayed-template-parsing (default on Windows) = C(const std::string &S) : S(S) {} + // using -fno-delayed-template-parsing (default on non-Windows systems) + C(std::string S) : S(std::move(S)) {} }; ``` **See also:** For more information about the pass-by-value idiom, read: Want Speed? Pass by Value \. ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **ValuesOnly** When *true*, the check only warns about copied parameters that are already passed by value. Default is *false*. - **IgnoreMacros** When *true*, the check will not give warnings inside macros. Default is *false*. ### modernize-raw-string-literal This check selectively replaces string literals containing escaped characters with raw string literals. Example: ``` const char *const Quotes{"embedded \"quotes\""}; const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; const char *const SingleLine{"Single line.\n"}; const char *const TrailingSpace{"Look here -> \n"}; const char *const Tab{"One\tTwo\n"}; const char *const Bell{"Hello!\a And welcome!"}; const char *const Path{"C:\\Program Files\\Vendor\\Application.exe"}; const char *const RegEx{"\\w\\([a-z]\\)"}; ``` becomes ``` const char *const Quotes{R"(embedded "quotes")"}; const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; const char *const SingleLine{"Single line.\n"}; const char *const TrailingSpace{"Look here -> \n"}; const char *const Tab{"One\tTwo\n"}; const char *const Bell{"Hello!\a And welcome!"}; const char *const Path{R"(C:\Program Files\Vendor\Application.exe)"}; const char *const RegEx{R"(\w\([a-z]\))"}; ``` The presence of any of the following escapes can cause the string to be converted to a raw string literal: **\\\\**, **\\'**, **\\"**, **\\?**, and octal or hexadecimal escapes for printable ASCII characters. A string literal containing only escaped newlines is a common way of writing lines of text output. Introducing physical newlines with raw string literals in this case is likely to impede readability. These string literals are left unchanged. An escaped horizontal tab, form feed, or vertical tab prevents the string literal from being converted. The presence of a horizontal tab, form feed or vertical tab in source code is not visually obvious. ### Options - **DelimiterStem** Custom delimiter to escape characters in raw string literals. It is used in the following construction: **R"stem\_delimiter(contents)stem\_delimiter"**. The default value is *lit*. - **ReplaceShorterLiterals** Controls replacing shorter non-raw string literals with longer raw string literals. Setting this option to *true* enables the replacement. The default value is *false* (shorter literals are not replaced). ### modernize-redundant-void-arg Finds and removes redundant **void** argument lists. Works in C++ and in C23 and up. - **Examples:** | | | | --- | --- | | Initial code | Code with applied fixes | | **int f(void);** | **int f();** | | **int (\*f(void))(void);** | **int (\*f())();** | | **typedef int (\*f\_t(void))(void);** | **typedef int (\*f\_t())();** | | **void (C::\*p)(void);** | **void (C::\*p)();** | | **C::C(void) {}** | **C::C() {}** | | **C::~C(void) {}** | **C::~C() {}** | ### modernize-replace-auto-ptr This check replaces the uses of the deprecated class **std::auto\_ptr** by **std::unique\_ptr** (introduced in C++11). The transfer of ownership, done by the copy-constructor and the assignment operator, is changed to match **std::unique\_ptr** usage by using explicit calls to **std::move()**. Migration example: ``` -void take_ownership_fn(std::auto_ptr int_ptr); +void take_ownership_fn(std::unique_ptr int_ptr); void f(int x) { - std::auto_ptr a(new int(x)); - std::auto_ptr b; + std::unique_ptr a(new int(x)); + std::unique_ptr b; - b = a; - take_ownership_fn(b); + b = std::move(a); + take_ownership_fn(std::move(b)); } ``` Since **std::move()** is a library function declared in **\** it may be necessary to add this include. The check will add the include directive when necessary. ### Limitations - • If headers modification is not activated or if a header is not allowed to be changed this check will produce broken code (compilation error), where the headers' code will stay unchanged while the code using them will be changed. - • Client code that declares a reference to an **std::auto\_ptr** coming from code that can't be migrated (such as a header coming from a 3rd party library) will produce a compilation error after migration. This is because the type of the reference will be changed to **std::unique\_ptr** but the type returned by the library won't change, binding a reference to **std::unique\_ptr** from an **std::auto\_ptr**. This pattern doesn't make much sense and usually **std::auto\_ptr** are stored by value (otherwise what is the point in using them instead of a reference or a pointer?). ``` // <3rd-party header...> std::auto_ptr get_value(); const std::auto_ptr & get_ref(); // -std::auto_ptr a(get_value()); +std::unique_ptr a(get_value()); // ok, unique_ptr constructed from auto_ptr -const std::auto_ptr & p = get_ptr(); +const std::unique_ptr & p = get_ptr(); // won't compile ``` - • Non-instantiated templates aren't modified. ``` template void f() { std::auto_ptr p; } // only 'f()' (or similar) will trigger the replacement. ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. ### modernize-replace-disallow-copy-and-assign-macro Finds macro expansions of **DISALLOW\_COPY\_AND\_ASSIGN(Type)** and replaces them with a deleted copy constructor and a deleted assignment operator. Before the **delete** keyword was introduced in C++11 it was common practice to declare a copy constructor and an assignment operator as private members. This effectively makes them unusable to the public API of a class. With the advent of the **delete** keyword in C++11 we can abandon the **private** access of the copy constructor and the assignment operator and delete the methods entirely. When running this check on a code like this: ``` class Foo { private: DISALLOW_COPY_AND_ASSIGN(Foo); }; ``` It will be transformed to this: ``` class Foo { private: Foo(const Foo &) = delete; const Foo &operator=(const Foo &) = delete; }; ``` ### Limitations - • Notice that the migration example above leaves the **private** access specification untouched. You might want to run the check modernize-use-equals-delete \<\> to get warnings for deleted functions in private sections. ### Options - **MacroName** A string specifying the macro name whose expansion will be replaced. Default is *DISALLOW\_COPY\_AND\_ASSIGN*. See: \ ### modernize-replace-random-shuffle This check will find occurrences of **std::random\_shuffle** and replace it with **std::shuffle**. In C++17 **std::random\_shuffle** will no longer be available and thus we need to replace it. Below are two examples of what kind of occurrences will be found and two examples of what it will be replaced with. ``` std::vector v; // First example std::random_shuffle(vec.begin(), vec.end()); // Second example std::random_shuffle(vec.begin(), vec.end(), randomFunc); ``` Both of these examples will be replaced with: ``` std::shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()())); ``` The second example will also receive a warning that **randomFunc** is no longer supported in the same way as before so if the user wants the same functionality, the user will need to change the implementation of the **randomFunc**. One thing to be aware of here is that **std::random\_device** is quite expensive to initialize. So if you are using the code in a performance critical place, you probably want to initialize it elsewhere. Another thing is that the seeding quality of the suggested fix is quite poor: **std::mt19937** has an internal state of 624 32-bit integers, but is only seeded with a single integer. So if you require higher quality randomness, you should consider seeding better, for example: ``` std::shuffle(v.begin(), v.end(), []() { std::mt19937::result_type seeds[std::mt19937::state_size]; std::random_device device; std::uniform_int_distribution dist; std::generate(std::begin(seeds), std::end(seeds), [&] { return dist(device); }); std::seed_seq seq(std::begin(seeds), std::end(seeds)); return std::mt19937(seq); }()); ``` ### modernize-return-braced-init-list Replaces explicit calls to the constructor in a return with a braced initializer list. This way the return type is not needlessly duplicated in the function definition and the return statement. ``` Foo bar() { Baz baz; return Foo(baz); } // transforms to: Foo bar() { Baz baz; return {baz}; } ``` ### modernize-shrink-to-fit Replace copy and swap tricks on shrinkable containers with the **shrink\_to\_fit()** method call. The **shrink\_to\_fit()** method is more readable and more effective than the copy and swap trick to reduce the capacity of a shrinkable container. Note that, the **shrink\_to\_fit()** method is only available in C++11 and up. ### modernize-type-traits Converts standard library type traits of the form **traits\<...\>::type** and **traits\<...\>::value** into **traits\_t\<...\>** and **traits\_v\<...\>** respectively. Also suggests converting **std::remove\_cv\_t\** into **std::remove\_cvref\_t\<...\>** when targeting C++20 or above. For example: ``` std::is_integral::value std::is_same::value typename std::add_const::type std::make_signed::type std::remove_cv_t> ``` Would be converted into: ``` std::is_integral_v std::is_same_v std::add_const_t std::make_signed_t std::remove_cvref_t ``` ### Options - **IgnoreMacros** If *true* don't diagnose traits defined in macros. Note: Fixes will never be emitted for code inside of macros. ``` #define IS_SIGNED(T) std::is_signed::value ``` Defaults to *false*. ### Limitations Does not currently diagnose uses of type traits with nested name specifiers (e.g. **std::chrono::is\_clock**, **std::chrono::treat\_as\_floating\_point**). ### modernize-unary-static-assert The check diagnoses any **static\_assert** declaration with an empty string literal and provides a fix-it note to replace the declaration with a single-argument **static\_assert** declaration. The check is only applicable for C++17 and later code. The following code: ``` void f_textless(int a) { static_assert(sizeof(a) <= 10, ""); } ``` is replaced by: ``` void f_textless(int a) { static_assert(sizeof(a) <= 10); } ``` ### modernize-use-auto This check is responsible for using the **auto** type specifier for variable declarations to *improve code readability and maintainability*. For example: ``` std::vector::iterator I = my_container.begin(); // transforms to: auto I = my_container.begin(); ``` The **auto** type specifier will only be introduced in situations where the variable type matches the type of the initializer expression. In other words **auto** should deduce the same type that was originally spelled in the source. However, not every situation should be transformed: ``` int val = 42; InfoStruct &I = SomeObject.getInfo(); // Should not become: auto val = 42; auto &I = SomeObject.getInfo(); ``` In this example using **auto** for builtins doesn't improve readability. In other situations it makes the code less self-documenting impairing readability and maintainability. As a result, **auto** is used only introduced in specific situations described below. ### Iterators Iterator type specifiers tend to be long and used frequently, especially in loop constructs. Since the functions generating iterators have a common format, the type specifier can be replaced without obscuring the meaning of code while improving readability and maintainability. ``` for (std::vector::iterator I = my_container.begin(), E = my_container.end(); I != E; ++I) { } // becomes for (auto I = my_container.begin(), E = my_container.end(); I != E; ++I) { } ``` The check will only replace iterator type-specifiers when all of the following conditions are satisfied: - • The iterator is for one of the standard containers in **std** namespace: - • **array** - • **deque** - • **forward\_list** - • **list** - • **vector** - • **map** - • **multimap** - • **set** - • **multiset** - • **unordered\_map** - • **unordered\_multimap** - • **unordered\_set** - • **unordered\_multiset** - • **queue** - • **priority\_queue** - • **stack** - • The iterator is one of the possible iterator types for standard containers: - • **iterator** - • **reverse\_iterator** - • **const\_iterator** - • **const\_reverse\_iterator** - • In addition to using iterator types directly, typedefs or other ways of referring to those types are also allowed. However, implementation-specific types for which a type like **std::vector\::iterator** is itself a typedef will not be transformed. Consider the following examples: ``` // The following direct uses of iterator types will be transformed. std::vector::iterator I = MyVec.begin(); { using namespace std; list::iterator I = MyList.begin(); } // The type specifier for J would transform to auto since it's a typedef // to a standard iterator type. typedef std::map::const_iterator map_iterator; map_iterator J = MyMap.begin(); // The following implementation-specific iterator type for which // std::vector::iterator could be a typedef would not be transformed. __gnu_cxx::__normal_iterator K = MyVec.begin(); ``` - • The initializer for the variable being declared is not a braced initializer list. Otherwise, use of **auto** would cause the type of the variable to be deduced as **std::initializer\_list**. ### New expressions Frequently, when a pointer is declared and initialized with **new**, the pointee type is written twice: in the declaration type and in the **new** expression. In this case, the declaration type can be replaced with **auto** improving readability and maintainability. ``` TypeName *my_pointer = new TypeName(my_param); // becomes auto *my_pointer = new TypeName(my_param); ``` The check will also replace the declaration type in multiple declarations, if the following conditions are satisfied: - • All declared variables have the same type (i.e. all of them are pointers to the same type). - • All declared variables are initialized with a **new** expression. - • The types of all the new expressions are the same than the pointee of the declaration type. ``` TypeName *my_first_pointer = new TypeName, *my_second_pointer = new TypeName; // becomes auto *my_first_pointer = new TypeName, *my_second_pointer = new TypeName; ``` ### Cast expressions Frequently, when a variable is declared and initialized with a cast, the variable type is written twice: in the declaration type and in the cast expression. In this case, the declaration type can be replaced with **auto** improving readability and maintainability. ``` TypeName *my_pointer = static_cast(my_param); // becomes auto *my_pointer = static_cast(my_param); ``` The check handles **static\_cast**, **dynamic\_cast**, **const\_cast**, **reinterpret\_cast**, functional casts, C-style casts and function templates that behave as casts, such as **llvm::dyn\_cast**, **boost::lexical\_cast** and **gsl::narrow\_cast**. Calls to function templates are considered to behave as casts if the first template argument is explicit and is a type, and the function returns that type, or a pointer or reference to it. ### Limitations - • If the initializer is an explicit conversion constructor, the check will not replace the type specifier even though it would be safe to do so. - • User-defined iterators are not handled at this time. ### Options - **MinTypeNameLength** If the option is set to non-zero (default *5*), the check will ignore type names having a length less than the option value. The option affects expressions only, not iterators. Spaces between multi-lexeme type names (**long int**) are considered as one. If the **RemoveStars** option (see below) is set to *true*, then **\*s** in the type are also counted as a part of the type name. ``` // MinTypeNameLength = 0, RemoveStars=0 int a = static_cast(foo()); // ---> auto a = ... // length(bool *) = 4 bool *b = new bool; // ---> auto *b = ... unsigned c = static_cast(foo()); // ---> auto c = ... // MinTypeNameLength = 5, RemoveStars=0 int a = static_cast(foo()); // ---> int a = ... bool b = static_cast(foo()); // ---> bool b = ... bool *pb = static_cast(foo()); // ---> bool *pb = ... unsigned c = static_cast(foo()); // ---> auto c = ... // length(long int) = 8 long int d = static_cast(foo()); // ---> auto d = ... // MinTypeNameLength = 5, RemoveStars=1 int a = static_cast(foo()); // ---> int a = ... // length(int * * ) = 5 int **pa = static_cast(foo()); // ---> auto pa = ... bool b = static_cast(foo()); // ---> bool b = ... bool *pb = static_cast(foo()); // ---> auto pb = ... unsigned c = static_cast(foo()); // ---> auto c = ... long int d = static_cast(foo()); // ---> auto d = ... ``` - **RemoveStars** If the option is set to *true* (default is *false*), the check will remove stars from the non-typedef pointer types when replacing type names with **auto**. Otherwise, the check will leave stars. For example: ``` TypeName *my_first_pointer = new TypeName, *my_second_pointer = new TypeName; // RemoveStars = 0 auto *my_first_pointer = new TypeName, *my_second_pointer = new TypeName; // RemoveStars = 1 auto my_first_pointer = new TypeName, my_second_pointer = new TypeName; ``` ### modernize-use-bool-literals Finds integer literals which are cast to **bool**. ``` bool p = 1; bool f = static_cast(1); std::ios_base::sync_with_stdio(0); bool x = p ? 1 : 0; // transforms to bool p = true; bool f = true; std::ios_base::sync_with_stdio(false); bool x = p ? true : false; ``` ### Options - **IgnoreMacros** If set to *true*, the check will not give warnings inside macros. Default is *true*. ### modernize-use-constraints Replace **std::enable\_if** with C++20 requires clauses. **std::enable\_if** is a SFINAE mechanism for selecting the desired function or class template based on type traits or other requirements. **enable\_if** changes the meta-arity of the template, and has other adverse side effects \ in the code. C++20 introduces concepts and constraints as a cleaner language provided solution to achieve the same outcome. This check finds some common **std::enable\_if** patterns that can be replaced by C++20 requires clauses. The tool can replace some of these patterns automatically, otherwise, the tool will emit a diagnostic without a replacement. The tool can detect the following **std::enable\_if** patterns - 1\. **std::enable\_if** in the return type of a function - 2\. **std::enable\_if** as the trailing template parameter for function templates Other uses, for example, in class templates for function parameters, are not currently supported by this tool. Other variants such as **boost::enable\_if** are not currently supported by this tool. Below are some examples of code using **std::enable\_if**. ``` // enable_if in function return type template std::enable_if_t only_if_t_has_the_trait() { ... } // enable_if in the trailing template parameter template = 0> void another_version() { ... } template typename std::enable_if::type existing_constraint() requires (T::another_value) { return Obj{}; } template = 0> struct my_class {}; ``` The tool will replace the above code with, ``` // warning: use C++20 requires constraints instead of enable_if [modernize-use-constraints] template int only_if_t_has_the_trait() requires T::some_trait { ... } // warning: use C++20 requires constraints instead of enable_if [modernize-use-constraints] template void another_version() requires T::some_trait { ... } // The tool will emit a diagnostic for the following, but will // not attempt to replace the code. // warning: use C++20 requires constraints instead of enable_if [modernize-use-constraints] template typename std::enable_if::type existing_constraint() requires (T::another_value) { return Obj{}; } // The tool will not emit a diagnostic or attempt to replace the code. template = 0> struct my_class {}; ``` **Note:** System headers are not analyzed by this check. ### modernize-use-default This check has been renamed to modernize-use-equals-default \<\>. ### modernize-use-default-member-init This check converts constructors' member initializers into the new default member initializers in C++11. Other member initializers that match the default member initializer are removed. This can reduce repeated code or allow use of '= default'. ``` struct A { A() : i(5), j(10.0) {} A(int i) : i(i), j(10.0) {} int i; double j; }; // becomes struct A { A() {} A(int i) : i(i) {} int i{5}; double j{10.0}; }; ``` **Note:** Only converts member initializers for built-in types, enums, and pointers. The *readability-redundant-member-init* check will remove redundant member initializers for classes. ### Options - **UseAssignment** If this option is set to *true* (default is *false*), the check will initialize members with an assignment. For example: ``` struct A { A() {} A(int i) : i(i) {} int i = 5; double j = 10.0; }; ``` - **IgnoreMacros** If this option is set to *true* (default is *true*), the check will not warn about members declared inside macros. - **IgnoreNonVisibleReferences** If this option is set to *true* (default is *true*), the check will not warn about member initializers that refer to declarations that would not be visible from the default member initializer created by the fix-it. If set to *false*, the check will warn about these cases without emitting fix-its. ### modernize-use-designated-initializers Finds initializer lists for aggregate types which could be written as designated initializers instead. With plain initializer lists, it is very easy to introduce bugs when adding new fields in the middle of a struct or class type. The same confusion might arise when changing the order of fields. C++20 supports the designated initializer syntax for aggregate types. By applying it, we can always be sure that aggregates are constructed correctly, because every variable being initialized is referenced by its name. Example: ``` struct S { int i, j; }; ``` is an aggregate type that should be initialized as ``` S s{.i = 1, .j = 2}; ``` instead of ``` S s{1, 2}; ``` which could easily become an issue when **i** and **j** are swapped in the declaration of **S**. Even when compiling in a language version older than C++20, depending on your compiler, designated initializers are potentially supported. Therefore, the check is by default restricted to C99/C++20 and above. Check out the options *-Wc99-designator* to get support for mixed designators in initializer list in C and *-Wc++20-designator* for support of designated initializers in older C++ language modes. ### Options - **IgnoreMacros** The value *false* specifies that components of initializer lists expanded from macros are not checked. The default value is *true*. - **IgnoreSingleElementAggregates** The value *false* specifies that even initializers for aggregate types with only a single element should be checked. The default value is *true*. **std::array** initializations are always excluded, as the type is a standard library abstraction and not intended to be initialized with designated initializers. - **RestrictToPODTypes** The value *true* specifies that only Plain Old Data (POD) types shall be checked. This makes the check applicable to even older C++ standards. The default value is *false*. - **StrictCStandardCompliance** When set to *false*, the check will not restrict itself to C99 and above. The default value is *true*. - **StrictCppStandardCompliance** When set to *false*, the check will not restrict itself to C++20 and above. The default value is *true*. ### modernize-use-emplace The check flags insertions to an STL-style container done by calling the **push\_back**, **push**, or **push\_front** methods with an explicitly-constructed temporary of the container element type. In this case, the corresponding **emplace** equivalent methods result in less verbose and potentially more efficient code. Right now the check doesn't support **insert**. It also doesn't support **insert** functions for associative containers because replacing **insert** with **emplace** may result in speed regression \, but it might get support with some addition flag in the future. The **ContainersWithPushBack**, **ContainersWithPush**, and **ContainersWithPushFront** options are used to specify the container types that support the **push\_back**, **push**, and **push\_front** operations respectively. The default values for these options are as follows: - • **ContainersWithPushBack**: **std::vector**, **std::deque**, and **std::list**. - • **ContainersWithPush**: **std::stack**, **std::queue**, and **std::priority\_queue**. - • **ContainersWithPushFront**: **std::forward\_list**, **std::list**, and **std::deque**. This check also reports when an **emplace**-like method is improperly used, for example using **emplace\_back** while also calling a constructor. This creates a temporary that requires at best a move and at worst a copy. Almost all **emplace**-like functions in the STL are covered by this, with **try\_emplace** on **std::map** and **std::unordered\_map** being the exception as it behaves slightly differently than all the others. More containers can be added with the **EmplacyFunctions** option, so long as the container defines a **value\_type** type, and the **emplace**-like functions construct a **value\_type** object. Before: ``` std::vector v; v.push_back(MyClass(21, 37)); v.emplace_back(MyClass(21, 37)); std::vector> w; w.push_back(std::pair(21, 37)); w.push_back(std::make_pair(21L, 37L)); w.emplace_back(std::make_pair(21L, 37L)); ``` After: ``` std::vector v; v.emplace_back(21, 37); v.emplace_back(21, 37); std::vector> w; w.emplace_back(21, 37); w.emplace_back(21L, 37L); w.emplace_back(21L, 37L); ``` By default, the check is able to remove unnecessary **std::make\_pair** and **std::make\_tuple** calls from **push\_back** calls on containers of **std::pair** and **std::tuple**. Custom tuple-like types can be modified by the **TupleTypes** option; custom make functions can be modified by the **TupleMakeFunctions** option. The other situation is when we pass arguments that will be converted to a type inside a container. Before: ``` std::vector > v; v.push_back("abc"); ``` After: ``` std::vector > v; v.emplace_back("abc"); ``` In some cases the transformation would be valid, but the code wouldn't be exception safe. In this case the calls of **push\_back** won't be replaced. ``` std::vector> v; v.push_back(std::unique_ptr(new int(0))); auto *ptr = new int(1); v.push_back(std::unique_ptr(ptr)); ``` This is because replacing it with **emplace\_back** could cause a leak of this pointer if **emplace\_back** would throw exception before emplacement (e.g. not enough memory to add a new element). For more info read item 42 - "Consider emplacement instead of insertion." of Scott Meyers "Effective Modern C++". The default smart pointers that are considered are **std::unique\_ptr**, **std::shared\_ptr**, **std::auto\_ptr**. To specify other smart pointers or other classes use the **SmartPointers** option. Check also doesn't fire if any argument of the constructor call would be: - • a bit-field (bit-fields can't bind to rvalue/universal reference) - • a **new** expression (to avoid leak) - • if the argument would be converted via derived-to-base cast. This check requires C++11 or higher to run. ### Options - **ContainersWithPushBack** Semicolon-separated list of class names of custom containers that support **push\_back**. - **ContainersWithPush** Semicolon-separated list of class names of custom containers that support **push**. - **ContainersWithPushFront** Semicolon-separated list of class names of custom containers that support **push\_front**. - **IgnoreImplicitConstructors** When *true*, the check will ignore implicitly constructed arguments of **push\_back**, e.g. ``` std::vector v; v.push_back("a"); // Ignored when IgnoreImplicitConstructors is `true`. ``` Default is *false*. - **SmartPointers** Semicolon-separated list of class names of custom smart pointers. - **TupleTypes** Semicolon-separated list of **std::tuple**-like class names. - **TupleMakeFunctions** Semicolon-separated list of **std::make\_tuple**-like function names. Those function calls will be removed from **push\_back** calls and turned into **emplace\_back**. - **EmplacyFunctions** Semicolon-separated list of containers without their template parameters and some **emplace**-like method of the container. Example: **vector::emplace\_back**. Those methods will be checked for improper use and the check will report when a temporary is unnecessarily created. All STL containers with such member functions are supported by default. ### Example ``` std::vector> x; x.push_back(MakeMyTuple(1, false, 'x')); x.emplace_back(MakeMyTuple(1, false, 'x')); ``` transforms to: ``` std::vector> x; x.emplace_back(1, false, 'x'); x.emplace_back(1, false, 'x'); ``` when **TupleTypes** is set to **MyTuple**, **TupleMakeFunctions** is set to **MakeMyTuple**, and **EmplacyFunctions** is set to **vector::emplace\_back**. ### modernize-use-equals-default This check replaces default bodies of special member functions with **=** **default;**. The explicitly defaulted function declarations enable more opportunities in optimization, because the compiler might treat explicitly defaulted functions as trivial. ``` struct A { A() {} ~A(); }; A::~A() {} // becomes struct A { A() = default; ~A(); }; A::~A() = default; ``` **Note:** Move-constructor and move-assignment operator are not supported yet. ### Options - **IgnoreMacros** If set to *true*, the check will not give warnings inside macros and will ignore special members with bodies contain macros or preprocessor directives. Default is *true*. ### modernize-use-equals-delete Identifies unimplemented private special member functions, and recommends using **= delete** for them. Additionally, it recommends relocating any deleted member function from the **private** to the **public** section. Before the introduction of C++11, the primary method to effectively "erase" a particular function involved declaring it as **private** without providing a definition. This approach would result in either a compiler error (when attempting to call a private function) or a linker error (due to an undefined reference). However, subsequent to the advent of C++11, a more conventional approach emerged for achieving this purpose. It involves flagging functions as **= delete** and keeping them in the **public** section of the class. To prevent false positives, this check is only active within a translation unit where all other member functions have been implemented. The check will generate partial fixes by introducing **= delete**, but the user is responsible for manually relocating functions to the **public** section. ``` // Example: bad class A { private: A(const A&); A& operator=(const A&); }; // Example: good class A { public: A(const A&) = delete; A& operator=(const A&) = delete; }; ``` - **IgnoreMacros** If this option is set to *true* (default is *true*), the check will not warn about functions declared inside macros. ### modernize-use-integer-sign-comparison Replace comparisons between signed and unsigned integers with their safe C++20 **std::cmp\_\*** alternative, if available. The check provides a replacement only for C++20 or later, otherwise it highlights the problem and expects the user to fix it manually. Examples of fixes created by the check: ``` unsigned int func(int a, unsigned int b) { return a == b; } ``` becomes ``` #include unsigned int func(int a, unsigned int b) { return std::cmp_equal(a, b); } ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **EnableQtSupport** Makes C++17 **q20::cmp\_\*** alternative available for Qt-based applications. Default is *false*. ### modernize-use-nodiscard Adds **\[\[nodiscard\]\]** attributes (introduced in C++17) to member functions in order to highlight at compile time which return values should not be ignored. Member functions need to satisfy the following conditions to be considered by this check: - • no **\[\[nodiscard\]\]**, **\[\[noreturn\]\]**, **\_\_attribute\_\_((warn\_unused\_result))**, **\[\[clang::warn\_unused\_result\]\]** nor **\[\[gcc::warn\_unused\_result\]\]** attribute, - • non-void return type, - • non-template return types, - • const member function, - • non-variadic functions, - • no non-const reference parameters, - • no pointer parameters, - • no template parameters, - • no template function parameters, - • not be a member of a class with mutable member variables, - • no Lambdas, - • no conversion functions. Such functions have no means of altering any state or passing values other than via the return type. Unless the member functions are altering state via some external call (e.g. I/O). ### Example ``` bool empty() const; bool empty(int i) const; ``` transforms to: ``` [[nodiscard]] bool empty() const; [[nodiscard]] bool empty(int i) const; ``` ### Options - **ReplacementString** Specifies a macro to use instead of **\[\[nodiscard\]\]**. This is useful when maintaining source code that needs to compile with a pre-C++17 compiler. ### Example ``` bool empty() const; bool empty(int i) const; ``` transforms to: ``` NO_DISCARD bool empty() const; NO_DISCARD bool empty(int i) const; ``` if the **ReplacementString** option is set to *NO\_DISCARD*. **Note:** If the **ReplacementString** is not a C++ attribute, but instead a macro, then that macro must be defined in scope or the fix-it will not be applied. **Note:** For alternative **\_\_attribute\_\_** syntax options to mark functions as **\[\[nodiscard\]\]** in non-c++17 source code. See \ ### modernize-use-noexcept This check replaces deprecated dynamic exception specifications with the appropriate noexcept specification (introduced in C++11). By default this check will replace **throw()** with **noexcept**, and **throw(\\[,...\])** or **throw(...)** with **noexcept(false)**. ### Example ``` void foo() throw(); void bar() throw(int) {} ``` transforms to: ``` void foo() noexcept; void bar() noexcept(false) {} ``` ### Options - **ReplacementString** Users can use **ReplacementString** \<#cmdoption-arg-ReplacementString\> to specify a macro to use instead of **noexcept**. This is useful when maintaining source code that uses custom exception specification marking other than **noexcept**. Fix-it hints will only be generated for non-throwing specifications. ### Example ``` void bar() throw(int); void foo() throw(); ``` transforms to: ``` void bar() throw(int); // No fix-it generated. void foo() NOEXCEPT; ``` if the **ReplacementString** \<#cmdoption-arg-ReplacementString\> option is set to *NOEXCEPT*. - **UseNoexceptFalse** Enabled by default, disabling will generate fix-it hints that remove throwing dynamic exception specs, e.g., **throw(\)**, completely without providing a replacement text, except for destructors and delete operators that are **noexcept(true)** by default. ### Example ``` void foo() throw(int) {} struct bar { void foobar() throw(int); void operator delete(void *ptr) throw(int); void operator delete[](void *ptr) throw(int); ~bar() throw(int); } ``` transforms to: ``` void foo() {} struct bar { void foobar(); void operator delete(void *ptr) noexcept(false); void operator delete[](void *ptr) noexcept(false); ~bar() noexcept(false); } ``` if the **UseNoexceptFalse** option is set to *false*. ### modernize-use-nullptr The check converts the usage of null pointer constants (e.g. **NULL**, **0**) to use the new C++11 and C23 **nullptr** keyword. ### Example ``` void assignment() { char *a = NULL; char *b = 0; char c = 0; } int *ret_ptr() { return 0; } ``` transforms to: ``` void assignment() { char *a = nullptr; char *b = nullptr; char c = 0; } int *ret_ptr() { return nullptr; } ``` ### Options - **IgnoredTypes** Semicolon-separated list of regular expressions to match pointer types for which implicit casts will be ignored. Default value: *std::\_CmpUnspecifiedParam::;^std::\_\_cmp\_cat::\_\_unspec*. - **NullMacros** Comma-separated list of macro names that will be transformed along with **NULL**. By default this check will only replace the **NULL** macro and will skip any similar user-defined macros. ### Example ``` #define MY_NULL (void*)0 void assignment() { void *p = MY_NULL; } ``` transforms to: ``` #define MY_NULL NULL void assignment() { int *p = nullptr; } ``` if the **NullMacros** option is set to **MY\_NULL**. ### modernize-use-override Adds **override** (introduced in C++11) to overridden virtual functions and removes **virtual** from those functions as it is not required. **virtual** on non base class implementations was used to help indicate to the user that a function was virtual. C++ compilers did not use the presence of this to signify an overridden function. In C++11 **override** and **final** keywords were introduced to allow overridden functions to be marked appropriately. Their presence allows compilers to verify that an overridden function correctly overrides a base class implementation. This can be useful as compilers can generate a compile time error when: - • The base class implementation function signature changes. - • The user has not created the override with the correct signature. ### Options - **IgnoreDestructors** If set to *true*, this check will not diagnose destructors. Default is *false*. - **IgnoreTemplateInstantiations** If set to *true*, instructs this check to ignore virtual function overrides that are part of template instantiations. Default is *false*. - **AllowOverrideAndFinal** If set to *true*, this check will not diagnose **override** as redundant with **final**. This is useful when code will be compiled by a compiler with warning/error checking flags requiring **override** explicitly on overridden members, such as **gcc -Wsuggest-override**/**gcc -Werror=suggest-override**. Default is *false*. - **AllowVirtualAndOverride** If set to *true*, this check will not diagnose **virtual** as redundant with **override**. Default is *false*. - **OverrideSpelling** Specifies a macro to use instead of **override**. This is useful when maintaining source code that also needs to compile with a pre-C++11 compiler. - **FinalSpelling** Specifies a macro to use instead of **final**. This is useful when maintaining source code that also needs to compile with a pre-C++11 compiler. **Note:** For more information on the use of **override** see \ ### modernize-use-ranges Detects calls to standard library iterator algorithms that could be replaced with a ranges version instead. ### Example ``` auto Iter1 = std::find(Items.begin(), Items.end(), 0); auto NewEnd = std::unique(Items.begin(), Items.end()); auto AreSame = std::equal(Items1.cbegin(), Items1.cend(), std::begin(Items2), std::end(Items2)); ``` Transforms to: ``` auto Iter1 = std::ranges::find(Items, 0); auto NewEnd = std::ranges::unique(Items).begin(); auto AreSame = std::ranges::equal(Items1, Items2); ``` ### Supported algorithms Calls to the following std library algorithms are checked: **std::adjacent\_find**, **std::all\_of**, **std::any\_of**, **std::binary\_search**, **std::copy\_backward**, **std::copy\_if**, **std::copy**, **std::destroy**, **std::equal\_range**, **std::equal**, **std::fill**, **std::find\_end**, **std::find\_if\_not**, **std::find\_if**, **std::find**, **std::for\_each**, **std::generate**, **std::includes**, **std::inplace\_merge**, **std::iota**, **std::is\_heap\_until**, **std::is\_heap**, **std::is\_partitioned**, **std::is\_permutation**, **std::is\_sorted\_until**, **std::is\_sorted**, **std::lexicographical\_compare**, **std::lower\_bound**, **std::make\_heap**, **std::max\_element**, **std::merge**, **std::min\_element**, **std::minmax\_element**, **std::mismatch**, **std::move\_backward**, **std::move**, **std::next\_permutation**, **std::none\_of**, **std::partial\_sort\_copy**, **std::partition\_copy**, **std::partition\_point**, **std::partition**, **std::pop\_heap**, **std::prev\_permutation**, **std::push\_heap**, **std::remove\_copy\_if**, **std::remove\_copy**, **std::remove**, **std::remove\_if**, **std::replace\_if**, **std::replace**, **std::reverse\_copy**, **std::reverse**, **std::rotate**, **std::rotate\_copy**, **std::sample**, **std::search**, **std::set\_difference**, **std::set\_intersection**, **std::set\_symmetric\_difference**, **std::set\_union**, **std::shift\_left**, **std::shift\_right**, **std::sort\_heap**, **std::sort**, **std::stable\_partition**, **std::stable\_sort**, **std::transform**, **std::uninitialized\_copy**, **std::uninitialized\_default\_construct**, **std::uninitialized\_fill**, **std::uninitialized\_move**, **std::uninitialized\_value\_construct**, **std::unique\_copy**, **std::unique**, **std::upper\_bound**. Note: some range algorithms for **vector\** require C++23 because it uses proxy iterators. ### Reverse Iteration If calls are made using reverse iterators on containers, The code will be fixed using the **std::views::reverse** adaptor. ``` auto AreSame = std::equal(Items1.rbegin(), Items1.rend(), std::crbegin(Items2), std::crend(Items2)); ``` Transforms to: ``` auto AreSame = std::ranges::equal(std::views::reverse(Items1), std::views::reverse(Items2)); ``` ### Options - **IncludeStyle** A string specifying which include-style is used, *llvm* or *google*. Default is *llvm*. - **UseReversePipe** When *true* (default *false*), fixes which involve reverse ranges will use the pipe adaptor syntax instead of the function syntax. ``` std::find(Items.rbegin(), Items.rend(), 0); ``` Transforms to: ``` std::ranges::find(Items | std::views::reverse, 0); ``` ### modernize-use-scoped-lock Finds uses of **std::lock\_guard** and suggests replacing them with C++17's alternative **std::scoped\_lock**. Fix-its are provided for single declarations of **std::lock\_guard** and warning is emitted for multiple declarations of **std::lock\_guard** or **std::scoped\_lock** that can be replaced with a single declaration of **std::scoped\_lock**. ### Examples Single **std::lock\_guard** declaration: ``` std::mutex M; std::lock_guard L(M); ``` Transforms to: ``` std::mutex M; std::scoped_lock L(M); ``` Single **std::lock\_guard** declaration with **std::adopt\_lock**: ``` std::mutex M; std::lock(M); std::lock_guard L(M, std::adopt_lock); ``` Transforms to: ``` std::mutex M; std::lock(M); std::scoped_lock L(std::adopt_lock, M); ``` Multiple consecutive lock declarations only emit warnings: ``` std::mutex M1, M2; std::lock(M1, M2); std::lock_guard Lock1(M1, std::adopt_lock); // warning: use single 'std::scoped_lock' instead of multiple locks std::scoped_lock Lock2(M2, std::adopt_lock); // note: additional 'std::scoped_lock' declared here ``` ### Limitations The check will not emit warnings if **std::lock\_guard** is used implicitly via **template** parameter: ``` template