1SD_HWDB_GET(3)                    sd_hwdb_get                   SD_HWDB_GET(3)
2
3
4

NAME

6       sd_hwdb_get, sd_hwdb_seek, sd_hwdb_enumerate, SD_HWDB_FOREACH_PROPERTY
7       - Seek to a location in hwdb or access entries
8

SYNOPSIS

10       #include <systemd/sd-hwdb.h>
11
12       int sd_hwdb_get(sd_hwdb *hwdb, const char *modalias, const char *key,
13                       const char **value);
14
15       int sd_hwdb_seek(sd_hwdb *hwdb, const char *modalias);
16
17       int sd_hwdb_enumerate(sd_hwdb *hwdb, const char **key,
18                             const char **value);
19
20       SD_HWDB_FOREACH_PROPERTY(hwdb, modalias, key, value);
21

DESCRIPTION

23       sd_hwdb_get() queries the hwdb object created earlier with
24       sd_hwdb_new(3) for entries matching the specified string modalias, and
25       returns the value corresponding to the key key. The value is returned
26       as a NUL-terminated string in value. It must not be modified by the
27       caller and is valid as long as a reference to hwdb is kept. When
28       multiple patterns in the database match modalias, the one with the
29       highest priority is used. See hwdb(7) for details.
30
31       sd_hwdb_seek() selects entries matching the specified string modalias.
32       Subsequent queries with sd_hwdb_enumerate() will access the key-value
33       pairs for that string.
34
35       sd_hwdb_enumerate() returns (in turn) all the key-value pairs defined
36       for the string used with sd_hwdb_seek(). Each pair is returned as
37       NUL-terminated strings in key and value. The strings must not be
38       modified by the caller and are valid as long as a reference to hwdb is
39       kept. When multiple patterns in the database match modalias, the
40       combination of all matching key-value pairs is used. See hwdb(7) for
41       details.
42
43       The SD_HWDB_FOREACH_PROPERTY() macro combines sd_hwdb_seek() and
44       sd_hwdb_enumerate(). No error handling is performed and iteration
45       simply stops on error. See the example below.
46

RETURN VALUE

48       On success, sd_hwdb_get() and sd_hwdb_seek() return a non-negative
49       integer. On failure, they return a negative errno-style error code.
50
51       sd_hwdb_enumerate() returns a positive integer if another key-value
52       pair was found or zero if all entries have already been enumerated. On
53       failure, it returns a negative errno-style error code.
54
55   Errors
56       Returned errors may indicate the following problems:
57
58       -EINVAL
59           A parameter is NULL.
60
61       -ENOENT
62           An entry for the specified modalias was not found.
63
64       -EAGAIN
65           sd_hwdb_seek() was not called before sd_hwdb_enumerate().
66

NOTES

68       These APIs are implemented as a shared library, which can be compiled
69       and linked to with the libsystemd pkg-config(1) file.
70

EXAMPLES

72       Example 1. Look up hwdb entries for a USB device
73
74           /* SPDX-License-Identifier: CC0-1.0 */
75
76           #include <stdio.h>
77           #include <stdint.h>
78           #include <sd-hwdb.h>
79
80           int print_usb_properties(uint16_t vid, uint16_t pid) {
81             char match[STRLEN("usb:vp") + DECIMAL_STR_MAX(uint16_t) * 2];
82             sd_hwdb *hwdb;
83             const char *key, *value;
84             int r;
85
86             /* Match this USB vendor and product ID combination */
87             xsprintf(match, "usb:v%04Xp%04X", vid, pid);
88
89             r = sd_hwdb_new(&hwdb);
90             if (r < 0)
91               return r;
92
93             SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
94               printf("%s: \"%s\" → \"%s\"\n", match, key, value);
95
96             sd_hwdb_unref(hwdb);
97             return 0;
98           }
99
100           int main(int argc, char **argv) {
101             print_usb_properties(0x046D, 0xC534);
102             return 0;
103           }
104
105       The effect is similar to calling systemd-hwdb query usb:v046DpC534.
106

SEE ALSO

108       systemd(1), systemd-udevd.service(8), sd-hwdb(3), systemd-hwdb(8)
109
110
111
112systemd 251                                                     SD_HWDB_GET(3)
Impressum