[clang-tidy] Add module for llvm-libc and restrict-system-libc-header-check.

[PaulkaToast]

Summary

This adds a new module to enforce standards specific to the llvm-libc project. This change also adds the first check which restricts user from including system libc headers accidentally which can lead to subtle bugs that would be a challenge to detect.

[njames93]

The test cases need fixing as they are causing the build to fail. Also would it be wise to add a .clang-tidy file to libc/ to enable this module for that subdirectory?

clang-tools-extra/clang-tidy/llvmlibc/CMakeLists.txt

16

Not sure why this error is here but can it be resolved

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

18

Should put this in an anonymous namespace as it doesn't need external linkage

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.h

19

FIXME

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

7

Should explain the rationale for this check

[Eugene.Zelenko]

Please mention new module in docs/clang-tidy/index.rst and Release Notes (new modules section is above new checks one and please add subsubsection).

clang-tools-extra/clang-tidy/llvmlibc/LLVMLibcTidyModule.cpp

22

Unnecessary empty line.

[abrachet]

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

41

Could you whitelist the freestanding/compiler provided headers like stddef, stdatomic...

[MaskRay]

I am of the feeling that this check should not be llvm-libc specific. It is a general need that certain system headers are not desired. This patch can provide a general mechanism (some whitelists and blacklists).

[njames93]

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

41

Or have a user configurable whitelist

43

Don't use auto when the type isn't an iterator or spelled out on the initialisation.

48

Ditto

[aaron.ballman]

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

41

It should be configurable and named something other than whitelist. I'd recommend AllowedHeaders or something along those lines.

[PaulkaToast]

In D75332#1897487, @njames93 wrote:

The test cases need fixing as they are causing the build to fail.

Done.

Also would it be wise to add a .clang-tidy file to libc/ to enable this module for that subdirectory?

Yes, this will be done in a separate patch. Thanks for pointing it out!

In D75332#1897868, @Eugene.Zelenko wrote:

Please mention new module in docs/clang-tidy/index.rst and Release Notes (new modules section is above new checks one and please add subsubsection).

Done.

In D75332#1899201, @MaskRay wrote:

I am of the feeling that this check should not be llvm-libc specific. It is a general need that certain system headers are not desired. This patch can provide a general mechanism (some whitelists and blacklists).

Please see my reply to aaron.

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

41

Maintaining a list of acceptable and blacklisted headers would produce a fair bit of maintenance burden. We have a specific use-case in mind here for llvm-libc which is to avoid use of system libc headers that aren't provided by the compiler. I've added a check to allow for compiler provided headers without necessitating a black/white list.

If a general check is desirable then my suggestion is to pull out fuchsia-restrict-system-includes which already implements the features mentioned.

[abrachet]

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

41

I've added a check to allow for compiler provided headers without necessitating a black/white list.

This is a much better solution for sure.

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

12–14

Nit: We do periods at the end of comments in real code so for parity I think it makes sense here too.

17–21

To be annoyingly pedantic, FILE is opaque so it would actually be ok in this situation. It is undefined to allocate your own FILE I believe. Something like jmp_buf or thrd_t might be better examples? Or macros like assert or errno.

[MaskRay]

RestrictSystemLibcHeadersCheck

As I commented previously, I think the checker name should be generalized, as it does not need to be coupled with llvm-libc. Other projects may have similar needs. For example, they don't want to accidentally include a system zlib.h -> they may ship a bundled zlib (say, in third_party/zlib/).

Maybe misc/ (or portability/) is more suitable?

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

50

This is actually an interesting topic.

On FreeBSD and linux-musl, stdalign.h stdarg.h stdbool.h stddef.h stdint.h stdnoreturn.h are provided by libc instead.

After D65699,

% clang -fsyntax-only -target x86_64-linux-musl -v /tmp/c/a.c
...
#include "..." search starts here:
#include <...> search starts here:
 /usr/local/include
 /usr/include/x86_64-linux-gnu
 /usr/include
 /tmp/ReleaseA/lib/clang/11.0.0/include
End of search list.

Note that the $resource_dir/include is after libc search directories on a Linux glibc (x86_64-linux-gnu) system.

