FreeBSD Manual Pages
EXTRACLANGTOOLS(1) Extra Clang Tools EXTRACLANGTOOLS(1) 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 11.0.0 RELEASE NOTES • Introduction • What's New in Extra Clang Tools 11.0.0? • Improvements to clangd • Performance • Selecting and targeting • Diagnostics • Refactorings • Code completion • Go-to-definition • Hover • Highlighting • Language support • System integration • Miscellaneous • Improvements to clang-tidy • New module • New checks • New check aliases • Changes in existing checks • Renamed checks • Other improvements Written by the LLVM Team Introduction This document contains the release notes for the Extra Clang Tools, part of the Clang release 11.0.0. 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 down- loaded 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. What's New in Extra Clang Tools 11.0.0? 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. Improvements to clangd Performance • Eliminated long delays after adding/removing includes ("async pream- bles") • Faster indexing • Less memory used to index headers used by open files ("dynamic in- dex") • Many requests are implicitly cancelled rather than queued when the file is edited, preventing a backlog • Background indexing can be selectively disabled per-path through con- fig Selecting and targeting • Improved understanding and selection around broken code ("recovery AST") • Operations like "go-to-definition" will target things on the left of the cursor, if there is nothing eligible on the right. • Arguments to assert()-like macros can be properly selected. Diagnostics • When a header is saved, diagnostics for files that use it are up- dated. • Calls std::make_unique produce diagnostics for the constructor call. (Template functions in general are not expanded for performance rea- sons). • Diagnostics update more quickly for files that build quickly (no 500ms delay) • Automatic fixes are offered even when they affect macro arguments. • Warnings from included headers are not shown (but errors still are). • A handful of high-quality clang-tidy checks are enabled by default: • readability-misleading-indentation, • readability-deleted-default, • bugprone-integer-division, • bugprone-sizeof-expression, • bugprone-suspicious-missing-comma, • bugprone-unused-raii, • bugprone-unused-return-value, • misc-unused-using-decls, • misc-unused-alias-decls, • misc-definitions-in-headers Refactorings • Rename applies across the project, using the index. • Accuracy of rename improved in many places. • New refactoring: add using declaration for qualified name. • New refactoring: move function definition out-of-line. Code completion • Function call parentheses are not inserted if they already exist. • Completion of #include filenames triggers earlier (after <, ", and /) and is less aggressive about replacing existing text. • Documentation is reflowed in the same way as on hover. Go-to-definition • Dependent names in templates may be heuristically resolved • Identifiers in comments may be resolved using other occurrences in the file or in the index. • Go-to-definition on an override or final specifier jumps to the over- ridden method. Hover • Expressions passed as function arguments show parameter name, conver- sions etc. • Members now include the access specifier in the displayed declara- tion. • Classes and fields show memory layout information (size and offset). • Somewhat improved understanding of formatting in documentation com- ments. • Trivial inline getters/setters are implicitly documented as such. Highlighting • The semanticTokens protocol from LSP 3.16 is supported. (Only token types are exposed, no modifiers yet). • The non-standard textDocument/semanticHighlighting notification is deprecated and will be removed in clangd 12. • Placing the cursor on a control flow keyword highlights related flow (e.g. break -> for). Language support • clangd features now work inside templates on windows. (MSVC-compati- ble delayed-template-parsing is no longer used). • Objective-C properties can be targeted and cross-references are in- dexed. • Field names in designated initializers (C++20) can be targeted, and code completion works in many cases. • goto labels: go-to-defintion, cross-references, and rename all work. • Concepts (C++20): go-to-definition on concept names, and some limited code completion support for concept members. System integration • The project index is now written to $PROJECT/.cache/clangd/index. $PROJECT/.clangd is now expected to be a configuration file. Old $PROJECT/.clangd directories can safely be deleted. We recommend including both .cache/ and .clangd/ (with trailing slash) in .gitignore, for backward-compatibility with earlier re- leases of clangd. • For non-project files (those without a compilation database), the in- dex location better reflects OS conventions: • %LocalAppData%\clangd\index on Windows • $(getconf DARWIN_USER_CACHE_DIR)/clangd/index on Mac • $XDG_CACHE_HOME/clangd/index or ~/.cache/clangd/index on others Old ~/.clangd/index directories can safely be deleted. • clangd now reads configuration from .clangd files inside your project, and from a user configuration file in an OS-specific loca- tion: • %LocalAppData%\clangd\config.yaml on Windows • ~/Library/Preferences/clangd/config.yaml on Mac • $XDG_CONFIG_HOME/clangd/config.yaml or ~/.config/clangd/config.yaml on others See clangd configuration format. • clangd will search for compilation databases (compile_commands.json) in a build/ subdirectory, as well as in the project root. This fol- lows CMake conventions, avoiding the need for a symlink in many cases. • Compile flags can be selectively modified per-path, using configura- tion. • Improved filtering of unhelpful compile flags (such as those relating to pre-compiled headers). • Improved detection of standard library headers location. Miscellaneous • Background indexing status is reported using LSP 3.15 progress events (window/workDoneProgress/create). • Infrastructure for gathering internal metrics. (Off by default, set $CLANGD_METRICS to generate a named CSV file). • Document versions are now tracked, version is reported along with di- agnostics. • Too many stability and correctness fixes to mention. Improvements to clang-tidy New module • New module llvmlibc. This module contains checks related to the LLVM-libc coding stan- dards. New checks • New abseil-string-find-str-contains check. Finds s.find(...) == string::npos comparisons (for various string-like types) and suggests replacing with absl::StrContains(). • New bugprone-misplaced-pointer-arithmetic-in-alloc check. 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. • New bugprone-no-escape check. Finds pointers with the noescape attribute that are captured by an asynchronously-executed block. • New bugprone-reserved-identifier check. Checks for usages of identifiers reserved for use by the implementa- tion. • New bugprone-spuriously-wake-up-functions check. 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. • New bugprone-suspicious-include check. Finds cases where an include refers to what appears to be an imple- mentation file, which often leads to hard-to-track-down ODR viola- tions, and diagnoses them. • New cert-oop57-cpp check. Flags use of the C standard library functions memset, memcpy and mem- cmp and similar derivatives on non-trivial types. • New cppcoreguidelines-avoid-non-const-global-variables check. Finds non-const global variables as described in check I.2 of C++ Core Guidelines. • New llvmlibc-callee-namespace check. Checks all calls resolve to functions within __llvm_libc namespace. • New llvmlibc-implementation-in-namespace check. Checks all llvm-libc implementation is within the correct namespace. • New llvmlibc-restrict-system-libc-headers check. Finds includes of system libc headers not provided by the compiler within llvm-libc implementations. • New misc-no-recursion check. Finds recursive functions and diagnoses them. • New modernize-replace-disallow-copy-and-assign-macro check. Finds macro expansions of DISALLOW_COPY_AND_ASSIGN and replaces them with a deleted copy constructor and a deleted assignment operator. • New objc-dealloc-in-category check. Finds implementations of -dealloc in Objective-C categories. • New objc-nsinvocation-argument-lifetime check. Finds calls to NSInvocation methods under ARC that don't have proper argument object lifetimes. • New readability-use-anyofallof check. Finds range-based for loops that can be replaced by a call to std::any_of or std::all_of. New check aliases • New alias cert-con36-c to bugprone-spuriously-wake-up-functions was added. • New alias cert-con54-cpp to bugprone-spuriously-wake-up-functions was added. • New alias cert-dcl37-c to bugprone-reserved-identifier was added. • New alias cert-dcl51-cpp to bugprone-reserved-identifier was added. • New alias cert-str34-c to bugprone-signed-char-misuse was added. • New alias llvm-else-after-return to readability-else-after-return was added. Changes in existing checks • Improved performance-faster-string-find check. Now checks std::basic_string_view by default. • Improved readability-else-after-return check now supports a WarnOn- ConditionVariables option to control whether to refactor condition variables where possible. • Improved readability-identifier-naming check. Now able to rename member references in class template definitions with explicit access. • Improved readability-redundant-string-init check now supports a StringNames option enabling its application to custom string classes. The check now detects in class initializers and constructor initial- izers which are deemed to be redundant. • Checks supporting the HeaderFileExtensions flag now support ; as a delimiter in addition to ,, with the latter being deprecated as of this release. This simplifies how one specifies the options on the command line: --config="{CheckOptions: [{ key: HeaderFileExtensions, value: h;;hpp;hxx }]}" • Improved readability-qualified-auto check now supports a AddConstTo- Qualified to enable adding const qualifiers to variables typed with auto * and auto &. Renamed checks • The 'fuchsia-restrict-system-headers' check was renamed to portability-restrict-system-includes Other improvements • For run-clang-tidy.py add option to use alpha checkers from clang-an- alyzer. CLANG-TIDY Contents • Clang-Tidy • Using clang-tidy • Suppressing Undesired Diagnostics See also: Clang-Tidy Checks abseil-duration-addition Check 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 in- stead 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 Du- ration 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<int>(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<double>(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 infor- mation 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 re- turns 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 in- teger 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 super- fluous 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<double>(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 func- tion. This check also looks for arguments with a zero value and sug- gests 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::Du- ration 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 infer- ence 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 oc- cur 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 con- version. 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 de- limiter is a single character string literal and replaces with a char- acter. 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))) { subl.. title:: clang-tidy - abseil-no-internal-dependencies 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 beaucse its an implementation detail. They cannot friend it, include it, you mention it or refer to it in any way. Doing so vio- lates Abseil's compatibility guidelines and may result in breakage. See https://abseil.io/about/compatibility 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 ar- gument for a functor. abseil-string-find-startswith Checks whether a std::string::find() result is compared with 0, and suggests replacing with absl::StartsWith(). This is both a readability and performance issue. string s = "..."; if (s.find("Hello World") == 0) { /* do something */ } becomes string s = "..."; if (absl::StartsWith(s, "Hello World")) { /* do something */ } Options StringLikeClasses Semicolon-separated list of names of string-like classes. By de- fault only std::basic_string is considered. The list of methods to 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 StringLike- Classes 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 de- fault 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 do- main. 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 a 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-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<float> 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<int> a; absl::Duration d = absl::Milliseconds(a); d *= a; becomes std::atomic<int> a; absl::Duration d = absl::Milliseconds(static_cast<int64_t>(a)); d *= static_cast<int64_t>(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 float- ing-point type. 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 do- main. 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 sensi- tive 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 ino- tify_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 us- ing the O_CLOEXEC flag. Without that flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux do- main, 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 checks 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 descrip- tor can be leaked to a child process, potentially into a lower-privi- leged 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 do- main. 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 argu- ment 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. } 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 behaviour. auto str = boost::lexical_cast<std::string>(42); auto wstr = boost::lexical_cast<std::wstring>(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. 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. Options StrictMode When zero (default value), the check will ignore leading and trailing underscores and case when comparing names -- otherwise they are taken into account. IgnoreSingleArgument When true, the check will ignore the single argument. CommentBoolLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the boolean literal argument. Before: void foo(bool TurnKey, bool PressButton); foo(true, false); After: void foo(bool TurnKey, bool PressButton); foo(/*TurnKey=*/true, /*PressButton=*/false); CommentIntegerLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the integer literal argument. Before: void foo(int MeaningOfLife); foo(42); After: void foo(int MeaningOfLife); foo(/*MeaningOfLife=*/42); CommentFloatLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the float/double literal argu- ment. Before: void foo(float Pi); foo(3.14159); After: void foo(float Pi); foo(/*Pi=*/3.14159); CommentStringLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the string literal argument. 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"); CommentCharacterLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the character literal argument. Before: void foo(char *Character); foo('A'); After: void foo(char *Character); foo(/*Character=*/'A'); CommentUserDefinedLiterals When true, the check will add argument comments in the format /*ParameterName=*/ right before the user defined literal argu- ment. 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); CommentNullPtrs When true, the check will add argument comments in the format /*ParameterName=*/ right before the nullptr literal argument. Before: void foo(A* Value); foo(nullptr); After: void foo(A* Value); foo(/*Value=*/nullptr); bugprone-assert-side-effect Finds assert() with side effect. The condition of assert() is evaluated only in debug builds so a condi- tion 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. 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. bugprone-bad-signal-to-kill-thread Finds pthread_kill function calls when a thread is terminated by rais- ing SIGTERM signal and the signal kills the entire process, not just the individual thread. Use any signal except SIGTERM. This check corresponds to the CERT C Coding Standard rule POS44-C. Do not use signals to terminate threads. 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 re- peated 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 con- ditional statement; otherwise the issue can be solved by fixing the branch that is handled incorrectly. The check also detects repeated branches in longer if/else if/else chains where it would be even harder to notice the problem. 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. 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 identi- cal only after preprocession. 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; }; 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 X4 : public Copyable { X4(const X4 &other) : Copyable() {} // other is missing }; The check also suggests a fix-its in some cases. bugprone-dangling-handle Detect dangling references in value handles like std::experimen- tal::string_view. These dangling references can be a result of con- structing handles from temporary values, where the temporary is de- stroyed soon after the handle is created. Examples: string_view View = string(); // View will dangle. string A; View = A + "A"; // still dangle. vector<string_view> 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; } Options HandleClasses A semicolon-separated list of class names that should be treated as handles. By default only std::experimental::ba- sic_string_view is considered. 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 sta- tic 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 synchro- nization, 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 prob- lems. 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-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 * 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 throw- ing way. Non throwing swap() operations are also used to create move operations. A throwing main() function also results in unexpected ter- mination. WARNING! This check may be expensive on large source files. Options 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. bugprone-fold-init-type The check flags type mismatches in folds like std::accumulate that might result in loss of precision. std::accumulate folds an input range into an initial value using the type of the latter, with opera- tor+ by default. This can cause loss of precision through: • Truncation: The following code uses a floating point range and an int initial value, so trucation will happen at every application of oper- ator+ and the result will be 0, which might not be what the user ex- pected. 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); 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 name- space. 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 per- fect 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<typename T> explicit Person(T&& n) {} // C2: perfect forwarding ctor with parameter default value template<typename T> explicit Person(T&& n, int x = 1) {} // C3: perfect forwarding ctor guarded with enable_if template<typename T, typename X = enable_if_t<is_special<T>,void>> 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 that are guarded with an enable_if, assuming the programmer was aware of the possible hiding. Background For deciding whether a constructor is guarded with enable_if, we con- sider the default values of the type parameters and the types of the constructor parameters. If any part of these types is std::enable_if or std::enable_if_t, we assume the constructor is guarded. 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<int> xs; ... xs.erase(std::remove(xs.begin(), xs.end(), 10)); Call the two-argument overload of erase() to remove the subrange: std::vector<int> xs; ... xs.erase(std::remove(xs.begin(), xs.end(), 10), xs.end()); bugprone-incorrect-roundings Checks the usage of patterns known to produce incorrect rounding. Pro- grammers 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 nega- tive 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 prob- lem). 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 dif- ferent 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 program- mer. 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-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 bugprone-macro-parentheses Finds macros that can have unexpected behaviour due to missing paren- theses. Macros are expanded by the preprocessor as-is. As a result, there can be unexpected behaviour; 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 sur- round it with parentheses. This ensures that the macro result is evalu- ated 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 calcu- lated properly. bugprone-macro-repeated-side-effects Checks for repeated argument with side effects in macros. 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[] opera- tor in C++. The check detects error cases even if one of these func- tions (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(), real- loc(), 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. Other- wise 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 re- sult 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 non-zero, enables detection of implicit casts. Default is non-zero. bugprone-move-forwarding-reference Warns if std::move is called on a forwarding reference, for example: template <typename T> void foo(T&& t) { bar(std::move(t)); } Forwarding references should typically be passed to std::forward in- stead 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 de- duced function template argument.) In this example, the suggested fix would be bar(std::forward<T>(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 inde- terminate 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 ar- gument 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-multiple-statement-macro Detect multiple statement macros that are used in unbraced condition- als. Only the first statement of the macro will be inside the condi- tional 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-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 at- tribute. void foo(__attribute__((noescape)) int *p) { dispatch_async(queue, ^{ *p = 123; }); }); bugprone-not-null-terminated-result Finds function calls where it is possible to cause a not null-termi- nated 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 behaviour 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 ter- minator. static char *stringCpy(const std::string &str) { char *result = reinterpret_cast<char *>(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<char *>(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 fol- lowing 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 AreSafeFunc- tionsAvailable is set to Yes, y or non-zero and it is possible to ob- tain 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 analysed 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 ar- ray 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 capac- ity. Rewrite based on the length of the source string • If the given length is strlen(source) or equal length of this expres- sion 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' charac- ters, 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 re- spectively (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 incre- mented 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 An integer non-zero value specifying if the target environment is considered to implement '_s' suffixed memory and string han- dler functions which are safer than older versions (e.g. 'mem- cpy_s()'). The default value is 1. 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-posix-return Checks if any calls to pthread_* or posix_* functions (except posix_openpt) expect negative return values. These functions return ei- ther 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-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 implementa- tion. 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 un- derscore, 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 di- rections. 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 non-zero, inverts the check, i.e. flags names that are not reserved. Default is 0. AllowedIdentifiers Semicolon-separated list of names that the check ignores. De- fault is an empty list. 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 0. 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 misinterpreta- tion, the desired way of converting from a signed char to an integer value is converting to unsigned char first, which stores all the char- acters in the positive [0..255] interval which matches the known char- acter 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 func- tionally 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 prob- lem 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 bellow. This code stops not only when it reaches the end of the file, but also when it gets a char- acter 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<unsigned char>(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<unsigned char>(SChar) == USChar) return true; return false; } CharTypdefsToIgnore 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 inte- ger alias like sal_Int8 or int8_t. In this case, human misinter- pretation is not an issue. DiagnoseSignedUnsignedCharComparisons When nonzero, the check will warn on signed char/unsigned char comparisons, otherwise these comparisons are ignored. By de- fault, this option is set to 1. 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<int, 3> 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 er- rors. 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 vulnera- bilities. 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 com- mon mistake is to query the sizeof on the integer or enum that repre- sents 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* in- stead of the aggregate type char[]. Using sizeof on an object declared with char* type is returning the size of a pointer instead of the num- ber 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 suspi- cious 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 re- ceiving 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. } Options WarnOnSizeOfConstant When non-zero, the check will warn on an expression like sizeof(CONSTANT). Default is 1. WarnOnSizeOfIntegerExpression When non-zero, the check will warn on an expression like sizeof(expr) where the expression results in an integer. Default is 0. WarnOnSizeOfThis When non-zero, the check will warn on an expression like sizeof(this). Default is 1. WarnOnSizeOfCompareToConstant When non-zero, the check will warn on an expression like sizeof(epxr) <= k for a suspicious constant k while k is 0 or greater than 0x8000. Default is 1. 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. 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 Cod- ing Standard rule CON36-C. Wrap functions that can spuriously wake up in a loop. bugprone-string-constructor Finds string constructors that are suspicious and probably errors. A common mistake is to swap parameters to the 'fill' string-construc- tor. 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". Creating an empty string from constructors with parameters is consid- ered suspicious. The programmer should use the empty constructor in- stead. Examples: std::string("test", 0); // Creation of an empty string. Options WarnOnLargeLength When non-zero, the check will warn on a string with a length greater than LargeLengthThreshold. Default is 1. LargeLengthThreshold An integer specifying the large length threshold. Default is 0x800000. bugprone-string-integer-assignment The check finds assignments of an integer to std::basic_string<CharT> (std::string, std::wstring, etc.). The source of the problem is the following assignment operator of std::basic_string<CharT>: 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<char>(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-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. We re- gard 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 repre- senting 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 <stdio.c> // Warning, filename is suspicious. Options HeaderFileExtensions Default value: ";h;hh;hpp;hxx" A semicolon-separated list of filename extensions of header files (the filename extensions should not contain a "." prefix). For extension-less header files, use an empty string or leave an empty string between ";" if there are other filename extensions. ImplementationFileExtensions Default value: "c;cc;cpp;cxx" Likewise, a semicolon-separated list of filename extensions of implementation files. bugprone-suspicious-memset-usage This check finds memset() calls with potential mistakes in their argu- ments. 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 custom- ary, 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 lit- eral to be considered by the check. Default is 5U. RatioThreshold A string specifying the maximum threshold ratio [0, 1.0] of sus- picious string literals to be considered. Default is ".2". MaxConcatenatedTokens An unsigned integer specifying the maximum number of concate- nated tokens. Default is 5U. 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 ana- lyzes the context of the code (e.g. indentation) in an attempt to de- termine 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 con- dition. 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 inden- tation 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 semi- colon 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 non-zero, the check will warn on implicit comparison. 1 by default. WarnOnLogicalNotComparison When non-zero, the check will warn on logical not comparison. 0 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, _mb- snbicmp_l, _mbsncmp, _mbsncmp_l, _mbsnicmp, _mbsnicmp_l, _memicmp, _memicmp_l, _stricmp, _stricmp_l, _strnicmp, _str- nicmp_l, _wcsicmp, _wcsicmp_l, _wcsnicmp, _wcsnicmp_l, lstrcmp, lstrcmpi, memcmp, memicmp, strcasecmp, strcmp, strcmpi, stricmp, strncasecmp, strncmp, strnicmp, wcscasecmp, wcscmp, wcsicmp, wc- sncmp, wcsnicmp, wmemcmp. bugprone-swapped-arguments Finds potentially swapped arguments by looking at implicit conversions. 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 effec- tively. 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-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 repre- sent 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 small amount of objects, but will lead to freeze for a a larger user input. 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 vari- able'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 unsigend 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-undefined-memory-manipulation Finds calls of memory manipulation functions memset(), memcpy() and memmove() on not TriviallyCopyable objects resulting in undefined be- havior. 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-self-assignment cert-oop54-cpp redirects here as an alias for this check. For the CERT alias, the WarnOnlyIfThisHasSuspiciousField option is set to 0. Finds user-defined copy assignment operators which do not protect the code against self-assignment either by checking self-assignment explic- itly 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 ob- ject 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; } }; WarnOnlyIfThisHasSuspiciousField When non-zero, the check will warn only if the container class of the copy assignment operator has any suspicious fields (pointer or C array). This option is set to 1 by default. 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 be- havior). • Ignore objects returned from a call. bugprone-unused-return-value Warns on unused function return values. The checked functions can be configured. Options CheckedFunctions Semicolon-separated list of functions to check. Defaults to ::std::async;::std::launder;::std::remove;::std::re- move_if;::std::unique;::std::unique_ptr::release;::std::ba- sic_string::empty;::std::vector::empty. This means that the calls to following functions are checked by default: • std::async(). Not using the return value makes the call syn- chronous. • 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 re- turned 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 any- where else. Often, ignoring the release() return value indi- cates 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(). 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<std::string> 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 af- ter 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; 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. 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; } Subsections below explain more precisely what exactly the check consid- ers to be a move, use, and reinitialization. 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 hap- pen before or after the move: void f(int i, std::vector<int> v); std::vector<int> 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 reinitial- izations occur in the same statement as moves or uses. A reinitializa- tion 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 vari- ables or function parameters. It does not check moves of member vari- ables 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 refer- ence 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<std::string> 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. 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. Use Any occurrence of the moved variable that is not a reinitialization (see below) is considered to be a use. An exception to this are objects of type std::unique_ptr, std::shared_ptr and std::weak_ptr, which have defined move behavior (objects of these classes are guaranteed to be empty after they have been moved from). Therefore, an object of these classes will only be considered to be used if it is dereferenced, i.e. if operator*, opera- tor-> or operator[] (in the case of std::unique_ptr<T []>) is called on it. 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, un- ordered_set, unordered_map, unordered_multiset, unordered_mul- timap. • reset() is called on the variable and the variable is of type std::unique_ptr, std::shared_ptr or std::weak_ptr. • A member function marked with the [[clang::reinitializes]] at- tribute is called on the variable. If the variable in question is a struct and an individual member vari- able 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-af- ter-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. bugprone-virtual-near-miss Warn if a function is a near miss (ie. 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 funk(); // warning: 'Derived::funk' has a similar name and the same signature as virtual method 'Base::func'; did you mean to override it? }; 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-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-dcl21-cpp This check flags postfix operator++ and operator-- declarations if the return type is not a const object. This also warns if the return type is a reference type. The object returned by a postfix increment or decrement operator is supposed to be a snapshot of the object's value prior to modification. With such an implementation, any modifications made to the resulting object from calling operator++(int) would be modifying a temporary ob- ject. Thus, such an implementation of a postfix increment or decrement operator should instead return a const object, prohibiting accidental mutation of a temporary object. Similarly, it is unexpected for the postfix operator to return a reference to its previous state, and any subsequent modifications would be operating on a stale object. This check corresponds to the CERT C++ Coding Standard recommendation DCL21-CPP. Overloaded postfix increment and decrement operators should return a const object. However, all of the CERT recommendations have been removed from public view, and so their justification for the be- havior of this check requires an account on their wiki to view. cert-dcl37-c The cert-dcl37-c check is an alias, please see bugprone-reserved-identifier for more information. cert-dcl50-cpp This check flags all function definitions (but not declarations) of C-style variadic functions. 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 Modification of the std or posix namespace can result in undefined be- havior. This check warns for such modifications. Examples: namespace std { int x; // May cause undefined behavior. } 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 google-build-namespaces for more information. cert-env33-c This check flags calls to system(), popen(), and _popen(), which exe- cute 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 com- mand processor but does not actually attempt to execute a command. 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 recom- mendations have been removed from public view, and so their justifica- tion for the behavior of this check requires an account on their wiki to view. cert-err34-c 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 func- tions that do perform better error checking. #include <stdlib.h> 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 */ } } This check corresponds to the CERT C Coding Standard rule ERR34-C. De- tect errors when converting a string to a number. cert-err52-cpp This check flags all call expressions involving setjmp() and longjmp(). This check corresponds to the CERT C++ Coding Standard rule ERR52-CPP. Do not use setjmp() or longjmp(). cert-err58-cpp This check flags all static or thread_local variable declarations where the initializer for the object may throw an exception. This check corresponds to the CERT C++ Coding Standard rule ERR58-CPP. Handle all exceptions thrown before main() begins executing. cert-err60-cpp This check flags all throw expressions where the exception object is not nothrow copy constructible. 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-fio38-c The cert-fio38-c check is an alias, please see misc-non-copyable-objects for more information. cert-flp30-c This check flags for loops where the induction expression has a float- ing-point type. This check corresponds to the CERT C Coding Standard rule FLP30-C. Do not use floating-point variables as loop counters. cert-mem57-cpp This check flags uses of default operator new where the type has ex- tended alignment (an alignment greater than the fundamental alignment). (The default operator new is guaranteed to provide the correct align- ment 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 alloca- tion). This check corresponds to the CERT C++ Coding Standard rule MEM57-CPP. Avoid using default operator new for over-aligned types. cert-msc30-c The cert-msc30-c check is an alias, please see cert-msc50-cpp for more information. cert-msc32-c The cert-msc32-c check is an alias, please see cert-msc51-cpp for more information. cert-msc50-cpp 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 re- sult. By manipulating the seed the result can be predictable. This check warns for the usage of std::rand(). cert-msc51-cpp This check flags all pseudo-random number engines, engine adaptor in- stantiations and srand() when initialized or seeded with default argu- ment, constant expression or any user-configurable type. Pseudo-random number engines seeded with a predictable value may cause vulnerabili- ties e.g. in security protocols. This is a CERT security rule, see MSC51-CPP. Ensure your random number generator is properly seeded and MSC32-C. Properly seed pseudorandom number generators. 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 values are time_t, std::time_t. 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 Flags use of the C standard library functions memset, memcpy and memcmp and similar derivatives on non-trivial types. Options MemSetNames Specify extra functions to flag that act similarily to memset. Specify names in a semicolon delimited list. Default is an empty string. The check will detect the following functions: memset, std::memset. MemCpyNames Specify extra functions to flag that act similarily to memcpy. Specify names in a semicolon delimited list. Default is an empty string. The check will detect the following functions: std::memcpy, memcpy, std::memmove, memmove, std::strcpy, strcpy, memccpy, stpncpy, strncpy. MemCmpNames Specify extra functions to flag that act similarily to memcmp. Specify names in a semicolon delimited list. Default is an empty string. The check will detect the following functions: std::memcmp, memcmp, std::strcmp, strcmp, strncmp. 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 Finds assignments to the copied object and its direct or indirect mem- bers 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. cert-pos44-c The cert-pos44-c check is an alias, please see bugprone-bad-signal-to-kill-thread 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.CallAndMessage The clang-analyzer-core.CallAndMessage check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.DivideZero The clang-analyzer-core.DivideZero check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.DynamicTypePropagation Generate dynamic type information clang-analyzer-core.NonNullParamChecker The clang-analyzer-core.NonNullParamChecker check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.NullDereference The clang-analyzer-core.NullDereference check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.StackAddressEscape The clang-analyzer-core.StackAddressEscape check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.UndefinedBinaryOperatorResult The clang-analyzer-core.UndefinedBinaryOperatorResult check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-core.VLASize The clang-analyzer-core.VLASize check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-core.uninitialized.ArraySubscript The clang-analyzer-core.uninitialized.ArraySubscript check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-core.uninitialized.Assign 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 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 clang-analyzer-core.uninitialized.UndefReturn The clang-analyzer-core.uninitialized.UndefReturn check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-cplusplus.InnerPointer Check for inner pointers of C++ containers used after re/deallocation clang-analyzer-cplusplus.Move The clang-analyzer-cplusplus.Move check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-cplusplus.NewDelete The clang-analyzer-cplusplus.NewDelete check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-cplusplus.NewDeleteLeaks The clang-analyzer-cplusplus.NewDeleteLeaks check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-deadcode.DeadStores The clang-analyzer-deadcode.DeadStores check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-nullability.NullPassedToNonnull The clang-analyzer-nullability.NullPassedToNonnull check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-nullability.NullReturnedFromNonnull The clang-analyzer-nullability.NullReturnedFromNonnull check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-nullability.NullableDereferenced The clang-analyzer-nullability.NullableDereferenced check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-nullability.NullablePassedToNonnull The clang-analyzer-nullability.NullablePassedToNonnull check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-nullability.NullableReturnedFromNonnull Warns when a nullable pointer is returned from a function that has _Nonnull return type. clang-analyzer-optin.cplusplus.UninitializedObject The clang-analyzer-optin.cplusplus.UninitializedObject check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-optin.cplusplus.VirtualCall The clang-analyzer-optin.cplusplus.VirtualCall check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-optin.mpi.MPI-Checker 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.OSObjectCStyleCast Checker for C-style casts of OSObjects clang-analyzer-optin.osx.cocoa.localizability.EmptyLocalizationCon- textChecker The clang-analyzer-optin.osx.cocoa.localizability.EmptyLocalizationCon- textChecker check is an alias, please see Clang Static Analyzer Avail- able Checkers for more information. clang-analyzer-optin.osx.cocoa.localizability.NonLocalizedStringChecker The clang-analyzer-optin.osx.cocoa.localizability.NonLocalized- StringChecker 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 clang-analyzer-optin.performance.Padding Check for excessively padded structs. clang-analyzer-optin.portability.UnixAPI Finds implementation-defined behavior in UNIX/Posix functions clang-analyzer-osx.API The clang-analyzer-osx.API check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-osx.MIG Find violations of the Mach Interface Generator calling convention clang-analyzer-osx.NumberObjectConversion Check for erroneous conversions of objects representing numbers into numbers clang-analyzer-osx.OSObjectRetainCount Check for leaks and improper reference count management for OSObject clang-analyzer-osx.ObjCProperty Check for proper uses of Objective-C properties clang-analyzer-osx.SecKeychainAPI The clang-analyzer-osx.SecKeychainAPI check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-osx.cocoa.AtSync 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 clang-analyzer-osx.cocoa.ClassRelease 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 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 The clang-analyzer-osx.cocoa.IncompatibleMethodTypes check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-osx.cocoa.Loops Improved modeling of loops using Cocoa collection types clang-analyzer-osx.cocoa.MissingSuperCall Warn about Objective-C methods that lack a necessary call to super clang-analyzer-osx.cocoa.NSAutoreleasePool The clang-analyzer-osx.cocoa.NSAutoreleasePool check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-osx.cocoa.NSError 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 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 clang-analyzer-osx.cocoa.ObjCGenerics 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 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 clang-analyzer-osx.cocoa.SelfInit 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 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 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 The clang-analyzer-osx.cocoa.VariadicMethodTypes check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-osx.coreFoundation.CFError 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 The clang-analyzer-osx.coreFoundation.CFNumber check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-osx.coreFoundation.CFRetainRelease The clang-analyzer-osx.coreFoundation.CFRetainRelease check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-osx.coreFoundation.containers.OutOfBounds 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 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 The clang-analyzer-security.FloatLoopCounter check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling The clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHan- dling check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-security.insecureAPI.UncheckedReturn The clang-analyzer-security.insecureAPI.UncheckedReturn check is an alias, please see Clang Static Analyzer Available Checkers for more in- formation. clang-analyzer-security.insecureAPI.bcmp 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 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 The clang-analyzer-security.insecureAPI.bzero check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-security.insecureAPI.getpw 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 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 The clang-analyzer-security.insecureAPI.mkstemp check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-security.insecureAPI.mktemp The clang-analyzer-security.insecureAPI.mktemp check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-security.insecureAPI.rand 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 The clang-analyzer-security.insecureAPI.strcpy check is an alias, please see Clang Static Analyzer Available Checkers for more informa- tion. clang-analyzer-security.insecureAPI.vfork The clang-analyzer-security.insecureAPI.vfork check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-unix.API The clang-analyzer-unix.API check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-unix.Malloc The clang-analyzer-unix.Malloc check is an alias, please see Clang Sta- tic Analyzer Available Checkers for more information. clang-analyzer-unix.MallocSizeof The clang-analyzer-unix.MallocSizeof check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-unix.MismatchedDeallocator The clang-analyzer-unix.MismatchedDeallocator check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-unix.Vfork The clang-analyzer-unix.Vfork check is an alias, please see Clang Sta- tic Analyzer Available Checkers for more information. clang-analyzer-unix.cstring.BadSizeArg 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 The clang-analyzer-unix.cstring.NullArg check is an alias, please see Clang Static Analyzer Available Checkers for more information. clang-analyzer-valist.CopyToSelf Check for va_lists which are copied onto itself. clang-analyzer-valist.Uninitialized Check for usages of uninitialized (or already released) va_lists. clang-analyzer-valist.Unterminated Check for va_lists which are not released by a va_end call. cppcoreguidelines-avoid-c-arrays The cppcoreguidelines-avoid-c-arrays check is an alias, please see modernize-avoid-c-arrays for more information. cppcoreguidelines-avoid-goto The usage of goto for control flow is error prone and should be re- placed with looping constructs. Only forward jumps in nested loops are accepted. This check implements ES.76 from the CppCoreGuidelines and 6.3.1 from High Integrity C++. 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++. 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 Guide- lines <https://github.com/isocpp/CppCoreGuidelines/blob/master/Cpp- CoreGuidelines.md#Ri-global> . As R.6 of C++ Core Guidelines <https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuide- lines.md#Rr-global> 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; }; Variables: a, c, c_ptr1, c_ptr2, c_const_ptr and c_reference, will all generate warnings since they are either: a globally accessible variable and non-const, a pointer or reference providing global access to non-const data or both. 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-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 behaviour if there is a code path that reads the variable before assigning to it. 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 <math.h> void function() { int x = 0; char *txt = nullptr; double d = NAN; // Rest of the function. } 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 math.h. cppcoreguidelines-interfaces-global-init This check flags initializers of globals that access extern objects, and therefore can lead to order-of-initialization problems. This rule is part of the "Interfaces" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-global-init Note that currently this does not flag calls to non-constexpr func- tions, and therefore globals could still be accessed from functions themselves. cppcoreguidelines-macro-usage Finds macro usage that is considered problematic because better lan- guage constructs exist for the task. The relevant sections in the C++ Core Guidelines are Enum.1, ES.30, ES.31 and ES.33. Options AllowedRegexp A regular expression to filter allowed macros. For example DE- BUG*|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 0/false. IgnoreCommandLineMacros Boolean flag to toggle ignoring command-line-defined macros. Default value is 1/true. cppcoreguidelines-narrowing-conversions 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; }. This rule is part of the "Expressions and statements" profile of the C++ Core Guidelines, corresponding to rule ES.46. See https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es46-avoid-lossy-narrowing-truncating-arithmetic-conversions. We enforce only part of the guideline, more specifically, we flag nar- rowing conversions from: • an integer to a narrower integer (e.g. char to unsigned char), • an integer to a narrower floating-point (e.g. uint64_t to float), • 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 conver- sions. For example: int i; i+= 0.1;. Options WarnOnFloatingPointNarrowingConversion When non-zero, the check will warn on narrowing floating point conversion (e.g. double to float). 1 by default. PedanticMode When non-zero, 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;). 0 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 'un- signed int' to signed type 'int' is implementation-defined". The C/C++ standard does not mandate twos 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 twos complement format. 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()). See 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 al- location functions. Defaults to ::malloc;::calloc. Deallocations Semicolon-separated list of fully qualified names of memory al- location functions. Defaults to ::free. Reallocations Semicolon-separated list of fully qualified names of memory al- location functions. Defaults to ::realloc. 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<T*>, which allows static analysis on code, that uses raw pointers to handle re- sources like dynamic memory, but won't introduce RAII concepts. The relevant sections in the C++ Core Guidelines are I.11, C.33, R.3 and GSL.Views The definition of a gsl::owner<T*> is straight forward namespace gsl { template <typename T> owner = T; } It is therefore simple to introduce the owner even without using an im- plementation 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 ini- tializations 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<int*> function_that_returns_owner() { return gsl::owner<int*>(new int(42)); } // Dynamic memory must be assigned to an owner int* Something = new int(42); // BAD, will be caught gsl::owner<int*> Owner = new int(42); // Good gsl::owner<int*> 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<int*> 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<int*> Owned = &Stack; // Bad, not a resource assigned In the case of dynamic memory as resource, only gsl::owner<T*> vari- ables 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<int*> 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<T*> as argument get called with either a gsl::owner<T*> or a newly created resource. void expects_owner(gsl::owner<int*> o) { delete o; } // Bad Code int NonOwner = 42; expects_owner(&NonOwner); // Bad, will get caught // Good Code gsl::owner<int*> 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*> 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;::real- loc;::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;::real- loc;::freopen;::fclose. Limitations Using gsl::owner<T*> in a typedef or alias is not handled correctly. using heap_int = gsl::owner<int*>; heap_int allocated = new int(42); // False positive! The gsl::owner<T*> 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<T*> 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<gsl::owner<T*>> // This template function works as expected. Type information doesn't get lost. template <typename T> void delete_owner(gsl::owner<T*> owned_object) { delete owned_object; // Everything alright } gsl::owner<int*> function_that_returns_owner() { return gsl::owner<int*>(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 <typename T> void bad_template_function(T some_object) { // This line will trigger the warning, that a non-owner is assigned to an owner gsl::owner<T*> new_owner = some_object; } // Calling the function with an owner still yields a false positive. bad_template_function(gsl::owner<int*>(new int(42))); // The same issue occurs with templated classes like the following. template <typename T> class OwnedValue { public: const T getValue() const { return _val; } private: T _val; }; // Code, that yields a false positive. OwnedValue<gsl::owner<int*>> Owner(new int(42)); // Type deduction yield T -> int * // False positive, getValue returns int* and not gsl::owner<int*> gsl::owner<int*> 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<int*> Owner1 = new int(42); gsl::owner<int*> Owner2 = new int(42); Owner2 = Owner1; // Conceptual Leak of initial resource of Owner2! Owner1 = nullptr; The semantic of a gsl::owner<T*> is mostly like a std::unique_ptr<T>, therefore assignment of two gsl::owner<T*> 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 improve- ments of this check with flowsensitive analysis. Currently, the Clang Static Analyzer catches this bug for dynamic memory, but not for gen- eral types of resources. cppcoreguidelines-pro-bounds-array-to-pointer-decay This check flags all array to pointer decays. Pointers should not be used as arrays. span<T> is a bounds-checked, safe alternative to using pointers to access arrays. This rule is part of the "Bounds safety" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-bounds-decay. 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" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-bounds-arrayindex. 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". 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<T> is a bounds-checked, safe type for accessing arrays of data. This rule is part of the "Bounds safety" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-bounds-arithmetic. cppcoreguidelines-pro-type-const-cast This check flags all uses of const_cast in C++ code. Modifying a variable that was declared const is undefined behavior, even with const_cast. This rule is part of the "Type safety" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-constcast. 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 ac- cess 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 reinter- pret_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" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-cstylecast. cppcoreguidelines-pro-type-member-init The check flags user-defined constructor definitions that do not ini- tialize 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 ac- count 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 ini- tialized. 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 non-zero, the check will not warn about array members that are not zero-initialized during construction. For perfor- mance critical code, it may be important to not initialize fixed-size array members. Default is 0. UseAssignment If set to non-zero, the check will provide fix-its with literal initializers ( int i = 0; ) instead of curly braces ( int i{}; ). This rule is part of the "Type safety" profile of the C++ Core Guide- lines, corresponding to rule Type.6. See https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-memberinit. 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 ac- cess 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" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast. 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 con- vert the cast to a dynamic_cast. Use of these casts can violate type safety and cause the program to ac- cess 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" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-downcast. 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 writ- ten, and writing to a union member assumes another member with a non- trivial destructor had its destructor called. This is fragile because it cannot generally be enforced to be safe in the language and so re- lies on programmer discipline to get it right. This rule is part of the "Type safety" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-unions. 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. Passing to varargs assumes the correct type will be read. This is frag- ile 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" profile of the C++ Core Guide- lines, see https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-varargs. cppcoreguidelines-slicing Flags slicing of member variables or vtable. Slicing happens when copy- ing a derived object into a base object: the members of the derived ob- ject (both member variables and virtual member functions) will be dis- carded. 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. See the relevant C++ Core Guidelines sections for details: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es63-dont-slice https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c145-access-polymorphic-objects-through-pointers-and-references 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 op- erator, move constructor, move assignment operator and destructor. The default can be suppressed by explicit user-definitions. The relation- ship 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 defi- nition. This rule is part of the "Constructors, assignments, and destructors" profile of the C++ Core Guidelines, corresponding to rule C.21. See https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c21-if-you-define-or-delete-any-default-operation-define-or-delete-them-all. Options AllowSoleDefaultDtor When set to 1 (default is 0), this check doesn't flag classes with a sole, explicitly defaulted destructor. An example for such a class is: struct A { virtual ~A() = default; }; AllowMissingMoveFunctions When set to 1 (default is 0), 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 assign- ment 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 1 (default is 0), this check doesn't flag classes which define deleted copy operations but don't define move oper- ations. This flags is related to Google C++ Style Guide https://google.github.io/styleguide/cppguide.html#Copyable_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(); }; darwin-avoid-spinlock Finds usages of OSSpinlock, which is deprecated due to potential live- lock problems. This check will detect following function invocations: • OSSpinlockLock • OSSpinlockTry • OSSpinlockUnlock The corresponding information about the problem of OSSpinlock: https://blog.postmates.com/why-spinlocks-are-bad-on-ios-b69fc5221058 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 diag- nosed. Calling it without defaults will not cause a warning: foo(); // warning foo(0); // no warning See the features disallowed in Fuchsia at https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md 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 https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md fuchsia-header-anon-namespaces The fuchsia-header-anon-namespaces check is an alias, please see google-build-namespace for more information. fuchsia-multiple-inheritance Warns if a class inherits from multiple classes that are not pure vir- tual. 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; } }; See the features disallowed in Fuchsia at https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md 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 https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md fuchsia-statically-constructed-objects Warns if global, non-trivial objects with static storage are con- structed, 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: C(int Val) : Val(Val) {} constexpr C() : Val(0) {} 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(get_i()) // Warning, as the constructor is dynamically initialized See the features disallowed in Fuchsia at https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md 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 <typename T1, typename T2> auto fn(const T1 &lhs, const T2 &rhs) -> decltype(lhs + rhs) { return lhs + rhs; } See the features disallowed in Fuchsia at https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md 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 https://fuchsia.googlesource.com/zircon/+/master/docs/cxx.md 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 cert-dcl59-cpp redirects here as an alias for this check. fuch- sia-header-anon-namespaces redirects here as an alias for this check. Finds anonymous namespaces in headers. https://google.github.io/styleguide/cppguide.html#Namespaces Corresponding cpplint.py check name: build/namespaces. Options HeaderFileExtensions A comma-separated list of filename extensions of header files (the filename extensions should not include "." prefix). Default is "h,hh,hpp,hxx". For header files without an extension, use an empty string (if there are no other desired extensions) or leave an empty element in the list. e.g., "h,hh,hpp,hxx," (note the trailing comma). 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 https://google.github.io/styleguide/cppguide.html#Default_Arguments google-explicit-constructor Checks that constructors callable with a single argument and conversion operators are marked explicit to avoid the risk of unintentional im- plicit 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 con- verted 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 ini- tializer_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; ... See https://google.github.io/styleguide/cppguide.html#Explicit_Constructors 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 https://google.github.io/styleguide/cppguide.html#Namespaces. Options HeaderFileExtensions A comma-separated list of filename extensions of header files (the filename extensions should not contain "." prefix). Default is "h". For header files without an extension, use an empty string (if there are no other desired extensions) or leave an empty element in the list. e.g., "h,hh,hpp,hxx," (note the trailing comma). 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 in- stantiate 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 throw- ing exceptions from Objective-C code. The corresponding C++ style guide rule: https://google.github.io/styleguide/cppguide.html#Exceptions Instead, prefer passing in NSError ** and return BOOL to indicate suc- cess 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: https://google.github.io/styleguide/objcguide.html#avoid-throwing-exceptions 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: https://google.github.io/styleguide/objcguide.html#function-names 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: https://google.github.io/styleguide/objcguide.html#variable-names All the global variables should follow the pattern of g[A-Z].* (vari- ables) 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 need to fix it on his own. google-readability-avoid-underscore-in-googletest-name Checks whether there are underscores in googletest test and test case names in test macros: • TEST • TEST_F • TEST_P • TYPED_TEST • TYPED_TEST_P The FRIEND_TEST macro is not included. For example: TEST(TestCaseName, Illegal_TestName) {} TEST(Illegal_TestCaseName, TestName) {} would trigger the check. Underscores are not allowed in test names nor test case names. The DISABLED_ prefix, which may be used to disable individual tests, is ignored when checking test names, but the rest of the rest of the test name is still checked. 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 Finds usages of C-style casts. https://google.github.io/styleguide/cppguide.html#Casting Corresponding cpplint.py check name: readability/casting. 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. 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 https://google.github.io/styleguide/cppguide.html#TODO_Comments. Corresponding cpplint.py check: readability/todo google-runtime-int Finds uses of short, long and long long and suggest replacing them with u?intXX(_t)?. The corresponding style guide rule: https://google.github.io/styleguide/cppguide.html#Integer_Types. 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 &. https://google.github.io/styleguide/cppguide.html#Operator_Overloading Corresponding cpplint.py check name: runtime/operator. google-runtime-references Checks the usage of non-constant references in function parameters. The corresponding style guide rule: https://google.github.io/styleguide/cppguide.html#Reference_Arguments Options IncludedTypes A semicolon-separated list of names of types to explicitly in- clude. Default is empty. google-upgrade-googletest-case Finds uses of deprecated Google Test version 1.9 APIs with names con- taining 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, test- ing::TestEventListener, testing::UnitTest, and any type inheriting from these types • The macros TYPED_TEST_CASE, TYPED_TEST_CASE_P, REGIS- TER_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 a only warning when a fix cannot be made safely, as is the case with some template and macro uses. hicpp-avoid-c-arrays The hicpp-avoid-c-arrays check is an alias, please see modernize-avoid-c-arrays for more information. hicpp-avoid-goto The hicpp-avoid-goto check is an alias to cppcoreguidelines-avoid-goto. Rule 6.3.1 High Integrity C++ requires that goto only skips parts of a block and is not used for other reasons. Both coding guidelines implement the same exception to the usage of goto. hicpp-braces-around-statements The hicpp-braces-around-statements check is an alias, please see readability-braces-around-statements for more information. It enforces the rule 6.1.1. hicpp-deprecated-headers The hicpp-deprecated-headers check is an alias, please see modernize-deprecated-headers for more information. It enforces the rule 1.3.3. hicpp-exception-baseclass Ensure that every value that in a throw expression is an instance of std::exception. This enforces rule 15.1 of the High Integrity C++ Coding Standard. 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(); } hicpp-explicit-conversions This check is an alias for google-explicit-constructor. Used to en- force parts of rule 5.4.1. This check will enforce that constructors and conversion operators are marked explicit. Other forms of casting checks are implemented in other places. The following checks can be used to check for more forms of casting: • cppcoreguidelines-pro-type-static-cast-downcast • cppcoreguidelines-pro-type-reinterpret-cast • cppcoreguidelines-pro-type-const-cast • cppcoreguidelines-pro-type-cstyle-cast hicpp-function-size This check is an alias for readability-function-size. Useful to en- force multiple sections on function complexity. • rule 8.2.2 • rule 8.3.1 • rule 8.3.2 hicpp-invalid-access-moved This check is an alias for bugprone-use-after-move. Implements parts of the rule 8.4.1 to check if moved-from objects are accessed. hicpp-member-init This check is an alias for cppcoreguidelines-pro-type-member-init. Im- plements the check for rule 12.4.2 to initialize class members in the right order. hicpp-move-const-arg The hicpp-move-const-arg check is an alias, please see performance-move-const-arg for more information. It enforces the rule 17.3.1. hicpp-multiway-paths-covered This check discovers situations where code paths are not fully-covered. It furthermore suggests using if instead of switch if the code will be more clear. The rule 6.1.2 and rule 6.1.4 of the High Integrity C++ Coding Standard are enforced. if-else if chains that miss a final else branch might lead to unex- pected program execution and be the result of a logical error. If the missing else branch is intended you can leave it empty with a clarify- ing 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 } The rule 6.1.4 requires every switch statement to have at least two case labels other than a default label. Otherwise, the switch could be better expressed with an if statement. Degenerated switch statements without any labels are caught as well. // Degenerated switch that could be better written as `if` int i = 42; switch(i) { case 1: // do something here default: // do somethe else here } // Should rather be the following: if (i == 1) { // do something here } else { // do something here } // A completely degenerated switch will be diagnosed. int i = 42; switch(i) {} Options WarnOnMissingElse Boolean flag that activates a warning for missing else branches. Default is 0. hicpp-named-parameter This check is an alias for readability-named-parameter. Implements rule 8.2.1. hicpp-new-delete-operators This check is an alias for misc-new-delete-overloads. Implements rule 12.3.1 to ensure the new and delete operators have the correct signa- ture. hicpp-no-array-decay The hicpp-no-array-decay check is an alias, please see cppcoreguidelines-pro-bounds-array-to-pointer-decay for more informa- tion. It enforces the rule 4.1.1. hicpp-no-assembler Check for assembler statements. No fix is offered. Inline assembler is forbidden by the High Intergrity C++ Coding Stan- dard as it restricts the portability of code. hicpp-no-malloc The hicpp-no-malloc check is an alias, please see cppcoreguidelines-no-malloc for more information. It enforces the rule 5.3.2. hicpp-noexcept-move This check is an alias for performance-noexcept-move-constructor. Checks rule 12.5.4 to mark move assignment and move construction noex- cept. hicpp-signed-bitwise Finds uses of bitwise operations on signed integer types, which may lead to undefined or implementation defined behaviour. The according rule is defined in the High Integrity C++ Standard, Sec- tion 5.6.1. Options IgnorePositiveIntegerLiterals If this option is set to true, the check will not warn on bit- wise operations with positive integer literals, e.g. ~0, 2 << 1, etc. Default value is false. hicpp-special-member-functions This check is an alias for cppcoreguidelines-special-member-functions. Checks that special member functions have the correct signature, ac- cording to rule 12.5.7. hicpp-static-assert The hicpp-static-assert check is an alias, please see misc-static-assert for more information. It enforces the rule 7.1.10. hicpp-undelegated-constructor This check is an alias for bugprone-undelegated-constructor. Partially implements rule 12.4.5 to find misplaced constructor calls inside a constructor. struct Ctor { Ctor(); Ctor(int); Ctor(int, int); Ctor(Ctor *i) { // All Ctor() calls result in a temporary object Ctor(); // did you intend to call a delegated constructor? Ctor(0); // did you intend to call a delegated constructor? Ctor(1, 2); // did you intend to call a delegated constructor? foo(); } }; hicpp-uppercase-literal-suffix The hicpp-uppercase-literal-suffix check is an alias, please see readability-uppercase-literal-suffix for more information. hicpp-use-auto The hicpp-use-auto check is an alias, please see modernize-use-auto for more information. It enforces the rule 7.1.8. hicpp-use-emplace The hicpp-use-emplace check is an alias, please see modernize-use-emplace for more information. It enforces the rule 17.4.2. hicpp-use-equals-default This check is an alias for modernize-use-equals-default. Implements rule 12.5.1 to explicitly default special member functions. hicpp-use-equals-delete This check is an alias for modernize-use-equals-delete. Implements rule 12.5.1 to explicitly default or delete special member functions. hicpp-use-noexcept The hicpp-use-noexcept check is an alias, please see modernize-use-noexcept for more information. It enforces the rule 1.3.5. hicpp-use-nullptr The hicpp-use-nullptr check is an alias, please see modernize-use-nullptr for more information. It enforces the rule 2.5.3. hicpp-use-override This check is an alias for modernize-use-override. Implements rule 10.2.1 to declare a virtual function override when overriding. hicpp-vararg The hicpp-vararg check is an alias, please see cppcoreguidelines-pro-type-vararg for more information. It enforces the rule 14.1.1. linuxkernel-must-use-errs Checks Linux kernel code to see if it uses the results from the func- tions 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 func- tions. 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 __at- tribute__((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-header-guard Finds and fixes header guards that do not adhere to LLVM style. Options HeaderFileExtensions A comma-separated list of filename extensions of header files (the filename extensions should not include "." prefix). Default is "h,hh,hpp,hxx". For header files without an extension, use an empty string (if there are no other desired extensions) or leave an empty element in the list. e.g., "h,hh,hpp,hxx," (note the trailing comma). llvm-include-order Checks the correct order of #includes. See https://llvm.org/docs/CodingStandards.html#include-style llvm-namespace-comment google-readability-namespace-comments redirects here as an alias for this check. Checks that long namespaces have a closing comment. https://llvm.org/docs/CodingStandards.html#namespace-indentation https://google.github.io/styleguide/cppguide.html#Namespaces 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 un- signed integer that defaults to 1U. SpacesBeforeComments An unsigned integer specifying the number of spaces before the comment closing a namespace definition. Default is 1U. 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<X>(var), where var is evaluated twice. // Finds these: if (auto x = cast<X>(y)) {} // is replaced by: if (auto x = dyn_cast<X>(y)) {} if (cast<X>(y)) {} // is replaced by: if (isa<X>(y)) {} if (dyn_cast<X>(y)) {} // is replaced by: if (isa<X>(y)) {} if (var && isa<T>(var)) {} // is replaced by: if (isa_and_nonnull<T>(var.foo())) {} // Other cases are ignored, e.g.: if (auto f = cast<Z>(y)->foo()) {} if (cast<Z>(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 un- signed. void example(MachineOperand &MO) { unsigned Reg = MO.getReg(); ... } becomes: void example(MachineOperand &MO) { Register Reg = MO.getReg(); ... } llvm-qualified-auto The llvm-qualified-auto check is an alias, please see readability-qualified-auto for more information. 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(); llvmlibc-callee-namespace Checks all calls resolve to functions within __llvm_libc namespace. namespace __llvm_libc { // Allow calls with the fully qualified name. __llvm_libc::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 __llvm_libc llvmlibc-implementation-in-namespace Checks that all declarations in the llvm-libc implementation are within the correct namespace. // Correct: implementation inside the correct namespace. namespace __llvm_libc { void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {} // Namespaces within __llvm_libc namespace are allowed. namespace inner{ int localVar = 0; } // Functions with C linkage are allowed. extern "C" void str_fuzz(){} } // Incorrect: implementation not in a namespace. void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {} // Incorrect: outer most namespace is not correct. namespace something_else { void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {} } llvmlibc-restrict-system-libc-headers Finds includes of system libc headers not provided by the compiler within llvm-libc implementations. #include <stdio.h> // Not allowed because it is part of system libc. #include <stddef.h> // 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 con- sider 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 in- clude 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 de- velopment headers. See portability-restrict-system-includes for more details. 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; // 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<typename T> 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 <typename T> struct B { void f1(); }; // OK: member function definition of a class template is allowed. template <typename T> void B<T>::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 <class T> constexpr T pi = T(3.1415926L); Options HeaderFileExtensions A comma-separated list of filename extensions of header files (the filename extensions should not include "." prefix). Default is "h,hh,hpp,hxx". For header files without an extension, use an empty string (if there are no other desired extensions) or leave an empty element in the list. e.g., "h,hh,hpp,hxx," (note the trailing comma). UseHeaderFileExtension When non-zero, the check will use the file extension to distin- guish header files. Default is 1. 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 con- structs 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 re- dundant (or disallowed) on the underlying pointee type. misc-new-delete-overloads cert-dcl54-cpp redirects here as an alias for this check. The check flags overloaded operator new() and operator delete() func- tions that do not have a corresponding free store function defined within the same scope. For instance, the check will flag a class im- plementation 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 pri- vate 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. The 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. 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 Allows to completely ignore classes if all the member variables in that class a declared with a public access specifier. IgnorePublicMemberVariables Allows to ignore (not diagnose) all the member variables de- clared with a public access specifier. 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 misc-static-assert cert-dcl03-c redirects here as an alias for this check. Replaces assert() with static_assert() if the condition is evaluatable at compile time. The condition of static_assert() is evaluated at compile time which is safer and more efficient. misc-throw-by-value-catch-by-reference cert-err09-cpp redirects here as an alias for this check. cert-err61-cpp redirects here as an alias for this check. Finds violations of the rule "Throw by value, catch by reference" pre- sented 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 idomatic. • Catching character pointers (char, wchar_t, unicode character types) will not be flagged to allow catching sting 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 throw- ing an anonymous temporary. This allows helper functions for throwing. • Re-throwing caught exception variables will not be flragged 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 1. WarnOnLargeObject Also warns for any large, trivial object caught by value. Catch- ing 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 0. MaxSize Determines the maximum size of an object allowed to be caught without warning. Only applicable if WarnOnLargeObject is set to 1. If option is set by the user to std::numeric_lim- its<uint64_t>::max() then it reverts to the default value. De- fault is the size of size_t. misc-unconventional-assign-operator Finds declarations of assign operators with the wrong return and/or ar- gument types and definitions with good return type but wrong return statements. • The return type must be Class&. • Works with move-assign and assign by value. • 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<Foo> 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<Foo>*. misc-unused-alias-decls Finds unused namespace alias declarations. 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 sug- gested 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). 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 zero (default value), the check will ignore trivially un- used parameters, i.e. when the corresponding function has an empty body (and in case of constructors - no constructor ini- tializers). When the function body is empty, an unused parameter is unlikely to be unnoticed by a human reader, and there's basi- cally no place for a bug to hide. misc-unused-using-decls Finds unused using declarations. Example: namespace n { class C; } using n::C; // Never actually used. 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. Cur- rently, 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 equiva- lent lambdas. Options PermissiveParameterList If the option is set to non-zero, the check will append auto&&... to the end of every placeholder parameter list. With- out 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. For example: int add(int x, int y) { return x + y; } int foo() { std::function<int(int,int)> 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<int(int,int)> ignore_args = [] { return add(2, 2); } return ignore_args(3, 3); } which will not compile, since the lambda does not contain an operator() that that accepts 2 arguments. With permissive parameter list, it in- stead generates int add(int x, int y) { return x + y; } int foo() { std::function<int(int,int)> 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. hicpp-avoid-c-arrays redirects here as an alias for this check. Finds C-style array types and recommend to use std::array<> / std::vec- tor<>. All types of C arrays are diagnosed. 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 <typename T, int Size> 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<int[4], 2> 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 parame- ters can be either char* argv[] or char** argv, but can not be std::ar- ray<>. 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(); } } } Will be modified to: namespace n1::n2 { void t(); } namespace n3 { namespace n4::n5 { void t(); } namespace n6::n7 { 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++ alterna- tives and removes redundant ones. Important note: the Standard doesn't guarantee that the C++ headers de- clare 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. • <assert.h> • <complex.h> • <ctype.h> • <errno.h> • <fenv.h> // deprecated since C++11 • <float.h> • <inttypes.h> • <limits.h> • <locale.h> • <math.h> • <setjmp.h> • <signal.h> • <stdarg.h> • <stddef.h> • <stdint.h> • <stdio.h> • <stdlib.h> • <string.h> • <tgmath.h> // deprecated since C++11 • <time.h> • <uchar.h> // deprecated since C++11 • <wchar.h> • <wctype.h> If the specified standard is older than C++11 the check will only re- place headers deprecated before C++11, otherwise -- every header that appeared in the previous list. These headers don't have effect in C++: • <iso646.h> • <stdalign.h> • <stdbool.h> modernize-deprecated-ios-base-aliases Detects usage of the deprecated member types of std::ios_base and re- places 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 confi- dence in the transformation due to the increased risk of changing se- mantics. 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 in- correct transformation when the minimum required confidence level is set to risky. reasonable (Default) If a loop calls .end() or .size() after each iteration, the transforma- tion 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<int> 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<int>::iterator it = v.begin(); it != v.end(); ++it) cout << *it; // reasonable conversion for (int i = 0; i < v.size(); ++i) cout << v[i]; After applying the check with minimum confidence level set to reason- able (default): const int N = 5; int arr[] = {1,2,3,4,5}; vector<int> 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; 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 behaviour 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 ini- tialization 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<T>::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 in- cluding 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 exam- ple, 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 <container ele- ment>.<member> instead due to the implicit dereference as part of the range-based for loop. Therefore any side effect of the overloaded op- erator->() 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 con- tainer 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<int> vec; vector<int> *ptr = &vec; vector<int> &ref = vec; for (vector<int>::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 been used on code with a compatibility requirements 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) on the specific for loops is recom- mended. 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<MyPair>(new MyPair(1, 2)); // becomes auto my_ptr = std::make_shared<MyPair>(1, 2); This check also finds calls to std::shared_ptr::reset() with a new ex- pression, and replaces it with a call to std::make_shared. my_ptr.reset(new MyPair(1, 2)); // becomes my_ptr = std::make_shared<MyPair>(1, 2); Options MakeSmartPtrFunction A string specifying the name of make-shared-ptr function. De- fault is std::make_shared. MakeSmartPtrFunctionHeader A string specifying the corresponding header of make-shared-ptr function. Default is memory. IncludeStyle A string specifying which include-style is used, llvm or google. Default is llvm. IgnoreMacros If set to non-zero, the check will not give warnings inside macros. Default is 1. 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<MyPair>(new MyPair(1, 2)); // becomes auto my_ptr = std::make_unique<MyPair>(1, 2); This check also finds calls to std::unique_ptr::reset() with a new ex- pression, and replaces it with a call to std::make_unique. my_ptr.reset(new MyPair(1, 2)); // becomes my_ptr = std::make_unique<MyPair>(1, 2); Options MakeSmartPtrFunction A string specifying the name of make-unique-ptr function. De- fault is std::make_unique. MakeSmartPtrFunctionHeader A string specifying the corresponding header of make-unique-ptr function. Default is memory. IncludeStyle A string specifying which include-style is used, llvm or google. Default is llvm. IgnoreMacros If set to non-zero, the check will not give warnings inside macros. Default is 1. modernize-pass-by-value With move semantics added to the language and the standard library up- dated 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 wel- come! 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 <utility> it may be necessary to add this include. The check will add the include directive when necessary. #include <string> 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 <string> void pass(const std::string &S); struct Foo { Foo(const std::string &S) : Str(S) { pass(S); } std::string Str; }; Known 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 tem- plated contexts; templated constructors, constructors in class tem- plates, constructors of inner classes of template classes, etc., are not transformed. Delayed template parsing is enabled by default on Win- dows as a Microsoft extension: Clang Compiler Users Manual - Microsoft extensions. Delayed template parsing can be enabled using the -fdelayed-tem- plate-parsing flag and disabled using -fno-delayed-template-parsing. Example: template <typename T> 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 non-zero, the check only warns about copied parameters that are already passed by value. Default is 0. 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 hexa- decimal 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. modernize-redundant-void-arg Find and remove redundant void argument lists. Examples: +----------------------------+-------------------------+ | Initial code | Code with applied fixes | +----------------------------+-------------------------+ | int f(void); | int f(); | +----------------------------+-------------------------+ | int (*f(void))(void); | int (*f())(); | +----------------------------+-------------------------+ | typedef int | typedef int (*f_t())(); | | (*f_t(void))(void); | | +----------------------------+-------------------------+ | 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> int_ptr); +void take_ownership_fn(std::unique_ptr<int> int_ptr); void f(int x) { - std::auto_ptr<int> a(new int(x)); - std::auto_ptr<int> b; + std::unique_ptr<int> a(new int(x)); + std::unique_ptr<int> 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 <utility> it may be necessary to add this include. The check will add the include directive when necessary. Known Limitations • If headers modification is not activated or if a header is not al- lowed 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 refer- ence 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 (other- wise what is the point in using them instead of a reference or a pointer?). // <3rd-party header...> std::auto_ptr<int> get_value(); const std::auto_ptr<int> & get_ref(); // <calling code (with migration)...> -std::auto_ptr<int> a(get_value()); +std::unique_ptr<int> a(get_value()); // ok, unique_ptr constructed from auto_ptr -const std::auto_ptr<int> & p = get_ptr(); +const std::unique_ptr<int> & p = get_ptr(); // won't compile • Non-instantiated templates aren't modified. template <typename X> void f() { std::auto_ptr<X> p; } // only 'f<int>()' (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 prac- tice to declare a copy constructor and an assignment operator as a pri- vate 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 pri- vate 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; }; Known Limitations • Notice that the migration example above leaves the private access specification untouched. You might want to run the check:doc:modern- ize-use-equals-delete <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 re- placed. Default is DISALLOW_COPY_AND_ASSIGN. See: https://en.cppreference.com/w/cpp/language/function#Deleted_functions 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<int> 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 ex- pensive 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 random- ness, 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<typename std::mt19937::result_type> 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-unary-static-assert The check diagnoses any static_assert declaration with an empty string literal and provides a fix-it to replace the declaration with a sin- gle-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 vari- able declarations to improve code readability and maintainability. For example: std::vector<int>::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 intro- duced in specific situations described below. Iterators Iterator type specifiers tend to be long and used frequently, espe- cially in loop constructs. Since the functions generating iterators have a common format, the type specifier can be replaced without ob- scuring the meaning of code while improving readability and maintain- ability. for (std::vector<int>::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 container 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 con- tainers: • 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, implementa- tion-specific types for which a type like std::vector<int>::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<int>::iterator I = MyVec.begin(); { using namespace std; list<int>::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<int, std::string>::const_iterator map_iterator; map_iterator J = MyMap.begin(); // The following implementation-specific iterator type for which // std::vector<int>::iterator could be a typedef would not be transformed. __gnu_cxx::__normal_iterator<int*, std::vector> K = MyVec.begin(); • The initializer for the variable being declared is not a braced ini- tializer 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 cases, 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 declara- tions, 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 cases, the declaration type can be replaced with auto improving readability and maintainability. TypeName *my_pointer = static_cast<TypeName>(my_param); // becomes auto *my_pointer = static_cast<TypeName>(my_param); The check handles static_cast, dynamic_cast, const_cast, reinter- pret_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. Known 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 ig- nore 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 RemoveStars option (see below) is set to non-zero, then *s in the type are also counted as a part of the type name. // MinTypeNameLength = 0, RemoveStars=0 int a = static_cast<int>(foo()); // ---> auto a = ... // length(bool *) = 4 bool *b = new bool; // ---> auto *b = ... unsigned c = static_cast<unsigned>(foo()); // ---> auto c = ... // MinTypeNameLength = 5, RemoveStars=0 int a = static_cast<int>(foo()); // ---> int a = ... bool b = static_cast<bool>(foo()); // ---> bool b = ... bool *pb = static_cast<bool*>(foo()); // ---> bool *pb = ... unsigned c = static_cast<unsigned>(foo()); // ---> auto c = ... // length(long <on-or-more-spaces> int) = 8 long int d = static_cast<long int>(foo()); // ---> auto d = ... // MinTypeNameLength = 5, RemoveStars=1 int a = static_cast<int>(foo()); // ---> int a = ... // length(int * * ) = 5 int **pa = static_cast<int**>(foo()); // ---> auto pa = ... bool b = static_cast<bool>(foo()); // ---> bool b = ... bool *pb = static_cast<bool*>(foo()); // ---> auto pb = ... unsigned c = static_cast<unsigned>(foo()); // ---> auto c = ... long int d = static_cast<long int>(foo()); // ---> auto d = ... RemoveStars If the option is set to non-zero (default is 0), 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<bool>(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 non-zero, the check will not give warnings inside macros. Default is 1. modernize-use-default This check has been renamed to modernize-use-equals-default. modernize-use-default-member-init This check converts a default constructor's 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 non-zero (default is 0), the check will initialise 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 non-zero (default is 1), the check will not warn about members declared inside macros. modernize-use-emplace The check flags insertions to an STL-style container done by calling the push_back method with an explicitly-constructed temporary of the container element type. In this case, the corresponding emplace_back method results in less verbose and potentially more efficient code. Right now the check doesn't support push_front and insert. It also doesn't support insert functions for associative containers because re- placing insert with emplace may result in speed regression, but it might get support with some addition flag in the future. By default only std::vector, std::deque, std::list are considered. This list can be modified using the ContainersWithPushBack option. Before: std::vector<MyClass> v; v.push_back(MyClass(21, 37)); std::vector<std::pair<int, int>> w; w.push_back(std::pair<int, int>(21, 37)); w.push_back(std::make_pair(21L, 37L)); After: std::vector<MyClass> v; v.emplace_back(21, 37); std::vector<std::pair<int, int>> w; w.emplace_back(21, 37); 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<boost::optional<std::string> > v; v.push_back("abc"); After: std::vector<boost::optional<std::string> > 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 re- placed. std::vector<std::unique_ptr<int>> v; v.push_back(std::unique_ptr<int>(new int(0))); auto *ptr = new int(1); v.push_back(std::unique_ptr<int>(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 inser- tion." 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. IgnoreImplicitConstructors When non-zero, the check will ignore implicitly constructed ar- guments of push_back, e.g. std::vector<std::string> v; v.push_back("a"); // Ignored when IgnoreImplicitConstructors is ``1``. Default is 0. SmartPointers Semicolon-separated list of class names of custom smart point- ers. 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. Example std::vector<MyTuple<int, bool, char>> x; x.push_back(MakeMyTuple(1, false, 'x')); transforms to: std::vector<MyTuple<int, bool, char>> x; x.emplace_back(1, false, 'x'); when TupleTypes is set to MyTuple and TupleMakeFunctions is set to MakeMyTuple. 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 explic- itly 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 non-zero, the check will not give warnings inside macros. Default is 1. modernize-use-equals-delete This check marks unimplemented private special member functions with = delete. To avoid false-positives, this check only applies in a trans- lation unit that has all other member functions implemented. struct A { private: A(const A&); A& operator=(const A&); }; // becomes struct A { private: A(const A&) = delete; A& operator=(const A&) = delete; }; IgnoreMacros If this option is set to non-zero (default is 1), the check will not warn about functions declared inside macros. 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 consid- ered by this check: • no [[nodiscard]], [[noreturn]], __attribute__((warn_unused_re- sult)), [[clang::warn_unused_result]] nor [[gcc::warn_unused_re- sult]] 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 alter- ing 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 use- ful 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 https://clang.llvm.org/docs/AttributeReference.html#nodiscard-warn-unused-result modernize-use-noexcept This check replaces deprecated dynamic exception specifications with the appropriate noexcept specification (introduced in C++11). By de- fault this check will replace throw() with noexcept, and throw(<excep- tion>[,...]) 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 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 option is set to NOEXCEPT. UseNoexceptFalse Enabled by default, disabling will generate fix-it hints that remove throwing dynamic exception specs, e.g., throw(<something>), 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 0. modernize-use-nullptr The check converts the usage of null pointer constants (eg. NULL, 0) to use the new C++11 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 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 overrid- den functions to be marked appropriately. Their presence allows compil- ers 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 non-zero, this check will not diagnose destructors. Default is 0. AllowOverrideAndFinal If set to non-zero, this check will not diagnose override as re- dundant 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-over- ride/gcc -Werror=suggest-override. Default is 0. 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 https://en.cppreference.com/w/cpp/language/override modernize-use-trailing-return-type Rewrites function signatures to use a trailing return type (introduced in C++11). This transformation is purely stylistic. The return type before the function name is replaced by auto and inserted after the function parameter list (and qualifiers). Example int f1(); inline int f2(int arg) noexcept; virtual float f3() const && = delete; transforms to: auto f1() -> int; inline auto f2(int arg) -> int noexcept; virtual auto f3() const && -> float = delete; Known Limitations The following categories of return types cannot be rewritten currently: * function pointers * member function pointers * member pointers * de- cltype, when it is the top level expression Unqualified names in the return type might erroneously refer to differ- ent entities after the rewrite. Preventing such errors requires a full lookup of all unqualified names present in the return type in the scope of the trailing return type location. This location includes e.g. function parameter names and members of the enclosing class (including all inherited classes). Such a lookup is currently not implemented. Given the following piece of code struct Object { long long value; }; Object f(unsigned Object) { return {Object * 2}; } class CC { int Object; struct Object m(); }; Object CC::m() { return {0}; } a careless rewrite would produce the following output: struct Object { long long value; }; auto f(unsigned Object) -> Object { return {Object * 2}; } // error class CC { int Object; auto m() -> struct Object; }; auto CC::m() -> Object { return {0}; } // error This code fails to compile because the Object in the context of f refers to the equally named function parameter. Similarly, the Object in the context of m refers to the equally named class member. The check can currently only detect a clash with a function parameter name. modernize-use-transparent-functors Prefer transparent functors to non-transparent ones. When using trans- parent functors, the type does not need to be repeated. The code is easier to read, maintain and less prone to errors. It is not possible to introduce unwanted conversions. // Non-transparent functor std::map<int, std::string, std::greater<int>> s; // Transparent functor. std::map<int, std::string, std::greater<>> s; // Non-transparent functor using MyFunctor = std::less<MyType>; It is not always a safe transformation though. The following case will be untouched to preserve the semantics. // Non-transparent functor std::map<const char *, std::string, std::greater<std::string>> s; Options SafeMode If the option is set to non-zero, the check will not diagnose cases where using a transparent functor cannot be guaranteed to produce identical results as the original code. The default value for this option is 0. This check requires using C++14 or higher to run. modernize-use-uncaught-exceptions This check will warn on calls to std::uncaught_exception and replace them with calls to std::uncaught_exceptions, since std::uncaught_excep- tion was deprecated in C++17. Below are a few examples of what kind of occurrences will be found and what they will be replaced with. #define MACRO1 std::uncaught_exception #define MACRO2 std::uncaught_exception int uncaught_exception() { return 0; } int main() { int res; res = uncaught_exception(); // No warning, since it is not the deprecated function from namespace std res = MACRO2(); // Warning, but will not be replaced res = std::uncaught_exception(); // Warning and replaced using std::uncaught_exception; // Warning and replaced res = uncaught_exception(); // Warning and replaced } After applying the fixes the code will look like the following: #define MACRO1 std::uncaught_exception #define MACRO2 std::uncaught_exception int uncaught_exception() { return 0; } int main() { int res; res = uncaught_exception(); res = MACRO2(); res = std::uncaught_exceptions(); using std::uncaught_exceptions; res = uncaught_exceptions(); } modernize-use-using The check converts the usage of typedef with using keyword. Before: typedef int variable; class Class{}; typedef void (Class::* MyPtrType)() const; typedef struct { int a; } R_t, *R_p; After: using variable = int; class Class{}; using MyPtrType = void (Class::*)() const; using R_t = struct { int a; }; using R_p = R_t*; This check requires using C++11 or higher to run. Options IgnoreMacros If set to non-zero, the check will not give warnings inside macros. Default is 1. mpi-buffer-deref This check verifies if a buffer passed to an MPI (Message Passing In- terface) function is sufficiently dereferenced. Buffers should be passed as a single pointer or array. As MPI function signatures specify void * for their buffer types, insufficiently dereferenced buffers can be passed, like for example as double pointers or multidimensional ar- rays, without a compiler warning emitted. Examples: // A double pointer is passed to the MPI function. char *buf; MPI_Send(&buf, 1, MPI_CHAR, 0, 0, MPI_COMM_WORLD); // A multidimensional array is passed to the MPI function. short buf[1][1]; MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); // A pointer to an array is passed to the MPI function. short *buf[1]; MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); mpi-type-mismatch This check verifies if buffer type and MPI (Message Passing Interface) datatype pairs match for used MPI functions. All MPI datatypes defined by the MPI standard (3.1) are verified by this check. User defined typedefs, custom MPI datatypes and null pointer constants are skipped, in the course of verification. Example: // In this case, the buffer type matches MPI datatype. char buf; MPI_Send(&buf, 1, MPI_CHAR, 0, 0, MPI_COMM_WORLD); // In the following case, the buffer type does not match MPI datatype. int buf; MPI_Send(&buf, 1, MPI_CHAR, 0, 0, MPI_COMM_WORLD); objc-avoid-nserror-init Finds improper initialization of NSError objects. According to Apple developer document, we should always use factory method errorWithDomain:code:userInfo: to create new NSError objects in- stead of [NSError alloc] init]. Otherwise it will lead to a warning message during runtime. The corresponding information about NSError creation: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ErrorHandlingCocoa/CreateCustomizeNSError/CreateCustomizeNSError.html objc-dealloc-in-category Finds implementations of -dealloc in Objective-C categories. The cate- gory implementation will override any -dealloc in the class implementa- tion, potentially causing issues. Classes implement -dealloc to perform important actions to deallocate an object. If a category on the class implements -dealloc, it will override the class's implementation and unexpected deallocation behav- ior may occur. objc-forbidden-subclassing Finds Objective-C classes which are subclasses of classes which are not designed to be subclassed. By default, includes a list of Objective-C classes which are publicly documented as not supporting subclassing. NOTE: Instead of using this check, for code under your control, you should add __attribute__((objc_subclassing_restricted)) before your @inter- face declarations to ensure the compiler prevents others from sub- classing your Objective-C classes. See https://clang.llvm.org/docs/AttributeReference.html#objc-subclassing-restricted Options ForbiddenSuperClassNames Semicolon-separated list of names of Objective-C classes which do not support subclassing. Defaults to ABNewPersonViewController;ABPeoplePickerNavigation- Controller;ABPersonViewController;ABUnknownPersonViewCon- troller;NSHashTable;NSMapTable;NSPointerArray;NSPointerFunc- tions;NSTimer;UIActionSheet;UIAlertView;UIImagePickerCon- troller;UITextInputMode;UIWebView. objc-missing-hash Finds Objective-C implementations that implement -isEqual: without also appropriately implementing -hash. Apple documentation highlights that objects that are equal must have the same hash value: https://developer.apple.com/documentation/objectivec/1418956-nsobject/1418795-isequal?language=objc Note that the check only verifies the presence of -hash in scenarios where its omission could result in unexpected behavior. The verifica- tion of the implementation of -hash is the responsibility of the devel- oper, e.g., through the addition of unit tests to verify the implemen- tation. objc-nsinvocation-argument-lifetime Finds calls to NSInvocation methods under ARC that don't have proper argument object lifetimes. When passing Objective-C objects as parame- ters to the NSInvocation methods getArgument:atIndex: and getReturn- Value:, the values are copied by value into the argument pointer, which leads to to incorrect releasing behavior if the object pointers are not declared __unsafe_unretained. For code: id arg; [invocation getArgument:&arg atIndex:2]; __strong id returnValue; [invocation getReturnValue:&returnValue]; The fix will be: __unsafe_unretained id arg; [invocation getArgument:&arg atIndex:2]; __unsafe_unretained id returnValue; [invocation getReturnValue:&returnValue]; The check will warn on being passed instance variable references that have lifetimes other than __unsafe_unretained, but does not propose a fix: // "id _returnValue" is declaration of instance variable of class. [invocation getReturnValue:&self->_returnValue]; objc-property-declaration Finds property declarations in Objective-C files that do not follow the pattern of property names in Apple's programming guide. The property name should be in the format of Lower Camel Case. For code: @property(nonatomic, assign) int LowerCamelCase; The fix will be: @property(nonatomic, assign) int lowerCamelCase; The check will only fix 'CamelCase' to 'camelCase'. In some other cases we will only provide warning messages since the property name could be complicated. Users will need to come up with a proper name by their own. This check also accepts special acronyms as prefixes or suffixes. Such prefixes or suffixes will suppress the Lower Camel Case check according to the guide: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingBasics.html#//apple_ref/doc/uid/20001281-1002931-BBCFHEAB For a full list of well-known acronyms: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/APIAbbreviations.html#//apple_ref/doc/uid/20001285-BCIHCGAE The corresponding style rule: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingIvarsAndTypes.html#//apple_ref/doc/uid/20001284-1001757 The check will also accept property declared in category with a prefix of lowercase letters followed by a '_' to avoid naming conflict. For example: @property(nonatomic, assign) int abc_lowerCamelCase; The corresponding style rule: https://developer.apple.com/library/content/qa/qa1908/_index.html objc-super-self Finds invocations of -self on super instances in initializers of sub- classes of NSObject and recommends calling a superclass initializer in- stead. Invoking -self on super instances in initializers is a common program- mer error when the programmer's original intent is to call a superclass initializer. Failing to call a superclass initializer breaks initial- izer chaining and can result in invalid object initialization. openmp-exception-escape Analyzes OpenMP Structured Blocks and checks that no exception escapes out of the Structured Block it was thrown in. As per the OpenMP specification, a structured block is an executable statement, possibly compound, with a single entry at the top and a sin- gle exit at the bottom. Which means, throw may not be used to to 'exit' out of the structured block. If an exception is not caught in the same structured block it was thrown in, the behaviour is undefined. FIXME: this check does not model SEH, setjmp/longjmp. WARNING! This check may be expensive on large source files. Options IgnoredExceptions Comma-separated list containing type names which are not counted as thrown exceptions in the check. Default value is an empty string. openmp-use-default-none Finds OpenMP directives that are allowed to contain a default clause, but either don't specify it or the clause is specified but with the kind other than none, and suggests to use the default(none) clause. Using default(none) clause forces developers to explicitly specify data sharing attributes for the variables referenced in the construct, thus making it obvious which variables are referenced, and what is their data sharing attribute, thus increasing readability and possibly making errors easier to spot. Example // ``for`` directive can not have ``default`` clause, no diagnostics. void n0(const int a) { #pragma omp for for (int b = 0; b < a; b++) ; } // ``parallel`` directive. // ``parallel`` directive can have ``default`` clause, but said clause is not // specified, diagnosed. void p0_0() { #pragma omp parallel ; // WARNING: OpenMP directive ``parallel`` does not specify ``default`` // clause. Consider specifying ``default(none)`` clause. } // ``parallel`` directive can have ``default`` clause, and said clause is // specified, with ``none`` kind, all good. void p0_1() { #pragma omp parallel default(none) ; } // ``parallel`` directive can have ``default`` clause, and said clause is // specified, but with ``shared`` kind, which is not ``none``, diagnose. void p0_2() { #pragma omp parallel default(shared) ; // WARNING: OpenMP directive ``parallel`` specifies ``default(shared)`` // clause. Consider using ``default(none)`` clause instead. } // ``parallel`` directive can have ``default`` clause, and said clause is // specified, but with ``firstprivate`` kind, which is not ``none``, diagnose. void p0_3() { #pragma omp parallel default(firstprivate) ; // WARNING: OpenMP directive ``parallel`` specifies ``default(firstprivate)`` // clause. Consider using ``default(none)`` clause instead. } performance-faster-string-find Optimize calls to std::string::find() and friends when the needle passed is a single character string literal. The character literal overload is more efficient. Examples: str.find("A"); // becomes str.find('A'); Options StringLikeClasses Semicolon-separated list of names of string-like classes. By de- fault only ::std::basic_string and ::std::basic_string_view are considered. The check will only consider member functions named find, rfind, find_first_of, find_first_not_of, find_last_of, or find_last_not_of within these classes. performance-for-range-copy Finds C++11 for ranges where the loop variable is copied in each itera- tion but it would suffice to obtain it by const reference. The check is only applied to loop variables of types that are expensive to copy which means they are not trivially copyable or have a non-triv- ial copy constructor or destructor. To ensure that it is safe to replace the copy with a const reference the following heuristic is employed: 1. The loop variable is const qualified. 2. The loop variable is not const, but only const methods or operators are invoked on it, or it is used as const reference or value argu- ment in constructors or function calls. Options WarnOnAllAutoCopies When non-zero, warns on any use of auto as the type of the range-based for loop variable. Default is 0. AllowedTypes A semicolon-separated list of names of types allowed to be copied in each iteration. Regular expressions are accepted, e.g. [Rr]ef(erence)?$ matches every type with suffix Ref, ref, Refer- ence and reference. The default is empty. performance-implicit-cast-in-loop This check has been renamed to performance-implicit-conversion-in-loop. performance-implicit-conversion-in-loop This warning appears in a range-based loop with a loop variable of const ref type where the type of the variable does not match the one returned by the iterator. This means that an implicit conversion hap- pens, which can for example result in expensive deep copies. Example: map<int, vector<string>> my_map; for (const pair<int, vector<string>>& p : my_map) {} // The iterator type is in fact pair<const int, vector<string>>, which means // that the compiler added a conversion, resulting in a copy of the vectors. The easiest solution is usually to use const auto& instead of writing the type manually. performance-inefficient-algorithm Warns on inefficient use of STL algorithms on associative containers. Associative containers implements some of the algorithms as methods which should be preferred to the algorithms in the algorithm header. The methods can take advantage of the order of the elements. std::set<int> s; auto it = std::find(s.begin(), s.end(), 43); // becomes auto it = s.find(43); std::set<int> s; auto c = std::count(s.begin(), s.end(), 43); // becomes auto c = s.count(43); performance-inefficient-string-concatenation This check warns about the performance overhead arising from concate- nating strings using the operator+, for instance: std::string a("Foo"), b("Bar"); a = a + b; Instead of this structure you should use operator+= or std::string's (std::basic_string) class member function append(). For instance: std::string a("Foo"), b("Baz"); for (int i = 0; i < 20000; ++i) { a = a + "Bar" + b; } Could be rewritten in a greatly more efficient way like: std::string a("Foo"), b("Baz"); for (int i = 0; i < 20000; ++i) { a.append("Bar").append(b); } And this can be rewritten too: void f(const std::string&) {} std::string a("Foo"), b("Baz"); void g() { f(a + "Bar" + b); } In a slightly more efficient way like: void f(const std::string&) {} std::string a("Foo"), b("Baz"); void g() { f(std::string(a).append("Bar").append(b)); } Options StrictMode When zero, the check will only check the string usage in while, for and for-range statements. Default is 0. performance-inefficient-vector-operation Finds possible inefficient std::vector operations (e.g. push_back, em- place_back) that may cause unnecessary memory reallocations. It can also find calls that add element to protobuf repeated field in a loop without calling Reserve() before the loop. Calling Reserve() first can avoid unnecessary memory reallocations. Currently, the check only detects following kinds of loops with a sin- gle statement body: • Counter-based for loops start with 0: std::vector<int> v; for (int i = 0; i < n; ++i) { v.push_back(n); // This will trigger the warning since the push_back may cause multiple // memory reallocations in v. This can be avoid by inserting a 'reserve(n)' // statement before the for statement. } SomeProto p; for (int i = 0; i < n; ++i) { p.add_xxx(n); // This will trigger the warning since the add_xxx may cause multiple memory // reallocations. This can be avoid by inserting a // 'p.mutable_xxx().Reserve(n)' statement before the for statement. } • For-range loops like for (range-declaration : range_expression), the type of range_expression can be std::vector, std::array, std::deque, std::set, std::unordered_set, std::map, std::unordered_set: std::vector<int> data; std::vector<int> v; for (auto element : data) { v.push_back(element); // This will trigger the warning since the 'push_back' may cause multiple // memory reallocations in v. This can be avoid by inserting a // 'reserve(data.size())' statement before the for statement. } Options VectorLikeClasses Semicolon-separated list of names of vector-like classes. By de- fault only ::std::vector is considered. EnableProto When non-zero, the check will also warn on inefficient opera- tions for proto repeated fields. Otherwise, the check only warns on inefficient vector operations. Default is 0. performance-move-const-arg The check warns • if std::move() is called with a constant argument, • if std::move() is called with an argument of a trivially-copyable type, • if the result of std::move() is passed as a const reference argument. In all three cases, the check will suggest a fix that removes the std::move(). Here are examples of each of the three cases: const string s; return std::move(s); // Warning: std::move of the const variable has no effect int x; return std::move(x); // Warning: std::move of the variable of a trivially-copyable type has no effect void f(const string &s); string s; f(std::move(s)); // Warning: passing result of std::move as a const reference argument; no move will actually happen Options CheckTriviallyCopyableMove If non-zero, enables detection of trivially copyable types that do not have a move constructor. Default is non-zero. performance-move-constructor-init "cert-oop11-cpp" redirects here as an alias for this check. The check flags user-defined move constructors that have a ctor-ini- tializer initializing a member or base class through a copy constructor instead of a move constructor. Options IncludeStyle A string specifying which include-style is used, llvm or google. Default is llvm. performance-no-automatic-move Finds local variables that cannot be automatically moved due to const- ness. Under certain conditions, local values are automatically moved out when returning from a function. A common mistake is to declare local lvalue variables const, which prevents the move. Example [1]: StatusOr<std::vector<int>> Cool() { std::vector<int> obj = ...; return obj; // calls StatusOr::StatusOr(std::vector<int>&&) } StatusOr<std::vector<int>> NotCool() { const std::vector<int> obj = ...; return obj; // calls `StatusOr::StatusOr(const std::vector<int>&)` } The former version (Cool) should be preferred over the latter (Uncool) as it will avoid allocations and potentially large memory copies. Semantics In the example above, StatusOr::StatusOr(T&&) have the same semantics as long as the copy and move constructors for T have the same seman- tics. Note that there is no guarantee that S::S(T&&) and S::S(const T&) have the same semantics for any single S, so we're not providing auto- mated fixes for this check, and judgement should be exerted when making the suggested changes. -Wreturn-std-move Another case where the move cannot happen is the following: StatusOr<std::vector<int>> Uncool() { std::vector<int>&& obj = ...; return obj; // calls `StatusOr::StatusOr(const std::vector<int>&)` } In that case the fix is more consensual: just return std::move(obj). This is handled by the -Wreturn-std-move warning. performance-noexcept-move-constructor The check flags user-defined move constructors and assignment operators not marked with noexcept or marked with noexcept(expr) where expr eval- uates to false (but is not a false literal itself). Move constructors of all the types used with STL containers, for exam- ple, need to be declared noexcept. Otherwise STL will choose copy con- structors instead. The same is valid for move assignment operations. performance-trivially-destructible Finds types that could be made trivially-destructible by removing out-of-line defaulted destructor declarations. struct A: TrivialType { ~A(); // Makes A non-trivially-destructible. TrivialType trivial_fields; }; A::~A() = default; performance-type-promotion-in-math-fn Finds calls to C math library functions (from math.h or, in C++, cmath) with implicit float to double promotions. For example, warns on ::sin(0.f), because this funciton's parameter is a double. You probably meant to call std::sin(0.f) (in C++), or sinf(0.f) (in C). float a; asin(a); // becomes float a; std::asin(a); performance-unnecessary-copy-initialization Finds local variable declarations that are initialized using the copy constructor of a non-trivially-copyable type but it would suffice to obtain a const reference. The check is only applied if it is safe to replace the copy by a const reference. This is the case when the variable is const qualified or when it is only used as a const, i.e. only const methods or operators are invoked on it, or it is used as const reference or value argument in constructors or function calls. Example: const string& constReference(); void Function() { // The warning will suggest making this a const reference. const string UnnecessaryCopy = constReference(); } struct Foo { const string& name() const; }; void Function(const Foo& foo) { // The warning will suggest making this a const reference. string UnnecessaryCopy1 = foo.name(); UnnecessaryCopy1.find("bar"); // The warning will suggest making this a const reference. string UnnecessaryCopy2 = UnnecessaryCopy1; UnnecessaryCopy2.find("bar"); } Options AllowedTypes A semicolon-separated list of names of types allowed to be ini- tialized by copying. Regular expressions are accepted, e.g. [Rr]ef(erence)?$ matches every type with suffix Ref, ref, Refer- ence and reference. The default is empty. performance-unnecessary-value-param Flags value parameter declarations of expensive to copy types that are copied for each invocation but it would suffice to pass them by const reference. The check is only applied to parameters of types that are expensive to copy which means they are not trivially copyable or have a non-trivial copy constructor or destructor. To ensure that it is safe to replace the value parameter with a const reference the following heuristic is employed: 1. the parameter is const qualified; 2. the parameter is not const, but only const methods or operators are invoked on it, or it is used as const reference or value argument in constructors or function calls. Example: void f(const string Value) { // The warning will suggest making Value a reference. } void g(ExpensiveToCopy Value) { // The warning will suggest making Value a const reference. Value.ConstMethd(); ExpensiveToCopy Copy(Value); } If the parameter is not const, only copied or assigned once and has a non-trivial move-constructor or move-assignment operator respectively the check will suggest to move it. Example: void setValue(string Value) { Field = Value; } Will become: #include <utility> void setValue(string Value) { Field = std::move(Value); } Options IncludeStyle A string specifying which include-style is used, llvm or google. Default is llvm. AllowedTypes A semicolon-separated list of names of types allowed to be passed by value. Regular expressions are accepted, e.g. [Rr]ef(erence)?$ matches every type with suffix Ref, ref, Refer- ence and reference. The default is empty. portability-restrict-system-includes Checks to selectively allow or disallow a configurable list of system headers. For example: In order to only allow zlib.h from the system you would set the options to -*,zlib.h. #include <curses.h> // Bad: disallowed system header. #include <openssl/ssl.h> // Bad: disallowed system header. #include <zlib.h> // Good: allowed system header. #include "src/myfile.h" // Good: non-system header always allowed. In order to allow everything except zlib.h from the system you would set the options to *,-zlib.h. #include <curses.h> // Good: allowed system header. #include <openssl/ssl.h> // Good: allowed system header. #include <zlib.h> // Bad: disallowed system header. #include "src/myfile.h" // Good: non-system header always allowed. Since the options support globbing you can use wildcarding to allow groups of headers. -*,openssl/*.h will allow all openssl headers but disallow any others. #include <curses.h> // Bad: disallowed system header. #include <openssl/ssl.h> // Good: allowed system header. #include <openssl/rsa.h> // Good: allowed system header. #include <zlib.h> // Bad: disallowed system header. #include "src/myfile.h" // Good: non-system header always allowed. Options Includes A string containing a comma separated glob list of allowed in- clude 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 allows all includes. portability-simd-intrinsics Finds SIMD intrinsics calls and suggests std::experimental::simd (- P0214) alternatives. If the option Suggest is set to non-zero, for _mm_add_epi32(a, b); // x86 vec_add(a, b); // Power the check suggests an alternative: operator+ on std::experimental::simd objects. Otherwise, it just complains the intrinsics are non-portable (and there are P0214 alternatives). Many architectures provide SIMD operations (e.g. x86 SSE/AVX, Power Al- tiVec/VSX, ARM NEON). It is common that SIMD code implementing the same algorithm, is written in multiple target-dispatching pieces to optimize for different architectures or micro-architectures. The C++ standard proposal P0214 and its extensions cover many common SIMD operations. By migrating from target-dependent intrinsics to P0214 operations, the SIMD code can be simplified and pieces for different targets can be unified. Refer to P0214 for introduction and motivation for the data-parallel standard library. Options Suggest If this option is set to non-zero (default is 0), the check will suggest P0214 alternatives, otherwise it only points out the in- trinsic function is non-portable. Std The namespace used to suggest P0214 alternatives. If not speci- fied, std:: for -std=c++20 and std::experimental:: for -std=c++11. readability-avoid-const-params-in-decls Checks whether a function declaration has parameters that are top level const. const values in declarations do not affect the signature of a function, so they should not be put there. Examples: void f(const string); // Bad: const is top level. void f(const string&); // Good: const is not top level. readability-braces-around-statements google-readability-braces-around-statements redirects here as an alias for this check. Checks that bodies of if statements and loops (for, do while, and while) are inside braces. Before: if (condition) statement; After: if (condition) { statement; } Options ShortStatementLines Defines the minimal number of lines that the statement should have in order to trigger this check. The number of lines is counted from the end of condition or ini- tial keyword (do/else) until the last line of the inner state- ment. Default value 0 means that braces will be added to all statements (not having them already). readability-const-return-type Checks for functions with a const-qualified return type and recommends removal of the const keyword. Such use of const is usually superfluous, and can prevent valuable compiler optimizations. Does not (yet) fix trailing return types. Examples: const int foo(); const Clazz foo(); Clazz *const foo(); Note that this applies strictly to top-level qualification, which ex- cludes pointers or references to const values. For example, these are fine: const int* foo(); const int& foo(); const Clazz* foo(); readability-container-size-empty Checks whether a call to the size() method can be replaced with a call to empty(). The emptiness of a container should be checked using the empty() method instead of the size() method. It is not guaranteed that size() is a constant-time function, and it is generally more efficient and also shows clearer intent to use empty(). Furthermore some containers may implement the empty() method but not implement the size() method. Using empty() whenever possible makes it easier to switch to another con- tainer in the future. The check issues warning if a container has size() and empty() methods matching following signatures: size_type size() const; bool empty() const; size_type can be any kind of integer type. readability-convert-member-functions-to-static Finds non-static member functions that can be made static because the functions don't use this. After applying modifications as suggested by the check, running the check again might find more opportunities to mark member functions sta- tic. After making a member function static, you might want to run the check readability-static-accessed-through-instance to replace calls like In- stance.method() by Class::method(). readability-delete-null-pointer Checks the if statements where a pointer's existence is checked and then deletes the pointer. The check is unnecessary as deleting a null pointer has no effect. int *p; if (p) delete p; readability-deleted-default Checks that constructors and assignment operators marked as = default are not actually deleted by the compiler. class Example { public: // This constructor is deleted because I is missing a default value. Example() = default; // This is fine. Example(const Example& Other) = default; // This operator is deleted because I cannot be assigned (it is const). Example& operator=(const Example& Other) = default; private: const int I; }; readability-else-after-return LLVM Coding Standards advises to reduce indentation where possible and where it makes understanding code easier. Early exit is one of the suggested enforcements of that. Please do not use else or else if after something that interrupts control flow - like return, break, continue, throw. The following piece of code illustrates how the check works. This piece of code: void foo(int Value) { int Local = 0; for (int i = 0; i < 42; i++) { if (Value == 1) { return; } else { Local++; } if (Value == 2) continue; else Local++; if (Value == 3) { throw 42; } else { Local++; } } } Would be transformed into: void foo(int Value) { int Local = 0; for (int i = 0; i < 42; i++) { if (Value == 1) { return; } Local++; if (Value == 2) continue; Local++; if (Value == 3) { throw 42; } Local++; } } Options WarnOnUnfixable When true, emit a warning for cases where the check can't output a Fix-It. These can occur with declarations inside the else branch that would have an extended lifetime if the else branch was removed. Default value is true. WarnOnConditionVariables When true, the check will attempt to refactor a variable defined inside the condition of the if statement that is used in the else branch defining them just before the if statement. This can only be done if the if statement is the last statement in its parents scope. Default value is true. LLVM alias There is an alias of this check called llvm-else-after-return. In that version the options WarnOnUnfixable and WarnOnConditionVariables are both set to false by default. This check helps to enforce this LLVM Coding Standards recommendation. readability-function-size google-readability-function-size redirects here as an alias for this check. Checks for large functions based on various metrics. Options LineThreshold Flag functions exceeding this number of lines. The default is -1 (ignore the number of lines). StatementThreshold Flag functions exceeding this number of statements. This may differ significantly from the number of lines for macro-heavy code. The default is 800. BranchThreshold Flag functions exceeding this number of control statements. The default is -1 (ignore the number of branches). ParameterThreshold Flag functions that exceed a specified number of parameters. The default is -1 (ignore the number of parameters). NestingThreshold Flag compound statements which create next nesting level after NestingThreshold. This may differ significantly from the ex- pected value for macro-heavy code. The default is -1 (ignore the nesting level). VariableThreshold Flag functions exceeding this number of variables declared in the body. The default is -1 (ignore the number of variables). Please note that function parameters and variables declared in lambdas, GNU Statement Expressions, and nested class inline functions are not counted. readability-identifier-naming Checks for identifiers naming style mismatch. This check will try to enforce coding guidelines on the identifiers naming. It supports one of the following casing types and tries to con- vert from one to another if a mismatch is detected Casing types include: • lower_case, • UPPER_CASE, • camelBack, • CamelCase, • camel_Snake_Back, • Camel_Snake_Case, • aNy_CasE. It also supports a fixed prefix and suffix that will be prepended or appended to the identifiers, regardless of the casing. Many configuration options are available, in order to be able to create different rules for different kinds of identifiers. In general, the rules are falling back to a more generic rule if the specific case is not configured. The naming of virtual methods is reported where they occur in the base class, but not where they are overridden, as it can't be fixed locally there. This also applies for pseudo-override patterns like CRTP. Options The following options are describe below: • AbstractClassCase, AbstractClassPrefix, AbstractClassSuffix • AggressiveDependentMemberLookup • ClassCase, ClassPrefix, ClassSuffix • ClassConstantCase, ClassConstantPrefix, ClassConstantSuffix • ClassMemberCase, ClassMemberPrefix, ClassMemberSuffix • ClassMethodCase, ClassMethodPrefix, ClassMethodSuffix • ConstantCase, ConstantPrefix, ConstantSuffix • ConstantMemberCase, ConstantMemberPrefix, ConstantMemberSuffix • ConstantParameterCase, ConstantParameterPrefix, ConstantParameterSuffix • ConstantPointerParameterCase, ConstantPointerParameterPrefix, ConstantPointerParameterSuffix • ConstexprFunctionCase, ConstexprFunctionPrefix, ConstexprFunctionSuffix • ConstexprMethodCase, ConstexprMethodPrefix, ConstexprMethodSuffix • ConstexprVariableCase, ConstexprVariablePrefix, ConstexprVariableSuffix • EnumCase, EnumPrefix, EnumSuffix • EnumConstantCase, EnumConstantPrefix, EnumConstantSuffix • FunctionCase, FunctionPrefix, FunctionSuffix • GlobalConstantCase, GlobalConstantPrefix, GlobalConstantSuffix • GlobalConstantPointerCase, GlobalConstantPointerPrefix, GlobalConstantPointerSuffix • GlobalFunctionCase, GlobalFunctionPrefix, GlobalFunctionSuffix • GlobalPointerCase, GlobalPointerPrefix, GlobalPointerSuffix • GlobalVariableCase, GlobalVariablePrefix, GlobalVariableSuffix • IgnoreMainLikeFunctions • InlineNamespaceCase, InlineNamespacePrefix, InlineNamespaceSuffix • LocalConstantCase, LocalConstantPrefix, LocalConstantSuffix • LocalConstantPointerCase, LocalConstantPointerPrefix, LocalConstantPointerSuffix • LocalPointerCase, LocalPointerPrefix, LocalPointerSuffix • LocalVariableCase, LocalVariablePrefix, LocalVariableSuffix • MacroDefinitionCase, MacroDefinitionPrefix, MacroDefinitionSuffix • MemberCase, MemberPrefix, MemberSuffix • MethodCase, MethodPrefix, MethodSuffix • NamespaceCase, NamespacePrefix, NamespaceSuffix • ParameterCase, ParameterPrefix, ParameterSuffix • ParameterPackCase, ParameterPackPrefix, ParameterPackSuffix • PointerParameterCase, PointerParameterPrefix, PointerParameterSuffix • PrivateMemberCase, PrivateMemberPrefix, PrivateMemberSuffix • PrivateMethodCase, PrivateMethodPrefix, PrivateMethodSuffix • ProtectedMemberCase, ProtectedMemberPrefix, ProtectedMemberSuffix • ProtectedMethodCase, ProtectedMethodPrefix, ProtectedMethodSuffix • PublicMemberCase, PublicMemberPrefix, PublicMemberSuffix • PublicMethodCase, PublicMethodPrefix, PublicMethodSuffix • StaticConstantCase, StaticConstantPrefix, StaticConstantSuffix • StaticVariableCase, StaticVariablePrefix, StaticVariableSuffix • StructCase, StructPrefix, StructSuffix • TemplateParameterCase, TemplateParameterPrefix, TemplateParameterSuffix • TemplateTemplateParameterCase, TemplateTemplateParameterPrefix, TemplateTemplateParameterSuffix • TypeAliasCase, TypeAliasPrefix, TypeAliasSuffix • TypedefCase, TypedefPrefix, TypedefSuffix • TypeTemplateParameterCase, TypeTemplateParameterPrefix, TypeTemplateParameterSuffix • UnionCase, UnionPrefix, UnionSuffix • ValueTemplateParameterCase, ValueTemplateParameterPrefix, ValueTemplateParameterSuffix • VariableCase, VariablePrefix, VariableSuffix • VirtualMethodCase, VirtualMethodPrefix, VirtualMethodSuffix AbstractClassCase When defined, the check will ensure abstract class names conform to the selected casing. AbstractClassPrefix When defined, the check will ensure abstract class names will add the prefixed with the given value (regardless of casing). AbstractClassSuffix When defined, the check will ensure abstract class names will add the suffix with the given value (regardless of casing). For example using values of: • AbstractClassCase of lower_case • AbstractClassPrefix of pre_ • AbstractClassSuffix of _post Identifies and/or transforms abstract class names as follows: Before: class ABSTRACT_CLASS { public: ABSTRACT_CLASS(); }; After: class pre_abstract_class_post { public: pre_abstract_class_post(); }; AggressiveDependentMemberLookup When set to 1 the check will look in dependent base classes for dependent member references that need changing. This can lead to errors with template specializations so the default value is 0. For example using values of: • ClassMemberCase of lower_case Before: template <typename T> struct Base { T BadNamedMember; }; template <typename T> struct Derived : Base<T> { void reset() { this->BadNamedMember = 0; } }; After if AggressiveDependentMemberLookup is 0: template <typename T> struct Base { T bad_named_member; }; template <typename T> struct Derived : Base<T> { void reset() { this->BadNamedMember = 0; } }; After if AggressiveDependentMemberLookup is 1: template <typename T> struct Base { T bad_named_member; }; template <typename T> struct Derived : Base<T> { void reset() { this->bad_named_member = 0; } }; ClassCase When defined, the check will ensure class names conform to the selected casing. ClassPrefix When defined, the check will ensure class names will add the prefixed with the given value (regardless of casing). ClassSuffix When defined, the check will ensure class names will add the suffix with the given value (regardless of casing). For example using values of: • ClassCase of lower_case • ClassPrefix of pre_ • ClassSuffix of _post Identifies and/or transforms class names as follows: Before: class FOO { public: FOO(); ~FOO(); }; After: class pre_foo_post { public: pre_foo_post(); ~pre_foo_post(); }; ClassConstantCase When defined, the check will ensure class constant names conform to the selected casing. ClassConstantPrefix When defined, the check will ensure class constant names will add the prefixed with the given value (regardless of casing). ClassConstantSuffix When defined, the check will ensure class constant names will add the suffix with the given value (regardless of casing). For example using values of: • ClassConstantCase of lower_case • ClassConstantPrefix of pre_ • ClassConstantSuffix of _post Identifies and/or transforms class constant names as follows: Before: class FOO { public: static const int CLASS_CONSTANT; }; After: class FOO { public: static const int pre_class_constant_post; }; ClassMemberCase When defined, the check will ensure class member names conform to the selected casing. ClassMemberPrefix When defined, the check will ensure class member names will add the prefixed with the given value (regardless of casing). ClassMemberSuffix When defined, the check will ensure class member names will add the suffix with the given value (regardless of casing). For example using values of: • ClassMemberCase of lower_case • ClassMemberPrefix of pre_ • ClassMemberSuffix of _post Identifies and/or transforms class member names as follows: Before: class FOO { public: static int CLASS_CONSTANT; }; After: class FOO { public: static int pre_class_constant_post; }; ClassMethodCase When defined, the check will ensure class method names conform to the selected casing. ClassMethodPrefix When defined, the check will ensure class method names will add the prefixed with the given value (regardless of casing). ClassMethodSuffix When defined, the check will ensure class method names will add the suffix with the given value (regardless of casing). For example using values of: • ClassMethodCase of lower_case • ClassMethodPrefix of pre_ • ClassMethodSuffix of _post Identifies and/or transforms class method names as follows: Before: class FOO { public: int CLASS_MEMBER(); }; After: class FOO { public: int pre_class_member_post(); }; ConstantCase When defined, the check will ensure constant names conform to the selected casing. ConstantPrefix When defined, the check will ensure constant names will add the prefixed with the given value (regardless of casing). ConstantSuffix When defined, the check will ensure constant names will add the suffix with the given value (regardless of casing). For example using values of: • ConstantCase of lower_case • ConstantPrefix of pre_ • ConstantSuffix of _post Identifies and/or transforms constant names as follows: Before: void function() { unsigned const MyConst_array[] = {1, 2, 3}; } After: void function() { unsigned const pre_myconst_array_post[] = {1, 2, 3}; } ConstantMemberCase When defined, the check will ensure constant member names con- form to the selected casing. ConstantMemberPrefix When defined, the check will ensure constant member names will add the prefixed with the given value (regardless of casing). ConstantMemberSuffix When defined, the check will ensure constant member names will add the suffix with the given value (regardless of casing). For example using values of: • ConstantMemberCase of lower_case • ConstantMemberPrefix of pre_ • ConstantMemberSuffix of _post Identifies and/or transforms constant member names as follows: Before: class Foo { char const MY_ConstMember_string[4] = "123"; } After: class Foo { char const pre_my_constmember_string_post[4] = "123"; } ConstantParameterCase When defined, the check will ensure constant parameter names conform to the selected casing. ConstantParameterPrefix When defined, the check will ensure constant parameter names will add the prefixed with the given value (regardless of cas- ing). ConstantParameterSuffix When defined, the check will ensure constant parameter names will add the suffix with the given value (regardless of casing). For example using values of: • ConstantParameterCase of lower_case • ConstantParameterPrefix of pre_ • ConstantParameterSuffix of _post Identifies and/or transforms constant parameter names as follows: Before: void GLOBAL_FUNCTION(int PARAMETER_1, int const CONST_parameter); After: void GLOBAL_FUNCTION(int PARAMETER_1, int const pre_const_parameter_post); ConstantPointerParameterCase When defined, the check will ensure constant pointer parameter names conform to the selected casing. ConstantPointerParameterPrefix When defined, the check will ensure constant pointer parameter names will add the prefixed with the given value (regardless of casing). ConstantPointerParameterSuffix When defined, the check will ensure constant pointer parameter names will add the suffix with the given value (regardless of casing). For example using values of: • ConstantPointerParameterCase of lower_case • ConstantPointerParameterPrefix of pre_ • ConstantPointerParameterSuffix of _post Identifies and/or transforms constant pointer parameter names as fol- lows: Before: void GLOBAL_FUNCTION(int const *CONST_parameter); After: void GLOBAL_FUNCTION(int const *pre_const_parameter_post); ConstexprFunctionCase When defined, the check will ensure constexpr function names conform to the selected casing. ConstexprFunctionPrefix When defined, the check will ensure constexpr function names will add the prefixed with the given value (regardless of cas- ing). ConstexprFunctionSuffix When defined, the check will ensure constexpr function names will add the suffix with the given value (regardless of casing). For example using values of: • ConstexprFunctionCase of lower_case • ConstexprFunctionPrefix of pre_ • ConstexprFunctionSuffix of _post Identifies and/or transforms constexpr function names as follows: Before: constexpr int CE_function() { return 3; } After: constexpr int pre_ce_function_post() { return 3; } ConstexprMethodCase When defined, the check will ensure constexpr method names con- form to the selected casing. ConstexprMethodPrefix When defined, the check will ensure constexpr method names will add the prefixed with the given value (regardless of casing). ConstexprMethodSuffix When defined, the check will ensure constexpr method names will add the suffix with the given value (regardless of casing). For example using values of: • ConstexprMethodCase of lower_case • ConstexprMethodPrefix of pre_ • ConstexprMethodSuffix of _post Identifies and/or transforms constexpr method names as follows: Before: class Foo { public: constexpr int CST_expr_Method() { return 2; } } After: class Foo { public: constexpr int pre_cst_expr_method_post() { return 2; } } ConstexprVariableCase When defined, the check will ensure constexpr variable names conform to the selected casing. ConstexprVariablePrefix When defined, the check will ensure constexpr variable names will add the prefixed with the given value (regardless of cas- ing). ConstexprVariableSuffix When defined, the check will ensure constexpr variable names will add the suffix with the given value (regardless of casing). For example using values of: • ConstexprVariableCase of lower_case • ConstexprVariablePrefix of pre_ • ConstexprVariableSuffix of _post Identifies and/or transforms constexpr variable names as follows: Before: constexpr int ConstExpr_variable = MyConstant; After: constexpr int pre_constexpr_variable_post = MyConstant; EnumCase When defined, the check will ensure enumeration names conform to the selected casing. EnumPrefix When defined, the check will ensure enumeration names will add the prefixed with the given value (regardless of casing). EnumSuffix When defined, the check will ensure enumeration names will add the suffix with the given value (regardless of casing). For example using values of: • EnumCase of lower_case • EnumPrefix of pre_ • EnumSuffix of _post Identifies and/or transforms enumeration names as follows: Before: enum FOO { One, Two, Three }; After: enum pre_foo_post { One, Two, Three }; EnumConstantCase When defined, the check will ensure enumeration constant names conform to the selected casing. EnumConstantPrefix When defined, the check will ensure enumeration constant names will add the prefixed with the given value (regardless of cas- ing). EnumConstantSuffix When defined, the check will ensure enumeration constant names will add the suffix with the given value (regardless of casing). For example using values of: • EnumConstantCase of lower_case • EnumConstantPrefix of pre_ • EnumConstantSuffix of _post Identifies and/or transforms enumeration constant names as follows: Before: enum FOO { One, Two, Three }; After: enum FOO { pre_One_post, pre_Two_post, pre_Three_post }; FunctionCase When defined, the check will ensure function names conform to the selected casing. FunctionPrefix When defined, the check will ensure function names will add the prefixed with the given value (regardless of casing). FunctionSuffix When defined, the check will ensure function names will add the suffix with the given value (regardless of casing). For example using values of: • FunctionCase of lower_case • FunctionPrefix of pre_ • FunctionSuffix of _post Identifies and/or transforms function names as follows: Before: char MY_Function_string(); After: char pre_my_function_string_post(); GlobalConstantCase When defined, the check will ensure global constant names con- form to the selected casing. GlobalConstantPrefix When defined, the check will ensure global constant names will add the prefixed with the given value (regardless of casing). GlobalConstantSuffix When defined, the check will ensure global constant names will add the suffix with the given value (regardless of casing). For example using values of: • GlobalConstantCase of lower_case • GlobalConstantPrefix of pre_ • GlobalConstantSuffix of _post Identifies and/or transforms global constant names as follows: Before: unsigned const MyConstGlobal_array[] = {1, 2, 3}; After: unsigned const pre_myconstglobal_array_post[] = {1, 2, 3}; GlobalConstantPointerCase When defined, the check will ensure global constant pointer names conform to the selected casing. GlobalConstantPointerPrefix When defined, the check will ensure global constant pointer names will add the prefixed with the given value (regardless of casing). GlobalConstantPointerSuffix When defined, the check will ensure global constant pointer names will add the suffix with the given value (regardless of casing). For example using values of: • GlobalConstantPointerCase of lower_case • GlobalConstantPointerPrefix of pre_ • GlobalConstantPointerSuffix of _post Identifies and/or transforms global constant pointer names as follows: Before: int *const MyConstantGlobalPointer = nullptr; After: int *const pre_myconstantglobalpointer_post = nullptr; GlobalFunctionCase When defined, the check will ensure global function names con- form to the selected casing. GlobalFunctionPrefix When defined, the check will ensure global function names will add the prefixed with the given value (regardless of casing). GlobalFunctionSuffix When defined, the check will ensure global function names will add the suffix with the given value (regardless of casing). For example using values of: • GlobalFunctionCase of lower_case • GlobalFunctionPrefix of pre_ • GlobalFunctionSuffix of _post Identifies and/or transforms global function names as follows: Before: void GLOBAL_FUNCTION(int PARAMETER_1, int const CONST_parameter); After: void pre_global_function_post(int PARAMETER_1, int const CONST_parameter); GlobalPointerCase When defined, the check will ensure global pointer names conform to the selected casing. GlobalPointerPrefix When defined, the check will ensure global pointer names will add the prefixed with the given value (regardless of casing). GlobalPointerSuffix When defined, the check will ensure global pointer names will add the suffix with the given value (regardless of casing). For example using values of: • GlobalPointerCase of lower_case • GlobalPointerPrefix of pre_ • GlobalPointerSuffix of _post Identifies and/or transforms global pointer names as follows: Before: int *GLOBAL3; After: int *pre_global3_post; GlobalVariableCase When defined, the check will ensure global variable names con- form to the selected casing. GlobalVariablePrefix When defined, the check will ensure global variable names will add the prefixed with the given value (regardless of casing). GlobalVariableSuffix When defined, the check will ensure global variable names will add the suffix with the given value (regardless of casing). For example using values of: • GlobalVariableCase of lower_case • GlobalVariablePrefix of pre_ • GlobalVariableSuffix of _post Identifies and/or transforms global variable names as follows: Before: int GLOBAL3; After: int pre_global3_post; IgnoreMainLikeFunctions When set to 1 functions that have a similar signature to main or wmain won't enforce checks on the names of their parameters. Default value is 0. InlineNamespaceCase When defined, the check will ensure inline namespaces names con- form to the selected casing. InlineNamespacePrefix When defined, the check will ensure inline namespaces names will add the prefixed with the given value (regardless of casing). InlineNamespaceSuffix When defined, the check will ensure inline namespaces names will add the suffix with the given value (regardless of casing). For example using values of: • InlineNamespaceCase of lower_case • InlineNamespacePrefix of pre_ • InlineNamespaceSuffix of _post Identifies and/or transforms inline namespaces names as follows: Before: namespace FOO_NS { inline namespace InlineNamespace { ... } } // namespace FOO_NS After: namespace FOO_NS { inline namespace pre_inlinenamespace_post { ... } } // namespace FOO_NS LocalConstantCase When defined, the check will ensure local constant names conform to the selected casing. LocalConstantPrefix When defined, the check will ensure local constant names will add the prefixed with the given value (regardless of casing). LocalConstantSuffix When defined, the check will ensure local constant names will add the suffix with the given value (regardless of casing). For example using values of: • LocalConstantCase of lower_case • LocalConstantPrefix of pre_ • LocalConstantSuffix of _post Identifies and/or transforms local constant names as follows: Before: void foo() { int const local_Constant = 3; } After: void foo() { int const pre_local_constant_post = 3; } LocalConstantPointerCase When defined, the check will ensure local constant pointer names conform to the selected casing. LocalConstantPointerPrefix When defined, the check will ensure local constant pointer names will add the prefixed with the given value (regardless of cas- ing). LocalConstantPointerSuffix When defined, the check will ensure local constant pointer names will add the suffix with the given value (regardless of casing). For example using values of: • LocalConstantPointerCase of lower_case • LocalConstantPointerPrefix of pre_ • LocalConstantPointerSuffix of _post Identifies and/or transforms local constant pointer names as follows: Before: void foo() { int const *local_Constant = 3; } After: void foo() { int const *pre_local_constant_post = 3; } LocalPointerCase When defined, the check will ensure local pointer names conform to the selected casing. LocalPointerPrefix When defined, the check will ensure local pointer names will add the prefixed with the given value (regardless of casing). LocalPointerSuffix When defined, the check will ensure local pointer names will add the suffix with the given value (regardless of casing). For example using values of: • LocalPointerCase of lower_case • LocalPointerPrefix of pre_ • LocalPointerSuffix of _post Identifies and/or transforms local pointer names as follows: Before: void foo() { int *local_Constant; } After: void foo() { int *pre_local_constant_post; } LocalVariableCase When defined, the check will ensure local variable names conform to the selected casing. LocalVariablePrefix When defined, the check will ensure local variable names will add the prefixed with the given value (regardless of casing). LocalVariableSuffix When defined, the check will ensure local variable names will add the suffix with the given value (regardless of casing). For example using values of: • LocalVariableCase of lower_case • LocalVariablePrefix of pre_ • LocalVariableSuffix of _post Identifies and/or transforms local variable names as follows: Before: void foo() { int local_Constant; } After: void foo() { int pre_local_constant_post; } MacroDefinitionCase When defined, the check will ensure macro definitions conform to the selected casing. MacroDefinitionPrefix When defined, the check will ensure macro definitions will add the prefixed with the given value (regardless of casing). MacroDefinitionSuffix When defined, the check will ensure macro definitions will add the suffix with the given value (regardless of casing). For example using values of: • MacroDefinitionCase of lower_case • MacroDefinitionPrefix of pre_ • MacroDefinitionSuffix of _post Identifies and/or transforms macro definitions as follows: Before: #define MY_MacroDefinition After: #define pre_my_macro_definition_post Note: This will not warn on builtin macros or macros defined on the command line using the -D flag. MemberCase When defined, the check will ensure member names conform to the selected casing. MemberPrefix When defined, the check will ensure member names will add the prefixed with the given value (regardless of casing). MemberSuffix When defined, the check will ensure member names will add the suffix with the given value (regardless of casing). For example using values of: • MemberCase of lower_case • MemberPrefix of pre_ • MemberSuffix of _post Identifies and/or transforms member names as follows: Before: class Foo { char MY_ConstMember_string[4]; } After: class Foo { char pre_my_constmember_string_post[4]; } MethodCase When defined, the check will ensure method names conform to the selected casing. MethodPrefix When defined, the check will ensure method names will add the prefixed with the given value (regardless of casing). MethodSuffix When defined, the check will ensure method names will add the suffix with the given value (regardless of casing). For example using values of: • MethodCase of lower_case • MethodPrefix of pre_ • MethodSuffix of _post Identifies and/or transforms method names as follows: Before: class Foo { char MY_Method_string(); } After: class Foo { char pre_my_method_string_post(); } NamespaceCase When defined, the check will ensure namespace names conform to the selected casing. NamespacePrefix When defined, the check will ensure namespace names will add the prefixed with the given value (regardless of casing). NamespaceSuffix When defined, the check will ensure namespace names will add the suffix with the given value (regardless of casing). For example using values of: • NamespaceCase of lower_case • NamespacePrefix of pre_ • NamespaceSuffix of _post Identifies and/or transforms namespace names as follows: Before: namespace FOO_NS { ... } After: namespace pre_foo_ns_post { ... } ParameterCase When defined, the check will ensure parameter names conform to the selected casing. ParameterPrefix When defined, the check will ensure parameter names will add the prefixed with the given value (regardless of casing). ParameterSuffix When defined, the check will ensure parameter names will add the suffix with the given value (regardless of casing). For example using values of: • ParameterCase of lower_case • ParameterPrefix of pre_ • ParameterSuffix of _post Identifies and/or transforms parameter names as follows: Before: void GLOBAL_FUNCTION(int PARAMETER_1, int const CONST_parameter); After: void GLOBAL_FUNCTION(int pre_parameter_post, int const CONST_parameter); ParameterPackCase When defined, the check will ensure parameter pack names conform to the selected casing. ParameterPackPrefix When defined, the check will ensure parameter pack names will add the prefixed with the given value (regardless of casing). ParameterPackSuffix When defined, the check will ensure parameter pack names will add the suffix with the given value (regardless of casing). For example using values of: • ParameterPackCase of lower_case • ParameterPackPrefix of pre_ • ParameterPackSuffix of _post Identifies and/or transforms parameter pack names as follows: Before: template <typename... TYPE_parameters> { void FUNCTION(int... TYPE_parameters); } After: template <typename... TYPE_parameters> { void FUNCTION(int... pre_type_parameters_post); } PointerParameterCase When defined, the check will ensure pointer parameter names con- form to the selected casing. PointerParameterPrefix When defined, the check will ensure pointer parameter names will add the prefixed with the given value (regardless of casing). PointerParameterSuffix When defined, the check will ensure pointer parameter names will add the suffix with the given value (regardless of casing). For example using values of: • PointerParameterCase of lower_case • PointerParameterPrefix of pre_ • PointerParameterSuffix of _post Identifies and/or transforms pointer parameter names as follows: Before: void FUNCTION(int *PARAMETER); After: void FUNCTION(int *pre_parameter_post); PrivateMemberCase When defined, the check will ensure private member names conform to the selected casing. PrivateMemberPrefix When defined, the check will ensure private member names will add the prefixed with the given value (regardless of casing). PrivateMemberSuffix When defined, the check will ensure private member names will add the suffix with the given value (regardless of casing). For example using values of: • PrivateMemberCase of lower_case • PrivateMemberPrefix of pre_ • PrivateMemberSuffix of _post Identifies and/or transforms private member names as follows: Before: class Foo { private: int Member_Variable; } After: class Foo { private: int pre_member_variable_post; } PrivateMethodCase When defined, the check will ensure private method names conform to the selected casing. PrivateMethodPrefix When defined, the check will ensure private method names will add the prefixed with the given value (regardless of casing). PrivateMethodSuffix When defined, the check will ensure private method names will add the suffix with the given value (regardless of casing). For example using values of: • PrivateMethodCase of lower_case • PrivateMethodPrefix of pre_ • PrivateMethodSuffix of _post Identifies and/or transforms private method names as follows: Before: class Foo { private: int Member_Method(); } After: class Foo { private: int pre_member_method_post(); } ProtectedMemberCase When defined, the check will ensure protected member names con- form to the selected casing. ProtectedMemberPrefix When defined, the check will ensure protected member names will add the prefixed with the given value (regardless of casing). ProtectedMemberSuffix When defined, the check will ensure protected member names will add the suffix with the given value (regardless of casing). For example using values of: • ProtectedMemberCase of lower_case • ProtectedMemberPrefix of pre_ • ProtectedMemberSuffix of _post Identifies and/or transforms protected member names as follows: Before: class Foo { protected: int Member_Variable; } After: class Foo { protected: int pre_member_variable_post; } ProtectedMethodCase When defined, the check will ensure protect method names conform to the selected casing. ProtectedMethodPrefix When defined, the check will ensure protect method names will add the prefixed with the given value (regardless of casing). ProtectedMethodSuffix When defined, the check will ensure protect method names will add the suffix with the given value (regardless of casing). For example using values of: • ProtectedMethodCase of lower_case • ProtectedMethodPrefix of pre_ • ProtectedMethodSuffix of _post Identifies and/or transforms protect method names as follows: Before: class Foo { protected: int Member_Method(); } After: class Foo { protected: int pre_member_method_post(); } PublicMemberCase When defined, the check will ensure public member names conform to the selected casing. PublicMemberPrefix When defined, the check will ensure public member names will add the prefixed with the given value (regardless of casing). PublicMemberSuffix When defined, the check will ensure public member names will add the suffix with the given value (regardless of casing). For example using values of: • PublicMemberCase of lower_case • PublicMemberPrefix of pre_ • PublicMemberSuffix of _post Identifies and/or transforms public member names as follows: Before: class Foo { public: int Member_Variable; } After: class Foo { public: int pre_member_variable_post; } PublicMethodCase When defined, the check will ensure public method names conform to the selected casing. PublicMethodPrefix When defined, the check will ensure public method names will add the prefixed with the given value (regardless of casing). PublicMethodSuffix When defined, the check will ensure public method names will add the suffix with the given value (regardless of casing). For example using values of: • PublicMethodCase of lower_case • PublicMethodPrefix of pre_ • PublicMethodSuffix of _post Identifies and/or transforms public method names as follows: Before: class Foo { public: int Member_Method(); } After: class Foo { public: int pre_member_method_post(); } StaticConstantCase When defined, the check will ensure static constant names con- form to the selected casing. StaticConstantPrefix When defined, the check will ensure static constant names will add the prefixed with the given value (regardless of casing). StaticConstantSuffix When defined, the check will ensure static constant names will add the suffix with the given value (regardless of casing). For example using values of: • StaticConstantCase of lower_case • StaticConstantPrefix of pre_ • StaticConstantSuffix of _post Identifies and/or transforms static constant names as follows: Before: static unsigned const MyConstStatic_array[] = {1, 2, 3}; After: static unsigned const pre_myconststatic_array_post[] = {1, 2, 3}; StaticVariableCase When defined, the check will ensure static variable names con- form to the selected casing. StaticVariablePrefix When defined, the check will ensure static variable names will add the prefixed with the given value (regardless of casing). StaticVariableSuffix When defined, the check will ensure static variable names will add the suffix with the given value (regardless of casing). For example using values of: • StaticVariableCase of lower_case • StaticVariablePrefix of pre_ • StaticVariableSuffix of _post Identifies and/or transforms static variable names as follows: Before: static unsigned MyStatic_array[] = {1, 2, 3}; After: static unsigned pre_mystatic_array_post[] = {1, 2, 3}; StructCase When defined, the check will ensure struct names conform to the selected casing. StructPrefix When defined, the check will ensure struct names will add the prefixed with the given value (regardless of casing). StructSuffix When defined, the check will ensure struct names will add the suffix with the given value (regardless of casing). For example using values of: • StructCase of lower_case • StructPrefix of pre_ • StructSuffix of _post Identifies and/or transforms struct names as follows: Before: struct FOO { FOO(); ~FOO(); }; After: struct pre_foo_post { pre_foo_post(); ~pre_foo_post(); }; TemplateParameterCase When defined, the check will ensure template parameter names conform to the selected casing. TemplateParameterPrefix When defined, the check will ensure template parameter names will add the prefixed with the given value (regardless of cas- ing). TemplateParameterSuffix When defined, the check will ensure template parameter names will add the suffix with the given value (regardless of casing). For example using values of: • TemplateParameterCase of lower_case • TemplateParameterPrefix of pre_ • TemplateParameterSuffix of _post Identifies and/or transforms template parameter names as follows: Before: template <typename T> class Foo {}; After: template <typename pre_t_post> class Foo {}; TemplateTemplateParameterCase When defined, the check will ensure template template parameter names conform to the selected casing. TemplateTemplateParameterPrefix When defined, the check will ensure template template parameter names will add the prefixed with the given value (regardless of casing). TemplateTemplateParameterSuffix When defined, the check will ensure template template parameter names will add the suffix with the given value (regardless of casing). For example using values of: • TemplateTemplateParameterCase of lower_case • TemplateTemplateParameterPrefix of pre_ • TemplateTemplateParameterSuffix of _post Identifies and/or transforms template template parameter names as fol- lows: Before: template <template <typename> class TPL_parameter, int COUNT_params, typename... TYPE_parameters> After: template <template <typename> class pre_tpl_parameter_post, int COUNT_params, typename... TYPE_parameters> TypeAliasCase When defined, the check will ensure type alias names conform to the selected casing. TypeAliasPrefix When defined, the check will ensure type alias names will add the prefixed with the given value (regardless of casing). TypeAliasSuffix When defined, the check will ensure type alias names will add the suffix with the given value (regardless of casing). For example using values of: • TypeAliasCase of lower_case • TypeAliasPrefix of pre_ • TypeAliasSuffix of _post Identifies and/or transforms type alias names as follows: Before: using MY_STRUCT_TYPE = my_structure; After: using pre_my_struct_type_post = my_structure; TypedefCase When defined, the check will ensure typedef names conform to the selected casing. TypedefPrefix When defined, the check will ensure typedef names will add the prefixed with the given value (regardless of casing). TypedefSuffix When defined, the check will ensure typedef names will add the suffix with the given value (regardless of casing). For example using values of: • TypedefCase of lower_case • TypedefPrefix of pre_ • TypedefSuffix of _post Identifies and/or transforms typedef names as follows: Before: typedef int MYINT; After: typedef int pre_myint_post; TypeTemplateParameterCase When defined, the check will ensure type template parameter names conform to the selected casing. TypeTemplateParameterPrefix When defined, the check will ensure type template parameter names will add the prefixed with the given value (regardless of casing). TypeTemplateParameterSuffix When defined, the check will ensure type template parameter names will add the suffix with the given value (regardless of casing). For example using values of: • TypeTemplateParameterCase of lower_case • TypeTemplateParameterPrefix of pre_ • TypeTemplateParameterSuffix of _post Identifies and/or transforms type template parameter names as follows: Before: template <template <typename> class TPL_parameter, int COUNT_params, typename... TYPE_parameters> After: template <template <typename> class TPL_parameter, int COUNT_params, typename... pre_type_parameters_post> UnionCase When defined, the check will ensure union names conform to the selected casing. UnionPrefix When defined, the check will ensure union names will add the prefixed with the given value (regardless of casing). UnionSuffix When defined, the check will ensure union names will add the suffix with the given value (regardless of casing). For example using values of: • UnionCase of lower_case • UnionPrefix of pre_ • UnionSuffix of _post Identifies and/or transforms union names as follows: Before: union FOO { int a; char b; }; After: union pre_foo_post { int a; char b; }; ValueTemplateParameterCase When defined, the check will ensure value template parameter names conform to the selected casing. ValueTemplateParameterPrefix When defined, the check will ensure value template parameter names will add the prefixed with the given value (regardless of casing). ValueTemplateParameterSuffix When defined, the check will ensure value template parameter names will add the suffix with the given value (regardless of casing). For example using values of: • ValueTemplateParameterCase of lower_case • ValueTemplateParameterPrefix of pre_ • ValueTemplateParameterSuffix of _post Identifies and/or transforms value template parameter names as follows: Before: template <template <typename> class TPL_parameter, int COUNT_params, typename... TYPE_parameters> After: template <template <typename> class TPL_parameter, int pre_count_params_post, typename... TYPE_parameters> VariableCase When defined, the check will ensure variable names conform to the selected casing. VariablePrefix When defined, the check will ensure variable names will add the prefixed with the given value (regardless of casing). VariableSuffix When defined, the check will ensure variable names will add the suffix with the given value (regardless of casing). For example using values of: • VariableCase of lower_case • VariablePrefix of pre_ • VariableSuffix of _post Identifies and/or transforms variable names as follows: Before: unsigned MyVariable; After: unsigned pre_myvariable_post; VirtualMethodCase When defined, the check will ensure virtual method names conform to the selected casing. VirtualMethodPrefix When defined, the check will ensure virtual method names will add the prefixed with the given value (regardless of casing). VirtualMethodSuffix When defined, the check will ensure virtual method names will add the suffix with the given value (regardless of casing). For example using values of: • VirtualMethodCase of lower_case • VirtualMethodPrefix of pre_ • VirtualMethodSuffix of _post Identifies and/or transforms virtual method names as follows: Before: class Foo { public: virtual int MemberFunction(); } After: class Foo { public: virtual int pre_member_function_post(); } readability-implicit-bool-cast This check has been renamed to readability-implicit-bool-conversion. readability-implicit-bool-conversion This check can be used to find implicit conversions between built-in types and booleans. Depending on use case, it may simply help with readability of the code, or in some cases, point to potential bugs which remain unnoticed due to implicit conversions. The following is a real-world example of bug which was hiding behind implicit bool conversion: class Foo { int m_foo; public: void setFoo(bool foo) { m_foo = foo; } // warning: implicit conversion bool -> int int getFoo() { return m_foo; } }; void use(Foo& foo) { bool value = foo.getFoo(); // warning: implicit conversion int -> bool } This code is the result of unsuccessful refactoring, where type of m_foo changed from bool to int. The programmer forgot to change all oc- currences of bool, and the remaining code is no longer correct, yet it still compiles without any visible warnings. In addition to issuing warnings, fix-it hints are provided to help solve the reported issues. This can be used for improving readability of code, for example: void conversionsToBool() { float floating; bool boolean = floating; // ^ propose replacement: bool boolean = floating != 0.0f; int integer; if (integer) {} // ^ propose replacement: if (integer != 0) {} int* pointer; if (!pointer) {} // ^ propose replacement: if (pointer == nullptr) {} while (1) {} // ^ propose replacement: while (true) {} } void functionTakingInt(int param); void conversionsFromBool() { bool boolean; functionTakingInt(boolean); // ^ propose replacement: functionTakingInt(static_cast<int>(boolean)); functionTakingInt(true); // ^ propose replacement: functionTakingInt(1); } In general, the following conversion types are checked: • integer expression/literal to boolean (conversion from a single bit bitfield to boolean is explicitly allowed, since there's no ambiguity / information loss in this case), • floating expression/literal to boolean, • pointer/pointer to member/nullptr/NULL to boolean, • boolean expression/literal to integer (conversion from boolean to a single bit bitfield is explicitly allowed), • boolean expression/literal to floating. The rules for generating fix-it hints are: • in case of conversions from other built-in type to bool, an explicit comparison is proposed to make it clear what exactly is being com- pared: • bool boolean = floating; is changed to bool boolean = floating == 0.0f;, • for other types, appropriate literals are used (0, 0u, 0.0f, 0.0, nullptr), • in case of negated expressions conversion to bool, the proposed re- placement with comparison is simplified: • if (!pointer) is changed to if (pointer == nullptr), • in case of conversions from bool to other built-in types, an explicit static_cast is proposed to make it clear that a conversion is taking place: • int integer = boolean; is changed to int integer = sta- tic_cast<int>(boolean);, • if the conversion is performed on type literals, an equivalent lit- eral is proposed, according to what type is actually expected, for example: • functionTakingBool(0); is changed to functionTakingBool(false);, • functionTakingInt(true); is changed to functionTakingInt(1);, • for other types, appropriate literals are used (false, true, 0, 1, 0u, 1u, 0.0f, 1.0f, 0.0, 1.0f). Some additional accommodations are made for pre-C++11 dialects: • false literal conversion to pointer is detected, • instead of nullptr literal, 0 is proposed as replacement. Occurrences of implicit conversions inside macros and template instan- tiations are deliberately ignored, as it is not clear how to deal with such cases. Options AllowIntegerConditions When non-zero, the check will allow conditional integer conver- sions. Default is 0. AllowPointerConditions When non-zero, the check will allow conditional pointer conver- sions. Default is 0. readability-inconsistent-declaration-parameter-name Find function declarations which differ in parameter names. Example: // in foo.hpp: void foo(int a, int b, int c); // in foo.cpp: void foo(int d, int e, int f); // warning This check should help to enforce consistency in large projects, where it often happens that a definition of function is refactored, changing the parameter names, but its declaration in header file is not updated. With this check, we can easily find and correct such inconsistencies, keeping declaration and definition always in sync. Unnamed parameters are allowed and are not taken into account when com- paring function declarations, for example: void foo(int a); void foo(int); // no warning One name is also allowed to be a case-insensitive prefix/suffix of the other: void foo(int count); void foo(int count_input) { // no warning int count = adjustCount(count_input); } To help with refactoring, in some cases fix-it hints are generated to align parameter names to a single naming convention. This works with the assumption that the function definition is the most up-to-date ver- sion, as it directly references parameter names in its body. Example: void foo(int a); // warning and fix-it hint (replace "a" to "b") int foo(int b) { return b + 2; } // definition with use of "b" In the case of multiple redeclarations or function template specializa- tions, a warning is issued for every redeclaration or specialization inconsistent with the definition or the first declaration seen in a translation unit. IgnoreMacros If this option is set to non-zero (default is 1), the check will not warn about names declared inside macros. Strict If this option is set to non-zero (default is 0), then names must match exactly (or be absent). readability-isolate-declaration Detects local variable declarations declaring more than one variable and tries to refactor the code to one statement per declaration. The automatic code-transformation will use the same indentation as the original for every created statement and add a line break after each statement. It keeps the order of the variable declarations consistent, too. void f() { int * pointer = nullptr, value = 42, * const const_ptr = &value; // This declaration will be diagnosed and transformed into: // int * pointer = nullptr; // int value = 42; // int * const const_ptr = &value; } The check excludes places where it is necessary or common to declare multiple variables in one statement and there is no other way supported in the language. Please note that structured bindings are not consid- ered. // It is not possible to transform this declaration and doing the declaration // before the loop will increase the scope of the variable 'Begin' and 'End' // which is undesirable. for (int Begin = 0, End = 100; Begin < End; ++Begin); if (int Begin = 42, Result = some_function(Begin); Begin == Result); // It is not possible to transform this declaration because the result is // not functionality preserving as 'j' and 'k' would not be part of the // 'if' statement anymore. if (SomeCondition()) int i = 42, j = 43, k = function(i,j); Limitations Global variables and member variables are excluded. The check currently does not support the automatic transformation of member-pointer-types. struct S { int a; const int b; void f() {} }; void f() { // Only a diagnostic message is emitted int S::*p = &S::a, S::*const q = &S::a; } Furthermore, the transformation is very cautious when it detects vari- ous kinds of macros or preprocessor directives in the range of the statement. In this case the transformation will not happen to avoid un- expected side-effects due to macros. #define NULL 0 #define MY_NICE_TYPE int ** #define VAR_NAME(name) name##__LINE__ #define A_BUNCH_OF_VARIABLES int m1 = 42, m2 = 43, m3 = 44; void macros() { int *p1 = NULL, *p2 = NULL; // Will be transformed to // int *p1 = NULL; // int *p2 = NULL; MY_NICE_TYPE p3, v1, v2; // Won't be transformed, but a diagnostic is emitted. int VAR_NAME(v3), VAR_NAME(v4), VAR_NAME(v5); // Won't be transformed, but a diagnostic is emitted. A_BUNCH_OF_VARIABLES // Won't be transformed, but a diagnostic is emitted. int Unconditional, #if CONFIGURATION IfConfigured = 42, #else IfConfigured = 0; #endif // Won't be transformed, but a diagnostic is emitted. } readability-magic-numbers Detects magic numbers, integer or floating point literals that are em- bedded in code and not introduced via constants or symbols. Many coding guidelines advise replacing the magic values with symbolic constants to improve readability. Here are a few references: • Rule ES.45: Avoid magic constants; use symbolic constants in C++ Core Guidelines • Rule 5.1.1 Use symbolic names instead of literal values in code in High Integrity C++ • Item 17 in "C++ Coding Standards: 101 Rules, Guidelines and Best Practices" by Herb Sutter and Andrei Alexandrescu • Chapter 17 in "Clean Code - A handbook of agile software crafts- manship." by Robert C. Martin • Rule 20701 in "TRAIN REAL TIME DATA PROTOCOL Coding Rules" by Armin-Hagen Weiss, Bombardier • http://wiki.c2.com/?MagicNumber Examples of magic values: double circleArea = 3.1415926535 * radius * radius; double totalCharge = 1.08 * itemPrice; int getAnswer() { return -3; // FILENOTFOUND } for (int mm = 1; mm <= 12; ++mm) { std::cout << month[mm] << '\n'; } Example with magic values refactored: double circleArea = M_PI * radius * radius; const double TAX_RATE = 0.08; // or make it variable and read from a file double totalCharge = (1.0 + TAX_RATE) * itemPrice; int getAnswer() { return E_FILE_NOT_FOUND; } for (int mm = 1; mm <= MONTHS_IN_A_YEAR; ++mm) { std::cout << month[mm] << '\n'; } For integral literals by default only 0 and 1 (and -1) integer values are accepted without a warning. This can be overridden with the IgnoredIntegerValues option. Negative values are accepted if their ab- solute value is present in the IgnoredIntegerValues list. As a special case for integral values, all powers of two can be ac- cepted without warning by enabling the IgnorePowersOf2IntegerValues op- tion. For floating point literals by default the 0.0 floating point value is accepted without a warning. The set of ignored floating point literals can be configured using the IgnoredFloatingPointValues option. For each value in that set, the given string value is converted to a float- ing-point value representation used by the target architecture. If a floating-point literal value compares equal to one of the converted values, then that literal is not diagnosed by this check. Because floating-point equality is used to determine whether to diagnose or not, the user needs to be aware of the details of floating-point repre- sentations for any values that cannot be precisely represented for their target architecture. For each value in the IgnoredFloatingPointValues set, both the sin- gle-precision form and double-precision form are accepted (for example, if 3.14 is in the set, neither 3.14f nor 3.14 will produce a warning). Scientific notation is supported for both source code input and option. Alternatively, the check for the floating point numbers can be disabled for all floating point values by enabling the IgnoreAllFloatingPointValues option. Since values 0 and 0.0 are so common as the base counter of loops, or initialization values for sums, they are always accepted without warn- ing, even if not present in the respective ignored values list. Options IgnoredIntegerValues Semicolon-separated list of magic positive integers that will be accepted without a warning. Default values are {1, 2, 3, 4}, and 0 is accepted unconditionally. IgnorePowersOf2IntegerValues Boolean value indicating whether to accept all powers-of-two in- teger values without warning. Default value is false. IgnoredFloatingPointValues Semicolon-separated list of magic positive floating point values that will be accepted without a warning. Default values are {1.0, 100.0} and 0.0 is accepted unconditionally. IgnoreAllFloatingPointValues Boolean value indicating whether to accept all floating point values without warning. Default value is false. IgnoreBitFieldsWidths Boolean value indicating whether to accept magic numbers as bit field widths without warning. This is useful for example for register definitions which are generated from hardware specifi- cations. Default value is true. readability-make-member-function-const Finds non-static member functions that can be made const because the functions don't use this in a non-const way. This check tries to annotate methods according to logical constness (not physical constness). Therefore, it will suggest to add a const qualifier to a non-const method only if this method does something that is already possible though the public interface on a const pointer to the object: • reading a public member variable • calling a public const-qualified member function • returning const-qualified this • passing const-qualified this as a parameter. This check will also suggest to add a const qualifier to a non-const method if this method uses private data and functions in a limited num- ber of ways where logical constness and physical constness coincide: • reading a member variable of builtin type Specifically, this check will not suggest to add a const to a non-const method if the method reads a private member variable of pointer type because that allows to modify the pointee which might not preserve log- ical constness. For the same reason, it does not allow to call private member functions or member functions on private member variables. In addition, this check ignores functions that • are declared virtual • contain a const_cast • are templated or part of a class template • have an empty body • do not (implicitly) use this at all (see readability-convert-member-functions-to-static). The following real-world examples will be preserved by the check: class E1 { Pimpl &getPimpl() const; public: int &get() { // Calling a private member function disables this check. return getPimpl()->i; } ... }; class E2 { public: const int *get() const; // const_cast disables this check. S *get() { return const_cast<int*>(const_cast<const C*>(this)->get()); } ... }; After applying modifications as suggested by the check, running the check again might find more opportunities to mark member functions const. readability-misleading-indentation Correct indentation helps to understand code. Mismatch of the syntacti- cal structure and the indentation of the code may hide serious prob- lems. Missing braces can also make it significantly harder to read the code, therefore it is important to use braces. The way to avoid dangling else is to always check that an else belongs to the if that begins in the same column. You can omit braces when your inner part of e.g. an if statement has only one statement in it. Although in that case you should begin the next statement in the same column with the if. Examples: // Dangling else: if (cond1) if (cond2) foo1(); else foo2(); // Wrong indentation: else belongs to if(cond2) statement. // Missing braces: if (cond1) foo1(); foo2(); // Not guarded by if(cond1). Limitations Note that this check only works as expected when the tabs or spaces are used consistently and not mixed. readability-misplaced-array-index This check warns for unusual array index syntax. The following code has unusual array index syntax: void f(int *X, int Y) { Y[X] = 0; } becomes void f(int *X, int Y) { X[Y] = 0; } The check warns about such unusual syntax for readability reasons: • There are programmers that are not familiar with this unusual syntax. • It is possible that variables are mixed up. readability-named-parameter Find functions with unnamed arguments. The check implements the following rule originating in the Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html#Function_Declarations_and_Definitions All parameters should be named, with identical names in the declaration and implementation. Corresponding cpplint.py check name: readability/function. readability-non-const-parameter The check finds function parameters of a pointer type that could be changed to point to a constant type instead. When const is used properly, many mistakes can be avoided. Advantages when using const properly: • prevent unintentional modification of data; • get additional warnings such as using uninitialized data; • make it easier for developers to see possible side effects. This check is not strict about constness, it only warns when the const- ness will make the function interface safer. // warning here; the declaration "const char *p" would make the function // interface safer. char f1(char *p) { return *p; } // no warning; the declaration could be more const "const int * const p" but // that does not make the function interface safer. int f2(const int *p) { return *p; } // no warning; making x const does not make the function interface safer int f3(int x) { return x; } // no warning; Technically, *p can be const ("const struct S *p"). But making // *p const could be misleading. People might think that it's safe to pass // const data to this function. struct S { int *a; int *b; }; int f3(struct S *p) { *(p->a) = 0; } readability-qualified-auto Adds pointer qualifications to auto-typed variables that are deduced to pointers. LLVM Coding Standards advises to make it obvious if a auto typed vari- able is a pointer. This check will transform auto to auto * when the type is deduced to be a pointer. for (auto Data : MutatablePtrContainer) { change(*Data); } for (auto Data : ConstantPtrContainer) { observe(*Data); } Would be transformed into: for (auto *Data : MutatablePtrContainer) { change(*Data); } for (const auto *Data : ConstantPtrContainer) { observe(*Data); } Note const volatile qualified types will retain their const and volatile qualifiers. Pointers to pointers will not be fully qualified. const auto Foo = cast<int *>(Baz1); const auto Bar = cast<const int *>(Baz2); volatile auto FooBar = cast<int *>(Baz3); auto BarFoo = cast<int **>(Baz4); Would be transformed into: auto *const Foo = cast<int *>(Baz1); const auto *const Bar = cast<const int *>(Baz2); auto *volatile FooBar = cast<int *>(Baz3); auto *BarFoo = cast<int **>(Baz4); Options AddConstToQualified When set to 1 the check will add const qualifiers variables de- fined as auto * or auto & when applicable. Default value is '1'. auto Foo1 = cast<const int *>(Bar1); auto *Foo2 = cast<const int *>(Bar2); auto &Foo3 = cast<const int &>(Bar3); If AddConstToQualified is set to 0, it will be transformed into: const auto *Foo1 = cast<const int *>(Bar1); auto *Foo2 = cast<const int *>(Bar2); auto &Foo3 = cast<const int &>(Bar3); Otherwise it will be transformed into: const auto *Foo1 = cast<const int *>(Bar1); const auto *Foo2 = cast<const int *>(Bar2); const auto &Foo3 = cast<const int &>(Bar3); Note in the LLVM alias, the default value is 0. readability-redundant-access-specifiers Finds classes, structs, and unions containing redundant member (field and method) access specifiers. Example class Foo { public: int x; int y; public: int z; protected: int a; public: int c; } In the example above, the second public declaration can be removed without any changes of behavior. Options CheckFirstDeclaration If set to non-zero, the check will also diagnose if the first access specifier declaration is redundant (e.g. private inside class, or public inside struct or union). Default is 0. Example struct Bar { public: int x; } If CheckFirstDeclaration option is enabled, a warning about redundant access specifier will be emitted, because public is the default member access for structs. readability-redundant-control-flow This check looks for procedures (functions returning no value) with re- turn statements at the end of the function. Such return statements are redundant. Loop statements (for, while, do while) are checked for redundant con- tinue statements at the end of the loop body. Examples: The following function f contains a redundant return statement: extern void g(); void f() { g(); return; } becomes extern void g(); void f() { g(); } The following function k contains a redundant continue statement: void k() { for (int i = 0; i < 10; ++i) { continue; } } becomes void k() { for (int i = 0; i < 10; ++i) { } } readability-redundant-declaration Finds redundant variable and function declarations. extern int X; extern int X; becomes extern int X; Such redundant declarations can be removed without changing program be- haviour. They can for instance be unintentional left overs from previ- ous refactorings when code has been moved around. Having redundant dec- larations could in worst case mean that there are typos in the code that cause bugs. Normally the code can be automatically fixed, clang-tidy can remove the second declaration. However there are 2 cases when you need to fix the code manually: • When the declarations are in different header files; • When multiple variables are declared together. Options IgnoreMacros If set to non-zero, the check will not give warnings inside macros. Default is 1. readability-redundant-function-ptr-dereference Finds redundant dereferences of a function pointer. Before: int f(int,int); int (*p)(int, int) = &f; int i = (**p)(10, 50); After: int f(int,int); int (*p)(int, int) = &f; int i = (*p)(10, 50); readability-redundant-member-init Finds member initializations that are unnecessary because the same de- fault constructor would be called if they were not present. Example // Explicitly initializing the member s is unnecessary. class Foo { public: Foo() : s() {} private: std::string s; }; Options IgnoreBaseInCopyConstructors Default is 0. When non-zero, the check will ignore unnecessary base class ini- tializations within copy constructors, since some compilers is- sue warnings/errors when base classes are not explicitly intial- ized in copy constructors. For example, gcc with -Wextra or -Werror=extra issues warning or error base class 'Bar' should be explicitly initialized in the copy constructor if Bar() were re- moved in the following example: // Explicitly initializing member s and base class Bar is unnecessary. struct Foo : public Bar { // Remove s() below. If IgnoreBaseInCopyConstructors!=0, keep Bar(). Foo(const Foo& foo) : Bar(), s() {} std::string s; }; readability-redundant-preprocessor Finds potentially redundant preprocessor directives. At the moment the following cases are detected: • #ifdef .. #endif pairs which are nested inside an outer pair with the same condition. For example: #ifdef FOO #ifdef FOO // inner ifdef is considered redundant void f(); #endif #endif • Same for #ifndef .. #endif pairs. For example: #ifndef FOO #ifndef FOO // inner ifndef is considered redundant void f(); #endif #endif • #ifndef inside an #ifdef with the same condition: #ifdef FOO #ifndef FOO // inner ifndef is considered redundant void f(); #endif #endif • #ifdef inside an #ifndef with the same condition: #ifndef FOO #ifdef FOO // inner ifdef is considered redundant void f(); #endif #endif • #if .. #endif pairs which are nested inside an outer pair with the same condition. For example: #define FOO 4 #if FOO == 4 #if FOO == 4 // inner if is considered redundant void f(); #endif #endif readability-redundant-smartptr-get Find and remove redundant calls to smart pointer's .get() method. Examples: ptr.get()->Foo() ==> ptr->Foo() *ptr.get() ==> *ptr *ptr->get() ==> **ptr if (ptr.get() == nullptr) ... => if (ptr == nullptr) ... IgnoreMacros If this option is set to non-zero (default is 1), the check will not warn about calls inside macros. readability-redundant-string-cstr Finds unnecessary calls to std::string::c_str() and std::string::data(). readability-redundant-string-init Finds unnecessary string initializations. Examples // Initializing string with empty string literal is unnecessary. std::string a = ""; std::string b(""); // becomes std::string a; std::string b; Options StringNames Default is ::std::basic_string. 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::ba- sic_string;llvm::StringRef;QString to perform this check on cus- tom classes. readability-simplify-boolean-expr Looks for boolean expressions involving boolean constants and simpli- fies them to use the appropriate boolean expression directly. Examples: +----------------------------+------------+ | Initial expression | Result | +----------------------------+------------+ | if (b == true) | if (b) | +----------------------------+------------+ | if (b == false) | if (!b) | +----------------------------+------------+ | if (b && true) | if (b) | +----------------------------+------------+ | if (b && false) | if (false) | +----------------------------+------------+ | if (b || true) | if (true) | +----------------------------+------------+ | if (b || false) | if (b) | +----------------------------+------------+ | e ? true : false | e | +----------------------------+------------+ | e ? false : true | !e | +----------------------------+------------+ | if (true) t(); else f(); | t(); | +----------------------------+------------+ | if (false) t(); else f(); | f(); | +----------------------------+------------+ | if (e) return true; else | return e; | | return false; | | +----------------------------+------------+ | if (e) return false; else | return !e; | | return true; | | +----------------------------+------------+ | if (e) b = true; else b = | b = e; | | false; | | +----------------------------+------------+ | if (e) b = false; else b = | b = !e; | | true; | | +----------------------------+------------+ | if (e) return true; return | return e; | | false; | | +----------------------------+------------+ | if (e) return false; re- | return !e; | | turn true; | | +----------------------------+------------+ The resulting expression e is modified as follows: 1. Unnecessary parentheses around the expression are removed. 2. Negated applications of ! are eliminated. 3. Negated applications of comparison operators are changed to use the opposite condition. 4. Implicit conversions of pointers, including pointers to mem- bers, to bool are replaced with explicit comparisons to nullptr in C++11 or NULL in C++98/03. 5. Implicit casts to bool are replaced with explicit casts to bool. 6. Object expressions with explicit operator bool conversion op- erators are replaced with explicit casts to bool. 7. Implicit conversions of integral types to bool are replaced with explicit comparisons to 0. Examples: 1. The ternary assignment bool b = (i < 0) ? true : false; has redundant parentheses and becomes bool b = i < 0;. 2. The conditional return if (!b) return false; return true; has an implied double negation and becomes return b;. 3. The conditional return if (i < 0) return false; return true; becomes return i >= 0;. The conditional return if (i != 0) return false; return true; becomes return i == 0;. 4. The conditional return if (p) return true; return false; has an implicit conversion of a pointer to bool and becomes re- turn p != nullptr;. The ternary assignment bool b = (i & 1) ? true : false; has an implicit conversion of i & 1 to bool and becomes bool b = (i & 1) != 0;. 5. The conditional return if (i & 1) return true; else return false; has an implicit conversion of an integer quantity i & 1 to bool and becomes return (i & 1) != 0; 6. Given struct X { explicit operator bool(); };, and an in- stance x of struct X, the conditional return if (x) return true; return false; becomes return static_cast<bool>(x); Options ChainedConditionalReturn If non-zero, conditional boolean return statements at the end of an if/else if chain will be transformed. Default is 0. ChainedConditionalAssignment If non-zero, conditional boolean assignments at the end of an if/else if chain will be transformed. Default is 0. readability-simplify-subscript-expr This check simplifies subscript expressions. Currently this covers calling .data() and immediately doing an array subscript operation to obtain a single element, in which case simply calling operator[] suf- fice. Examples: std::string s = ...; char c = s.data()[i]; // char c = s[i]; Options Types The list of type(s) that triggers this check. Default is ::std::basic_string;::std::basic_string_view;::std::vec- tor;::std::array readability-static-accessed-through-instance Checks for member expressions that access static members through in- stances, and replaces them with uses of the appropriate qualified-id. Example: The following code: struct C { static void foo(); static int x; }; C *c1 = new C(); c1->foo(); c1->x; is changed to: C *c1 = new C(); C::foo(); C::x; readability-static-definition-in-anonymous-namespace Finds static function and variable definitions in anonymous namespace. In this case, static is redundant, because anonymous namespace limits the visibility of definitions to a single translation unit. namespace { static int a = 1; // Warning. static const b = 1; // Warning. } The check will apply a fix by removing the redundant static qualifier. readability-string-compare Finds string comparisons using the compare method. A common mistake is to use the string's compare method instead of using the equality or inequality operators. The compare method is intended for sorting functions and thus returns a negative number, a positive number or zero depending on the lexicographical relationship between the strings compared. If an equality or inequality check can suffice, that is recommended. This is recommended to avoid the risk of incorrect interpretation of the return value and to simplify the code. The string equality and inequality operators can also be faster than the compare method due to early termination. Examples: std::string str1{"a"}; std::string str2{"b"}; // use str1 != str2 instead. if (str1.compare(str2)) { } // use str1 == str2 instead. if (!str1.compare(str2)) { } // use str1 == str2 instead. if (str1.compare(str2) == 0) { } // use str1 != str2 instead. if (str1.compare(str2) != 0) { } // use str1 == str2 instead. if (0 == str1.compare(str2)) { } // use str1 != str2 instead. if (0 != str1.compare(str2)) { } // Use str1 == "foo" instead. if (str1.compare("foo") == 0) { } The above code examples shows the list of if-statements that this check will give a warning for. All of them uses compare to check if equality or inequality of two strings instead of using the correct operators. readability-uniqueptr-delete-release Replace delete <unique_ptr>.release() with <unique_ptr> = nullptr. The latter is shorter, simpler and does not require use of raw pointer APIs. std::unique_ptr<int> P; delete P.release(); // becomes std::unique_ptr<int> P; P = nullptr; readability-uppercase-literal-suffix cert-dcl16-c redirects here as an alias for this check. By default, only the suffixes that begin with l (l, ll, lu, llu, but not u, ul, ull) are diagnosed by that alias. hicpp-uppercase-literal-suffix redirects here as an alias for this check. Detects when the integral literal or floating point (decimal or hexa- decimal) literal has a non-uppercase suffix and provides a fix-it hint with the uppercase suffix. All valid combinations of suffixes are supported. auto x = 1; // OK, no suffix. auto x = 1u; // warning: integer literal suffix 'u' is not upper-case auto x = 1U; // OK, suffix is uppercase. ... Options NewSuffixes Optionally, a list of the destination suffixes can be provided. When the suffix is found, a case-insensitive lookup in that list is made, and if a replacement is found that is different from the current suffix, then the diagnostic is issued. This allows for fine-grained control of what suffixes to consider and what their replacements should be. Example Given a list L;uL: • l -> L • L will be kept as is. • ul -> uL • Ul -> uL • UL -> uL • uL will be kept as is. • ull will be kept as is, since it is not in the list • and so on. IgnoreMacros If this option is set to non-zero (default is 1), the check will not warn about literal suffixes inside macros. readability-use-anyofallof Finds range-based for loops that can be replaced by a call to std::any_of or std::all_of. In C++ 20 mode, suggests std::ranges::any_of or std::ranges::all_of. Example: bool all_even(std::vector<int> V) { for (int I : V) { if (I % 2) return false; } return true; // Replace loop by // return std::ranges::all_of(V, [](int I) { return I % 2 == 0; }); } zircon-temporary-objects Warns on construction of specific temporary objects in the Zircon ker- nel. If the object should be flagged, 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. +---------------------------------------------------------+--------------+ | Name | Offers fixes | +---------------------------------------------------------+--------------+ | abseil-duration-addition | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-comparison | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-conversion-cast | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-division | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-factory-float | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-factory-scale | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-subtraction | Yes | +---------------------------------------------------------+--------------+ | abseil-duration-unnecessary-conversion | Yes | +---------------------------------------------------------+--------------+ | abseil-faster-strsplit-delimiter | Yes | +---------------------------------------------------------+--------------+ | abseil-no-internal-dependencies | | +---------------------------------------------------------+--------------+ | abseil-no-namespace | | +---------------------------------------------------------+--------------+ | abseil-redundant-strcat-calls | Yes | +---------------------------------------------------------+--------------+ | abseil-str-cat-append | Yes | +---------------------------------------------------------+--------------+ | abseil-string-find-startswith | Yes | +---------------------------------------------------------+--------------+ | abseil-string-find-str-contains | Yes | +---------------------------------------------------------+--------------+ | abseil-time-comparison | Yes | +---------------------------------------------------------+--------------+ | abseil-time-subtraction | Yes | +---------------------------------------------------------+--------------+ | abseil-upgrade-duration-conversions | Yes | +---------------------------------------------------------+--------------+ | android-cloexec-accept | Yes | +---------------------------------------------------------+--------------+ | android-cloexec-accept4 | | +---------------------------------------------------------+--------------+ | android-cloexec-creat | Yes | +---------------------------------------------------------+--------------+ | android-cloexec-dup | Yes | +---------------------------------------------------------+--------------+ | android-cloexec-epoll-create | | +---------------------------------------------------------+--------------+ | android-cloexec-epoll-create1 | | +---------------------------------------------------------+--------------+ | android-cloexec-fopen | | +---------------------------------------------------------+--------------+ | android-cloexec-inotify-init | | +---------------------------------------------------------+--------------+ | android-cloexec-inotify-init1 | | +---------------------------------------------------------+--------------+ | android-cloexec-memfd-create | | +---------------------------------------------------------+--------------+ | android-cloexec-open | | +---------------------------------------------------------+--------------+ | android-cloexec-pipe | Yes | +---------------------------------------------------------+--------------+ | android-cloexec-pipe2 | | +---------------------------------------------------------+--------------+ | android-cloexec-socket | | +---------------------------------------------------------+--------------+ | android-comparison-in-temp-failure-retry | | +---------------------------------------------------------+--------------+ | boost-use-to-string | Yes | +---------------------------------------------------------+--------------+ | bugprone-argument-comment | Yes | +---------------------------------------------------------+--------------+ | bugprone-assert-side-effect | | +---------------------------------------------------------+--------------+ | bugprone-bad-signal-to-kill-thread | | +---------------------------------------------------------+--------------+ | bugprone-bool-pointer-implicit-conversion | Yes | +---------------------------------------------------------+--------------+ | bugprone-branch-clone | | +---------------------------------------------------------+--------------+ | bugprone-copy-constructor-init | Yes | +---------------------------------------------------------+--------------+ | bugprone-dangling-handle | | +---------------------------------------------------------+--------------+ | bugprone-dynamic-static-initializers | | +---------------------------------------------------------+--------------+ | bugprone-exception-escape | | +---------------------------------------------------------+--------------+ | bugprone-fold-init-type | | +---------------------------------------------------------+--------------+ | bugprone-forward-declaration-namespace | | +---------------------------------------------------------+--------------+ | bugprone-forwarding-reference-overload | | +---------------------------------------------------------+--------------+ | bugprone-inaccurate-erase | Yes | +---------------------------------------------------------+--------------+ | bugprone-incorrect-roundings | | +---------------------------------------------------------+--------------+ | bugprone-infinite-loop | | +---------------------------------------------------------+--------------+ | bugprone-integer-division | | +---------------------------------------------------------+--------------+ | bugprone-lambda-function-name | | +---------------------------------------------------------+--------------+ | bugprone-macro-parentheses | Yes | +---------------------------------------------------------+--------------+ | bugprone-macro-repeated-side-effects | | +---------------------------------------------------------+--------------+ | bugprone-misplaced-operator-in-strlen-in-alloc | Yes | +---------------------------------------------------------+--------------+ | bugprone-misplaced-pointer-arithmetic-in-alloc | Yes | +---------------------------------------------------------+--------------+ | bugprone-misplaced-widening-cast | | +---------------------------------------------------------+--------------+ | bugprone-move-forwarding-reference | Yes | +---------------------------------------------------------+--------------+ | bugprone-multiple-statement-macro | | +---------------------------------------------------------+--------------+ | bugprone-no-escape | Yes | +---------------------------------------------------------+--------------+ | bugprone-not-null-terminated-result | Yes | +---------------------------------------------------------+--------------+ | bugprone-parent-virtual-call | Yes | +---------------------------------------------------------+--------------+ | bugprone-posix-return | Yes | +---------------------------------------------------------+--------------+ | bugprone-reserved-identifier | Yes | +---------------------------------------------------------+--------------+ | bugprone-signed-char-misuse | | +---------------------------------------------------------+--------------+ | bugprone-sizeof-container | | +---------------------------------------------------------+--------------+ | bugprone-sizeof-expression | | +---------------------------------------------------------+--------------+ | bugprone-spuriously-wake-up-functions | | +---------------------------------------------------------+--------------+ | bugprone-string-constructor | Yes | +---------------------------------------------------------+--------------+ | bugprone-string-integer-assignment | Yes | +---------------------------------------------------------+--------------+ | bugprone-string-literal-with-embedded-nul | | +---------------------------------------------------------+--------------+ | bugprone-suspicious-enum-usage | | +---------------------------------------------------------+--------------+ | bugprone-suspicious-include | | +---------------------------------------------------------+--------------+ | bugprone-suspicious-memset-usage | Yes | +---------------------------------------------------------+--------------+ | bugprone-suspicious-missing-comma | | +---------------------------------------------------------+--------------+ | bugprone-suspicious-semicolon | Yes | +---------------------------------------------------------+--------------+ | bugprone-suspicious-string-compare | Yes | +---------------------------------------------------------+--------------+ | bugprone-swapped-arguments | Yes | +---------------------------------------------------------+--------------+ | bugprone-terminating-continue | Yes | +---------------------------------------------------------+--------------+ | bugprone-throw-keyword-missing | | +---------------------------------------------------------+--------------+ | bugprone-too-small-loop-variable | | +---------------------------------------------------------+--------------+ | bugprone-undefined-memory-manipulation | | +---------------------------------------------------------+--------------+ | bugprone-undelegated-constructor | | +---------------------------------------------------------+--------------+ | bugprone-unhandled-self-assignment | | +---------------------------------------------------------+--------------+ | bugprone-unused-raii | Yes | +---------------------------------------------------------+--------------+ | bugprone-unused-return-value | | +---------------------------------------------------------+--------------+ | bugprone-use-after-move | | +---------------------------------------------------------+--------------+ | bugprone-virtual-near-miss | Yes | +---------------------------------------------------------+--------------+ | cert-dcl21-cpp | | +---------------------------------------------------------+--------------+ | cert-dcl50-cpp | | +---------------------------------------------------------+--------------+ | cert-dcl58-cpp | | +---------------------------------------------------------+--------------+ | cert-env33-c | | +---------------------------------------------------------+--------------+ | cert-err34-c | | +---------------------------------------------------------+--------------+ | cert-err52-cpp | | +---------------------------------------------------------+--------------+ | cert-err58-cpp | | +---------------------------------------------------------+--------------+ | cert-err60-cpp | | +---------------------------------------------------------+--------------+ | cert-flp30-c | | +---------------------------------------------------------+--------------+ | cert-mem57-cpp | | +---------------------------------------------------------+--------------+ | cert-msc50-cpp | | +---------------------------------------------------------+--------------+ | cert-msc51-cpp | | +---------------------------------------------------------+--------------+ | cert-oop57-cpp | | +---------------------------------------------------------+--------------+ | cert-oop58-cpp | | +---------------------------------------------------------+--------------+ | clang-analyzer-core.DynamicTypePropagation | | +---------------------------------------------------------+--------------+ | clang-analyzer-core.uninitialized.CapturedBlockVariable | | +---------------------------------------------------------+--------------+ | clang-analyzer-cplusplus.InnerPointer | | +---------------------------------------------------------+--------------+ | clang-analyzer-nullability.NullableReturnedFromNonnull | | +---------------------------------------------------------+--------------+ | clang-analyzer-optin.osx.OSObjectCStyleCast | | +---------------------------------------------------------+--------------+ | clang-analyzer-optin.performance.GCDAntipattern | | +---------------------------------------------------------+--------------+ | clang-analyzer-optin.performance.Padding | | +---------------------------------------------------------+--------------+ | clang-analyzer-optin.portability.UnixAPI | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.MIG | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.NumberObjectConversion | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.OSObjectRetainCount | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.ObjCProperty | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.AutoreleaseWrite | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.Loops | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.MissingSuperCall | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.NonNilReturnValue | | +---------------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.RunLoopAutoreleaseLeak | | +---------------------------------------------------------+--------------+ | clang-analyzer-valist.CopyToSelf | | +---------------------------------------------------------+--------------+ | clang-analyzer-valist.Uninitialized | | +---------------------------------------------------------+--------------+ | clang-analyzer-valist.Unterminated | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-avoid-goto | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-avoid-non-const-global-variables | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-init-variables | Yes | +---------------------------------------------------------+--------------+ | cppcoreguidelines-interfaces-global-init | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-macro-usage | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-narrowing-conversions | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-no-malloc | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-owning-memory | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-bounds-array-to-pointer-decay | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-bounds-constant-array-index | Yes | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-bounds-pointer-arithmetic | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-const-cast | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-cstyle-cast | Yes | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-member-init | Yes | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-reinterpret-cast | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-static-cast-downcast | Yes | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-union-access | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-pro-type-vararg | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-slicing | | +---------------------------------------------------------+--------------+ | cppcoreguidelines-special-member-functions | | +---------------------------------------------------------+--------------+ | darwin-avoid-spinlock | | +---------------------------------------------------------+--------------+ | darwin-dispatch-once-nonstatic | Yes | +---------------------------------------------------------+--------------+ | fuchsia-default-arguments-calls | | +---------------------------------------------------------+--------------+ | fuchsia-default-arguments-declarations | Yes | +---------------------------------------------------------+--------------+ | fuchsia-multiple-inheritance | | +---------------------------------------------------------+--------------+ | fuchsia-overloaded-operator | | +---------------------------------------------------------+--------------+ | fuchsia-statically-constructed-objects | | +---------------------------------------------------------+--------------+ | fuchsia-trailing-return | | +---------------------------------------------------------+--------------+ | fuchsia-virtual-inheritance | | +---------------------------------------------------------+--------------+ | google-build-explicit-make-pair | | +---------------------------------------------------------+--------------+ | google-build-namespaces | | +---------------------------------------------------------+--------------+ | google-build-using-namespace | | +---------------------------------------------------------+--------------+ | google-default-arguments | | +---------------------------------------------------------+--------------+ | google-explicit-constructor | Yes | +---------------------------------------------------------+--------------+ | google-global-names-in-headers | | +---------------------------------------------------------+--------------+ | google-objc-avoid-nsobject-new | | +---------------------------------------------------------+--------------+ | google-objc-avoid-throwing-exception | | +---------------------------------------------------------+--------------+ | google-objc-function-naming | | +---------------------------------------------------------+--------------+ | google-objc-global-variable-declaration | | +---------------------------------------------------------+--------------+ | google-readability-avoid-underscore-in-googletest-name | | +---------------------------------------------------------+--------------+ | google-readability-casting | | +---------------------------------------------------------+--------------+ | google-readability-todo | | +---------------------------------------------------------+--------------+ | google-runtime-int | | +---------------------------------------------------------+--------------+ | google-runtime-operator | | +---------------------------------------------------------+--------------+ | google-runtime-references | | +---------------------------------------------------------+--------------+ | google-upgrade-googletest-case | Yes | +---------------------------------------------------------+--------------+ | hicpp-avoid-goto | | +---------------------------------------------------------+--------------+ | hicpp-exception-baseclass | | +---------------------------------------------------------+--------------+ | hicpp-multiway-paths-covered | | +---------------------------------------------------------+--------------+ | hicpp-no-assembler | | +---------------------------------------------------------+--------------+ | hicpp-signed-bitwise | | +---------------------------------------------------------+--------------+ | linuxkernel-must-use-errs | | +---------------------------------------------------------+--------------+ | llvm-header-guard | | +---------------------------------------------------------+--------------+ | llvm-include-order | Yes | +---------------------------------------------------------+--------------+ | llvm-namespace-comment | | +---------------------------------------------------------+--------------+ | llvm-prefer-isa-or-dyn-cast-in-conditionals | Yes | +---------------------------------------------------------+--------------+ | llvm-prefer-register-over-unsigned | Yes | +---------------------------------------------------------+--------------+ | llvm-twine-local | Yes | +---------------------------------------------------------+--------------+ | llvmlibc-callee-namespace | | +---------------------------------------------------------+--------------+ | llvmlibc-implementation-in-namespace | | +---------------------------------------------------------+--------------+ | llvmlibc-restrict-system-libc-headers | Yes | +---------------------------------------------------------+--------------+ | misc-definitions-in-headers | Yes | +---------------------------------------------------------+--------------+ | misc-misplaced-const | | +---------------------------------------------------------+--------------+ | misc-new-delete-overloads | | +---------------------------------------------------------+--------------+ | misc-no-recursion | | +---------------------------------------------------------+--------------+ | misc-non-copyable-objects | | +---------------------------------------------------------+--------------+ | misc-non-private-member-variables-in-classes | | +---------------------------------------------------------+--------------+ | misc-redundant-expression | Yes | +---------------------------------------------------------+--------------+ | misc-static-assert | Yes | +---------------------------------------------------------+--------------+ | misc-throw-by-value-catch-by-reference | | +---------------------------------------------------------+--------------+ | misc-unconventional-assign-operator | | +---------------------------------------------------------+--------------+ | misc-uniqueptr-reset-release | Yes | +---------------------------------------------------------+--------------+ | misc-unused-alias-decls | Yes | +---------------------------------------------------------+--------------+ | misc-unused-parameters | Yes | +---------------------------------------------------------+--------------+ | misc-unused-using-decls | Yes | +---------------------------------------------------------+--------------+ | modernize-avoid-bind | Yes | +---------------------------------------------------------+--------------+ | modernize-avoid-c-arrays | | +---------------------------------------------------------+--------------+ | modernize-concat-nested-namespaces | Yes | +---------------------------------------------------------+--------------+ | modernize-deprecated-headers | Yes | +---------------------------------------------------------+--------------+ | modernize-deprecated-ios-base-aliases | Yes | +---------------------------------------------------------+--------------+ | modernize-loop-convert | Yes | +---------------------------------------------------------+--------------+ | modernize-make-shared | Yes | +---------------------------------------------------------+--------------+ | modernize-make-unique | Yes | +---------------------------------------------------------+--------------+ | modernize-pass-by-value | Yes | +---------------------------------------------------------+--------------+ | modernize-raw-string-literal | Yes | +---------------------------------------------------------+--------------+ | modernize-redundant-void-arg | Yes | +---------------------------------------------------------+--------------+ | modernize-replace-auto-ptr | Yes | +---------------------------------------------------------+--------------+ | modernize-replace-disallow-copy-and-assign-macro | Yes | +---------------------------------------------------------+--------------+ | modernize-replace-random-shuffle | Yes | +---------------------------------------------------------+--------------+ | modernize-return-braced-init-list | Yes | +---------------------------------------------------------+--------------+ | modernize-shrink-to-fit | Yes | +---------------------------------------------------------+--------------+ | modernize-unary-static-assert | Yes | +---------------------------------------------------------+--------------+ | modernize-use-auto | Yes | +---------------------------------------------------------+--------------+ | modernize-use-bool-literals | Yes | +---------------------------------------------------------+--------------+ | modernize-use-default-member-init | Yes | +---------------------------------------------------------+--------------+ | modernize-use-emplace | Yes | +---------------------------------------------------------+--------------+ | modernize-use-equals-default | Yes | +---------------------------------------------------------+--------------+ | modernize-use-equals-delete | Yes | +---------------------------------------------------------+--------------+ | modernize-use-nodiscard | Yes | +---------------------------------------------------------+--------------+ | modernize-use-noexcept | Yes | +---------------------------------------------------------+--------------+ | modernize-use-nullptr | Yes | +---------------------------------------------------------+--------------+ | modernize-use-override | Yes | +---------------------------------------------------------+--------------+ | modernize-use-trailing-return-type | Yes | +---------------------------------------------------------+--------------+ | modernize-use-transparent-functors | Yes | +---------------------------------------------------------+--------------+ | modernize-use-uncaught-exceptions | Yes | +---------------------------------------------------------+--------------+ | modernize-use-using | Yes | +---------------------------------------------------------+--------------+ | mpi-buffer-deref | Yes | +---------------------------------------------------------+--------------+ | mpi-type-mismatch | Yes | +---------------------------------------------------------+--------------+ | objc-avoid-nserror-init | | +---------------------------------------------------------+--------------+ | objc-dealloc-in-category | | +---------------------------------------------------------+--------------+ | objc-forbidden-subclassing | | +---------------------------------------------------------+--------------+ | objc-missing-hash | | +---------------------------------------------------------+--------------+ | objc-nsinvocation-argument-lifetime | Yes | +---------------------------------------------------------+--------------+ | objc-property-declaration | Yes | +---------------------------------------------------------+--------------+ | objc-super-self | Yes | +---------------------------------------------------------+--------------+ | openmp-exception-escape | | +---------------------------------------------------------+--------------+ | openmp-use-default-none | | +---------------------------------------------------------+--------------+ | performance-faster-string-find | Yes | +---------------------------------------------------------+--------------+ | performance-for-range-copy | Yes | +---------------------------------------------------------+--------------+ | performance-implicit-conversion-in-loop | | +---------------------------------------------------------+--------------+ | performance-inefficient-algorithm | Yes | +---------------------------------------------------------+--------------+ | performance-inefficient-string-concatenation | | +---------------------------------------------------------+--------------+ | performance-inefficient-vector-operation | Yes | +---------------------------------------------------------+--------------+ | performance-move-const-arg | Yes | +---------------------------------------------------------+--------------+ | performance-move-constructor-init | Yes | +---------------------------------------------------------+--------------+ | performance-no-automatic-move | | +---------------------------------------------------------+--------------+ | performance-noexcept-move-constructor | Yes | +---------------------------------------------------------+--------------+ | performance-trivially-destructible | Yes | +---------------------------------------------------------+--------------+ | performance-type-promotion-in-math-fn | Yes | +---------------------------------------------------------+--------------+ | performance-unnecessary-copy-initialization | | +---------------------------------------------------------+--------------+ | performance-unnecessary-value-param | Yes | +---------------------------------------------------------+--------------+ | portability-restrict-system-includes | Yes | +---------------------------------------------------------+--------------+ | portability-simd-intrinsics | | +---------------------------------------------------------+--------------+ | readability-avoid-const-params-in-decls | | +---------------------------------------------------------+--------------+ | readability-braces-around-statements | Yes | +---------------------------------------------------------+--------------+ | readability-const-return-type | Yes | +---------------------------------------------------------+--------------+ | readability-container-size-empty | Yes | +---------------------------------------------------------+--------------+ | readability-convert-member-functions-to-static | | +---------------------------------------------------------+--------------+ | readability-delete-null-pointer | Yes | +---------------------------------------------------------+--------------+ | readability-deleted-default | | +---------------------------------------------------------+--------------+ | readability-else-after-return | Yes | +---------------------------------------------------------+--------------+ | readability-function-size | | +---------------------------------------------------------+--------------+ | readability-identifier-naming | Yes | +---------------------------------------------------------+--------------+ | readability-implicit-bool-conversion | Yes | +---------------------------------------------------------+--------------+ | readability-inconsistent-declaration-parameter-name | Yes | +---------------------------------------------------------+--------------+ | readability-isolate-declaration | Yes | +---------------------------------------------------------+--------------+ | readability-magic-numbers | | +---------------------------------------------------------+--------------+ | readability-make-member-function-const | Yes | +---------------------------------------------------------+--------------+ | readability-misleading-indentation | | +---------------------------------------------------------+--------------+ | readability-misplaced-array-index | Yes | +---------------------------------------------------------+--------------+ | readability-named-parameter | Yes | +---------------------------------------------------------+--------------+ | readability-non-const-parameter | Yes | +---------------------------------------------------------+--------------+ | readability-qualified-auto | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-access-specifiers | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-control-flow | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-declaration | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-function-ptr-dereference | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-member-init | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-preprocessor | | +---------------------------------------------------------+--------------+ | readability-redundant-smartptr-get | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-string-cstr | Yes | +---------------------------------------------------------+--------------+ | readability-redundant-string-init | Yes | +---------------------------------------------------------+--------------+ | readability-simplify-boolean-expr | Yes | +---------------------------------------------------------+--------------+ | readability-simplify-subscript-expr | Yes | +---------------------------------------------------------+--------------+ | readability-static-accessed-through-instance | Yes | +---------------------------------------------------------+--------------+ | readability-static-definition-in-anonymous-namespace | Yes | +---------------------------------------------------------+--------------+ | readability-string-compare | Yes | +---------------------------------------------------------+--------------+ | readability-uniqueptr-delete-release | Yes | +---------------------------------------------------------+--------------+ | readability-uppercase-literal-suffix | Yes | +---------------------------------------------------------+--------------+ | readability-use-anyofallof | | +---------------------------------------------------------+--------------+ | zircon-temporary-objects | | +---------------------------------------------------------+--------------+ Aliases.. +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | Name | Redirect | Offers fixes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-con36-c | bugprone-spuriously-wake-up-functions | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-con54-cpp | bugprone-spuriously-wake-up-functions | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl03-c | misc-static-assert | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl16-c | readability-uppercase-literal-suffix | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl37-c | bugprone-reserved-identifier | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl51-cpp | bugprone-reserved-identifier | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl54-cpp | misc-new-delete-overloads | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-dcl59-cpp | google-build-namespaces | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-err09-cpp | misc-throw-by-value-catch-by-reference | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-err61-cpp | misc-throw-by-value-catch-by-reference | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-fio38-c | misc-non-copyable-objects | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-msc30-c | cert-msc50-cpp | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-msc32-c | cert-msc51-cpp | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-oop11-cpp | performance-move-constructor-init | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-oop54-cpp | bugprone-unhandled-self-assignment | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-pos44-c | bugprone-bad-signal-to-kill-thread | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cert-str34-c | bugprone-signed-char-misuse | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.CallAndMessage | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.DivideZero | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.NonNullParamChecker | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.NullDereference | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.StackAddressEscape | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.UndefinedBinaryOperatorResult | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.VLASize | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.uninitialized.ArraySubscript | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.uninitialized.Assign | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.uninitialized.Branch | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-core.uninitialized.UndefReturn | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-cplusplus.Move | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-cplusplus.NewDelete | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-cplusplus.NewDeleteLeaks | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-deadcode.DeadStores | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-nullability.NullPassedToNonnull | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-nullability.NullReturnedFromNonnull | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-nullability.NullableDereferenced | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-nullability.NullablePassedToNonnull | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-optin.cplusplus.UninitializedObject | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-optin.cplusplus.VirtualCall | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-optin.mpi.MPI-Checker | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-optin.osx.cocoa.localizability.EmptyLocalizationContextChecker | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-optin.osx.cocoa.localizability.NonLocalizedStringChecker | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.API | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.SecKeychainAPI | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.AtSync | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.ClassRelease | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.Dealloc | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.IncompatibleMethodTypes | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.NSAutoreleasePool | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.NSError | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.NilArg | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.ObjCGenerics | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.RetainCount | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.SelfInit | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.SuperDealloc | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.UnusedIvars | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.cocoa.VariadicMethodTypes | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.coreFoundation.CFError | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.coreFoundation.CFNumber | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.coreFoundation.CFRetainRelease | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.coreFoundation.containers.OutOfBounds | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-osx.coreFoundation.containers.PointerSizedValues | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.FloatLoopCounter | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.UncheckedReturn | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.bcmp | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.bcopy | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.bzero | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.getpw | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.gets | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.mkstemp | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.mktemp | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.rand | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.strcpy | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-security.insecureAPI.vfork | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.API | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.Malloc | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.MallocSizeof | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.MismatchedDeallocator | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.Vfork | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.cstring.BadSizeArg | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | clang-analyzer-unix.cstring.NullArg | Clang Static Analyzer | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cppcoreguidelines-avoid-c-arrays | modernize-avoid-c-arrays | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cppcoreguidelines-avoid-magic-numbers | readability-magic-numbers | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cppcoreguidelines-c-copy-assignment-signature | misc-unconventional-assign-operator | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cppcoreguidelines-explicit-virtual-functions | modernize-use-override | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | cppcoreguidelines-non-private-member-variables-in-classes | misc-non-private-member-variables-in-classes | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | fuchsia-header-anon-namespaces | google-build-namespaces | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | google-readability-braces-around-statements | readability-braces-around-statements | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | google-readability-function-size | readability-function-size | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | google-readability-namespace-comments | llvm-namespace-comment | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-avoid-c-arrays | modernize-avoid-c-arrays | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-braces-around-statements | readability-braces-around-statements | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-deprecated-headers | modernize-deprecated-headers | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-explicit-conversions | google-explicit-constructor | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-function-size | readability-function-size | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-invalid-access-moved | bugprone-use-after-move | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-member-init | cppcoreguidelines-pro-type-member-init | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-move-const-arg | performance-move-const-arg | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-named-parameter | readability-named-parameter | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-new-delete-operators | misc-new-delete-overloads | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-no-array-decay | cppcoreguidelines-pro-bounds-array-to-pointer-decay | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-no-malloc | cppcoreguidelines-no-malloc | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-noexcept-move | performance-noexcept-move-constructor | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-special-member-functions | cppcoreguidelines-special-member-functions | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-static-assert | misc-static-assert | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-undelegated-constructor | bugprone-undelegated-constructor | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-uppercase-literal-suffix | readability-uppercase-literal-suffix | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-auto | modernize-use-auto | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-emplace | modernize-use-emplace | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-equals-default | modernize-use-equals-default | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-equals-delete | modernize-use-equals-delete | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-noexcept | modernize-use-noexcept | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-nullptr | modernize-use-nullptr | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-use-override | modernize-use-override | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | hicpp-vararg | cppcoreguidelines-pro-type-vararg | | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | llvm-else-after-return | readability-else-after-return | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ | llvm-qualified-auto | readability-qualified-auto | Yes | +-------------------------------------------------------------------------------+-----------------------------------------------------+--------------+ Clang-tidy IDE/Editor Integrations Apart from being a standalone tool, clang-tidy is integrated into vari- ous IDEs, code analyzers, and editors. Besides, it is currently being integrated into Clangd. The following table shows the most well-known clang-tidy integrations in detail. +-------------+------------+-------------+-------------+-------------+------------+ | | Feature | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Tool | On-the-fly | Check list | Options to | Configura- | Custom | | | inspection | configura- | checks | tion via | clang-tidy | | | | tion (GUI) | (GUI) | .clang-tidy | binary | | | | | | files | | +-------------+------------+-------------+-------------+-------------+------------+ | A.L.E. for | + | - | - | - | + | | Vim | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Clang Power | - | + | - | + | - | | Tools for | | | | | | | Visual Stu- | | | | | | | dio | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Clangd | + | - | - | - | - | +-------------+------------+-------------+-------------+-------------+------------+ | CLion IDE | + | + | + | + | + | +-------------+------------+-------------+-------------+-------------+------------+ | CodeChecker | - | - | - | - | + | +-------------+------------+-------------+-------------+-------------+------------+ | CPPCheck | - | - | - | - | - | +-------------+------------+-------------+-------------+-------------+------------+ | CPPDepend | - | - | - | - | - | +-------------+------------+-------------+-------------+-------------+------------+ | Flycheck | + | - | - | + | + | | for Emacs | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | KDevelop | - | + | + | + | + | | IDE | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Qt Creator | + | + | - | + | + | | IDE | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | ReSharper | + | + | - | + | + | | C++ for Vi- | | | | | | | sual Studio | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Syntastic | + | - | - | - | + | | for Vim | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ | Visual As- | + | + | - | - | - | | sist for | | | | | | | Visual Stu- | | | | | | | dio | | | | | | +-------------+------------+-------------+-------------+-------------+------------+ IDEs CLion 2017.2 and later integrates clang-tidy as an extension to the built-in code analyzer. Starting from 2018.2 EAP, CLion allows using clang-tidy via Clangd. Inspections and applicable quick-fixes are per- formed on the fly, and checks can be configured in standard command line format. In this integration, you can switch to the clang-tidy bi- nary different from the bundled one, pass the configuration in .clang-tidy files instead of using the IDE settings, and configure op- tions for particular checks. KDevelop with the kdev-clang-tidy plugin, starting from version 5.1, performs static analysis using clang-tidy. The plugin launches the clang-tidy binary from the specified location and parses its output to provide a list of issues. QtCreator 4.6 integrates clang-tidy warnings into the editor diagnos- tics under the Clang Code Model. To employ clang-tidy inspection in Qt- Creator, you need to create a copy of one of the presets and choose the checks to be performed. Since QtCreator 4.7 project-wide analysis is possible with the Clang Tools analyzer. MS Visual Studio has a native clang-tidy-vs plugin and also can inte- grate clang-tidy by means of three other tools. The ReSharper C++ ex- tension, version 2017.3 and later, provides seamless clang-tidy inte- gration: checks and quick-fixes run alongside native inspections. Apart from that, ReSharper C++ incorporates clang-tidy as a separate step of its code clean-up process. Visual Assist build 2210 includes a subset of clang-tidy checklist to inspect the code as you edit. Another way to bring clang-tidy functionality to Visual Studio is the Clang Power Tools plugin, which includes most of the clang-tidy checks and runs them during compilation or as a separate step of code analysis. Editors Emacs24, when expanded with the Flycheck plugin, incorporates the clang-tidy inspection into the syntax analyzer. For Vim, you can use Syntastic, which includes clang-tidy, or A.L.E., a lint engine that ap- plies clang-tidy along with other linters. Analyzers clang-tidy is integrated in CPPDepend starting from version 2018.1 and CPPCheck 1.82. CPPCheck integration lets you import Visual Studio solu- tions and run the clang-tidy inspection on them. The CodeChecker appli- cation of version 5.3 or later, which also comes as a plugin for Eclipse, supports clang-tidy as a static analysis instrument and allows to use a custom clang-tidy binary. Getting Involved clang-tidy has several own checks and can run Clang static analyzer checks, but its power is in the ability to easily write custom checks. Checks are organized in modules, which can be linked into clang-tidy with minimal or no code changes in clang-tidy. Checks can plug into the analysis on the preprocessor level using PPCallbacks or on the AST level using AST Matchers. When an error is found, checks can report them in a way similar to how Clang diagnostics work. A fix-it hint can be attached to a diagnostic message. The interface provided by clang-tidy makes it easy to write useful and precise checks in just a few lines of code. If you have an idea for a good check, the rest of this document explains how to do this. There are a few tools particularly useful when developing clang-tidy checks: • add_new_check.py is a script to automate the process of adding a new check, it will create the check, update the CMake file and create a test; • rename_check.py does what the script name suggests, renames an existing check; • clang-query is invaluable for interactive prototyping of AST matchers and exploration of the Clang AST; • clang-check with the -ast-dump (and optionally -ast-dump-fil- ter) provides a convenient way to dump AST of a C++ program. If CMake is configured with CLANG_ENABLE_STATIC_ANALYZER, clang-tidy will not be built with support for the clang-analyzer-* checks or the mpi-* checks. Choosing the Right Place for your Check If you have an idea of a check, you should decide whether it should be implemented as a: • Clang diagnostic: if the check is generic enough, targets code pat- terns that most probably are bugs (rather than style or readability issues), can be implemented effectively and with extremely low false positive rate, it may make a good Clang diagnostic. • Clang static analyzer check: if the check requires some sort of con- trol flow analysis, it should probably be implemented as a static an- alyzer check. • clang-tidy check is a good choice for linter-style checks, checks that are related to a certain coding style, checks that address code readability, etc. Preparing your Workspace If you are new to LLVM development, you should read the Getting Started with the LLVM System, Using Clang Tools and How To Setup Clang Tooling For LLVM documents to check out and build LLVM, Clang and Clang Extra Tools with CMake. Once you are done, change to the llvm/clang-tools-extra directory, and let's start! The Directory Structure clang-tidy source code resides in the llvm/clang-tools-extra directory and is structured as follows: clang-tidy/ # Clang-tidy core. |-- ClangTidy.h # Interfaces for users. |-- ClangTidyCheck.h # Interfaces for checks. |-- ClangTidyModule.h # Interface for clang-tidy modules. |-- ClangTidyModuleRegistry.h # Interface for registering of modules. ... |-- google/ # Google clang-tidy module. |-+ |-- GoogleTidyModule.cpp |-- GoogleTidyModule.h ... |-- llvm/ # LLVM clang-tidy module. |-+ |-- LLVMTidyModule.cpp |-- LLVMTidyModule.h ... |-- objc/ # Objective-C clang-tidy module. |-+ |-- ObjCTidyModule.cpp |-- ObjCTidyModule.h ... |-- tool/ # Sources of the clang-tidy binary. ... test/clang-tidy/ # Integration tests. ... unittests/clang-tidy/ # Unit tests. |-- ClangTidyTest.h |-- GoogleModuleTest.cpp |-- LLVMModuleTest.cpp |-- ObjCModuleTest.cpp ... Writing a clang-tidy Check So you have an idea of a useful check for clang-tidy. First, if you're not familiar with LLVM development, read through the Getting Started with LLVM document for instructions on setting up your workflow and the LLVM Coding Standards document to familiarize yourself with the coding style used in the project. For code reviews we mostly use LLVM Phabricator. Next, you need to decide which module the check belongs to. Modules are located in subdirectories of clang-tidy/ and contain checks targeting a certain aspect of code quality (performance, readability, etc.), cer- tain coding style or standard (Google, LLVM, CERT, etc.) or a widely used API (e.g. MPI). Their names are same as user-facing check groups names described above. After choosing the module and the name for the check, run the clang-tidy/add_new_check.py script to create the skeleton of the check and plug it to clang-tidy. It's the recommended way of adding new checks. If we want to create a readability-awesome-function-names, we would run: $ clang-tidy/add_new_check.py readability awesome-function-names The add_new_check.py script will: • create the class for your check inside the specified module's directory and register it in the module and in the build sys- tem; • create a lit test file in the test/clang-tidy/ directory; • create a documentation file and include it into the docs/clang-tidy/checks/list.rst. Let's see in more detail at the check class definition: ... #include "../ClangTidyCheck.h" namespace clang { namespace tidy { namespace readability { ... class AwesomeFunctionNamesCheck : public ClangTidyCheck { public: AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context) : ClangTidyCheck(Name, Context) {} void registerMatchers(ast_matchers::MatchFinder *Finder) override; void check(const ast_matchers::MatchFinder::MatchResult &Result) override; }; } // namespace readability } // namespace tidy } // namespace clang ... Constructor of the check receives the Name and Context parameters, and must forward them to the ClangTidyCheck constructor. In our case the check needs to operate on the AST level and it over- rides the registerMatchers and check methods. If we wanted to analyze code on the preprocessor level, we'd need instead to override the reg- isterPPCallbacks method. In the registerMatchers method we create an AST Matcher (see AST Match- ers for more information) that will find the pattern in the AST that we want to inspect. The results of the matching are passed to the check method, which can further inspect them and report diagnostics. using namespace ast_matchers; void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) { Finder->addMatcher(functionDecl().bind("x"), this); } void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) { const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x"); if (MatchedDecl->getName().startswith("awesome_")) return; diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome") << MatchedDecl << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_"); } (If you want to see an example of a useful check, look at clang-tidy/google/ExplicitConstructorCheck.h and clang-tidy/google/ExplicitConstructorCheck.cpp). Registering your Check (The add_new_check.py takes care of registering the check in an exist- ing module. If you want to create a new module or know the details, read on.) The check should be registered in the corresponding module with a dis- tinct name: class MyModule : public ClangTidyModule { public: void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override { CheckFactories.registerCheck<ExplicitConstructorCheck>( "my-explicit-constructor"); } }; Now we need to register the module in the ClangTidyModuleRegistry using a statically initialized variable: static ClangTidyModuleRegistry::Add<MyModule> X("my-module", "Adds my lint checks."); When using LLVM build system, we need to use the following hack to en- sure the module is linked into the clang-tidy binary: Add this near the ClangTidyModuleRegistry::Add<MyModule> variable: // This anchor is used to force the linker to link in the generated object file // and thus register the MyModule. volatile int MyModuleAnchorSource = 0; And this to the main translation unit of the clang-tidy binary (or the binary you link the clang-tidy library in) clang-tidy/tool/ClangTidy- Main.cpp: // This anchor is used to force the linker to link the MyModule. extern volatile int MyModuleAnchorSource; static int MyModuleAnchorDestination = MyModuleAnchorSource; Configuring Checks If a check needs configuration options, it can access check-specific options using the Options.get<Type>("SomeOption", DefaultValue) call in the check constructor. In this case the check should also override the ClangTidyCheck::storeOptions method to make the options provided by the check discoverable. This method lets clang-tidy know which options the check implements and what the current values are (e.g. for the -dump-config command line option). class MyCheck : public ClangTidyCheck { const unsigned SomeOption1; const std::string SomeOption2; public: MyCheck(StringRef Name, ClangTidyContext *Context) : ClangTidyCheck(Name, Context), SomeOption(Options.get("SomeOption1", -1U)), SomeOption(Options.get("SomeOption2", "some default")) {} void storeOptions(ClangTidyOptions::OptionMap &Opts) override { Options.store(Opts, "SomeOption1", SomeOption1); Options.store(Opts, "SomeOption2", SomeOption2); } ... Assuming the check is registered with the name "my-check", the option can then be set in a .clang-tidy file in the following way: CheckOptions: - key: my-check.SomeOption1 value: 123 - key: my-check.SomeOption2 value: 'some other value' If you need to specify check options on a command line, you can use the inline YAML format: $ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value: y}]}" ... Testing Checks To run tests for clang-tidy use the command: $ ninja check-clang-tools clang-tidy checks can be tested using either unit tests or lit tests. Unit tests may be more convenient to test complex replacements with strict checks. Lit tests allow using partial text matching and regular expressions which makes them more suitable for writing compact tests for diagnostic messages. The check_clang_tidy.py script provides an easy way to test both diag- nostic messages and fix-its. It filters out CHECK lines from the test file, runs clang-tidy and verifies messages and fixes with two separate FileCheck invocations: once with FileCheck's directive prefix set to CHECK-MESSAGES, validating the diagnostic messages, and once with the directive prefix set to CHECK-FIXES, running against the fixed code (i.e., the code after generated fix-its are applied). In particular, CHECK-FIXES: can be used to check that code was not modified by fix-its, by checking that it is present unchanged in the fixed code. The full set of FileCheck directives is available (e.g., CHECK-MES- SAGES-SAME:, CHECK-MESSAGES-NOT:), though typically the basic CHECK forms (CHECK-MESSAGES and CHECK-FIXES) are sufficient for clang-tidy tests. Note that the FileCheck documentation mostly assumes the default prefix (CHECK), and hence describes the directive as CHECK:, CHECK-SAME:, CHECK-NOT:, etc. Replace CHECK by either CHECK-FIXES or CHECK-MESSAGES for clang-tidy tests. An additional check enabled by check_clang_tidy.py ensures that if CHECK-MESSAGES: is used in a file then every warning or error must have an associated CHECK in that file. Or, you can use CHECK-NOTES: instead, if you want to also ensure that all the notes are checked. To use the check_clang_tidy.py script, put a .cpp file with the appro- priate RUN line in the test/clang-tidy directory. Use CHECK-MESSAGES: and CHECK-FIXES: lines to write checks against diagnostic messages and fixed code. It's advised to make the checks as specific as possible to avoid checks matching to incorrect parts of the input. Use [[@LINE+X]]/[[@LINE-X]] substitutions and distinct function and variable names in the test code. Here's an example of a test using the check_clang_tidy.py script (the full source code is at test/clang-tidy/google-readability-casting.cpp): // RUN: %check_clang_tidy %s google-readability-casting %t void f(int a) { int b = (int)a; // CHECK-MESSAGES: :[[@LINE-1]]:11: warning: redundant cast to the same type [google-readability-casting] // CHECK-FIXES: int b = a; } To check more than one scenario in the same test file use -check-suf- fix=SUFFIX-NAME on check_clang_tidy.py command line or -check-suf- fixes=SUFFIX-NAME-1,SUFFIX-NAME-2,.... With -check-suffix[es]=SUF- FIX-NAME you need to replace your CHECK-* directives with CHECK-MES- SAGES-SUFFIX-NAME and CHECK-FIXES-SUFFIX-NAME. Here's an example: // RUN: %check_clang_tidy -check-suffix=USING-A %s misc-unused-using-decls %t -- -- -DUSING_A // RUN: %check_clang_tidy -check-suffix=USING-B %s misc-unused-using-decls %t -- -- -DUSING_B // RUN: %check_clang_tidy %s misc-unused-using-decls %t ... // CHECK-MESSAGES-USING-A: :[[@LINE-8]]:10: warning: using decl 'A' {{.*}} // CHECK-MESSAGES-USING-B: :[[@LINE-7]]:10: warning: using decl 'B' {{.*}} // CHECK-MESSAGES: :[[@LINE-6]]:10: warning: using decl 'C' {{.*}} // CHECK-FIXES-USING-A-NOT: using a::A;$ // CHECK-FIXES-USING-B-NOT: using a::B;$ // CHECK-FIXES-NOT: using a::C;$ There are many dark corners in the C++ language, and it may be diffi- cult to make your check work perfectly in all cases, especially if it issues fix-it hints. The most frequent pitfalls are macros and tem- plates: 1. code written in a macro body/template definition may have a differ- ent meaning depending on the macro expansion/template instantiation; 2. multiple macro expansions/template instantiations may result in the same code being inspected by the check multiple times (possibly, with different meanings, see 1), and the same warning (or a slightly different one) may be issued by the check multiple times; clang-tidy will deduplicate _identical_ warnings, but if the warnings are slightly different, all of them will be shown to the user (and used for applying fixes, if any); 3. making replacements to a macro body/template definition may be fine for some macro expansions/template instantiations, but easily break some other expansions/instantiations. Running clang-tidy on LLVM To test a check it's best to try it out on a larger code base. LLVM and Clang are the natural targets as you already have the source code around. The most convenient way to run clang-tidy is with a compile command database; CMake can automatically generate one, for a descrip- tion of how to enable it see How To Setup Clang Tooling For LLVM. Once compile_commands.json is in place and a working version of clang-tidy is in PATH the entire code base can be analyzed with clang-tidy/tool/run-clang-tidy.py. The script executes clang-tidy with the default set of checks on every translation unit in the compile com- mand database and displays the resulting warnings and errors. The script provides multiple configuration flags. • The default set of checks can be overridden using the -checks argu- ment, taking the identical format as clang-tidy does. For example -checks=-*,modernize-use-override will run the modernize-use-override check only. • To restrict the files examined you can provide one or more regex ar- guments that the file names are matched against. run-clang-tidy.py clang-tidy/.*Check\.cpp will only analyze clang-tidy checks. It may also be necessary to restrict the header files warnings are displayed from using the -header-filter flag. It has the same behavior as the corresponding clang-tidy flag. • To apply suggested fixes -fix can be passed as an argument. This gathers all changes in a temporary directory and applies them. Pass- ing -format will run clang-format over changed lines. On checks profiling clang-tidy can collect per-check profiling info, and output it for each processed source file (translation unit). To enable profiling info collection, use the -enable-check-profile ar- gument. The timings will be output to stderr as a table. Example out- put: $ clang-tidy -enable-check-profile -checks=-*,readability-function-size source.cpp ===-------------------------------------------------------------------------=== clang-tidy checks profiling ===-------------------------------------------------------------------------=== Total Execution Time: 1.0282 seconds (1.0258 wall clock) ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) readability-function-size 0.9136 (100.0%) 0.1146 (100.0%) 1.0282 (100.0%) 1.0258 (100.0%) Total It can also store that data as JSON files for further processing. Exam- ple output: $ clang-tidy -enable-check-profile -store-check-profile=. -checks=-*,readability-function-size source.cpp $ # Note that there won't be timings table printed to the console. $ ls /tmp/out/ 20180516161318717446360-source.cpp.json $ cat 20180516161318717446360-source.cpp.json { "file": "/path/to/source.cpp", "timestamp": "2018-05-16 16:13:18.717446360", "profile": { "time.clang-tidy.readability-function-size.wall": 1.0421266555786133e+00, "time.clang-tidy.readability-function-size.user": 9.2088400000005421e-01, "time.clang-tidy.readability-function-size.sys": 1.2418899999999974e-01 } } There is only one argument that controls profile storage: • -store-check-profile=<prefix> By default reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. If the prefix is not an absolute path, it is considered to be relative to the directory from where you have run clang-tidy. All . and .. patterns in the path are collapsed, and symlinks are re- solved. Example: Let's suppose you have a source file named example.cpp, lo- cated in the /source directory. Only the input filename is used, not the full path to the source file. Additionally, it is prefixed with the current timestamp. • If you specify -store-check-profile=/tmp, then the profile will be saved to /tmp/<ISO8601-like timestamp>-example.cpp.json • If you run clang-tidy from within /foo directory, and specify -store-check-profile=., then the profile will still be saved to /foo/<ISO8601-like timestamp>-example.cpp.json clang-tidy is a clang-based C++ "linter" tool. Its purpose is to pro- vide an extensible framework for diagnosing and fixing typical program- ming errors, like style violations, interface misuse, or bugs that can be deduced via static analysis. clang-tidy is modular and provides a convenient interface for writing new checks. Using clang-tidy clang-tidy is a LibTooling-based tool, and it's easier to work with if you set up a compile command database for your project (for an example of how to do this see How To Setup Tooling For LLVM). You can also specify compilation options on the command line after --: $ clang-tidy test.cpp -- -Imy_project/include -DMY_DEFINES ... clang-tidy has its own checks and can also run Clang static analyzer checks. Each check has a name and the checks to run can be chosen using the -checks= option, which specifies a comma-separated list of positive and negative (prefixed with -) globs. Positive globs add subsets of checks, negative globs remove them. For example, $ clang-tidy test.cpp -checks=-*,clang-analyzer-*,-clang-analyzer-cplusplus* will disable all default checks (-*) and enable all clang-analyzer-* checks except for clang-analyzer-cplusplus* ones. The -list-checks option lists all the enabled checks. When used without -checks=, it shows checks enabled by default. Use -checks=* to see all available checks or with any other value of -checks= to see which checks are enabled by this value. There are currently the following groups of checks: +--------------------+----------------------------+ | Name prefix | Description | +--------------------+----------------------------+ | abseil- | Checks related to Abseil | | | library. | +--------------------+----------------------------+ | android- | Checks related to Android. | +--------------------+----------------------------+ | boost- | Checks related to Boost | | | library. | +--------------------+----------------------------+ | bugprone- | Checks that target bug- | | | prone code constructs. | +--------------------+----------------------------+ | cert- | Checks related to CERT Se- | | | cure Coding Guidelines. | +--------------------+----------------------------+ | clang-analyzer- | Clang Static Analyzer | | | checks. | +--------------------+----------------------------+ | cppcoreguidelines- | Checks related to C++ Core | | | Guidelines. | +--------------------+----------------------------+ | darwin- | Checks related to Darwin | | | coding conventions. | +--------------------+----------------------------+ | fuchsia- | Checks related to Fuchsia | | | coding conventions. | +--------------------+----------------------------+ | google- | Checks related to Google | | | coding conventions. | +--------------------+----------------------------+ | hicpp- | Checks related to High In- | | | tegrity C++ Coding Stan- | | | dard. | +--------------------+----------------------------+ | linuxkernel- | Checks related to the | | | Linux Kernel coding con- | | | ventions. | +--------------------+----------------------------+ | llvm- | Checks related to the LLVM | | | coding conventions. | +--------------------+----------------------------+ | llvmlibc- | Checks related to the | | | LLVM-libc coding stan- | | | dards. | +--------------------+----------------------------+ | misc- | Checks that we didn't have | | | a better category for. | +--------------------+----------------------------+ | modernize- | Checks that advocate usage | | | of modern (currently "mod- | | | ern" means "C++11") lan- | | | guage constructs. | +--------------------+----------------------------+ | mpi- | Checks related to MPI | | | (Message Passing Inter- | | | face). | +--------------------+----------------------------+ | objc- | Checks related to Objec- | | | tive-C coding conventions. | +--------------------+----------------------------+ | openmp- | Checks related to OpenMP | | | API. | +--------------------+----------------------------+ | performance- | Checks that target perfor- | | | mance-related issues. | +--------------------+----------------------------+ | portability- | Checks that target porta- | | | bility-related issues that | | | don't relate to any par- | | | ticular coding style. | +--------------------+----------------------------+ | readability- | Checks that target read- | | | ability-related issues | | | that don't relate to any | | | particular coding style. | +--------------------+----------------------------+ | zircon- | Checks related to Zircon | | | kernel coding conventions. | +--------------------+----------------------------+ Clang diagnostics are treated in a similar way as check diagnostics. Clang diagnostics are displayed by clang-tidy and can be filtered out using -checks= option. However, the -checks= option does not affect compilation arguments, so it can not turn on Clang warnings which are not already turned on in build configuration. The -warnings-as-errors= option upgrades any warnings emitted under the -checks= flag to errors (but it does not enable any checks itself). Clang diagnostics have check names starting with clang-diagnostic-. Diagnostics which have a corresponding warning option, are named clang-diagnostic-<warning-option>, e.g. Clang warning controlled by -Wliteral-conversion will be reported with check name clang-diagnos- tic-literal-conversion. The -fix flag instructs clang-tidy to fix found errors if supported by corresponding checks. An overview of all the command-line options: $ clang-tidy --help USAGE: clang-tidy [options] <source0> [... <sourceN>] OPTIONS: Generic Options: --help - Display available options (--help-hidden for more) --help-list - Display list of available options (--help-list-hidden for more) --version - Display the version of this program clang-tidy options: --checks=<string> - Comma-separated list of globs with optional '-' prefix. Globs are processed in order of appearance in the list. Globs without '-' prefix add checks with matching names to the set, globs with the '-' prefix remove checks with matching names from the set of enabled checks. This option's value is appended to the value of the 'Checks' option in .clang-tidy file, if any. --config=<string> - Specifies a configuration in YAML/JSON format: -config="{Checks: '*', CheckOptions: [{key: x, value: y}]}" When the value is empty, clang-tidy will attempt to find a file named .clang-tidy for each source file in its parent directories. --dump-config - Dumps configuration in the YAML format to stdout. This option can be used along with a file name (and '--' if the file is outside of a project with configured compilation database). The configuration used for this file will be printed. Use along with -checks=* to include configuration of all checks. --enable-check-profile - Enable per-check timing profiles, and print a report to stderr. --explain-config - For each enabled check explains, where it is enabled, i.e. in clang-tidy binary, command line or a specific configuration file. --export-fixes=<filename> - YAML file to store suggested fixes in. The stored fixes can be applied to the input source code with clang-apply-replacements. --extra-arg=<string> - Additional argument to append to the compiler command line Can be used several times. --extra-arg-before=<string> - Additional argument to prepend to the compiler command line Can be used several times. --fix - Apply suggested fixes. Without -fix-errors clang-tidy will bail out if any compilation errors were found. --fix-errors - Apply suggested fixes even if compilation errors were found. If compiler errors have attached fix-its, clang-tidy will apply them as well. --format-style=<string> - Style for formatting code around applied fixes: - 'none' (default) turns off formatting - 'file' (literally 'file', not a placeholder) uses .clang-format file in the closest parent directory - '{ <json> }' specifies options inline, e.g. -format-style='{BasedOnStyle: llvm, IndentWidth: 8}' - 'llvm', 'google', 'webkit', 'mozilla' See clang-format documentation for the up-to-date information about formatting styles and options. This option overrides the 'FormatStyle` option in .clang-tidy file, if any. --header-filter=<string> - Regular expression matching the names of the headers to output diagnostics from. Diagnostics from the main file of each translation unit are always displayed. Can be used together with -line-filter. This option overrides the 'HeaderFilterRegex' option in .clang-tidy file, if any. --line-filter=<string> - List of files with line ranges to filter the warnings. Can be used together with -header-filter. The format of the list is a JSON array of objects: [ {"name":"file1.cpp","lines":[[1,3],[5,7]]}, {"name":"file2.h"} ] --list-checks - List all enabled checks and exit. Use with -checks=* to list all available checks. -p=<string> - Build path --quiet - Run clang-tidy in quiet mode. This suppresses printing statistics about ignored warnings and warnings treated as errors if the respective options are specified. --store-check-profile=<prefix> - By default reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. --system-headers - Display the errors from system headers. --vfsoverlay=<filename> - Overlay the virtual filesystem described by file over the real file system. --warnings-as-errors=<string> - Upgrades warnings to errors. Same format as '-checks'. This option's value is appended to the value of the 'WarningsAsErrors' option in .clang-tidy file, if any. -p <build-path> is used to read a compile command database. For example, it can be a CMake build directory in which a file named compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON CMake option to get this output). When no build path is specified, a search for compile_commands.json will be attempted through all parent paths of the first input file . See: https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an example of setting up Clang Tooling on a source tree. <source0> ... specify the paths of source files. These paths are looked up in the compile command database. If the path of a file is absolute, it needs to point into CMake's source tree. If the path is relative, the current working directory needs to be in the CMake source tree and the file must be in a subdirectory of the current working directory. "./" prefixes in the relative files will be automatically removed, but the rest of a relative path must be a suffix of a path in the compile command database. Configuration files: clang-tidy attempts to read configuration for each source file from a .clang-tidy file located in the closest parent directory of the source file. If InheritParentConfig is true in a config file, the configuration file in the parent directory (if any exists) will be taken and current config file will be applied on top of the parent one. If any configuration options have a corresponding command-line option, command-line option takes precedence. The effective configuration can be inspected using -dump-config: $ clang-tidy -dump-config --- Checks: '-*,some-check' WarningsAsErrors: '' HeaderFilterRegex: '' FormatStyle: none InheritParentConfig: true User: user CheckOptions: - key: some-check.SomeOption value: 'some value' ... Suppressing Undesired Diagnostics clang-tidy diagnostics are intended to call out code that does not ad- here to a coding standard, or is otherwise problematic in some way. However, if the code is known to be correct, it may be useful to si- lence the warning. Some clang-tidy checks provide a check-specific way to silence the diagnostics, e.g. bugprone-use-after-move can be si- lenced by re-initializing the variable after it has been moved out, bugprone-string-integer-assignment can be suppressed by explicitly casting the integer to char, readability-implicit-bool-conversion can also be suppressed by using explicit casts, etc. If a specific suppression mechanism is not available for a certain warning, or its use is not desired for some reason, clang-tidy has a generic mechanism to suppress diagnostics using NOLINT or NOLINT- NEXTLINE comments. The NOLINT comment instructs clang-tidy to ignore warnings on the same line (it doesn't apply to a function, a block of code or any other lan- guage construct, it applies to the line of code it is on). If introduc- ing the comment in the same line would change the formatting in unde- sired way, the NOLINTNEXTLINE comment allows to suppress clang-tidy warnings on the next line. Both comments can be followed by an optional list of check names in parentheses (see below for the formal syntax). For example: class Foo { // Suppress all the diagnostics for the line Foo(int param); // NOLINT // Consider explaining the motivation to suppress the warning. Foo(char param); // NOLINT: Allow implicit conversion from `char`, because <some valid reason>. // Silence only the specified checks for the line Foo(double param); // NOLINT(google-explicit-constructor, google-runtime-int) // Silence only the specified diagnostics for the next line // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int) Foo(bool param); }; The formal syntax of NOLINT/NOLINTNEXTLINE is the following: lint-comment: lint-command lint-command lint-args lint-args: ( check-name-list ) check-name-list: check-name check-name-list , check-name lint-command: NOLINT NOLINTNEXTLINE Note that whitespaces between NOLINT/NOLINTNEXTLINE and the opening parenthesis are not allowed (in this case the comment will be treated just as NOLINT/NOLINTNEXTLINE), whereas in check names list (inside the parenthesis) whitespaces can be used and will be ignored. CLANG-INCLUDE-FIXER Contents • Clang-Include-Fixer • Setup • Creating a Symbol Index From a Compilation Database • Integrate with Vim • Integrate with Emacs • How it Works One of the major nuisances of C++ compared to other languages is the manual management of #include directives in any file. clang-in- clude-fixer addresses one aspect of this problem by providing an auto- mated way of adding #include directives for missing symbols in one translation unit. While inserting missing #include, clang-include-fixer adds missing namespace qualifiers to all instances of an unidentified symbol if the symbol is missing some prefix namespace qualifiers. Setup To use clang-include-fixer two databases are required. Both can be gen- erated with existing tools. • Compilation database. Contains the compiler commands for any given file in a project and can be generated by CMake, see How To Setup Tooling For LLVM. • Symbol index. Contains all symbol information in a project to match a given identifier to a header file. Ideally both databases (compile_commands.json and find_all_sym- bols_db.yaml) are linked into the root of the source tree they corre- spond to. Then the clang-include-fixer can automatically pick them up if called with a source file from that tree. Note that by default com- pile_commands.json as generated by CMake does not include header files, so only implementation files can be handled by tools. Creating a Symbol Index From a Compilation Database The include fixer contains find-all-symbols, a tool to create a symbol database in YAML format from a compilation database by parsing all source files listed in it. The following list of commands shows how to set up a database for LLVM, any project built by CMake should follow similar steps. $ cd path/to/llvm-build $ ninja find-all-symbols // build find-all-symbols tool. $ ninja clang-include-fixer // build clang-include-fixer tool. $ ls compile_commands.json # Make sure compile_commands.json exists. compile_commands.json $ path/to/llvm/source/clang-tools-extra/clang-include-fixer/find-all-symbols/tool/run-find-all-symbols.py ... wait as clang indexes the code base ... $ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree. $ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already. $ cd path/to/llvm/source $ /path/to/clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp Added #include "foo.h" Integrate with Vim To run clang-include-fixer on a potentially unsaved buffer in Vim. Add the following key binding to your .vimrc: noremap <leader>cf :pyf path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/clang-include-fixer.py<cr> This enables clang-include-fixer for NORMAL and VISUAL mode. Change <leader>cf to another binding if you need clang-include-fixer on a dif- ferent key. The <leader> key is a reference to a specific key defined by the mapleader variable and is bound to backslash by default. Make sure vim can find clang-include-fixer: • Add the path to clang-include-fixer to the PATH environment variable. • Or set g:clang_include_fixer_path in vimrc: let g:clang_in- clude_fixer_path=path/to/clang-include-fixer You can customize the number of headers being shown by setting let g:clang_include_fixer_maximum_suggested_headers=5 Customized settings in .vimrc: • let g:clang_include_fixer_path = "clang-include-fixer" Set clang-include-fixer binary file path. • let g:clang_include_fixer_maximum_suggested_headers = 3 Set the maximum number of #includes to show. Default is 3. • let g:clang_include_fixer_increment_num = 5 Set the increment number of #includes to show every time when press- ing m. Default is 5. • let g:clang_include_fixer_jump_to_include = 0 Set to 1 if you want to jump to the new inserted #include line. De- fault is 0. • let g:clang_include_fixer_query_mode = 0 Set to 1 if you want to insert #include for the symbol under the cur- sor. Default is 0. Compared to normal mode, this mode won't parse the source file and only search the symbol from database, which is faster than normal mode. See clang-include-fixer.py for more details. Integrate with Emacs To run clang-include-fixer on a potentially unsaved buffer in Emacs. Ensure that Emacs finds clang-include-fixer.el by adding the directory containing the file to the load-path and requiring the clang-in- clude-fixer in your .emacs: (add-to-list 'load-path "path/to/llvm/source/clang-tools-extra/clang-include-fixer/tool/" (require 'clang-include-fixer) Within Emacs the tool can be invoked with the command M-x clang-in- clude-fixer. This will insert the header that defines the first unde- fined symbol; if there is more than one header that would define the symbol, the user is prompted to select one. To include the header that defines the symbol at point, run M-x clang-include-fixer-at-point. Make sure Emacs can find clang-include-fixer: • Either add the parent directory of clang-include-fixer to the PATH environment variable, or customize the Emacs user option clang-in- clude-fixer-executable to point to the file name of the program. How it Works To get the most information out of Clang at parse time, clang-in- clude-fixer runs in tandem with the parse and receives callbacks from Clang's semantic analysis. In particular it reuses the existing support for typo corrections. Whenever Clang tries to correct a potential typo it emits a callback to the include fixer which then looks for a corre- sponding file. At this point rich lookup information is still avail- able, which is not available in the AST at a later stage. The identifier that should be typo corrected is then sent to the data- base, if a header file is returned it is added as an include directive at the top of the file. Currently clang-include-fixer only inserts a single include at a time to avoid getting caught in follow-up errors. If multiple #include addi- tions are desired the program can be rerun until a fix-point is reached. MODULARIZE USER'S MANUAL Modularize Usage modularize [<modularize-options>] [<module-map>|<include-files-list>]* [<front-end-options>...] <modularize-options> is a place-holder for options specific to modular- ize, which are described below in Modularize Command Line Options. <module-map> specifies the path of a file name for an existing module map. The module map must be well-formed in terms of syntax. Modularize will extract the header file names from the map. Only normal headers are checked, assuming headers marked "private", "textual", or "exclude" are not to be checked as a top-level include, assuming they either are included by other headers which are checked, or they are not suitable for modules. <include-files-list> specifies the path of a file name for a file con- taining the newline-separated list of headers to check with respect to each other. Lines beginning with '#' and empty lines are ignored. Header file names followed by a colon and other space-separated file names will include those extra files as dependencies. The file names can be relative or full paths, but must be on the same line. For exam- ple: header1.h header2.h header3.h: header1.h header2.h Note that unless a -prefix (header path) option is specified, non-ab- solute file paths in the header list file will be relative to the header list file directory. Use -prefix to specify a different direc- tory. <front-end-options> is a place-holder for regular Clang front-end argu- ments, which must follow the <include-files-list>. Note that by de- fault, modularize assumes .h files contain C++ source, so if you are using a different language, you might need to use a -x option to tell Clang that the header contains another language, i.e.: -x c Note also that because modularize does not use the clang driver, you will likely need to pass in additional compiler front-end arguments to match those passed in by default by the driver. Modularize Command Line Options -prefix=<header-path> Prepend the given path to non-absolute file paths in the header list file. By default, headers are assumed to be relative to the header list file directory. Use -prefix to specify a differ- ent directory. -module-map-path=<module-map-path> Generate a module map and output it to the given file. See the description in Module Map Generation. -problem-files-list=<problem-files-list-file-name> For use only with module map assistant. Input list of files that have problems with respect to modules. These will still be in- cluded in the generated module map, but will be marked as "ex- cluded" headers. -root-module=<root-name> Put modules generated by the -module-map-path option in an en- closing module with the given name. See the description in Module Map Generation. -block-check-header-list-only Limit the #include-inside-extern-or-namespace-block check to only those headers explicitly listed in the header list. This is a work-around for avoiding error messages for private in- cludes that purposefully get included inside blocks. -no-coverage-check Don't do the coverage check for a module map. -coverage-check-only Only do the coverage check for a module map. -display-file-lists Display lists of good files (no compile errors), problem files, and a combined list with problem files preceded by a '#'. This can be used to quickly determine which files have problems. The latter combined list might be useful in starting to modularize a set of headers. You can start with a full list of headers, use -display-file-lists option, and then use the combined list as your intermediate list, uncommenting-out headers as you fix them. modularize is a standalone tool that checks whether a set of headers provides the consistent definitions required to use modules. For exam- ple, it detects whether the same entity (say, a NULL macro or size_t typedef) is defined in multiple headers or whether a header produces different definitions under different circumstances. These conditions cause modules built from the headers to behave poorly, and should be fixed before introducing a module map. modularize also has an assistant mode option for generating a module map file based on the provided header list. The generated file is a functional module map that can be used as a starting point for a mod- ule.map file. Getting Started To build from source: 1. Read Getting Started with the LLVM System and Clang Tools Documenta- tion for information on getting sources for LLVM, Clang, and Clang Extra Tools. 2. Getting Started with the LLVM System and Building LLVM with CMake give directions for how to build. With sources all checked out into the right place the LLVM build will build Clang Extra Tools and their dependencies automatically. • If using CMake, you can also use the modularize target to build just the modularize tool and its dependencies. Before continuing, take a look at Modularize Usage to see how to invoke modularize. What Modularize Checks Modularize will check for the following: • Duplicate global type and variable definitions • Duplicate macro definitions • Macro instances, 'defined(macro)', or #if, #elif, #ifdef, #ifndef conditions that evaluate differently in a header • #include directives inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks • Module map header coverage completeness (in the case of a module map input only) Modularize will do normal C/C++ parsing, reporting normal errors and warnings, but will also report special error messages like the follow- ing: error: '(symbol)' defined at multiple locations: (file):(row):(column) (file):(row):(column) error: header '(file)' has different contents depending on how it was included The latter might be followed by messages like the following: note: '(symbol)' in (file) at (row):(column) not always provided Checks will also be performed for macro expansions, defined(macro) ex- pressions, and preprocessor conditional directives that evaluate incon- sistently, and can produce error messages like the following: (...)/SubHeader.h:11:5: #if SYMBOL == 1 ^ error: Macro instance 'SYMBOL' has different values in this header, depending on how it was included. 'SYMBOL' expanded to: '1' with respect to these inclusion paths: (...)/Header1.h (...)/SubHeader.h (...)/SubHeader.h:3:9: #define SYMBOL 1 ^ Macro defined here. 'SYMBOL' expanded to: '2' with respect to these inclusion paths: (...)/Header2.h (...)/SubHeader.h (...)/SubHeader.h:7:9: #define SYMBOL 2 ^ Macro defined here. Checks will also be performed for '#include' directives that are nested inside 'extern "C/C++" {}' or 'namespace (name) {}' blocks, and can produce error message like the following: IncludeInExtern.h:2:3: #include "Empty.h" ^ error: Include directive within extern "C" {}. IncludeInExtern.h:1:1: extern "C" { ^ The "extern "C" {}" block is here. Module Map Coverage Check The coverage check uses the Clang library to read and parse the module map file. Starting at the module map file directory, or just the in- clude paths, if specified, it will collect the names of all the files it considers headers (no extension, .h, or .inc--if you need more, mod- ify the isHeader function). It then compares the headers against those referenced in the module map, either explicitly named, or implicitly named via an umbrella directory or umbrella file, as parsed by the Mod- uleMap object. If headers are found which are not referenced or cov- ered by an umbrella directory or file, warning messages will be pro- duced, and this program will return an error code of 1. If no problems are found, an error code of 0 is returned. Note that in the case of umbrella headers, this tool invokes the com- piler to preprocess the file, and uses a callback to collect the header files included by the umbrella header or any of its nested includes. If any front end options are needed for these compiler invocations, these can be included on the command line after the module map file argument. Warning message have the form: warning: module.modulemap does not account for file: Level3A.h Note that for the case of the module map referencing a file that does not exist, the module map parser in Clang will (at the time of this writing) display an error message. To limit the checks modularize does to just the module map coverage check, use the -coverage-check-only option. For example: modularize -coverage-check-only module.modulemap Module Map Generation If you specify the -module-map-path=<module map file>, modularize will output a module map based on the input header list. A module will be created for each header. Also, if the header in the header list is a partial path, a nested module hierarchy will be created in which a mod- ule will be created for each subdirectory component in the header path, with the header itself represented by the innermost module. If other headers use the same subdirectories, they will be enclosed in these same modules also. For example, for the header list: SomeTypes.h SomeDecls.h SubModule1/Header1.h SubModule1/Header2.h SubModule2/Header3.h SubModule2/Header4.h SubModule2.h The following module map will be generated: // Output/NoProblemsAssistant.txt // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \ -root-module=Root NoProblemsAssistant.modularize module SomeTypes { header "SomeTypes.h" export * } module SomeDecls { header "SomeDecls.h" export * } module SubModule1 { module Header1 { header "SubModule1/Header1.h" export * } module Header2 { header "SubModule1/Header2.h" export * } } module SubModule2 { module Header3 { header "SubModule2/Header3.h" export * } module Header4 { header "SubModule2/Header4.h" export * } header "SubModule2.h" export * } An optional -root-module=<root-name> option can be used to cause a root module to be created which encloses all the modules. An optional -problem-files-list=<problem-file-name> can be used to in- put a list of files to be excluded, perhaps as a temporary stop-gap measure until problem headers can be fixed. For example, with the same header list from above: // Output/NoProblemsAssistant.txt // Generated by: modularize -module-map-path=Output/NoProblemsAssistant.txt \ -root-module=Root NoProblemsAssistant.modularize module Root { module SomeTypes { header "SomeTypes.h" export * } module SomeDecls { header "SomeDecls.h" export * } module SubModule1 { module Header1 { header "SubModule1/Header1.h" export * } module Header2 { header "SubModule1/Header2.h" export * } } module SubModule2 { module Header3 { header "SubModule2/Header3.h" export * } module Header4 { header "SubModule2/Header4.h" export * } header "SubModule2.h" export * } } Note that headers with dependents will be ignored with a warning, as the Clang module mechanism doesn't support headers the rely on other headers to be included first. The module map format defines some keywords which can't be used in mod- ule names. If a header has one of these names, an underscore ('_') will be prepended to the name. For example, if the header name is header.h, because header is a keyword, the module name will be _header. For a list of the module map keywords, please see: Lexical structure PP-TRACE USER'S MANUAL pp-trace is a standalone tool that traces preprocessor activity. It's also used as a test of Clang's PPCallbacks interface. It runs a given source file through the Clang preprocessor, displaying selected infor- mation from callback functions overridden in a PPCallbacks derivation. The output is in a high-level YAML format, described in pp-trace Output Format. pp-trace Usage Command Line Format pp-trace [<pp-trace-options>] <source-file> [-- <front-end-options>] <pp-trace-options> is a place-holder for options specific to pp-trace, which are described below in Command Line Options. <source-file> specifies the source file to run through the preproces- sor. <front-end-options> is a place-holder for regular Clang Compiler Op- tions, which must follow the <source-file>. Command Line Options -callbacks <comma-separated-globs> This option specifies a comma-separated list of globs describing the list of callbacks that should be traced. Globs are processed in order of appearance. Positive globs add matched callbacks to the set, netative globs (those with the '-' prefix) remove callacks from the set. • FileChanged • FileSkipped • FileNotFound • InclusionDirective • moduleImport • EndOfMainFile • Ident • PragmaDirective • PragmaComment • PragmaDetectMismatch • PragmaDebug • PragmaMessage • PragmaDiagnosticPush • PragmaDiagnosticPop • PragmaDiagnostic • PragmaOpenCLExtension • PragmaWarning • PragmaWarningPush • PragmaWarningPop • MacroExpands • MacroDefined • MacroUndefined • Defined • SourceRangeSkipped • If • Elif • Ifdef • Ifndef • Else • Endif -output <output-file> By default, pp-trace outputs the trace information to stdout. Use this option to output the trace information to a file. pp-trace Output Format The pp-trace output is formatted as YAML. See https://yaml.org/ for general YAML information. It's arranged as a sequence of information about the callback call, including the callback name and argument in- formation, for example:: --- - Callback: Name Argument1: Value1 Argument2: Value2 (etc.) ... With real data:: --- - Callback: FileChanged Loc: "c:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1" Reason: EnterFile FileType: C_User PrevFID: (invalid) (etc.) - Callback: FileChanged Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:5:1" Reason: ExitFile FileType: C_User PrevFID: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/Input/Level1B.h" - Callback: EndOfMainFile ... In all but one case (MacroDirective) the "Argument" scalars have the same name as the argument in the corresponding PPCallbacks callback function. Callback Details The following sections describe the purpose and output format for each callback. Click on the callback name in the section heading to see the Doxygen documentation for the callback. The argument descriptions table describes the callback argument infor- mation displayed. The Argument Name field in most (but not all) cases is the same name as the callback function parameter. The Argument Value Syntax field describes the values that will be dis- played for the argument value. It uses an ad hoc representation that mixes literal and symbolic representations. Enumeration member symbols are shown as the actual enum member in a (member1|member2|...) form. A name in parentheses can either represent a place holder for the de- scribed value, or confusingly, it might be a literal, such as (null), for a null pointer. Locations are shown as quoted only to avoid con- fusing the documentation generator. The Clang C++ Type field is the type from the callback function decla- ration. The description describes the argument or what is displayed for it. Note that in some cases, such as when a structure pointer is an argu- ment value, only some key member or members are shown to represent the value, instead of trying to display all members of the structure. FileChanged Callback FileChanged is called when the preprocessor enters or exits a file, both the top level file being compiled, as well as any #include direc- tives. It will also be called as a result of a system header pragma or in internal renaming of a file. Argument descriptions: +---------------+-----------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+------------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+------------------+------------------+ | Reason | (EnterFile|Exit- | PPCall- | Reason for | | | File|SystemHeader- | backs::FileChan- | change. | | | Pragma|RenameFile) | geReason | | +---------------+-----------------------+------------------+------------------+ | FileType | (C_User|C_Sys- | SrcMgr::Charac- | Include type. | | | tem|C_ExternCSystem) | teristicKind | | +---------------+-----------------------+------------------+------------------+ | PrevFID | ((file)|(invalid)) | FileID | Previous file, | | | | | if any. | +---------------+-----------------------+------------------+------------------+ Example:: - Callback: FileChanged Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-include.cpp:1:1" Reason: EnterFile FileType: C_User PrevFID: (invalid) FileSkipped Callback FileSkipped is called when a source file is skipped as the result of header guard optimization. Argument descriptions: +---------------+------------------+-----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+------------------+-----------------+------------------+ | ParentFile | ("(file)" or | const FileEntry | The file that | | | (null)) | | #included the | | | | | skipped file. | +---------------+------------------+-----------------+------------------+ | FilenameTok | (token) | const Token | The token in | | | | | ParentFile that | | | | | indicates the | | | | | skipped file. | +---------------+------------------+-----------------+------------------+ | FileType | (C_User|C_Sys- | SrcMgr::Charac- | The file type. | | | tem|C_ExternC- | teristicKind | | | | System) | | | +---------------+------------------+-----------------+------------------+ Example:: - Callback: FileSkipped ParentFile: "/path/filename.h" FilenameTok: "filename.h" FileType: C_User FileNotFound Callback FileNotFound is called when an inclusion directive results in a file-not-found error. Argument descriptions: +---------------+------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+------------------+----------------+------------------+ | FileName | "(file)" | StringRef | The name of the | | | | | file being in- | | | | | cluded, as writ- | | | | | ten in the | | | | | source code. | +---------------+------------------+----------------+------------------+ | RecoveryPath | (path) | SmallVec- | If this client | | | | torImpl<char> | indicates that | | | | | it can recover | | | | | from this miss- | | | | | ing file, the | | | | | client should | | | | | set this as an | | | | | additional | | | | | header search | | | | | patch. | +---------------+------------------+----------------+------------------+ Example:: - Callback: FileNotFound FileName: "/path/filename.h" RecoveryPath: InclusionDirective Callback InclusionDirective is called when an inclusion directive of any kind (#include</code>, #import</code>, etc.) has been processed, regardless of whether the inclusion will actually result in an inclusion. Argument descriptions: +---------------+-----------------------+-----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+-----------------+------------------+ | HashLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the '#' that | | | | | starts the in- | | | | | clusion direc- | | | | | tive. | +---------------+-----------------------+-----------------+------------------+ | IncludeTok | (token) | const Token | The token that | | | | | indicates the | | | | | kind of inclu- | | | | | sion directive, | | | | | e.g., 'include' | | | | | or 'import'. | +---------------+-----------------------+-----------------+------------------+ | FileName | "(file)" | StringRef | The name of the | | | | | file being in- | | | | | cluded, as writ- | | | | | ten in the | | | | | source code. | +---------------+-----------------------+-----------------+------------------+ | IsAngled | (true|false) | bool | Whether the file | | | | | name was en- | | | | | closed in angle | | | | | brackets; other- | | | | | wise, it was en- | | | | | closed in | | | | | quotes. | +---------------+-----------------------+-----------------+------------------+ | FilenameRange | "(file)" | CharSourceRange | The character | | | | | range of the | | | | | quotes or angle | | | | | brackets for the | | | | | written file | | | | | name. | +---------------+-----------------------+-----------------+------------------+ | File | "(file)" | const FileEntry | The actual file | | | | | that may be in- | | | | | cluded by this | | | | | inclusion direc- | | | | | tive. | +---------------+-----------------------+-----------------+------------------+ | SearchPath | "(path)" | StringRef | Contains the | | | | | search path | | | | | which was used | | | | | to find the file | | | | | in the file sys- | | | | | tem. | +---------------+-----------------------+-----------------+------------------+ | RelativePath | "(path)" | StringRef | The path rela- | | | | | tive to Search- | | | | | Path, at which | | | | | the include file | | | | | was found. | +---------------+-----------------------+-----------------+------------------+ | Imported | ((module | const Module | The module, | | | name)|(null)) | | whenever an in- | | | | | clusion direc- | | | | | tive was auto- | | | | | matically turned | | | | | into a module | | | | | import or null | | | | | otherwise. | +---------------+-----------------------+-----------------+------------------+ Example:: - Callback: InclusionDirective IncludeTok: include FileName: "Input/Level1B.h" IsAngled: false FilenameRange: "Input/Level1B.h" File: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/Input/Level1B.h" SearchPath: "D:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace" RelativePath: "Input/Level1B.h" Imported: (null) moduleImport Callback moduleImport is called when there was an explicit module-import syntax. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | ImportLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | import directive | | | | | token. | +---------------+-----------------------+----------------+------------------+ | Path | "(path)" | ModuleIdPath | The identifiers | | | | | (and their loca- | | | | | tions) of the | | | | | module "path". | +---------------+-----------------------+----------------+------------------+ | Imported | ((module | const Module | The imported | | | name)|(null)) | | module; can be | | | | | null if import- | | | | | ing failed. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: moduleImport ImportLoc: "d:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:2" Path: [{Name: Level1B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:9"}, {Name: Level2B, Loc: "d:/Clang/llvmnewmod/clang-tools-extra/test/pp-trace/pp-trace-modules.cpp:4:17"}] Imported: Level2B EndOfMainFile Callback EndOfMainFile is called when the end of the main file is reached. Argument descriptions: +----------------+------------------+----------------+-------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+------------------+----------------+-------------+ | (no arguments) | | | | +----------------+------------------+----------------+-------------+ Example:: - Callback: EndOfMainFile Ident Callback Ident is called when a #ident or #sccs directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | str | (name) | const | The text of the | | | | std::string | directive. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: Ident Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-ident.cpp:3:1" str: "$Id$" PragmaDirective Callback PragmaDirective is called when start reading any pragma directive. Argument descriptions: +---------------+----------------------------------+-----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+----------------------------------+-----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+----------------------------------+-----------------+------------------+ | Introducer | (PIK_Hash- | PragmaIntroduc- | The type of the | | | Pragma|PIK__Pragma|PIK___pragma) | erKind | pragma direc- | | | | | tive. | +---------------+----------------------------------+-----------------+------------------+ Example:: - Callback: PragmaDirective Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Introducer: PIK_HashPragma PragmaComment Callback PragmaComment is called when a #pragma comment directive is read. Argument descriptions: +---------------+-----------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+------------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+------------------+------------------+ | Kind | ((name)|(null)) | const Identi- | The comment kind | | | | fierInfo | symbol. | +---------------+-----------------------+------------------+------------------+ | Str | (message directive) | const | The comment mes- | | | | std::string | sage directive. | +---------------+-----------------------+------------------+------------------+ Example:: - Callback: PragmaComment Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Kind: library Str: kernel32.lib PragmaDetectMismatch Callback PragmaDetectMismatch is called when a #pragma detect_mismatch directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Name | "(name)" | const | The name. | | | | std::string | | +---------------+-----------------------+----------------+------------------+ | Value | (string) | const | The value. | | | | std::string | | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaDetectMismatch Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Name: name Value: value PragmaDebug Callback PragmaDebug is called when a #pragma clang __debug directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | DebugType | (string) | StringRef | Indicates type | | | | | of debug mes- | | | | | sage. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaDebug Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" DebugType: warning PragmaMessage Callback PragmaMessage is called when a #pragma message directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Namespace | (name) | StringRef | The namespace of | | | | | the message di- | | | | | rective. | +---------------+-----------------------+----------------+------------------+ | Kind | (PMK_Mes- | PPCall- | The type of the | | | sage|PMK_Warn- | backs::Prag- | message direc- | | | ing|PMK_Error) | maMessageKind | tive. | +---------------+-----------------------+----------------+------------------+ | Str | (string) | StringRef | The text of the | | | | | message direc- | | | | | tive. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaMessage Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" Kind: PMK_Message Str: The message text. PragmaDiagnosticPush Callback PragmaDiagnosticPush is called when a #pragma gcc diagnostic push di- rective is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Namespace | (name) | StringRef | Namespace name. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaDiagnosticPush Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" PragmaDiagnosticPop Callback PragmaDiagnosticPop is called when a #pragma gcc diagnostic pop direc- tive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Namespace | (name) | StringRef | Namespace name. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaDiagnosticPop Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" PragmaDiagnostic Callback PragmaDiagnostic is called when a #pragma gcc diagnostic directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Namespace | (name) | StringRef | Namespace name. | +---------------+-----------------------+----------------+------------------+ | mapping | (0|MAP_IG- | diag::Severity | Mapping type. | | | NORE|MAP_WARN- | | | | | ING|MAP_ERROR|MAP_FA- | | | | | TAL) | | | +---------------+-----------------------+----------------+------------------+ | Str | (string) | StringRef | Warning/error | | | | | name. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaDiagnostic Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Namespace: "GCC" mapping: MAP_WARNING Str: WarningName PragmaOpenCLExtension Callback PragmaOpenCLExtension is called when OpenCL extension is either dis- abled or enabled with a pragma. Argument descriptions: +---------------+-----------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+------------------+------------------+ | NameLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the name. | +---------------+-----------------------+------------------+------------------+ | Name | (name) | const Identi- | Name symbol. | | | | fierInfo | | +---------------+-----------------------+------------------+------------------+ | StateLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the state. | +---------------+-----------------------+------------------+------------------+ | State | (1|0) | unsigned | Enabled/disabled | | | | | state. | +---------------+-----------------------+------------------+------------------+ Example:: - Callback: PragmaOpenCLExtension NameLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:10" Name: Name StateLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:18" State: 1 PragmaWarning Callback PragmaWarning is called when a #pragma warning directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | WarningSpec | (string) | StringRef | The warning | | | | | specifier. | +---------------+-----------------------+----------------+------------------+ | Ids | [(number)[, ...]] | ArrayRef<int> | The warning num- | | | | | bers. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaWarning Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" WarningSpec: disable Ids: 1,2,3 PragmaWarningPush Callback PragmaWarningPush is called when a #pragma warning(push) directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ | Level | (number) | int | Warning level. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaWarningPush Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" Level: 1 PragmaWarningPop Callback PragmaWarningPop is called when a #pragma warning(pop) directive is read. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: PragmaWarningPop Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-pragma.cpp:3:1" MacroExpands Callback MacroExpands is called when ::HandleMacroExpandedIdentifier when a macro invocation is found. Argument descriptions: +----------------+-------------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-------------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+-------------------------+------------------+------------------+ | MacroDirective | (MD_De- | const MacroDi- | The kind of | | | fine|MD_Unde- | rective | macro directive | | | fine|MD_Visibil- | | from the | | | ity) | | MacroDirective | | | | | structure. | +----------------+-------------------------+------------------+------------------+ | Range | ["(file):(line):(col)", | SourceRange | The source range | | | "(file):(line):(col)"] | | for the expan- | | | | | sion. | +----------------+-------------------------+------------------+------------------+ | Args | [(name)|(number)|<(to- | const MacroArgs | The argument to- | | | ken name)>[, ...]] | | kens. Names and | | | | | numbers are lit- | | | | | eral, everything | | | | | else is of the | | | | | form '<' token- | | | | | Name '>'. | +----------------+-------------------------+------------------+------------------+ Example:: - Callback: MacroExpands MacroNameTok: X_IMPL MacroDirective: MD_Define Range: [(nonfile), (nonfile)] Args: [a <plus> y, b] MacroDefined Callback MacroDefined is called when a macro definition is seen. Argument descriptions: +----------------+------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+------------------+------------------+------------------+ | MacroDirective | (MD_De- | const MacroDi- | The kind of | | | fine|MD_Unde- | rective | macro directive | | | fine|MD_Visibil- | | from the | | | ity) | | MacroDirective | | | | | structure. | +----------------+------------------+------------------+------------------+ Example:: - Callback: MacroDefined MacroNameTok: X_IMPL MacroDirective: MD_Define MacroUndefined Callback MacroUndefined is called when a macro #undef is seen. Argument descriptions: +----------------+------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+------------------+------------------+------------------+ | MacroDirective | (MD_De- | const MacroDi- | The kind of | | | fine|MD_Unde- | rective | macro directive | | | fine|MD_Visibil- | | from the | | | ity) | | MacroDirective | | | | | structure. | +----------------+------------------+------------------+------------------+ Example:: - Callback: MacroUndefined MacroNameTok: X_IMPL MacroDirective: MD_Define Defined Callback Defined is called when the 'defined' operator is seen. Argument descriptions: +----------------+-------------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-------------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+-------------------------+------------------+------------------+ | MacroDirective | (MD_De- | const MacroDi- | The kind of | | | fine|MD_Unde- | rective | macro directive | | | fine|MD_Visibil- | | from the | | | ity) | | MacroDirective | | | | | structure. | +----------------+-------------------------+------------------+------------------+ | Range | ["(file):(line):(col)", | SourceRange | The source range | | | "(file):(line):(col)"] | | for the direc- | | | | | tive. | +----------------+-------------------------+------------------+------------------+ Example:: - Callback: Defined MacroNameTok: MACRO MacroDirective: (null) Range: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:5", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:19"] SourceRangeSkipped Callback SourceRangeSkipped is called when a source range is skipped. Argument descriptions: +---------------+-------------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-------------------------+----------------+------------------+ | Range | ["(file):(line):(col)", | SourceRange | The source range | | | "(file):(line):(col)"] | | skipped. | +---------------+-------------------------+----------------+------------------+ Example:: - Callback: SourceRangeSkipped Range: [":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2", ":/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:2"] If Callback If is called when an #if is seen. Argument descriptions: +----------------+-------------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-------------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +----------------+-------------------------+----------------+------------------+ | ConditionRange | ["(file):(line):(col)", | SourceRange | The source range | | | "(file):(line):(col)"] | | for the condi- | | | | | tion. | +----------------+-------------------------+----------------+------------------+ | ConditionValue | (true|false) | bool | The condition | | | | | value. | +----------------+-------------------------+----------------+------------------+ Example:: - Callback: If Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:9:1"] ConditionValue: false Elif Callback Elif is called when an #elif is seen. Argument descriptions: +----------------+-------------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-------------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +----------------+-------------------------+----------------+------------------+ | ConditionRange | ["(file):(line):(col)", | SourceRange | The source range | | | "(file):(line):(col)"] | | for the condi- | | | | | tion. | +----------------+-------------------------+----------------+------------------+ | ConditionValue | (true|false) | bool | The condition | | | | | value. | +----------------+-------------------------+----------------+------------------+ | IfLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +----------------+-------------------------+----------------+------------------+ Example:: - Callback: Elif Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" ConditionRange: ["D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:4", "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:11:1"] ConditionValue: false IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" Ifdef Callback Ifdef is called when an #ifdef is seen. Argument descriptions: +----------------+-----------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-----------------------+------------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +----------------+-----------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+-----------------------+------------------+------------------+ | MacroDirective | (MD_Define|MD_Unde- | const MacroDi- | The kind of | | | fine|MD_Visibility) | rective | macro directive | | | | | from the | | | | | MacroDirective | | | | | structure. | +----------------+-----------------------+------------------+------------------+ Example:: - Callback: Ifdef Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1" MacroNameTok: MACRO MacroDirective: MD_Define Ifndef Callback Ifndef is called when an #ifndef is seen. Argument descriptions: +----------------+-----------------------+------------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +----------------+-----------------------+------------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the directive. | +----------------+-----------------------+------------------+------------------+ | MacroNameTok | (token) | const Token | The macro name | | | | | token. | +----------------+-----------------------+------------------+------------------+ | MacroDirective | (MD_Define|MD_Unde- | const MacroDi- | The kind of | | | fine|MD_Visibility) | rective | macro directive | | | | | from the | | | | | MacroDirective | | | | | structure. | +----------------+-----------------------+------------------+------------------+ Example:: - Callback: Ifndef Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-conditional.cpp:3:1" MacroNameTok: MACRO MacroDirective: MD_Define Else Callback Else is called when an #else is seen. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the else direc- | | | | | tive. | +---------------+-----------------------+----------------+------------------+ | IfLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the if direc- | | | | | tive. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: Else Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" Endif Callback Endif is called when an #endif is seen. Argument descriptions: +---------------+-----------------------+----------------+------------------+ | Argument Name | Argument Value | Clang C++ Type | Description | | | Syntax | | | +---------------+-----------------------+----------------+------------------+ | Loc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the endif direc- | | | | | tive. | +---------------+-----------------------+----------------+------------------+ | IfLoc | "(file):(line):(col)" | SourceLocation | The location of | | | | | the if direc- | | | | | tive. | +---------------+-----------------------+----------------+------------------+ Example:: - Callback: Endif Loc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:10:2" IfLoc: "D:/Clang/llvm/clang-tools-extra/test/pp-trace/pp-trace-macro.cpp:8:2" Building pp-trace To build from source: 1. Read Getting Started with the LLVM System and Clang Tools Documenta- tion for information on getting sources for LLVM, Clang, and Clang Extra Tools. 2. Getting Started with the LLVM System and Building LLVM with CMake give directions for how to build. With sources all checked out into the right place the LLVM build will build Clang Extra Tools and their dependencies automatically. • If using CMake, you can also use the pp-trace target to build just the pp-trace tool and its dependencies. CLANG-RENAME Contents • Clang-Rename • Using Clang-Rename • Vim Integration • Emacs Integration See also: clang-rename is a C++ refactoring tool. Its purpose is to perform effi- cient renaming actions in large-scale projects such as renaming classes, functions, variables, arguments, namespaces etc. The tool is in a very early development stage, so you might encounter bugs and crashes. Submitting reports with information about how to re- produce the issue to the LLVM bugtracker will definitely help the project. If you have any ideas or suggestions, you might want to put a feature request there. Using Clang-Rename clang-rename is a LibTooling-based tool, and it's easier to work with if you set up a compile command database for your project (for an exam- ple of how to do this see How To Setup Tooling For LLVM). You can also specify compilation options on the command line after --: $ clang-rename -offset=42 -new-name=foo test.cpp -- -Imy_project/include -DMY_DEFINES ... To get an offset of a symbol in a file run $ grep -FUbo 'foo' file.cpp The tool currently supports renaming actions inside a single transla- tion unit only. It is planned to extend the tool's functionality to support multi-TU renaming actions in the future. clang-rename also aims to be easily integrated into popular text edi- tors, such as Vim and Emacs, and improve the workflow of users. Although a command line interface exists, it is highly recommended to use the text editor interface instead for better experience. You can also identify one or more symbols to be renamed by giving the fully qualified name: $ clang-rename -qualified-name=foo -new-name=bar test.cpp Renaming multiple symbols at once is supported, too. However, clang-re- name doesn't accept both -offset and -qualified-name at the same time. So, you can either specify multiple -offset or -qualified-name. $ clang-rename -offset=42 -new-name=bar1 -offset=150 -new-name=bar2 test.cpp or $ clang-rename -qualified-name=foo1 -new-name=bar1 -qualified-name=foo2 -new-name=bar2 test.cpp Alternatively, {offset | qualified-name} / new-name pairs can be put into a YAML file: --- - Offset: 42 NewName: bar1 - Offset: 150 NewName: bar2 ... or --- - QualifiedName: foo1 NewName: bar1 - QualifiedName: foo2 NewName: bar2 ... That way you can avoid spelling out all the names as command line argu- ments: $ clang-rename -input=test.yaml test.cpp clang-rename offers the following options: $ clang-rename --help USAGE: clang-rename [subcommand] [options] <source0> [... <sourceN>] OPTIONS: Generic Options: -help - Display available options (-help-hidden for more) -help-list - Display list of available options (-help-list-hidden for more) -version - Display the version of this program clang-rename common options: -export-fixes=<filename> - YAML file to store suggested fixes in. -extra-arg=<string> - Additional argument to append to the compiler command line Can be used several times. -extra-arg-before=<string> - Additional argument to prepend to the compiler command line Can be used several times. -force - Ignore nonexistent qualified names. -i - Overwrite edited <file>s. -input=<string> - YAML file to load oldname-newname pairs from. -new-name=<string> - The new name to change the symbol to. -offset=<uint> - Locates the symbol by offset as opposed to <line>:<column>. -p=<string> - Build path -pl - Print the locations affected by renaming to stderr. -pn - Print the found symbol's name prior to renaming to stderr. -qualified-name=<string> - The fully qualified name of the symbol. Vim Integration You can call clang-rename directly from Vim! To set up clang-rename in- tegration for Vim see clang/tools/clang-rename/clang-rename.py. Please note that you have to save all buffers, in which the replacement will happen before running the tool. Once installed, you can point your cursor to symbols you want to re- name, press <leader>cr and type new desired name. The <leader> key is a reference to a specific key defined by the mapleader variable and is bound to backslash by default. Emacs Integration You can also use clang-rename while using Emacs! To set up clang-rename integration for Emacs see clang-rename/tool/clang-rename.el. Once installed, you can point your cursor to symbols you want to re- name, press M-X, type clang-rename and new desired name. Please note that you have to save all buffers, in which the replacement will happen before running the tool. CLANG-DOC Contents • Clang-Doc • Use • Output • Configuration • Options clang-doc is a tool for generating C and C++ documentation from source code and comments. The tool is in a very early development stage, so you might encounter bugs and crashes. Submitting reports with information about how to re- produce the issue to the LLVM bugtracker will definitely help the project. If you have any ideas or suggestions, please to put a feature request there. Use clang-doc is a LibTooling-based tool, and so requires a compile command database for your project (for an example of how to do this see How To Setup Tooling For LLVM). By default, the tool will run on all files listed in the given compile commands database: $ clang-doc /path/to/compile_commands.json The tool can also be used on a single file or multiple files if a build path is passed with the -p flag. $ clang-doc /path/to/file.cpp -p /path/to/build Output clang-doc produces a directory of documentation. One file is produced for each namespace and record in the project source code, containing all documentation (including contained functions, methods, and enums) for that item. The top-level directory is configurable through the output flag: $ clang-doc -output=output/directory/ compile_commands.json Configuration Configuration for clang-doc is currently limited to command-line op- tions. In the future, it may develop the ability to use a configura- tion file, but no such efforts are currently in progress. Options clang-doc offers the following options: $ clang-doc --help USAGE: clang-doc [options] <source0> [... <sourceN>] OPTIONS: Generic Options: -help - Display available options (-help-hidden for more) -help-list - Display list of available options (-help-list-hidden for more) -version - Display the version of this program clang-doc options: --doxygen - Use only doxygen-style comments to generate docs. --extra-arg=<string> - Additional argument to append to the compiler command line Can be used several times. --extra-arg-before=<string> - Additional argument to prepend to the compiler command line Can be used several times. --format=<value> - Format for outputted docs. =yaml - Documentation in YAML format. =md - Documentation in MD format. =html - Documentation in HTML format. --ignore-map-errors - Continue if files are not mapped correctly. --output=<string> - Directory for outputting generated files. -p=<string> - Build path --project-name=<string> - Name of project. --public - Document only public declarations. --repository=<string> - URL of repository that hosts code. Used for links to definition locations. --source-root=<string> - Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir. --stylesheets=<string> - CSS stylesheets to extend the default styles. The following flags should only be used if format is set to html: - repository - source-root - stylesheets • Index • Search Page AUTHOR The Clang Team COPYRIGHT 2007-2025, The Clang Team 11 Apr 17, 2025 EXTRACLANGTOOLS(1)
NAME | EXTRA CLANG TOOLS 11.0.0 RELEASE NOTES | CLANG-TIDY | CLANG-INCLUDE-FIXER | MODULARIZE USER'S MANUAL | PP-TRACE USER'S MANUAL | CLANG-RENAME | CLANG-DOC | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=extraclangtools11&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>