1.. SPDX-License-Identifier: GPL-2.0 2 3.. _deprecated: 4 5===================================================================== 6Deprecated Interfaces, Language Features, Attributes, and Conventions 7===================================================================== 8 9In a perfect world, it would be possible to convert all instances of 10some deprecated API into the new API and entirely remove the old API in 11a single development cycle. However, due to the size of the kernel, the 12maintainership hierarchy, and timing, it's not always feasible to do these 13kinds of conversions at once. This means that new instances may sneak into 14the kernel while old ones are being removed, only making the amount of 15work to remove the API grow. In order to educate developers about what 16has been deprecated and why, this list has been created as a place to 17point when uses of deprecated things are proposed for inclusion in the 18kernel. 19 20__deprecated 21------------ 22While this attribute does visually mark an interface as deprecated, 23it `does not produce warnings during builds any more 24<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ 25because one of the standing goals of the kernel is to build without 26warnings and no one was actually doing anything to remove these deprecated 27interfaces. While using `__deprecated` is nice to note an old API in 28a header file, it isn't the full solution. Such interfaces must either 29be fully removed from the kernel, or added to this file to discourage 30others from using them in the future. 31 32BUG() and BUG_ON() 33------------------ 34Use WARN() and WARN_ON() instead, and handle the "impossible" 35error condition as gracefully as possible. While the BUG()-family 36of APIs were originally designed to act as an "impossible situation" 37assert and to kill a kernel thread "safely", they turn out to just be 38too risky. (e.g. "In what order do locks need to be released? Have 39various states been restored?") Very commonly, using BUG() will 40destabilize a system or entirely break it, which makes it impossible 41to debug or even get viable crash reports. Linus has `very strong 42<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_ 43feelings `about this 44<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_. 45 46Note that the WARN()-family should only be used for "expected to 47be unreachable" situations. If you want to warn about "reachable 48but undesirable" situations, please use the pr_warn()-family of 49functions. System owners may have set the *panic_on_warn* sysctl, 50to make sure their systems do not continue running in the face of 51"unreachable" conditions. (For example, see commits like `this one 52<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.) 53 54open-coded arithmetic in allocator arguments 55-------------------------------------------- 56Dynamic size calculations (especially multiplication) should not be 57performed in memory allocator (or similar) function arguments due to the 58risk of them overflowing. This could lead to values wrapping around and a 59smaller allocation being made than the caller was expecting. Using those 60allocations could lead to linear overflows of heap memory and other 61misbehaviors. (One exception to this is literal values where the compiler 62can warn if they might overflow. Though using literals for arguments as 63suggested below is also harmless.) 64 65For example, do not use ``count * size`` as an argument, as in:: 66 67 foo = kmalloc(count * size, GFP_KERNEL); 68 69Instead, the 2-factor form of the allocator should be used:: 70 71 foo = kmalloc_array(count, size, GFP_KERNEL); 72 73If no 2-factor form is available, the saturate-on-overflow helpers should 74be used:: 75 76 bar = vmalloc(array_size(count, size)); 77 78Another common case to avoid is calculating the size of a structure with 79a trailing array of others structures, as in:: 80 81 header = kzalloc(sizeof(*header) + count * sizeof(*header->item), 82 GFP_KERNEL); 83 84Instead, use the helper:: 85 86 header = kzalloc(struct_size(header, item, count), GFP_KERNEL); 87 88See array_size(), array3_size(), and struct_size(), 89for more details as well as the related check_add_overflow() and 90check_mul_overflow() family of functions. 91 92simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() 93---------------------------------------------------------------------- 94The simple_strtol(), simple_strtoll(), 95simple_strtoul(), and simple_strtoull() functions 96explicitly ignore overflows, which may lead to unexpected results 97in callers. The respective kstrtol(), kstrtoll(), 98kstrtoul(), and kstrtoull() functions tend to be the 99correct replacements, though note that those require the string to be 100NUL or newline terminated. 101 102strcpy() 103-------- 104strcpy() performs no bounds checking on the destination 105buffer. This could result in linear overflows beyond the 106end of the buffer, leading to all kinds of misbehaviors. While 107`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the 108risk of using this function, there is no good reason to add new uses of 109this function. The safe replacement is strscpy(). 110 111strncpy() on NUL-terminated strings 112----------------------------------- 113Use of strncpy() does not guarantee that the destination buffer 114will be NUL terminated. This can lead to various linear read overflows 115and other misbehavior due to the missing termination. It also NUL-pads the 116destination buffer if the source contents are shorter than the destination 117buffer size, which may be a needless performance penalty for callers using 118only NUL-terminated strings. The safe replacement is strscpy(). 119(Users of strscpy() still needing NUL-padding should instead 120use strscpy_pad().) 121 122If a caller is using non-NUL-terminated strings, strncpy()() can 123still be used, but destinations should be marked with the `__nonstring 124<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ 125attribute to avoid future compiler warnings. 126 127strlcpy() 128--------- 129strlcpy() reads the entire source buffer first, possibly exceeding 130the given limit of bytes to copy. This is inefficient and can lead to 131linear read overflows if a source string is not NUL-terminated. The 132safe replacement is strscpy(). 133 134%p format specifier 135------------------- 136Traditionally, using "%p" in format strings would lead to regular address 137exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to 138be exploitable, all "%p" uses in the kernel are being printed as a hashed 139value, rendering them unusable for addressing. New uses of "%p" should not 140be added to the kernel. For text addresses, using "%pS" is likely better, 141as it produces the more useful symbol name instead. For nearly everything 142else, just do not add "%p" at all. 143 144Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_: 145 146- If the hashed "%p" value is pointless, ask yourself whether the pointer 147 itself is important. Maybe it should be removed entirely? 148- If you really think the true pointer value is important, why is some 149 system state or user privilege level considered "special"? If you think 150 you can justify it (in comments and commit log) well enough to stand 151 up to Linus's scrutiny, maybe you can use "%px", along with making sure 152 you have sensible permissions. 153 154And finally, know that a toggle for "%p" hashing will `not be accepted <https://lore.kernel.org/lkml/CA+55aFwieC1-nAs+NFq9RTwaR8ef9hWa4MjNBWL41F-8wM49eA@mail.gmail.com/>`_. 155 156Variable Length Arrays (VLAs) 157----------------------------- 158Using stack VLAs produces much worse machine code than statically 159sized stack arrays. While these non-trivial `performance issues 160<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to 161eliminate VLAs, they are also a security risk. Dynamic growth of a stack 162array may exceed the remaining memory in the stack segment. This could 163lead to a crash, possible overwriting sensitive contents at the end of the 164stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting 165memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) 166 167Implicit switch case fall-through 168--------------------------------- 169The C language allows switch cases to fall through to the next case 170when a "break" statement is missing at the end of a case. This, however, 171introduces ambiguity in the code, as it's not always clear if the missing 172break is intentional or a bug. For example, it's not obvious just from 173looking at the code if `STATE_ONE` is intentionally designed to fall 174through into `STATE_TWO`:: 175 176 switch (value) { 177 case STATE_ONE: 178 do_something(); 179 case STATE_TWO: 180 do_other(); 181 break; 182 default: 183 WARN("unknown state"); 184 } 185 186As there have been a long list of flaws `due to missing "break" statements 187<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow 188implicit fall-through. In order to identify intentional fall-through 189cases, we have adopted a pseudo-keyword macro "fallthrough" which 190expands to gcc's extension `__attribute__((__fallthrough__)) 191<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_. 192(When the C17/C18 `[[fallthrough]]` syntax is more commonly supported by 193C compilers, static analyzers, and IDEs, we can switch to using that syntax 194for the macro pseudo-keyword.) 195 196All switch/case blocks must end in one of: 197 198* break; 199* fallthrough; 200* continue; 201* goto <label>; 202* return [expression]; 203