[PATCH 1/1] container_of: Document container_of_const() is preferred

From: Sakari Ailus
Date: Mon Jun 17 2024 - 06:09:05 EST


There is a warning in kerneldoc documentation of container_of() that
constness of @ptr is lost. While this is a suggestion container_of_const()
should be used instead, the vast majority of new code still uses
container_of():

$ git diff v6.8 v6.9|grep container_of\(|wc -l
788
$ git diff v6.8 v6.9|grep container_of_const|wc -l
11

Make an explicit recommendation to use container_of_const(), unless @ptr
is const but its container isn't.

Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
---
include/linux/container_of.h | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/include/linux/container_of.h b/include/linux/container_of.h
index 713890c867be..7563015ff165 100644
--- a/include/linux/container_of.h
+++ b/include/linux/container_of.h
@@ -13,7 +13,9 @@
* @type: the type of the container struct this is embedded in.
* @member: the name of the member within the struct.
*
- * WARNING: any const qualifier of @ptr is lost.
+ * WARNING: any const qualifier of @ptr is lost. container_of() should only be
+ * used in cases where @ptr is const and its container is not and you know what
+ * you're doing. Otherwise always use container_of_const().
*/
#define container_of(ptr, type, member) ({ \
void *__mptr = (void *)(ptr); \
--
2.39.2