]>
Commit | Line | Data |
---|---|---|
84253c8b KC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
98348577 FV |
3 | .. _deprecated: |
4 | ||
84253c8b KC |
5 | ===================================================================== |
6 | Deprecated Interfaces, Language Features, Attributes, and Conventions | |
7 | ===================================================================== | |
8 | ||
9 | In a perfect world, it would be possible to convert all instances of | |
10 | some deprecated API into the new API and entirely remove the old API in | |
11 | a single development cycle. However, due to the size of the kernel, the | |
12 | maintainership hierarchy, and timing, it's not always feasible to do these | |
13 | kinds of conversions at once. This means that new instances may sneak into | |
14 | the kernel while old ones are being removed, only making the amount of | |
15 | work to remove the API grow. In order to educate developers about what | |
16 | has been deprecated and why, this list has been created as a place to | |
17 | point when uses of deprecated things are proposed for inclusion in the | |
18 | kernel. | |
19 | ||
20 | __deprecated | |
21 | ------------ | |
22 | While this attribute does visually mark an interface as deprecated, | |
23 | it `does not produce warnings during builds any more | |
24 | <https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ | |
25 | because one of the standing goals of the kernel is to build without | |
26 | warnings and no one was actually doing anything to remove these deprecated | |
27 | interfaces. While using `__deprecated` is nice to note an old API in | |
28 | a header file, it isn't the full solution. Such interfaces must either | |
29 | be fully removed from the kernel, or added to this file to discourage | |
30 | others from using them in the future. | |
31 | ||
32 | open-coded arithmetic in allocator arguments | |
33 | -------------------------------------------- | |
34 | Dynamic size calculations (especially multiplication) should not be | |
35 | performed in memory allocator (or similar) function arguments due to the | |
36 | risk of them overflowing. This could lead to values wrapping around and a | |
37 | smaller allocation being made than the caller was expecting. Using those | |
38 | allocations could lead to linear overflows of heap memory and other | |
39 | misbehaviors. (One exception to this is literal values where the compiler | |
40 | can warn if they might overflow. Though using literals for arguments as | |
41 | suggested below is also harmless.) | |
42 | ||
43 | For example, do not use ``count * size`` as an argument, as in:: | |
44 | ||
45 | foo = kmalloc(count * size, GFP_KERNEL); | |
46 | ||
47 | Instead, the 2-factor form of the allocator should be used:: | |
48 | ||
49 | foo = kmalloc_array(count, size, GFP_KERNEL); | |
50 | ||
51 | If no 2-factor form is available, the saturate-on-overflow helpers should | |
52 | be used:: | |
53 | ||
54 | bar = vmalloc(array_size(count, size)); | |
55 | ||
56 | Another common case to avoid is calculating the size of a structure with | |
57 | a trailing array of others structures, as in:: | |
58 | ||
59 | header = kzalloc(sizeof(*header) + count * sizeof(*header->item), | |
60 | GFP_KERNEL); | |
61 | ||
62 | Instead, use the helper:: | |
63 | ||
64 | header = kzalloc(struct_size(header, item, count), GFP_KERNEL); | |
65 | ||
66 | See :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`, | |
67 | for more details as well as the related :c:func:`check_add_overflow` and | |
68 | :c:func:`check_mul_overflow` family of functions. | |
69 | ||
70 | simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() | |
71 | ---------------------------------------------------------------------- | |
72 | The :c:func:`simple_strtol`, :c:func:`simple_strtoll`, | |
73 | :c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions | |
74 | explicitly ignore overflows, which may lead to unexpected results | |
75 | in callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`, | |
76 | :c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the | |
77 | correct replacements, though note that those require the string to be | |
78 | NUL or newline terminated. | |
79 | ||
80 | strcpy() | |
81 | -------- | |
82 | :c:func:`strcpy` performs no bounds checking on the destination | |
83 | buffer. This could result in linear overflows beyond the | |
84 | end of the buffer, leading to all kinds of misbehaviors. While | |
85 | `CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the | |
86 | risk of using this function, there is no good reason to add new uses of | |
87 | this function. The safe replacement is :c:func:`strscpy`. | |
88 | ||
89 | strncpy() on NUL-terminated strings | |
90 | ----------------------------------- | |
91 | Use of :c:func:`strncpy` does not guarantee that the destination buffer | |
92 | will be NUL terminated. This can lead to various linear read overflows | |
93 | and other misbehavior due to the missing termination. It also NUL-pads the | |
94 | destination buffer if the source contents are shorter than the destination | |
95 | buffer size, which may be a needless performance penalty for callers using | |
96 | only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. | |
97 | (Users of :c:func:`strscpy` still needing NUL-padding will need an | |
98 | explicit :c:func:`memset` added.) | |
99 | ||
100 | If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can | |
101 | still be used, but destinations should be marked with the `__nonstring | |
102 | <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ | |
103 | attribute to avoid future compiler warnings. | |
104 | ||
105 | strlcpy() | |
106 | --------- | |
107 | :c:func:`strlcpy` reads the entire source buffer first, possibly exceeding | |
108 | the given limit of bytes to copy. This is inefficient and can lead to | |
109 | linear read overflows if a source string is not NUL-terminated. The | |
110 | safe replacement is :c:func:`strscpy`. | |
111 | ||
112 | Variable Length Arrays (VLAs) | |
113 | ----------------------------- | |
114 | Using stack VLAs produces much worse machine code than statically | |
115 | sized stack arrays. While these non-trivial `performance issues | |
116 | <https://git.kernel.org/linus/02361bc77888>`_ are reason enough to | |
117 | eliminate VLAs, they are also a security risk. Dynamic growth of a stack | |
118 | array may exceed the remaining memory in the stack segment. This could | |
119 | lead to a crash, possible overwriting sensitive contents at the end of the | |
120 | stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting | |
121 | memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) |