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