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       Functions described here are available as a shared library, which can
69       be compiled against and linked to with the libsystemd pkg-config(1)
70       file.
71
72       The code described here uses getenv(3), which is declared to be not
73       multi-thread-safe. This means that the code calling the functions
74       described here must not call setenv(3) from a parallel thread. It is
75       recommended to only do calls to setenv() from an early phase of the
76       program when no other threads have been started.
77

EXAMPLES

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

SEE ALSO

115       systemd(1), systemd-udevd.service(8), sd-hwdb(3), systemd-hwdb(8)
116
117
118
119systemd 254                                                     SD_HWDB_GET(3)
Impressum