From: Shubhendra Kushwaha Date: Sat, 24 May 2025 20:01:27 +0000 (+0530) Subject: docs: add man pages for sd_device_enumerator_[new,ref,unref,unrefp] (#37586) X-Git-Tag: v258-rc1~498 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ac8ed83947237956b867de9cfbf5fcd26de8ea96;p=thirdparty%2Fsystemd.git docs: add man pages for sd_device_enumerator_[new,ref,unref,unrefp] (#37586) For #20929. --- diff --git a/man/meson.build b/man/meson.build index c12b7e6dde9..d96c1a8af00 100644 --- a/man/meson.build +++ b/man/meson.build @@ -276,6 +276,7 @@ simple_examples = files( 'sd-bus-container-read.c', 'sd_bus_error-example.c', 'sd_bus_service_reconnect.c', + 'sd_device_enumerator_new-example.c', 'send-unit-files-changed.c', 'vtable-example.c', ) diff --git a/man/rules/meson.build b/man/rules/meson.build index 048cc79430a..778b12c86a3 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -524,6 +524,12 @@ manpages = [ 'sd_bus_track_unrefp'], ''], ['sd_bus_wait', '3', [], ''], + ['sd_device_enumerator_new', + '3', + ['sd_device_enumerator_ref', + 'sd_device_enumerator_unref', + 'sd_device_enumerator_unrefp'], + ''], ['sd_device_get_syspath', '3', ['sd_device_get_device_id', diff --git a/man/sd_device_enumerator_new-example.c b/man/sd_device_enumerator_new-example.c new file mode 100644 index 00000000000..301d6039a1a --- /dev/null +++ b/man/sd_device_enumerator_new-example.c @@ -0,0 +1,22 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include + +int main(void) { + sd_device_enumerator *enumerator; + int r; + + r = sd_device_enumerator_new(&enumerator); + if (r < 0) { + fprintf(stderr, "Failed to create enumerator: %s\n", strerror(-r)); + return 1; + } + + sd_device_enumerator_ref(enumerator); + sd_device_enumerator_unref(enumerator); + + sd_device_enumerator_unref(enumerator); + + return 0; +} diff --git a/man/sd_device_enumerator_new.xml b/man/sd_device_enumerator_new.xml new file mode 100644 index 00000000000..34f52e6dbdf --- /dev/null +++ b/man/sd_device_enumerator_new.xml @@ -0,0 +1,151 @@ + + + + + + + sd_device_enumerator_new + systemd + + + + sd_device_enumerator_new + 3 + + + + sd_device_enumerator_new + sd_device_enumerator_ref + sd_device_enumerator_unref + sd_device_enumerator_unrefp + Create, reference, and release a device enumerator object + + + + + #include <systemd/sd-device.h> + + + int sd_device_enumerator_new + sd_device_enumerator **ret + + + + sd_device_enumerator* sd_device_enumerator_ref + sd_device_enumerator *enumerator + + + + sd_device_enumerator* sd_device_enumerator_unref + sd_device_enumerator *enumerator + + + + void sd_device_enumerator_unrefp + sd_device_enumerator **enumerator + + + + + + Description + The sd_device_enumerator family of functions provides a way to iterate + over devices recognized by systemd-udevd8 + . The enumerator allows filtering and matching devices by subsystem, properties and + other attributes. + + sd_device_enumerator_new() creates a new device enumerator object and + stores the result in the pointer referenced by ret. Returns 0 on success, + or a negative errno-style error code on failure. + + sd_device_enumerator_ref() increases the reference count of the + specified enumerator by one. + + sd_device_enumerator_unref() decreases the reference count of the + enumerator by one. When the reference count reaches zero, the enumerator + object is destroyed and cannot be used anymore, so further calls to sd_device_enumerator_unref() + or sd_device_enumerator_unrefp() are illegal. + + sd_device_enumerator_unrefp() is similar to + sd_device_enumerator_unref() but takes a pointer to a + pointer to an sd_device_enumerator object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as an + inline function. Use a declaration like the following, in order to + allocate a sd_device_enumerator object that is freed automatically as the code + block is left: + + { + __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL; + int r; + … + r = sd_device_enumerator_new(&enumerator); + if (r < 0) + fprintf(stderr, "Failed to allocate sd_device_enumerator: %s\n", strerror(-r)); + … +} + + sd_device_enumerator_ref() and sd_device_enumerator_unref() + execute no operation if the enumerator is NULL. + sd_device_enumerator_unrefp() will first dereference + its argument, which must not be NULL, and will execute no operation if + that is NULL. + + + + Return Value + + sd_device_enumerator_new() returns 0 on success or a negative + errno-style error code on failure. + + sd_device_enumerator_ref() always returns the enumerator pointer. + sd_device_enumerator_unref() always returns NULL. + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Memory allocation failed. + + + -EINVAL + + The argument is invalid. + + + + + + + Example + + Using sd_device_enumerator_new() + + + + + + History + sd_device_enumerator_new(), sd_device_enumerator_ref(), + sd_device_enumerator_unref(), and sd_device_enumerator_unrefp() + were added in version 240. + + + + See Also + + sd_device_ref3 + + sd_device_enumerator_add_match_parent + 3 + + + +