From 92067f843854be0eef1e41ff00cb465247a83c42 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sun, 28 Apr 2019 10:48:10 +1000 Subject: [PATCH] kobject: Improve docs for kobject_add/del There is currently some confusion on how to wind back kobject_init_and_add() during the error paths in code that uses this function. Add documentation to kobject_add() and kobject_del() to help clarify the usage. Signed-off-by: Tobin C. Harding Signed-off-by: Greg Kroah-Hartman --- lib/kobject.c | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/lib/kobject.c b/lib/kobject.c index ede4000..c97b572 100644 --- a/lib/kobject.c +++ b/lib/kobject.c @@ -406,15 +406,19 @@ static __printf(3, 0) int kobject_add_varg(struct kobject *kobj, * is assigned to the kobject, then the kobject will be located in the * root of the sysfs tree. * - * If this function returns an error, kobject_put() must be called to - * properly clean up the memory associated with the object. - * Under no instance should the kobject that is passed to this function - * be directly freed with a call to kfree(), that can leak memory. - * * Note, no "add" uevent will be created with this call, the caller should set * up all of the necessary sysfs files for the object and then call * kobject_uevent() with the UEVENT_ADD parameter to ensure that * userspace is properly notified of this kobject's creation. + * + * Return: If this function returns an error, kobject_put() must be + * called to properly clean up the memory associated with the + * object. Under no instance should the kobject that is passed + * to this function be directly freed with a call to kfree(), + * that can leak memory. + * + * If this call returns successfully and you later need to unwind + * kobject_add() for the error path you should call kobject_del(). */ int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...) @@ -589,6 +593,9 @@ EXPORT_SYMBOL_GPL(kobject_move); /** * kobject_del - unlink kobject from hierarchy. * @kobj: object. + * + * This is the function that should be called to delete an object + * successfully added via kobject_add(). */ void kobject_del(struct kobject *kobj) { -- 2.7.4