From: Kees Cook Date: Fri, 6 Jan 2023 20:06:04 +0000 (-0800) Subject: docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=8763a30bc15b;p=linux.git docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage There wasn't any mention of when/where DECLARE_FLEX_ARRAY() should be used, so add the rationale and an example to the deprecation docs. Suggested-by: Vincent Mailhol Cc: "Gustavo A. R. Silva" Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20230106200600.never.735-kees@kernel.org [jc: minor wording tweaks] Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a207..f91b8441f2ef7 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count; memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +There are two special cases of replacement where the DECLARE_FLEX_ARRAY() +helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for +use in UAPI headers.) Those cases are when the flexible array is either +alone in a struct or is part of a union. These are disallowed by the C99 +specification, but for no technical reason (as can be seen by both the +existing use of such arrays in those places and the work-around that +DECLARE_FLEX_ARRAY() uses). For example, to convert this:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +The helper must be used:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + };