From 8763a30bc15b36c3bd90d6da7272d972b995f318 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Fri, 6 Jan 2023 12:06:04 -0800 Subject: 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 --- Documentation/process/deprecated.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a20..f91b8441f2ef 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); + }; + }; -- cgit v1.2.3