docs: deprecated.rst: Clean up fall-through details
Subsystems (2)
PATCH 1/1 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().
--- Documentation/process/deprecated.rst | 48 +++++++++++++++++----------- 1 file changed, 29 insertions(+), 19 deletions(-)
Documentation/process/deprecated.rst +29 -19
@@ -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 buffer size, which may be a needless performance penalty for callers using only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. -(Users of :c:func:`strscpy` still needing NUL-padding will need an -explicit :c:func:`memset` added.) +(Users of :c:func:`strscpy` still needing NUL-padding should instead +use strscpy_pad().) If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can still be used, but destinations should be marked with the `__nonstring
@@ -122,27 +122,37 @@ memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) Implicit switch case fall-through --------------------------------- -The C language allows switch cases to "fall-through" when a "break" statement -is missing at the end of a case. This, however, introduces ambiguity in the -code, as it's not always clear if the missing break is intentional or a bug. +The C language allows switch cases to fall through to the next case +when a "break" statement is missing at the end of a case. This, however, +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 <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow -"implicit fall-through". - -In order to identify intentional fall-through cases, we have adopted a -pseudo-keyword macro 'fallthrough' which expands to gcc's extension -__attribute__((__fallthrough__)). `Statement Attributes -<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_ - -When the C17/C18 [[fallthrough]] syntax is more commonly supported by +implicit fall-through. In order to identify intentional fall-through +cases, we have adopted a pseudo-keyword macro "fallthrough" which +expands to gcc's extension `__attribute__((__fallthrough__)) +<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 -for the macro pseudo-keyword. +for the macro pseudo-keyword.) All switch/case blocks must end in one of: - break; - fallthrough; - continue; - goto <label>; - return [expression]; +* break; +* fallthrough; +* continue; +* goto <label>; +* return [expression];
Signature · 5 lines
2.20.1 -- Kees Cook
Quoted 5 lines · Kees Cook
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 mentionstrscpy_pad().Signed-off-by Kees Cook <[email protected]>
Quoted 75 lines
--- Documentation/process/deprecated.rst | 48 +++++++++++++++++----------- 1 file changed, 29 insertions(+), 19 deletions(-)Documentation/process/deprecated.rst +29
-19@@ -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 buffer size, which may be a needless performance penalty for callers using only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. -(Users of :c:func:`strscpy` still needing NUL-padding will need an -explicit :c:func:`memset` added.) +(Users of :c:func:`strscpy` still needing NUL-padding should instead +use strscpy_pad().) If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can still be used, but destinations should be marked with the `__nonstring@@ -122,27 +122,37 @@ memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) Implicit switch case fall-through --------------------------------- -The C language allows switch cases to "fall-through" when a "break" statement -is missing at the end of a case. This, however, introduces ambiguity in the -code, as it's not always clear if the missing break is intentional or a bug. +The C language allows switch cases to fall through to the next case +when a "break" statement is missing at the end of a case. This, however, +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 <https://cwe.mitre.org/data/definitions/484.html>`_, we no longer allow -"implicit fall-through". - -In order to identify intentional fall-through cases, we have adopted a -pseudo-keyword macro 'fallthrough' which expands to gcc's extension -__attribute__((__fallthrough__)). `Statement Attributes -<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_ - -When the C17/C18 [[fallthrough]] syntax is more commonly supported by +implicit fall-through. In order to identify intentional fall-through +cases, we have adopted a pseudo-keyword macro "fallthrough" which +expands to gcc's extension `__attribute__((__fallthrough__)) +<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 -for the macro pseudo-keyword. +for the macro pseudo-keyword.) All switch/case blocks must end in one of: - break; - fallthrough; - continue; - goto <label>; - return [expression]; +* break; +* fallthrough; +* continue; +* goto <label>; +* return [expression];
Quoted 5 lines · On Wed, 4 Mar 2020 11:03:24 -0800 Kees Cook <[email protected]> wrote:
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 mentionstrscpy_pad().Signed-off-by Kees Cook <[email protected]>
Applied, thanks. But ...
Quoted 9 lines
--- Documentation/process/deprecated.rst | 48 +++++++++++++++++----------- 1 file changed, 29 insertions(+), 19 deletions(-)Documentation/process/deprecated.rst +0
-0
Documentation/process/deprecated.rst and other misbehavior due to the missing termination. It also NUL-pads the · line 98
Quoted 7 lines
Documentation/process/deprecated.rst +2
-2@@ -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 buffer size, which may be a needless performance penalty for callers using only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. -(Users of :c:func:`strscpy` still needing NUL-padding will need an -explicit :c:func:`memset` added.) +(Users of :c:func:`strscpy` still needing NUL-padding should instead +use strscpy_pad().)
:c:func: usage should really be stomped on when we encounter it. There's a few in this file; I'll tack on a quick patch making them go away.
jon
Quoted 15 lines · Jonathan Corbet
Quoted 5 lines · On Wed, 4 Mar 2020 11:03:24 -0800 Kees Cook <[email protected]> wrote:
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 mentionstrscpy_pad().Signed-off-by Kees Cook <[email protected]>Applied, thanks. But ...
Quoted 4 lines
--- Documentation/process/deprecated.rst | 48 +++++++++++++++++----------- 1 file changed, 29 insertions(+), 19 deletions(-)
Quoted 15 lines
Documentation/process/deprecated.rst and other misbehavior due to the missing termination. It also NUL-pads the · line 98
Quoted 12 lines
Documentation/process/deprecated.rst +2
-2@@ -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 buffer size, which may be a needless performance penalty for callers using only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. -(Users of :c:func:`strscpy` still needing NUL-padding will need an -explicit :c:func:`memset` added.) +(Users of :c:func:`strscpy` still needing NUL-padding should instead +use strscpy_pad().):c:func: usage should really be stomped on when we encounter it. There's a few in this file; I'll tack on a quick patch making them go away.
Oops, yes, I meant to do another pass for that. I will double-check future patches!
Signature · 1 line
Kees Cook