Using a compiler intrinsic file (e.g. x86intrin.h) may be less controversial. It leaves to llvm-libc to decide which ordering is better. (I lean toward FreeBSD/linux musl way.)

53

Drop excess parentheses.

[MaskRay]

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

17–21

FILE is a problem of glibc. Other libcs don't necessarily have the problem.

glibc exposes the internals of FILE: typedef struct _IO_FILE FILE; and struct _IO_FILE { ... } is exposed. musl does not expose the underlying structure of FILE (POSIX intentionally does not require that to allow a flexible implementation).

[PaulkaToast]

In D75332#1903570, @MaskRay wrote:

RestrictSystemLibcHeadersCheck

As I commented previously, I think the checker name should be generalized, as it does not need to be coupled with llvm-libc. Other projects may have similar needs. For example, they don't want to accidentally include a system zlib.h -> they may ship a bundled zlib (say, in third_party/zlib/).

Maybe misc/ (or portability/) is more suitable?

This is a simple check made precisely for llvm libc's use-case and doesn't require a human maintained list. As I mentioned, if a more general/configurable check is desired then porting out the fuchsia-restrict-system-includes would make more sense as it already implements white-lists and would handle the situation you described.

[MaskRay]

In D75332#1904264, @PaulkaToast wrote:

In D75332#1903570, @MaskRay wrote:

RestrictSystemLibcHeadersCheck

As I commented previously, I think the checker name should be generalized, as it does not need to be coupled with llvm-libc. Other projects may have similar needs. For example, they don't want to accidentally include a system zlib.h -> they may ship a bundled zlib (say, in third_party/zlib/).

Maybe misc/ (or portability/) is more suitable?

This is a simple check made precisely for llvm libc's use-case and doesn't require a human maintained list. As I mentioned, if a more general/configurable check is desired then porting out the fuchsia-restrict-system-includes would make more sense as it already implements white-lists and would handle the situation you described.

1. D43778 fuchsia-restrict-system-includes
2. This patch llvmlibc-restrict-system-libc-headers
3. The zlib use case I mentioned.

I think we should consider generalizing the existing fuchsia-restrict-system-includes (I did not know it). +@juliehockett

Fuchsia and llvm-libc developers can use a config once the general checker is ready.

[Eugene.Zelenko]

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

19

Please use double-ticks for language constructs.

[aaron.ballman]

In D75332#1904317, @MaskRay wrote:

In D75332#1904264, @PaulkaToast wrote:

In D75332#1903570, @MaskRay wrote:

RestrictSystemLibcHeadersCheck

As I commented previously, I think the checker name should be generalized, as it does not need to be coupled with llvm-libc. Other projects may have similar needs. For example, they don't want to accidentally include a system zlib.h -> they may ship a bundled zlib (say, in third_party/zlib/).

Maybe misc/ (or portability/) is more suitable?

This is a simple check made precisely for llvm libc's use-case and doesn't require a human maintained list. As I mentioned, if a more general/configurable check is desired then porting out the fuchsia-restrict-system-includes would make more sense as it already implements white-lists and would handle the situation you described.

1. D43778 fuchsia-restrict-system-includes
2. This patch llvmlibc-restrict-system-libc-headers
3. The zlib use case I mentioned.

I think we should consider generalizing the existing fuchsia-restrict-system-includes (I did not know it). +@juliehockett

Fuchsia and llvm-libc developers can use a config once the general checker is ready.

+1

[PaulkaToast]

Thanks for the suggestions, the general check sounds like a great idea. I can see the use case for this as it can be used by anyone. I took the time to port out fuchsia's check and flesh out the user facing documentation. Here is the patch for that D75786.

Keeping that in mind, I believe using the general check with a list of headers in llvm-libc's case is a bad idea due the following edge cases:

1. The compiler stops providing an include

If we had a list that specifically allowed stdbool.h and imagine the compiler used stopped providing this header, then we may accidentally pick up the system stdbool.h. Having to change the .clang-tidy file in llvm-libc's tree when the compiler provided includes changes is a maintenance burden and can quickly become stale.

2. Platform differences

