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
88.. note:: If you are using struct_size() on a structure containing a zero-length
89        or a one-element array as a trailing array member, please refactor such
90        array usage and switch to a `flexible array member
91        <#zero-length-and-one-element-arrays>`_ instead.
92
93See array_size(), array3_size(), and struct_size(),
94for more details as well as the related check_add_overflow() and
95check_mul_overflow() family of functions.
96
97simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
98----------------------------------------------------------------------
99The simple_strtol(), simple_strtoll(),
100simple_strtoul(), and simple_strtoull() functions
101explicitly ignore overflows, which may lead to unexpected results
102in callers. The respective kstrtol(), kstrtoll(),
103kstrtoul(), and kstrtoull() functions tend to be the
104correct replacements, though note that those require the string to be
105NUL or newline terminated.
106
107strcpy()
108--------
109strcpy() performs no bounds checking on the destination buffer. This
110could result in linear overflows beyond the end of the buffer, leading to
111all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various
112compiler flags help reduce the risk of using this function, there is
113no good reason to add new uses of this function. The safe replacement
114is strscpy(), though care must be given to any cases where the return
115value of strcpy() was used, since strscpy() does not return a pointer to
116the destination, but rather a count of non-NUL bytes copied (or negative
117errno when it truncates).
118
119strncpy() on NUL-terminated strings
120-----------------------------------
121Use of strncpy() does not guarantee that the destination buffer will
122be NUL terminated. This can lead to various linear read overflows and
123other misbehavior due to the missing termination. It also NUL-pads
124the destination buffer if the source contents are shorter than the
125destination buffer size, which may be a needless performance penalty
126for callers using only NUL-terminated strings. The safe replacement is
127strscpy(), though care must be given to any cases where the return value
128of strncpy() was used, since strscpy() does not return a pointer to the
129destination, but rather a count of non-NUL bytes copied (or negative
130errno when it truncates). Any cases still needing NUL-padding should
131instead use strscpy_pad().
132
133If a caller is using non-NUL-terminated strings, strncpy() can
134still be used, but destinations should be marked with the `__nonstring
135<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_
136attribute to avoid future compiler warnings.
137
138strlcpy()
139---------
140strlcpy() reads the entire source buffer first (since the return value
141is meant to match that of strlen()). This read may exceed the destination
142size limit. This is both inefficient and can lead to linear read overflows
143if a source string is not NUL-terminated. The safe replacement is strscpy(),
144though care must be given to any cases where the return value of strlcpy()
145is used, since strscpy() will return negative errno values when it truncates.
146
147%p format specifier
148-------------------
149Traditionally, using "%p" in format strings would lead to regular address
150exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to
151be exploitable, all "%p" uses in the kernel are being printed as a hashed
152value, rendering them unusable for addressing. New uses of "%p" should not
153be added to the kernel. For text addresses, using "%pS" is likely better,
154as it produces the more useful symbol name instead. For nearly everything
155else, just do not add "%p" at all.
156
157Paraphrasing Linus's current `guidance <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_:
158
159- If the hashed "%p" value is pointless, ask yourself whether the pointer
160  itself is important. Maybe it should be removed entirely?
161- If you really think the true pointer value is important, why is some
162  system state or user privilege level considered "special"? If you think
163  you can justify it (in comments and commit log) well enough to stand
164  up to Linus's scrutiny, maybe you can use "%px", along with making sure
165  you have sensible permissions.
166
167And 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/>`_.
168
169Variable Length Arrays (VLAs)
170-----------------------------
171Using stack VLAs produces much worse machine code than statically
172sized stack arrays. While these non-trivial `performance issues
173<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to
174eliminate VLAs, they are also a security risk. Dynamic growth of a stack
175array may exceed the remaining memory in the stack segment. This could
176lead to a crash, possible overwriting sensitive contents at the end of the
177stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting
178memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
179
180Implicit switch case fall-through
181---------------------------------
182The C language allows switch cases to fall through to the next case
183when a "break" statement is missing at the end of a case. This, however,
184introduces ambiguity in the code, as it's not always clear if the missing
185break is intentional or a bug. For example, it's not obvious just from
186looking at the code if `STATE_ONE` is intentionally designed to fall
187through into `STATE_TWO`::
188
189	switch (value) {
190	case STATE_ONE:
191		do_something();
192	case STATE_TWO:
193		do_other();
194		break;
195	default:
196		WARN("unknown state");
197	}
198
199As there have been a long list of flaws `due to missing "break" statements
200<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
201implicit fall-through. In order to identify intentional fall-through
202cases, we have adopted a pseudo-keyword macro "fallthrough" which
203expands to gcc's extension `__attribute__((__fallthrough__))
204<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.
205(When the C17/C18  `[[fallthrough]]` syntax is more commonly supported by
206C compilers, static analyzers, and IDEs, we can switch to using that syntax
207for the macro pseudo-keyword.)
208
209All switch/case blocks must end in one of:
210
211* break;
212* fallthrough;
213* continue;
214* goto <label>;
215* return [expression];
216
217Zero-length and one-element arrays
218----------------------------------
219There is a regular need in the kernel to provide a way to declare having
220a dynamically sized set of trailing elements in a structure. Kernel code
221should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_
222for these cases. The older style of one-element or zero-length arrays should
223no longer be used.
224
225In older C code, dynamically sized trailing elements were done by specifying
226a one-element array at the end of a structure::
227
228        struct something {
229                size_t count;
230                struct foo items[1];
231        };
232
233This led to fragile size calculations via sizeof() (which would need to
234remove the size of the single trailing element to get a correct size of
235the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_
236was introduced to allow for zero-length arrays, to avoid these kinds of
237size problems::
238
239        struct something {
240                size_t count;
241                struct foo items[0];
242        };
243
244But this led to other problems, and didn't solve some problems shared by
245both styles, like not being able to detect when such an array is accidentally
246being used _not_ at the end of a structure (which could happen directly, or
247when such a struct was in unions, structs of structs, etc).
248
249C99 introduced "flexible array members", which lacks a numeric size for
250the array declaration entirely::
251
252        struct something {
253                size_t count;
254                struct foo items[];
255        };
256
257This is the way the kernel expects dynamically sized trailing elements
258to be declared. It allows the compiler to generate errors when the
259flexible array does not occur last in the structure, which helps to prevent
260some kind of `undefined behavior
261<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_
262bugs from being inadvertently introduced to the codebase. It also allows
263the compiler to correctly analyze array sizes (via sizeof(),
264`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance,
265there is no mechanism that warns us that the following application of the
266sizeof() operator to a zero-length array always results in zero::
267
268        struct something {
269                size_t count;
270                struct foo items[0];
271        };
272
273        struct something *instance;
274
275        instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
276        instance->count = count;
277
278        size = sizeof(instance->items) * instance->count;
279        memcpy(instance->items, source, size);
280
281At the last line of code above, ``size`` turns out to be ``zero``, when one might
282have thought it represents the total size in bytes of the dynamic memory recently
283allocated for the trailing array ``items``. Here are a couple examples of this
284issue: `link 1
285<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
286`link 2
287<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
288Instead, `flexible array members have incomplete type, and so the sizeof()
289operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
290so any misuse of such operators will be immediately noticed at build time.
291
292With respect to one-element arrays, one has to be acutely aware that `such arrays
293occupy at least as much space as a single object of the type
294<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_,
295hence they contribute to the size of the enclosing structure. This is prone
296to error every time people want to calculate the total size of dynamic memory
297to allocate for a structure containing an array of this kind as a member::
298
299        struct something {
300                size_t count;
301                struct foo items[1];
302        };
303
304        struct something *instance;
305
306        instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
307        instance->count = count;
308
309        size = sizeof(instance->items) * instance->count;
310        memcpy(instance->items, source, size);
311
312In the example above, we had to remember to calculate ``count - 1`` when using
313the struct_size() helper, otherwise we would have --unintentionally-- allocated
314memory for one too many ``items`` objects. The cleanest and least error-prone way
315to implement this is through the use of a `flexible array member`, together with
316struct_size() and flex_array_size() helpers::
317
318        struct something {
319                size_t count;
320                struct foo items[];
321        };
322
323        struct something *instance;
324
325        instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
326        instance->count = count;
327
328        memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
329