libudev: enumerate - clarify documentation

[elogind.git] / libudev / libudev-enumerate.c

diff --git a/libudev/libudev-enumerate.c b/libudev/libudev-enumerate.c
index 320ab66647d523bab91e1361dacc3aff77f84945..b332ecdae136f065841aa2bd27ba28237ebd9227 100644 (file)
--- a/libudev/libudev-enumerate.c
+++ b/libudev/libudev-enumerate.c
@@ -464,9 +464,10 @@ UDEV_EXPORT int udev_enumerate_add_match_tag(struct udev_enumerate *udev_enumera
 /**
  * udev_enumerate_add_match_parent:
  * @udev_enumerate: context
- * @parent: filter for the parent device
+ * @parent: parent device where to start searching
  *
- * Return only the children of a given device.
+ * Return the devices on the subtree of one given device. The parent
+ * itself is included in the list.
  *
  * A reference for the device is held until the udev_enumerate context
  * is cleaned up.
@@ -862,6 +863,15 @@ static int parent_crawl_children(struct udev_enumerate *enumerate, const char *p
        return 0;
 }
 
+static int scan_devices_children(struct udev_enumerate *enumerate)
+{
+       const char *path;
+
+       path = udev_device_get_syspath(enumerate->parent_match);
+       parent_add_child(enumerate, path);
+       return parent_crawl_children(enumerate, path, 256);
+}
+
 static int scan_devices_all(struct udev_enumerate *udev_enumerate)
 {
        struct udev *udev = udev_enumerate_get_udev(udev_enumerate);
@@ -893,12 +903,15 @@ UDEV_EXPORT int udev_enumerate_scan_devices(struct udev_enumerate *udev_enumerat
        if (udev_enumerate == NULL)
                return -EINVAL;
 
+       /* efficiently lookup tags only, we maintain a reverse-index */
        if (udev_list_get_entry(&udev_enumerate->tags_match_list) != NULL)
                return scan_devices_tags(udev_enumerate);
 
+       /* walk the subtree of one parent device only */
        if (udev_enumerate->parent_match != NULL)
-               return parent_crawl_children(udev_enumerate, udev_device_get_syspath(udev_enumerate->parent_match), 256);
+               return scan_devices_children(udev_enumerate);
 
+       /* scan devices of all subsystems */
        return scan_devices_all(udev_enumerate);
 }