From ec7ea47dae738b7bd0d52ac4bd5e3e652cea4d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 20 Apr 2020 22:18:33 +0200 Subject: [PATCH] man: add description of all the sd-hwdb funtions --- man/rules/meson.build | 3 + man/sd-hwdb.xml | 57 ++++++++++++++++++ man/sd_hwdb_get.xml | 132 ++++++++++++++++++++++++++++++++++++++++++ man/sd_hwdb_new.xml | 121 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 313 insertions(+) create mode 100644 man/sd-hwdb.xml create mode 100644 man/sd_hwdb_get.xml create mode 100644 man/sd_hwdb_new.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index ef11525ef2..d3457e7ccc 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -107,6 +107,7 @@ manpages = [ 'SD_WARNING'], ''], ['sd-event', '3', [], ''], + ['sd-hwdb', '3', [], ''], ['sd-id128', '3', ['SD_ID128_CONST_STR', @@ -559,6 +560,8 @@ manpages = [ '3', ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'], 'HAVE_PAM'], + ['sd_hwdb_get', '3', ['sd_hwdb_enumerate', 'sd_hwdb_seek'], ''], + ['sd_hwdb_new', '3', ['sd_hwdb_ref', 'sd_hwdb_unref'], ''], ['sd_id128_get_machine', '3', ['sd_id128_get_boot', diff --git a/man/sd-hwdb.xml b/man/sd-hwdb.xml new file mode 100644 index 0000000000..13552e5846 --- /dev/null +++ b/man/sd-hwdb.xml @@ -0,0 +1,57 @@ + + + + + + + + sd-hwdb + systemd + + + + sd-hwdb + 3 + + + + sd-hwdb + Read-only access to the hardware description database + + + + + #include <systemd/sd-hwdb.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-hwdb.h allows read-only access the systemd database of hardware properties. + See hwdb7 and + systemd-hwdb8 for more + information about the database. + + See sd_hwdb_new3 + and sd_hwdb_get3 for + information about the functions available. + + + + + + See Also + + systemd1, + systemd-udevd.service8 + + + + diff --git a/man/sd_hwdb_get.xml b/man/sd_hwdb_get.xml new file mode 100644 index 0000000000..b5c5b1cc6f --- /dev/null +++ b/man/sd_hwdb_get.xml @@ -0,0 +1,132 @@ + + + + + + + sd_hwdb_get + systemd + + + + sd_hwdb_get + 3 + + + + sd_hwdb_get + sd_hwdb_seek + sd_hwdb_enumerate + + Seek to a location in hwdb or access entries + + + + + #include <systemd/sd-hwdb.h> + + + int sd_hwdb_get + sd_hwdb *hwdb + const char *modalias + const char *key + const char **value + + + + int sd_hwdb_seek + sd_hwdb *hwdb + const char *modalias + + + + int sd_hwdb_enumerate + sd_hwdb *hwdb + const char **key + const char **value + + + + + + + Description + + sd_hwdb_get() queries the hwdb object created earlier + with sd_hwdb_new3 for + entries matching the specified string modalias, and returns the value + corresponding to the the key key. The value is returned as a + NUL-terminated string in value. It must not be modified by + the caller and is valid as long as a reference to hwdb is kept. When multiple + patterns in the database match modalias, the one with the highest priority is + used. See hwdb7 for + details. + + sd_hwdb_seek() selects entries matching the specified string + modalias. Subsequent queries with sd_hwdb_enumerate() will + access the key-value pairs for that string. + + sd_hwdb_enumerate() returns (in turn) all the key-value pairs defined for the + string used with sd_hwdb_seek(). Each pair is returned as + NUL-terminated strings in key and + value. The strings must not be modified by the caller and are valid as long as a + reference to hwdb is kept. When multiple patterns in the database match + modalias, the combination of all matching key-value pairs is used. See + hwdb7 for + details. + + + + Return Value + + On success, sd_hwdb_get() and sd_hwdb_seek() return a + non-negative integer. On failure, they return a negative errno-style error code. + + sd_hwdb_enumerate() returns a positive integer if another key-value pair was found or zero if + all entries have already been enumerated. On failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + A parameter is NULL. + + + + -ENOENT + + An entry for the specified modalias was not found. + + + + + -EAGAIN + + sd_hwdb_seek() was not called before + sd_hwdb_enumerate(). + + + + + + + + + See Also + + + systemd1, + systemd-udev.service8, + sd-hwdb3, + systemd-hwdb8 + + + + diff --git a/man/sd_hwdb_new.xml b/man/sd_hwdb_new.xml new file mode 100644 index 0000000000..257b347b9b --- /dev/null +++ b/man/sd_hwdb_new.xml @@ -0,0 +1,121 @@ + + + + + + + sd_hwdb_new + systemd + + + + sd_hwdb_new + 3 + + + + sd_hwdb_new + sd_hwdb_ref + sd_hwdb_unref + + Create a new hwdb object and create or destroy references to it + + + + + #include <systemd/sd-hwdb.h> + + + int sd_hwdb_new + sd_hwdb **hwdb + + + + sd_hwdb* sd_hwdb_ref + sd_hwdb *hwdb + + + + sd_hwdb* sd_hwdb_unref + sd_hwdb *hwdb + + + + + + Description + + sd_hwdb_new() creates a new hwdb object to access the binary hwdb + database. Upon initialization, the file containing the binary representation of the hardware database is + located and opened. The new object is returned in hwdb. + + The hwdb object is reference counted. sd_hwdb_ref() and + sd_hwdb_unref() may be used to get a new reference or destroy an existing reference + to an object. The caller must dispose of the reference acquired with sd_hwdb_new() + by calling sd_hwdb_unref() when done with the object. + + Use + sd_hwdb_seek3, + sd_hwdb_get3, and + sd_hwdb_enumerate3 to + access entries. + + + + Return Value + + On success, sd_hwdb_new() returns a non-negative integer. On + failure, it returns a negative errno-style error code. + + sd_hwdb_ref() always returns the argument. + + + sd_hwdb_unref() always returns NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOENT + + The binary hardware database file could not be located. See + systemd-hwdb8 + for more information. + + + + + -EINVAL + + The located binary hardware database file is in an incompatible format. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + + + + See Also + + + systemd1, + systemd-udev.service8, + sd-hwdb3, + systemd-hwdb3 + + + +