docs: deprecated.rst: Clean up fall-through details
Add example of fall-through, list-ify the case ending statements, and adjust the markup for links and readability. While here, adjust strscpy() details to mention strscpy_pad(). Signed-off-by: Kees Cook <keescook@chromium.org> Acked-by: Gustavo A. R. Silva <gustavo@embeddedor.com> Link: https://lore.kernel.org/r/202003041102.47A4E4B62@keescook Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
parent
6505a18e66
commit
76136e028d
|
@ -94,8 +94,8 @@ and other misbehavior due to the missing termination. It also NUL-pads the
|
||||||
destination buffer if the source contents are shorter than the destination
|
destination buffer if the source contents are shorter than the destination
|
||||||
buffer size, which may be a needless performance penalty for callers using
|
buffer size, which may be a needless performance penalty for callers using
|
||||||
only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
|
only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
|
||||||
(Users of :c:func:`strscpy` still needing NUL-padding will need an
|
(Users of :c:func:`strscpy` still needing NUL-padding should instead
|
||||||
explicit :c:func:`memset` added.)
|
use strscpy_pad().)
|
||||||
|
|
||||||
If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can
|
If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can
|
||||||
still be used, but destinations should be marked with the `__nonstring
|
still be used, but destinations should be marked with the `__nonstring
|
||||||
|
@ -144,27 +144,37 @@ memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
|
||||||
|
|
||||||
Implicit switch case fall-through
|
Implicit switch case fall-through
|
||||||
---------------------------------
|
---------------------------------
|
||||||
The C language allows switch cases to "fall-through" when a "break" statement
|
The C language allows switch cases to fall through to the next case
|
||||||
is missing at the end of a case. This, however, introduces ambiguity in the
|
when a "break" statement is missing at the end of a case. This, however,
|
||||||
code, as it's not always clear if the missing break is intentional or a bug.
|
introduces ambiguity in the code, as it's not always clear if the missing
|
||||||
|
break is intentional or a bug. For example, it's not obvious just from
|
||||||
|
looking at the code if `STATE_ONE` is intentionally designed to fall
|
||||||
|
through into `STATE_TWO`::
|
||||||
|
|
||||||
|
switch (value) {
|
||||||
|
case STATE_ONE:
|
||||||
|
do_something();
|
||||||
|
case STATE_TWO:
|
||||||
|
do_other();
|
||||||
|
break;
|
||||||
|
default:
|
||||||
|
WARN("unknown state");
|
||||||
|
}
|
||||||
|
|
||||||
As there have been a long list of flaws `due to missing "break" statements
|
As there have been a long list of flaws `due to missing "break" statements
|
||||||
<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
|
<https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow
|
||||||
"implicit fall-through".
|
implicit fall-through. In order to identify intentional fall-through
|
||||||
|
cases, we have adopted a pseudo-keyword macro "fallthrough" which
|
||||||
In order to identify intentional fall-through cases, we have adopted a
|
expands to gcc's extension `__attribute__((__fallthrough__))
|
||||||
pseudo-keyword macro 'fallthrough' which expands to gcc's extension
|
<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.
|
||||||
__attribute__((__fallthrough__)). `Statement Attributes
|
(When the C17/C18 `[[fallthrough]]` syntax is more commonly supported by
|
||||||
<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_
|
|
||||||
|
|
||||||
When the C17/C18 [[fallthrough]] syntax is more commonly supported by
|
|
||||||
C compilers, static analyzers, and IDEs, we can switch to using that syntax
|
C compilers, static analyzers, and IDEs, we can switch to using that syntax
|
||||||
for the macro pseudo-keyword.
|
for the macro pseudo-keyword.)
|
||||||
|
|
||||||
All switch/case blocks must end in one of:
|
All switch/case blocks must end in one of:
|
||||||
|
|
||||||
break;
|
* break;
|
||||||
fallthrough;
|
* fallthrough;
|
||||||
continue;
|
* continue;
|
||||||
goto <label>;
|
* goto <label>;
|
||||||
return [expression];
|
* return [expression];
|
||||||
|
|
Loading…
Reference in New Issue