blob: b5c5b1cc6f064206c133795e466e3ea962a7894f (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="sd_hwdb_get" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_hwdb_get</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_hwdb_get</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_hwdb_get</refname>
<refname>sd_hwdb_seek</refname>
<refname>sd_hwdb_enumerate</refname>
<refpurpose>Seek to a location in hwdb or access entries</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-hwdb.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_hwdb_get</function></funcdef>
<paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
<paramdef>const char *<parameter>modalias</parameter></paramdef>
<paramdef>const char *<parameter>key</parameter></paramdef>
<paramdef>const char **<parameter>value</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_hwdb_seek</function></funcdef>
<paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
<paramdef>const char *<parameter>modalias</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_hwdb_enumerate</function></funcdef>
<paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
<paramdef>const char **<parameter>key</parameter></paramdef>
<paramdef>const char **<parameter>value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_hwdb_get()</function> queries the <parameter>hwdb</parameter> object created earlier
with <citerefentry><refentrytitle>sd_hwdb_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
entries matching the specified string <parameter>modalias</parameter>, and returns the value
corresponding to the the key <parameter>key</parameter>. The value is returned as a
<constant>NUL</constant>-terminated string in <parameter>value</parameter>. It must not be modified by
the caller and is valid as long as a reference to <parameter>hwdb</parameter> is kept. When multiple
patterns in the database match <parameter>modalias</parameter>, the one with the highest priority is
used. See <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details.</para>
<para><function>sd_hwdb_seek()</function> selects entries matching the specified string
<parameter>modalias</parameter>. Subsequent queries with <function>sd_hwdb_enumerate()</function> will
access the key-value pairs for that string.</para>
<para><function>sd_hwdb_enumerate()</function> returns (in turn) all the key-value pairs defined for the
string used with <function>sd_hwdb_seek()</function>. Each pair is returned as
<constant>NUL</constant>-terminated strings in <parameter>key</parameter> and
<parameter>value</parameter>. The strings must not be modified by the caller and are valid as long as a
reference to <parameter>hwdb</parameter> is kept. When multiple patterns in the database match
<parameter>modalias</parameter>, the combination of all matching key-value pairs is used. See
<citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_hwdb_get()</function> and <function>sd_hwdb_seek()</function> return a
non-negative integer. On failure, they return a negative errno-style error code.</para>
<para><function>sd_hwdb_enumerate()</function> 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.
</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>A parameter is <constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOENT</constant></term>
<listitem><para>An entry for the specified <parameter>modalias</parameter> was not found.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EAGAIN</constant></term>
<listitem><para><function>sd_hwdb_seek()</function> was not called before
<function>sd_hwdb_enumerate()</function>.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-udev.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
|
