docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage
Subsystems (2)
PATCH 1/1 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.
--- Documentation/process/deprecated.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)
Documentation/process/deprecated.rst +26 -0
@@ -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.) 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); + }; + };
Signature · 1 line
2.34.1
Jonathan Corbet
maintainerQuoted 11 lines · Kees Cook
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 <[email protected]>Cc Jonathan Corbet <[email protected]>Cc "Gustavo A. R. Silva" <[email protected]>Signed-off-by Kees Cook <[email protected]>--- Documentation/process/deprecated.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)
I've applied this, but couldn't resist making one tweak...
Documentation/process/deprecated.rst struct_size() and flex_array_size() helpers:: · line 353
Quoted 13 lines
Documentation/process/deprecated.rst +5
-0@@ -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.) When the flexible array is either alone in a struct, +or is part of a union.
The pedant in me couldn't stand leaving that sentence fragment, so I made a complete sentence out of it.
Thanks,
jon
Quoted 23 lines · Jonathan Corbet
Quoted 11 lines · Kees Cook
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 <[email protected]>Cc Jonathan Corbet <[email protected]>Cc "Gustavo A. R. Silva" <[email protected]>Signed-off-by Kees Cook <[email protected]>--- Documentation/process/deprecated.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)I've applied this, but couldn't resist making one tweak...
Quoted 7 lines
Documentation/process/deprecated.rst +0
-0@@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count;
Quoted 9 lines
Documentation/process/deprecated.rst struct_size() and flex_array_size() helpers::
Quoted 6 lines
Documentation/process/deprecated.rst +5
-0memcpy(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.) When the flexible array is either alone in a struct, +or is part of a union.The pedant in me couldn't stand leaving that sentence fragment, so I made a complete sentence out of it.
Thank you; I appreciate the help! :)
Signature · 1 line
Kees Cook