HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |EXAMPLES |HISTORY |SEE ALSO |COLOPHON | |
SD_DE...PARENT(3) sd_device_enumerator_add_match_parentSD_DE...PARENT(3)sd_device_enumerator_add_match_parent, sd_device_enumerator_add_match_property, sd_device_enumerator_add_match_property_required, sd_device_enumerator_add_match_subsystem, sd_device_enumerator_add_match_sysattr, sd_device_enumerator_add_match_sysname, sd_device_enumerator_add_nomatch_sysname, sd_device_enumerator_add_match_tag, sd_device_enumerator_allow_uninitialized, sd_device_enumerator_add_all_parents - Add a filter to the device enumerator
#include <systemd/sd-device.h>intsd_device_enumerator_add_match_parent(sd_device_enumerator *enumerator,sd_device *parent);intsd_device_enumerator_add_match_property(sd_device_enumerator *enumerator,const char *property,const char *value);intsd_device_enumerator_add_match_property_required(sd_device_enumerator *enumerator,const char *property,const char *value);intsd_device_enumerator_add_match_subsystem(sd_device_enumerator *enumerator,const char *subsystem,intmatch);intsd_device_enumerator_add_match_sysattr(sd_device_enumerator *enumerator,const char *sysattr,const char *value,intmatch);intsd_device_enumerator_add_match_sysname(sd_device_enumerator *enumerator,const char *sysname);intsd_device_enumerator_add_nomatch_sysname(sd_device_enumerator *enumerator,const char *sysname);intsd_device_enumerator_add_match_tag(sd_device_enumerator *enumerator,const char *tag);intsd_device_enumerator_allow_uninitialized(sd_device_enumerator *enumerator);intsd_device_enumerator_add_all_parents(sd_device_enumerator *enumerator);
Thesd_device_enumerator_add_match_parent()function adds a filter to theenumerator so that only devices under the tree of the specifiedparent device are enumerated. If this is called multiple times the previously setparent device is cleared and only the last call takes an effect. Thesd_device_enumerator_add_match_property()function adds a filter to theenumerator so that only devices with the specifiedproperty equals to thevalue are enumerated. Bothproperty andvalue can be a glob pattern. When this is called multiple times, devices that have at least one of the specified properties with matching values are enumerated. That is, filters are ORed. Thesd_device_enumerator_add_match_property_required()function adds a filter to theenumerator so that only devices with the specifiedproperty equals to thevalue are enumerated. This function is similar tosd_device_enumerator_add_match_property(), but when this is called multiple times, devices that haveall specified properties with matching values are enumerated. That is, filters are ANDed. Thesd_device_enumerator_add_match_subsystem()function adds a filter to theenumerator so that all devices in the specifiedsubsystem, whenmatch istrue. Whenmatch isfalse, then all devices except those in the specifiedsubsystem are enumerated. When called multiple times, positive filters are ORed, and negative ones are ANDed. Thesd_device_enumerator_add_match_sysattr()function adds a filter on the sysfs attributesysattr matchingvalue.value can be a glob pattern. Ifvalue isNULL, devices that either have (ifmatch istrue) or do not have (ifmatch isfalse) the specifiedsysattr are included, regardless of its value. That is,NULLis mostly equivalent to "*". When this function is called multiple times, only devices that match all specifiedsysattr filters are enumerated. That is, these filters are ANDed. Thesd_device_enumerator_add_match_sysname()function adds a filter so that only devices whose sysname equals tosysname are enumerated.sysname can be a glob pattern. When called multiple times, filters are ORed. Thesd_device_enumerator_add_nomatch_sysname()function adds a filter so that devices whose sysname equals tosysname are excluded from the enumeration. This is useful for excluding specific devices from the enumeration process. When called multiple times, features are ANDed. Thesd_device_enumerator_add_match_tag()function adds a filter so that only devices tagged withtag are enumerated. When called multiple times, filters are ORed. Thesd_device_enumerator_allow_uninitialized()function allows devices that have not yet been initialized by udev to be included in the enumeration. Thesd_device_enumerator_add_all_parents()function enumerates all parent devices of the matching devices. This is useful for cases where you want to include all parent devices in the enumeration, such as when you are interested in the entire device tree leading up to a specific device.
All functions return0or a positive integer on success, or a negative errno-style error code on failure.Errors Returned errors may indicate the following problems:-ENOMEM Memory allocation failed.-EINVAL One of the arguments is invalid.
Example 1. Detect Removable USB Devices (Using Match and Exclude) /* SPDX-License-Identifier: MIT-0 */ #include <stdbool.h> #include <stdio.h> #include <systemd/sd-device.h> int main(void) { __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL; sd_device *device; int r; /* Create a new device enumerator */ r = sd_device_enumerator_new(&enumerator); if (r < 0) { fprintf(stderr, "Failed to create device enumerator: %s\n", strerror(-r)); return 1; } /* Include only devices from the "usb" subsystem */ r = sd_device_enumerator_add_match_subsystem(enumerator, "usb", true); if (r < 0) { fprintf(stderr, "Failed to add subsystem match: %s\n", strerror(-r)); return 1; } /* * Exclude devices where the "removable" sysattr is "0" * These are typically non-removable devices like built-in USB interfaces */ r = sd_device_enumerator_add_match_sysattr(enumerator, "removable", "0", false); if (r < 0) { fprintf(stderr, "Failed to add sysattr match: %s\n", strerror(-r)); return 1; } /* Begin enumerating matching devices */ for (device = sd_device_enumerator_get_device_first(enumerator); device; device = sd_device_enumerator_get_device_next(enumerator)) { const char *syspath; /* Get syspath for the device */ if (sd_device_get_syspath(device, &syspath) >= 0) printf("Removable USB device found: %s\n", syspath); } return 0; }sd_device_enumerator_add_match_parent(),sd_device_enumerator_add_match_property(),sd_device_enumerator_add_match_subsystem(),sd_device_enumerator_add_match_sysattr(),sd_device_enumerator_add_match_sysname(),sd_device_enumerator_add_match_tag(), andsd_device_enumerator_allow_uninitialized()were added in version 240.sd_device_enumerator_add_nomatch_sysname()was added in version 251.sd_device_enumerator_add_match_property_required()was added in version 255.sd_device_enumerator_add_all_parents()was added in version 258.
sd_device_ref(3),sd_device_enumerator_new(3),sd_device_enumerator_get_device_first(3)
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_DE...PARENT(3)Pages that refer to this page:sd_device_enumerator_get_device_first(3), sd_device_enumerator_new(3), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |