Debian Codegraph @

upstream/debian-unstable/man3/sd_hwdb_get.3

raw
1 '\" t
2 .TH "SD_HWDB_GET" "3" "" "systemd 261~rc3" "sd_hwdb_get"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_hwdb_get, sd_hwdb_seek, sd_hwdb_enumerate, SD_HWDB_FOREACH_PROPERTY \- Seek to a location in hwdb or access entries
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-hwdb\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_hwdb_get('u
32 .BI "int sd_hwdb_get(sd_hwdb\ *" "hwdb" ", const\ char\ *" "modalias" ", const\ char\ *" "key" ", const\ char\ **" "value" ");"
33 .HP \w'int\ sd_hwdb_seek('u
34 .BI "int sd_hwdb_seek(sd_hwdb\ *" "hwdb" ", const\ char\ *" "modalias" ");"
35 .HP \w'int\ sd_hwdb_enumerate('u
36 .BI "int sd_hwdb_enumerate(sd_hwdb\ *" "hwdb" ", const\ char\ **" "key" ", const\ char\ **" "value" ");"
37 .HP \w'SD_HWDB_FOREACH_PROPERTY('u
38 .BI "SD_HWDB_FOREACH_PROPERTY(hwdb, modalias, key, value);"
39 .SH "DESCRIPTION"
40 .PP
41 \fBsd_hwdb_get()\fR
42 queries the
43 \fIhwdb\fR
44 object created earlier with
45 \fBsd_hwdb_new\fR(3)
46 for entries matching the specified string
47 \fImodalias\fR, and returns the value corresponding to the key
48 \fIkey\fR\&. The value is returned as a
49 \fBNUL\fR\-terminated string in
50 \fIvalue\fR\&. It must not be modified by the caller and is valid as long as a reference to
51 \fIhwdb\fR
52 is kept\&. When multiple patterns in the database match
53 \fImodalias\fR, the one with the highest priority is used\&. See
54 \fBhwdb\fR(7)
55 for details\&.
56 .PP
57 \fBsd_hwdb_seek()\fR
58 selects entries matching the specified string
59 \fImodalias\fR\&. Subsequent queries with
60 \fBsd_hwdb_enumerate()\fR
61 will access the key\-value pairs for that string\&.
62 .PP
63 \fBsd_hwdb_enumerate()\fR
64 returns (in turn) all the key\-value pairs defined for the string used with
65 \fBsd_hwdb_seek()\fR\&. Each pair is returned as
66 \fBNUL\fR\-terminated strings in
67 \fIkey\fR
68 and
69 \fIvalue\fR\&. The strings must not be modified by the caller and are valid as long as a reference to
70 \fIhwdb\fR
71 is kept\&. When multiple patterns in the database match
72 \fImodalias\fR, the combination of all matching key\-value pairs is used\&. See
73 \fBhwdb\fR(7)
74 for details\&.
75 .PP
76 The
77 \fBSD_HWDB_FOREACH_PROPERTY()\fR
78 macro combines
79 \fBsd_hwdb_seek()\fR
80 and
81 \fBsd_hwdb_enumerate()\fR\&. No error handling is performed and iteration simply stops on error\&. See the example below\&.
82 .SH "RETURN VALUE"
83 .PP
84 On success,
85 \fBsd_hwdb_get()\fR
86 and
87 \fBsd_hwdb_seek()\fR
88 return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
89 .PP
90 \fBsd_hwdb_enumerate()\fR
91 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\&.
92 .SS "Errors"
93 .PP
94 Returned errors may indicate the following problems:
95 .PP
96 \fB\-EINVAL\fR
97 .RS 4
98 A parameter is
99 \fBNULL\fR\&.
100 .sp
101 Added in version 246\&.
102 .RE
103 .PP
104 \fB\-ENOENT\fR
105 .RS 4
106 An entry for the specified
107 \fImodalias\fR
108 was not found\&.
109 .sp
110 Added in version 246\&.
111 .RE
112 .PP
113 \fB\-EAGAIN\fR
114 .RS 4
115 \fBsd_hwdb_seek()\fR
116 was not called before
117 \fBsd_hwdb_enumerate()\fR\&.
118 .sp
119 Added in version 246\&.
120 .RE
121 .SH "NOTES"
122 .PP
123 Functions described here are available as a shared library, which can be compiled against and linked to with the
124 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
125 file\&.
126 .PP
127 The code described here uses
128 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
129 \fBsetenv\fR(3)
130 from a parallel thread\&. It is recommended to only do calls to
131 \fBsetenv()\fR
132 from an early phase of the program when no other threads have been started\&.
133 .SH "EXAMPLES"
134 .PP
135 \fBExample\ \&1.\ \&Look up hwdb entries for a USB device\fR
136 .sp
137 .if n \{\
138 .RS 4
139 .\}
140 .nf
141 /* SPDX\-License\-Identifier: MIT\-0 */
142
143 #define _GNU_SOURCE 1
144 #include <stdio\&.h>
145 #include <stdint\&.h>
146 #include <systemd/sd\-hwdb\&.h>
147
148 int print_usb_properties(uint16_t vid, uint16_t pid) {
149 char match[128];
150 sd_hwdb *hwdb;
151 const char *key, *value;
152 int r;
153
154 /* Match this USB vendor and product ID combination */
155 snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
156
157 r = sd_hwdb_new(&hwdb);
158 if (r < 0)
159 return r;
160
161 SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
162 printf("%s: \e"%s\e" → \e"%s\e"\en", match, key, value);
163
164 sd_hwdb_unref(hwdb);
165 return 0;
166 }
167
168 int main(int argc, char **argv) {
169 print_usb_properties(0x046D, 0xC534);
170 return 0;
171 }
172 .fi
173 .if n \{\
174 .RE
175 .\}
176 .PP
177 The effect is similar to calling
178 \fBsystemd\-hwdb query usb:v046DpC534\fR\&.
179 .SH "HISTORY"
180 .PP
181 \fBsd_hwdb_get()\fR,
182 \fBsd_hwdb_seek()\fR,
183 \fBsd_hwdb_enumerate()\fR, and
184 \fBSD_HWDB_FOREACH_PROPERTY()\fR
185 were added in version 246\&.
186 .SH "SEE ALSO"
187 .PP
188 \fBsystemd\fR(1), \fBsystemd-udevd.service\fR(8), \fBsd-hwdb\fR(3), \fBsystemd-hwdb\fR(8)