108 lines · plain
1.. _clang_tidy_checks:2 3LLVM libc clang-tidy checks4===========================5 6 7.. warning::8 This page is severely out of date. Much of the information it contains may be9 incorrect. Please only remove this warning once the page has been updated.10 11These are the clang-tidy checks designed to help enforce implementation12standards.13The configuration file is ``src/.clang-tidy``.14 15restrict-system-libc-header16---------------------------17One of libc-project’s design goals is to use kernel headers and compiler18provided headers to prevent code duplication on a per platform basis. This19presents a problem when writing implementations since system libc headers are20easy to include accidentally and we can't just use the ``-nostdinc`` flag.21Improperly included system headers can introduce runtime errors because the C22standard outlines function prototypes and behaviors but doesn’t define23underlying implementation details such as the layout of a struct.24 25This check prevents accidental inclusion of system libc headers when writing a26libc implementation.27 28.. code-block:: c++29 30 #include <stdio.h> // Not allowed because it is part of system libc.31 #include <stddef.h> // Allowed because it is provided by the compiler.32 #include "internal/stdio.h" // Allowed because it is NOT part of system libc.33 34 35implementation-in-namespace36---------------------------37 38It is part of our implementation standards that all implementation pieces live39under the ``LIBC_NAMESPACE_DECL`` namespace. This prevents pollution of the40global namespace. Without a formal check to ensure this, an implementation41might compile and pass unit tests, but not produce a usable libc function.42 43This check that ensures any function call resolves to a function within the44``LIBC_NAMESPACE_DECL`` namespace.45 46.. code-block:: c++47 48 // Correct: implementation inside the correct namespace.49 namespace LIBC_NAMESPACE_DECL {50 void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}51 // Namespaces within LIBC_NAMESPACE namespace are allowed.52 namespace inner{53 int localVar = 0;54 }55 // Functions with C linkage are allowed.56 extern "C" void str_fuzz(){}57 }58 59 // Incorrect: implementation not in a namespace.60 void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}61 62 // Incorrect: outer most namespace is not correct.63 namespace something_else {64 void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}65 }66 67..68 TODO(97655): The clang-tidy check should be updated to ensure the namespace69 declaration uses LIBC_NAMESPACE_DECL as opposed to LIBC_NAMESPACE. The former70 should be used for accessing globals in LIBC_NAMESPACE rather than declaration.71 72 73callee-namespace74----------------75LLVM-libc is distinct because it is designed to maintain interoperability with76other libc libraries, including the one that lives on the system. This feature77creates some uncertainty about which library a call resolves to especially when78a public header with non-namespaced functions like ``string.h`` is included.79 80This check ensures any function call resolves to a function within the81LIBC_NAMESPACE namespace.82 83There are exceptions for the following functions:84``__errno_location`` so that ``errno`` can be set;85``malloc``, ``calloc``, ``realloc``, ``aligned_alloc``, and ``free`` since they86are always external and can be intercepted.87 88.. code-block:: c++89 90 namespace LIBC_NAMESPACE_DECL {91 92 // Allow calls with the fully qualified name.93 LIBC_NAMESPACE::strlen("hello");94 95 // Allow calls to compiler provided functions.96 (void)__builtin_abs(-1);97 98 // Bare calls are allowed as long as they resolve to the correct namespace.99 strlen("world");100 101 // Disallow calling into functions in the global namespace.102 ::strlen("!");103 104 // Allow calling into specific global functions (explained above)105 ::malloc(10);106 107 } // namespace LIBC_NAMESPACE_DECL108