1.. _clang_tidy_checks: 2 3LLVM libc clang-tidy checks 4=========================== 5 6 7.. warning:: 8 This page is severely out of date. Much of the information it contains may be 9 incorrect. Please only remove this warning once the page has been updated. 10 11These are the clang-tidy checks designed to help enforce implementation 12standards. 13The configuration file is ``src/.clang-tidy``. 14 15restrict-system-libc-header 16--------------------------- 17One of libc-project’s design goals is to use kernel headers and compiler 18provided headers to prevent code duplication on a per platform basis. This 19presents a problem when writing implementations since system libc headers are 20easy to include accidentally and we can't just use the ``-nostdinc`` flag. 21Improperly included system headers can introduce runtime errors because the C 22standard outlines function prototypes and behaviors but doesn’t define 23underlying implementation details such as the layout of a struct. 24 25This check prevents accidental inclusion of system libc headers when writing a 26libc 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-namespace 36--------------------------- 37 38It is part of our implementation standards that all implementation pieces live 39under the ``LIBC_NAMESPACE_DECL`` namespace. This prevents pollution of the 40global namespace. Without a formal check to ensure this, an implementation 41might 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 the 44``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 namespace 69 declaration uses LIBC_NAMESPACE_DECL as opposed to LIBC_NAMESPACE. The former 70 should be used for accessing globals in LIBC_NAMESPACE rather than declaration. 71 72 73callee-namespace 74---------------- 75LLVM-libc is distinct because it is designed to maintain interoperability with 76other libc libraries, including the one that lives on the system. This feature 77creates some uncertainty about which library a call resolves to especially when 78a public header with non-namespaced functions like ``string.h`` is included. 79 80This check ensures any function call resolves to a function within the 81LIBC_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 they 86are 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_DECL 108