kobject: Improve docs for kobject_add/del
Subsystems (2)
PATCH 1/1 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.
---
The assumption is that this is the correct usage, and that's what I've tried to document. Is this correct?
void fn(void)
{
int ret;
ret = kobject_init_and_add(kobj, ktype, NULL, "foo");
if (ret) {
kobject_put(kobj);
return -1;
}
ret = some_init_fn();
if (ret)
goto err;
ret = some_other_init_fn();
if (ret)
goto other_err;
kobject_uevent(kobj, KOBJ_ADD);
return 0;other_err:
other_clean_up_fn(); err: kobject_del(kobj); return ret; }
thanks,
Tobin.
lib/kobject.c | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-)
lib/kobject.c +12 -5
@@ -397,15 +397,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, ...)
@@ -580,6 +584,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) {
Signature · 1 line
2.21.0
Quoted 13 lines · Tobin C. Harding
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()andkobject_del()to help clarify the usage.Signed-off-by Tobin C. Harding <[email protected]>---
The assumption is that this is the correct usage, and that's what I've tried to document. Is this correct?
Quoted 8 lines
void fn(void)
{ int ret; ret = kobject_init_and_add(kobj, ktype, NULL, "foo"); if (ret) { kobject_put(kobj); return -1;
Don't make up error numbers, use a real one :)
Quoted 13 lines
} ret = some_init_fn(); if (ret) goto err; ret = some_other_init_fn(); if (ret) goto other_err; kobject_uevent(kobj, KOBJ_ADD); return 0;
Quoted 6 lines
other_err:other_clean_up_fn(); err: kobject_del(kobj); return ret; }
Yes, this looks correct.
I've queued both of these patches up now, thanks!
greg k-h