2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_hwdb_get" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
8 <title>sd_hwdb_get
</title>
9 <productname>systemd
</productname>
13 <refentrytitle>sd_hwdb_get
</refentrytitle>
14 <manvolnum>3</manvolnum>
18 <refname>sd_hwdb_get
</refname>
19 <refname>sd_hwdb_seek
</refname>
20 <refname>sd_hwdb_enumerate
</refname>
21 <refname>SD_HWDB_FOREACH_PROPERTY
</refname>
23 <refpurpose>Seek to a location in hwdb or access entries
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-hwdb.h
></funcsynopsisinfo>
31 <funcdef>int
<function>sd_hwdb_get
</function></funcdef>
32 <paramdef>sd_hwdb *
<parameter>hwdb
</parameter></paramdef>
33 <paramdef>const char *
<parameter>modalias
</parameter></paramdef>
34 <paramdef>const char *
<parameter>key
</parameter></paramdef>
35 <paramdef>const char **
<parameter>value
</parameter></paramdef>
39 <funcdef>int
<function>sd_hwdb_seek
</function></funcdef>
40 <paramdef>sd_hwdb *
<parameter>hwdb
</parameter></paramdef>
41 <paramdef>const char *
<parameter>modalias
</parameter></paramdef>
45 <funcdef>int
<function>sd_hwdb_enumerate
</function></funcdef>
46 <paramdef>sd_hwdb *
<parameter>hwdb
</parameter></paramdef>
47 <paramdef>const char **
<parameter>key
</parameter></paramdef>
48 <paramdef>const char **
<parameter>value
</parameter></paramdef>
52 <funcdef><function>SD_HWDB_FOREACH_PROPERTY
</function></funcdef>
53 <paramdef>hwdb
</paramdef>
54 <paramdef>modalias
</paramdef>
55 <paramdef>key
</paramdef>
56 <paramdef>value
</paramdef>
62 <title>Description
</title>
64 <para><function>sd_hwdb_get()
</function> queries the
<parameter>hwdb
</parameter> object created earlier
65 with
<citerefentry><refentrytitle>sd_hwdb_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
66 entries matching the specified string
<parameter>modalias
</parameter>, and returns the value
67 corresponding to the the key
<parameter>key
</parameter>. The value is returned as a
68 <constant>NUL
</constant>-terminated string in
<parameter>value
</parameter>. It must not be modified by
69 the caller and is valid as long as a reference to
<parameter>hwdb
</parameter> is kept. When multiple
70 patterns in the database match
<parameter>modalias
</parameter>, the one with the highest priority is
71 used. See
<citerefentry><refentrytitle>hwdb
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
74 <para><function>sd_hwdb_seek()
</function> selects entries matching the specified string
75 <parameter>modalias
</parameter>. Subsequent queries with
<function>sd_hwdb_enumerate()
</function> will
76 access the key-value pairs for that string.
</para>
78 <para><function>sd_hwdb_enumerate()
</function> returns (in turn) all the key-value pairs defined for the
79 string used with
<function>sd_hwdb_seek()
</function>. Each pair is returned as
80 <constant>NUL
</constant>-terminated strings in
<parameter>key
</parameter> and
81 <parameter>value
</parameter>. The strings must not be modified by the caller and are valid as long as a
82 reference to
<parameter>hwdb
</parameter> is kept. When multiple patterns in the database match
83 <parameter>modalias
</parameter>, the combination of all matching key-value pairs is used. See
84 <citerefentry><refentrytitle>hwdb
</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
87 <para>The
<function>SD_HWDB_FOREACH_PROPERTY
</function> macro combines
88 <function>sd_hwdb_seek()
</function> and
<function>sd_hwdb_enumerate()
</function>. No error handling is
89 performed and iteration simply stops on error. See the example below.
</para>
93 <title>Return Value
</title>
95 <para>On success,
<function>sd_hwdb_get()
</function> and
<function>sd_hwdb_seek()
</function> return a
96 non-negative integer. On failure, they return a negative errno-style error code.
</para>
98 <para><function>sd_hwdb_enumerate()
</function> returns a positive integer if another key-value pair was found or zero if
99 all entries have already been enumerated. On failure, it returns a negative errno-style error code.
103 <title>Errors
</title>
105 <para>Returned errors may indicate the following problems:
</para>
109 <term><constant>-EINVAL
</constant></term>
111 <listitem><para>A parameter is
<constant>NULL
</constant>.
</para></listitem>
115 <term><constant>-ENOENT
</constant></term>
117 <listitem><para>An entry for the specified
<parameter>modalias
</parameter> was not found.
122 <term><constant>-EAGAIN
</constant></term>
124 <listitem><para><function>sd_hwdb_seek()
</function> was not called before
125 <function>sd_hwdb_enumerate()
</function>.
</para></listitem>
131 <xi:include href=
"libsystemd-pkgconfig.xml" />
134 <title>Examples
</title>
137 <title>Look up hwdb entries for a USB device
</title>
139 <programlisting><xi:include href=
"hwdb-usb-device.c" parse=
"text" /></programlisting>
141 <para>The effect is similar to calling
<command>systemd-hwdb query usb:v046DpC534
</command>.
147 <title>See Also
</title>
150 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
151 <citerefentry><refentrytitle>systemd-udev.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
152 <citerefentry><refentrytitle>sd-hwdb
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
153 <citerefentry><refentrytitle>systemd-hwdb
</refentrytitle><manvolnum>8</manvolnum></citerefentry>