summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorTobin C. Harding <tobin@kernel.org>2019-04-28 10:48:10 +1000
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>2019-04-28 18:16:03 +0200
commit92067f843854be0eef1e41ff00cb465247a83c42 (patch)
tree42612775c8cbaa4be86fee361f34a6b25de8ca7b /lib
parentedb16da34b084c66763f29bee42b4e6bb33c3d66 (diff)
downloadlinux-92067f843854be0eef1e41ff00cb465247a83c42.tar.bz2
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 <tobin@kernel.org> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'lib')
-rw-r--r--lib/kobject.c17
1 files changed, 12 insertions, 5 deletions
diff --git a/lib/kobject.c b/lib/kobject.c
index ede40005db28..c97b5729f94d 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)
{