## udev_enumerate

udev_enumerate — lookup and sort sys devices

## Synopsis

    struct              udev_enumerate;
    struct udev_enumerate * udev_enumerate_ref              (struct udev_enumerate *udev_enumerate);
    void                udev_enumerate_unref                (struct udev_enumerate *udev_enumerate);
    struct udev *       udev_enumerate_get_udev             (struct udev_enumerate *udev_enumerate);
    struct udev_enumerate * udev_enumerate_new              (struct udev *udev);
    int                 udev_enumerate_add_match_subsystem  (struct udev_enumerate *udev_enumerate,
                                                             const char *subsystem);
    int                 udev_enumerate_add_nomatch_subsystem
                                                            (struct udev_enumerate *udev_enumerate,
                                                             const char *subsystem);
    int                 udev_enumerate_add_match_sysattr    (struct udev_enumerate *udev_enumerate,
                                                             const char *sysattr,
                                                             const char *value);
    int                 udev_enumerate_add_nomatch_sysattr  (struct udev_enumerate *udev_enumerate,
                                                             const char *sysattr,
                                                             const char *value);
    int                 udev_enumerate_add_match_property   (struct udev_enumerate *udev_enumerate,
                                                             const char *property,
                                                             const char *value);
    int                 udev_enumerate_add_match_tag        (struct udev_enumerate *udev_enumerate,
                                                             const char *tag);
    int                 udev_enumerate_add_match_parent     (struct udev_enumerate *udev_enumerate,
                                                             struct udev_device *parent);
    int                 udev_enumerate_add_match_is_initialized
                                                            (struct udev_enumerate *udev_enumerate);
    int                 udev_enumerate_add_match_sysname    (struct udev_enumerate *udev_enumerate,
                                                             const char *sysname);
    int                 udev_enumerate_add_syspath          (struct udev_enumerate *udev_enumerate,
                                                             const char *syspath);
    int                 udev_enumerate_scan_devices         (struct udev_enumerate *udev_enumerate);
    int                 udev_enumerate_scan_subsystems      (struct udev_enumerate *udev_enumerate);
    struct udev_list_entry * udev_enumerate_get_list_entry  (struct udev_enumerate *udev_enumerate);

## Description

Lookup devices in the sys filesystem, filter devices by properties, and return a sorted list of devices.

## Details

### struct udev_enumerate

    struct udev_enumerate;

Opaque object representing one device lookup/sort context.

### udev_enumerate_ref ()

    struct udev_enumerate * udev_enumerate_ref              (struct udev_enumerate *udev_enumerate);

Take a reference of a enumeration context.

`udev_enumerate` : | context
Returns : | the passed enumeration context

### udev_enumerate_unref ()

    void                udev_enumerate_unref                (struct udev_enumerate *udev_enumerate);

Drop a reference of an enumeration context. If the refcount reaches zero, all resources of the enumeration context will be released.

`udev_enumerate` : | context

### udev_enumerate_get_udev ()

    struct udev *       udev_enumerate_get_udev             (struct udev_enumerate *udev_enumerate);

`udev_enumerate` : | context
Returns : | the udev library context.

### udev_enumerate_new ()

    struct udev_enumerate * udev_enumerate_new              (struct udev *udev);

`udev` : | udev library context
Returns : | an enumeration context

### udev_enumerate_add_match_subsystem ()

    int                 udev_enumerate_add_match_subsystem  (struct udev_enumerate *udev_enumerate,
                                                             const char *subsystem);

`udev_enumerate` : | context
`subsystem` : | filter for a subsystem of the device to include in the list
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_nomatch_subsystem ()

    int                 udev_enumerate_add_nomatch_subsystem
                                                            (struct udev_enumerate *udev_enumerate,
                                                             const char *subsystem);

`udev_enumerate` : | context
`subsystem` : | filter for a subsystem of the device to exclude from the list
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_sysattr ()

    int                 udev_enumerate_add_match_sysattr    (struct udev_enumerate *udev_enumerate,
                                                             const char *sysattr,
                                                             const char *value);

`udev_enumerate` : | context
`sysattr` : | filter for a sys attribute at the device to include in the list
`value` : | optional value of the sys attribute
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_nomatch_sysattr ()

    int                 udev_enumerate_add_nomatch_sysattr  (struct udev_enumerate *udev_enumerate,
                                                             const char *sysattr,
                                                             const char *value);

`udev_enumerate` : | context
`sysattr` : | filter for a sys attribute at the device to exclude from the list
`value` : | optional value of the sys attribute
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_property ()

    int                 udev_enumerate_add_match_property   (struct udev_enumerate *udev_enumerate,
                                                             const char *property,
                                                             const char *value);

`udev_enumerate` : | context
`property` : | filter for a property of the device to include in the list
`value` : | value of the property
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_tag ()

    int                 udev_enumerate_add_match_tag        (struct udev_enumerate *udev_enumerate,
                                                             const char *tag);

`udev_enumerate` : | context
`tag` : | filter for a tag of the device to include in the list
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_parent ()

    int                 udev_enumerate_add_match_parent     (struct udev_enumerate *udev_enumerate,
                                                             struct udev_device *parent);

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.

`udev_enumerate` : | context
`parent` : | parent device where to start searching
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_is_initialized ()

    int                 udev_enumerate_add_match_is_initialized
                                                            (struct udev_enumerate *udev_enumerate);

Match only devices which udev has set up already. This makes sure, that the device node permissions and context are properly set and that network devices are fully renamed.

Usually, devices which are found in the kernel but not already handled by udev, have still pending events. Services should subscribe to monitor events and wait for these devices to become ready, instead of using uninitialized devices.

For now, this will not affect devices which do not have a device node and are not network interfaces.

`udev_enumerate` : | context
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_match_sysname ()

    int                 udev_enumerate_add_match_sysname    (struct udev_enumerate *udev_enumerate,
                                                             const char *sysname);

`udev_enumerate` : | context
`sysname` : | filter for the name of the device to include in the list
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_add_syspath ()

    int                 udev_enumerate_add_syspath          (struct udev_enumerate *udev_enumerate,
                                                             const char *syspath);

Add a device to the list of devices, to retrieve it back sorted in dependency order.

`udev_enumerate` : | context
`syspath` : | path of a device
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_scan_devices ()

    int                 udev_enumerate_scan_devices         (struct udev_enumerate *udev_enumerate);

`udev_enumerate` : | udev enumeration context
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_scan_subsystems ()

    int                 udev_enumerate_scan_subsystems      (struct udev_enumerate *udev_enumerate);

`udev_enumerate` : | udev enumeration context
Returns : | 0 on success, otherwise a negative error value.

### udev_enumerate_get_list_entry ()

    struct udev_list_entry * udev_enumerate_get_list_entry  (struct udev_enumerate *udev_enumerate);

`udev_enumerate` : | context
Returns : | the first entry of the sorted list of device paths.