The compiler provided headers may not be the same from operating system to operating system. This introduces the need for multiple lists for each system supported, where each list suffers from the above problem.

3. Accidental changes to the include order

In situations where a mistake is made in the build system and higher priority is given to the system includes over the compiler includes. A hand maintained list would not be able to catch this.

---

Above all else this test needs to be as strict as possible since many of these situations would allow libc to continue to compile, maybe even pass the tests but at run-time it could introduce bad behavior due to possible differences in implementation details. It is important to us to not have a human-point of failure on this check in my opinion.

[aaron.ballman]

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

53

No need for the local DiagnosticBuilder object, you can stream into the Check.diag() call.

58

No need for the local DiagnosticBuilder object, you can stream into the Check.diag() call.

67–68

The user can control this path -- is that an issue? You're using it to determine what a compiler-provided header file is, and this seems like an escape hatch for users to get around that. If that's reasonable to you, then I'm okay with it, but you had mentioned you want to remove human error as a factor and this seems like it could be a subtle human error situation.

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

17

necesary -> necessary

[PaulkaToast]

Addressed @aaron.ballman comments (:

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

67–68

Ah, thanks for pointing this out! I didn't consider this. I feel like scenario is a more unlikely then situations I mentioned. Probably not something to be too concerned about unless you know of a way to get the default resource path?

[Eugene.Zelenko]

clang-tools-extra/docs/ReleaseNotes.rst

107

Please synchronize with first statement in documentation.

[PaulkaToast]

Addressed @Eugene.Zelenko comments.

[aaron.ballman]

LGTM!

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

67–68

I also don't think it's particularly likely people will want to use this just to silence diagnostics, so I think it's fine as-is.

[PaulkaToast]

Mocked the header files so that we don't experience failures due to differences in systems. Mind taking a quick look @aaron.ballman?

[aaron.ballman]

LGTM!

clang-tools-extra/clang-tidy/CMakeLists.txt

 add_subdirectory(cert)
 add_subdirectory(cppcoreguidelines)
 add_subdirectory(darwin)
 add_subdirectory(fuchsia)
 add_subdirectory(google)
 add_subdirectory(hicpp)
 add_subdirectory(linuxkernel)
 add_subdirectory(llvm)
+add_subdirectory(llvmlibc)
 add_subdirectory(misc)
 add_subdirectory(modernize)
 if(CLANG_ENABLE_STATIC_ANALYZER)
   add_subdirectory(mpi)
 endif()
 add_subdirectory(objc)
 add_subdirectory(openmp)
 add_subdirectory(performance)
 add_subdirectory(portability)
 add_subdirectory(readability)
 add_subdirectory(zircon)
 set(ALL_CLANG_TIDY_CHECKS
   clangTidyAndroidModule
   clangTidyAbseilModule
   clangTidyBoostModule
   clangTidyBugproneModule
   clangTidyCERTModule
   clangTidyCppCoreGuidelinesModule
   clangTidyDarwinModule
   clangTidyFuchsiaModule
   clangTidyGoogleModule
   clangTidyHICPPModule
   clangTidyLinuxKernelModule
   clangTidyLLVMModule
+  clangTidyLLVMLibcModule
   clangTidyMiscModule
   clangTidyModernizeModule
   clangTidyObjCModule
   clangTidyOpenMPModule
   clangTidyPerformanceModule
   clangTidyPortabilityModule
   clangTidyReadabilityModule
   clangTidyZirconModule

clang-tools-extra/clang-tidy/ClangTidyForceLinker.h

 static int LLVM_ATTRIBUTE_UNUSED LinuxKernelModuleAnchorDestination =
     LinuxKernelModuleAnchorSource;
 
 // This anchor is used to force the linker to link the LLVMModule.
 extern volatile int LLVMModuleAnchorSource;
 static int LLVM_ATTRIBUTE_UNUSED LLVMModuleAnchorDestination =
     LLVMModuleAnchorSource;
 
+// This anchor is used to force the linker to link the LLVMLibcModule.
+extern volatile int LLVMLibcModuleAnchorSource;
+static int LLVM_ATTRIBUTE_UNUSED LLVMLibcModuleAnchorDestination =
+    LLVMLibcModuleAnchorSource;
+
 // This anchor is used to force the linker to link the CppCoreGuidelinesModule.
 extern volatile int CppCoreGuidelinesModuleAnchorSource;
 static int LLVM_ATTRIBUTE_UNUSED CppCoreGuidelinesModuleAnchorDestination =
     CppCoreGuidelinesModuleAnchorSource;
 
 // This anchor is used to force the linker to link the DarwinModule.
 extern volatile int DarwinModuleAnchorSource;
 static int LLVM_ATTRIBUTE_UNUSED DarwinModuleAnchorDestination =

clang-tools-extra/clang-tidy/llvmlibc/CMakeLists.txt

+set(LLVM_LINK_COMPONENTS support)
+
+add_clang_library(clangTidyLLVMLibcModule
+  LLVMLibcTidyModule.cpp
+  RestrictSystemLibcHeadersCheck.cpp
+
+  LINK_LIBS
+  clangAST
+  clangASTMatchers
+  clangBasic
+  clangLex
+  clangTidy
+  clangTidyUtils
+  clangTooling
+  )

clang-tools-extra/clang-tidy/llvmlibc/LLVMLibcTidyModule.cpp

+//===--- LLVMLibcTidyModule.cpp - clang-tidy ------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "../ClangTidy.h"
+#include "../ClangTidyModule.h"
+#include "../ClangTidyModuleRegistry.h"
+#include "RestrictSystemLibcHeadersCheck.h"
+
+namespace clang {
+namespace tidy {
+namespace llvm_libc {
+
+class LLVMLibcModule : public ClangTidyModule {
+public:
+  void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
+    CheckFactories.registerCheck<RestrictSystemLibcHeadersCheck>(
+        "llvmlibc-restrict-system-libc-headers");
+  }
+};
+
+// Register the LLVMLibcTidyModule using this statically initialized variable.
+static ClangTidyModuleRegistry::Add<LLVMLibcModule>
+    X("llvmlibc-module", "Adds LLVM libc standards checks.");
+
+} // namespace llvm_libc
+
+// This anchor is used to force the linker to link in the generated object file
+// and thus register the LLVMLibcModule.
+volatile int LLVMLibcModuleAnchorSource = 0;
+
+} // namespace tidy
+} // namespace clang

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.h

+//===--- RestrictSystemLibcHeadersCheck.h - clang-tidy ----------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_LLVMLIBC_RESTRICTSYSTEMLIBCHEADERSCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_LLVMLIBC_RESTRICTSYSTEMLIBCHEADERSCHECK_H
+
+#include "../ClangTidyCheck.h"
+
+namespace clang {
+namespace tidy {
+namespace llvm_libc {
+
+/// Warns of accidental inclusions of system libc headers that aren't
+/// compiler provided.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.html
+class RestrictSystemLibcHeadersCheck : public ClangTidyCheck {
+public:
+  RestrictSystemLibcHeadersCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  void registerPPCallbacks(const SourceManager &SM, Preprocessor *PP,
+                           Preprocessor *ModuleExpanderPP) override;
+};
+
+} // namespace llvm_libc
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_LLVMLIBC_RESTRICTSYSTEMLIBCHEADERSCHECK_H

clang-tools-extra/clang-tidy/llvmlibc/RestrictSystemLibcHeadersCheck.cpp

+//===--- RestrictSystemLibcHeadersCheck.cpp - clang-tidy ------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "RestrictSystemLibcHeadersCheck.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/Lex/HeaderSearch.h"
+#include "clang/Lex/HeaderSearchOptions.h"
+
+namespace clang {
+namespace tidy {
+namespace llvm_libc {
+
+namespace {
+
+class RestrictedIncludesPPCallbacks : public PPCallbacks {
+public:
+  explicit RestrictedIncludesPPCallbacks(
+      RestrictSystemLibcHeadersCheck &Check, const SourceManager &SM,
+      const SmallString<128> CompilerIncudeDir)
+      : Check(Check), SM(SM), CompilerIncudeDir(CompilerIncudeDir) {}
+
+  void InclusionDirective(SourceLocation HashLoc, const Token &IncludeTok,
+                          StringRef FileName, bool IsAngled,
+                          CharSourceRange FilenameRange, const FileEntry *File,
+                          StringRef SearchPath, StringRef RelativePath,
+                          const Module *Imported,
+                          SrcMgr::CharacteristicKind FileType) override;
+
+private:
+  RestrictSystemLibcHeadersCheck &Check;
+  const SourceManager &SM;
+  const SmallString<128> CompilerIncudeDir;
+};
+
+} // namespace
+
+void RestrictedIncludesPPCallbacks::InclusionDirective(
+    SourceLocation HashLoc, const Token &IncludeTok, StringRef FileName,
+    bool IsAngled, CharSourceRange FilenameRange, const FileEntry *File,
+    StringRef SearchPath, StringRef RelativePath, const Module *Imported,
+    SrcMgr::CharacteristicKind FileType) {
+  if (SrcMgr::isSystem(FileType)) {
+    // Compiler provided headers are allowed (e.g stddef.h).
+    if (SearchPath == CompilerIncudeDir) return;
+    if (!SM.isInMainFile(HashLoc)) {
+      Check.diag(
+          HashLoc,
+          "system libc header %0 not allowed, transitively included from %1")
+          << FileName << SM.getFilename(HashLoc);
+    } else {
+      Check.diag(HashLoc, "system libc header %0 not allowed") << FileName;
+    }
+  }
+}
+
+void RestrictSystemLibcHeadersCheck::registerPPCallbacks(
+    const SourceManager &SM, Preprocessor *PP, Preprocessor *ModuleExpanderPP) {
+  SmallString<128> CompilerIncudeDir =
+      StringRef(PP->getHeaderSearchInfo().getHeaderSearchOpts().ResourceDir);
+  llvm::sys::path::append(CompilerIncudeDir, "include");
+  PP->addPPCallbacks(std::make_unique<RestrictedIncludesPPCallbacks>(
+      *this, SM, CompilerIncudeDir));
+}
+
+} // namespace llvm_libc
+} // namespace tidy
+} // namespace clang

clang-tools-extra/docs/ReleaseNotes.rst

 Improvements to clang-rename
 ----------------------------
 
 The improvements are...
 
 Improvements to clang-tidy
 --------------------------
 
+New module
+^^^^^^^^^^
+- New module `llvmlibc`.
+
+  This module contains checks related to the LLVM-libc coding standards.
+
 New checks
 ^^^^^^^^^^
 
 - New :doc:`bugprone-misplaced-pointer-arithmetic-in-alloc
   <clang-tidy/checks/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()``,
- New :doc:`bugprone-suspicious-include
   them.
 
 - New :doc:`cert-oop57-cpp
   <clang-tidy/checks/cert-oop57-cpp>` check.
 
   Flags use of the `C` standard library functions ``memset``, ``memcpy`` and
   ``memcmp`` and similar derivatives on non-trivial types.
 
+- New :doc:`llvmlibc-restrict-system-libc-headers
+  <clang-tidy/checks/llvmlibc-restrict-system-libc-headers>` check.
+
+  Finds includes of system libc headers not provided by the compiler within
+  llvm-libc implementations.
+
 - New :doc:`objc-dealloc-in-category
   <clang-tidy/checks/objc-dealloc-in-category>` check.
 
   Finds implementations of -dealloc in Objective-C categories.
 
 - New :doc:`misc-no-recursion
   <clang-tidy/checks/misc-no-recursion>` check.
 

clang-tools-extra/docs/clang-tidy/checks/list.rst

.. csv-table::
    `hicpp-signed-bitwise <hicpp-signed-bitwise.html>`_,
    `linuxkernel-must-use-errs <linuxkernel-must-use-errs.html>`_,
    `llvm-header-guard <llvm-header-guard.html>`_,
    `llvm-include-order <llvm-include-order.html>`_, "Yes"
    `llvm-namespace-comment <llvm-namespace-comment.html>`_,
    `llvm-prefer-isa-or-dyn-cast-in-conditionals <llvm-prefer-isa-or-dyn-cast-in-conditionals.html>`_, "Yes"
    `llvm-prefer-register-over-unsigned <llvm-prefer-register-over-unsigned.html>`_, "Yes"
    `llvm-twine-local <llvm-twine-local.html>`_, "Yes"
+   `llvmlibc-restrict-system-libc-headers <llvmlibc-restrict-system-libc-headers.html>`_,
    `misc-definitions-in-headers <misc-definitions-in-headers.html>`_, "Yes"
    `misc-misplaced-const <misc-misplaced-const.html>`_,
    `misc-new-delete-overloads <misc-new-delete-overloads.html>`_,
    `misc-no-recursion <misc-no-recursion.html>`_,
    `misc-non-copyable-objects <misc-non-copyable-objects.html>`_,
    `misc-non-private-member-variables-in-classes <misc-non-private-member-variables-in-classes.html>`_,
    `misc-redundant-expression <misc-redundant-expression.html>`_, "Yes"
    `misc-static-assert <misc-static-assert.html>`_, "Yes"

clang-tools-extra/docs/clang-tidy/checks/llvmlibc-restrict-system-libc-headers.rst

+.. title:: clang-tidy - llvmlibc-restrict-system-libc-headers
+
+llvmlibc-restrict-system-libc-headers
+=====================================
+
+Finds includes of system libc headers not provided by the compiler within
+llvm-libc implementations.
+
+.. code-block:: c++
+
+   #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 consider a system libc
+whose ``dirent`` struct has slightly different field ordering than llvm-libc.
+While this will compile successfully, this can cause issues during runtime
+because they are ABI incompatible.

clang-tools-extra/docs/clang-tidy/index.rst

 ``bugprone-``          Checks that target bugprone code constructs.
 ``cert-``              Checks related to CERT Secure Coding Guidelines.
 ``cppcoreguidelines-`` Checks related to C++ Core Guidelines.
 ``clang-analyzer-``    Clang Static Analyzer checks.
 ``fuchsia-``           Checks related to Fuchsia coding conventions.
 ``google-``            Checks related to Google coding conventions.
 ``hicpp-``             Checks related to High Integrity C++ Coding Standard.
 ``llvm-``              Checks related to the LLVM coding conventions.
+``llvmlibc-``          Checks related to the LLVM-libc coding standards.
 ``misc-``              Checks that we didn't have a better category for.
 ``modernize-``         Checks that advocate usage of modern (currently "modern"
                        means "C++11") language constructs.
 ``mpi-``               Checks related to MPI (Message Passing Interface).
 ``objc-``              Checks related to Objective-C coding conventions.
 ``openmp-``            Checks related to OpenMP API.
 ``performance-``       Checks that target performance-related issues.
 ``portability-``       Checks that target portability-related issues that don't

clang-tools-extra/test/clang-tidy/checkers/Inputs/llvmlibc/transitive.h

+#include <math.h>

clang-tools-extra/test/clang-tidy/checkers/llvmlibc-restrict-system-libc-headers-transitive.cpp

+// RUN: %check_clang_tidy %s llvmlibc-restrict-system-libc-headers %t \
+// RUN:   -- -header-filter=.* \
+// RUN:   -- -I %S/Inputs/llvmlibc \
+// RUN:   -isystem %S/Inputs/llvmlibc/system \
+// RUN:   -resource-dir %S/Inputs/llvmlibc/resource
+
+#include "transitive.h"
+// CHECK-MESSAGES: :1:1: warning: system libc header math.h not allowed, transitively included from {{.*}}

clang-tools-extra/test/clang-tidy/checkers/llvmlibc-restrict-system-libc-headers.cpp

+// RUN: %check_clang_tidy %s llvmlibc-restrict-system-libc-headers %t \
+// RUN:   -- -- -isystem %S/Inputs/llvmlibc/system \
+// RUN:   -resource-dir %S/Inputs/llvmlibc/resource
+
+#include <stdio.h>
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: system libc header stdio.h not allowed
+#include <stdlib.h>
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: system libc header stdlib.h not allowed
+#include "string.h"
+// CHECK-MESSAGES: :[[@LINE-1]]:1: warning: system libc header string.h not allowed
+#include "stdatomic.h"
+#include <stddef.h>
+// Compiler provided headers should not throw warnings.