Extra Clang Tools Documentation Release 8 The Clang Team Aug 13, 2018 Contents 1 Extra Clang Tools 8.0.0 (In-Progress) Release Notes3 2 Contents 5 3 Doxygen Documentation 151 4 Indices and tables 153 i ii Extra Clang Tools Documentation, Release 8 Welcome to the clang-tools-extra project which contains extra tools built using Clang’s tooling API’s. Contents 1 Extra Clang Tools Documentation, Release 8 2 Contents CHAPTER 1 Extra Clang Tools 8.0.0 (In-Progress) Release Notes • Introduction • What’s New in Extra Clang Tools 8.0.0? – Major New Features – Improvements to clang-query – Improvements to clang-rename – Improvements to clang-tidy – Improvements to include-fixer – Improvements to modularize Written by the LLVM Team Warning: These are in-progress notes for the upcoming Extra Clang Tools 8 release. Release notes for previous releases can be found on the Download Page. 1.1 Introduction This document contains the release notes for the Extra Clang Tools, part of the Clang release 8.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 downloaded from the LLVM releases web site. For more information about Clang or LLVM, including information about the latest release, please see the Clang Web Site or the LLVM Web Site. Note that if you are reading this file from a Subversion checkout or the main Clang web page, this document applies to the next release, not the current one. To see the release notes for a specific release, please see the releases page. 3 Extra Clang Tools Documentation, Release 8 1.2 What’s New in Extra Clang Tools 8.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. 1.2.1 Major New Features ... 1.2.2 Improvements to clang-query The improvements are. 1.2.3 Improvements to clang-rename The improvements are. 1.2.4 Improvements to clang-tidy The improvements are. • New readability-magic-numbers check. Detect usage of magic numbers, numbers that are used as literals instead of introduced via constants or symbols. 1.2.5 Improvements to include-fixer The improvements are. 1.2.6 Improvements to modularize The improvements are. 4 Chapter 1. Extra Clang Tools 8.0.0 (In-Progress) Release Notes CHAPTER 2 Contents 2.1 Clang-Tidy Contents • Clang-Tidy – Using clang-tidy – Getting Involved * Choosing the Right Place for your Check * Preparing your Workspace * The Directory Structure * Writing a clang-tidy Check * Registering your Check * Configuring Checks * Testing Checks * Running clang-tidy on LLVM * On checks profiling See also: 5 Extra Clang Tools Documentation, Release 8 2.1.1 Clang-Tidy Checks 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 default only std::basic_string is consid- ered. 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. android-cloexec-accept The usage of accept() is not recommended, it’s better to use accept4(). Without this flag, an opened sensitive file descriptor would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: accept(sockfd, addr, addrlen); // becomes accept4(sockfd, addr, addrlen, SOCK_CLOEXEC); android-cloexec-accept4 accept4() should include SOCK_CLOEXEC in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: accept4(sockfd, addr, addrlen, SOCK_NONBLOCK); // becomes accept4(sockfd, addr, addrlen, SOCK_NONBLOCK| SOCK_CLOEXEC); 6 Chapter 2. Contents Extra Clang Tools Documentation, Release 8 android-cloexec-creat The usage of creat() is not recommended, it’s better to use open(). Examples: int fd= creat(path, mode); // becomes int fd= open(path, O_WRONLY| O_CREAT| O_TRUNC| O_CLOEXEC, mode); android-cloexec-dup The usage of dup() is not recommended, it’s better to use fcntl(), which can set the close-on-exec flag. Otherwise, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: int fd= dup(oldfd); // becomes int fd= fcntl(oldfd, F_DUPFD_CLOEXEC); android-cloexec-epoll-create The usage of epoll_create() is not recommended, it’s better to use epoll_create1(), which allows close- on-exec. Examples: epoll_create(size); // becomes epoll_create1(EPOLL_CLOEXEC); android-cloexec-epoll-create1 epoll_create1() should include EPOLL_CLOEXEC in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: epoll_create1(0); // becomes epoll_create1(EPOLL_CLOEXEC); 2.1. Clang-Tidy 7 Extra Clang Tools Documentation, Release 8 android-cloexec-fopen fopen() should include e in their mode string; so re would be valid. This is equivalent to having set FD_CLOEXEC on that descriptor. Examples: fopen("fn","r"); // becomes fopen("fn","re"); android-cloexec-inotify-init The usage of inotify_init() is not recommended, it’s better to use inotify_init1(). Examples: inotify_init(); // becomes inotify_init1(IN_CLOEXEC); android-cloexec-inotify-init1 inotify_init1() should include IN_CLOEXEC in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: inotify_init1(IN_NONBLOCK); // becomes inotify_init1(IN_NONBLOCK| IN_CLOEXEC); android-cloexec-memfd-create memfd_create() should include MFD_CLOEXEC in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: memfd_create(name, MFD_ALLOW_SEALING); // becomes memfd_create(name, MFD_ALLOW_SEALING| MFD_CLOEXEC); 8 Chapter 2. Contents Extra Clang Tools Documentation, Release 8 android-cloexec-open A common source of security bugs is code that opens a file without using the O_CLOEXEC flag. Without that flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain, leaking that sensitive data. Open-like functions including open(), openat(), and open64() should include O_CLOEXEC in their flags argument. Examples: open("filename", O_RDWR); open64("filename", O_RDWR); openat(0,"filename", O_RDWR); // becomes open("filename", O_RDWR| O_CLOEXEC); open64("filename", O_RDWR| O_CLOEXEC); openat(0,"filename", O_RDWR| O_CLOEXEC); android-cloexec-socket socket() should include SOCK_CLOEXEC in its type argument to avoid the file descriptor leakage. Without this flag, an opened sensitive file would remain open across a fork+exec to a lower-privileged SELinux domain. Examples: socket(domain, type, SOCK_STREAM); // becomes socket(domain, type, SOCK_STREAM| SOCK_CLOEXEC); android-comparison-in-temp-failure-retry Diagnoses comparisons that appear to be incorrectly placed in the argument to the TEMP_FAILURE_RETRY macro. Having such a use is incorrect in the vast majority of cases, and will often silently defeat the purpose of the TEMP_FAILURE_RETRY macro. For context, TEMP_FAILURE_RETRY is a convenience macro provided by both glibc and Bionic. Its purpose is to repeatedly run a syscall until it either succeeds, or fails for reasons other than being interrupted. Example buggy usage looks like: char cs[1]; while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs))!=0)) { // Do something with cs. } Because TEMP_FAILURE_RETRY will check for whether the result of the comparison is -1, and retry if so. If you encounter this, the fix is simple: lift the comparison out of the TEMP_FAILURE_RETRY argument, like so: char cs[1]; while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs)))!=0){ // Do something with cs. } 2.1. Clang-Tidy 9 Extra Clang Tools Documentation, Release 8 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. bugprone-assert-side-effect