2020-04-20 23:18:33 +03:00
<?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>
2020-04-21 10:07:08 +03:00
<refname > SD_HWDB_FOREACH_PROPERTY</refname>
2020-04-20 23:18:33 +03:00
<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>
2020-04-21 10:07:08 +03:00
<funcprototype >
<funcdef > <function > SD_HWDB_FOREACH_PROPERTY</function> </funcdef>
<paramdef > hwdb</paramdef>
<paramdef > modalias</paramdef>
<paramdef > key</paramdef>
<paramdef > value</paramdef>
</funcprototype>
2020-04-20 23:18:33 +03:00
</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
2020-06-30 16:24:57 +03:00
corresponding to the key <parameter > key</parameter> . The value is returned as a
2020-04-20 23:18:33 +03:00
<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>
2020-04-21 10:07:08 +03:00
<para > The <function > SD_HWDB_FOREACH_PROPERTY</function> macro combines
<function > sd_hwdb_seek()</function> and <function > sd_hwdb_enumerate()</function> . No error handling is
2020-04-21 21:46:53 +03:00
performed and iteration simply stops on error. See the example below.</para>
2020-04-20 23:18:33 +03:00
</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" />
2020-04-21 10:07:08 +03:00
<refsect1 >
<title > Examples</title>
<example >
<title > Look up hwdb entries for a USB device</title>
<programlisting > <xi:include href= "hwdb-usb-device.c" parse= "text" /> </programlisting>
<para > The effect is similar to calling <command > systemd-hwdb query usb:v046DpC534</command> .
</para>
</example>
</refsect1>
2020-04-20 23:18:33 +03:00
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2020-06-25 15:38:21 +03:00
<citerefentry > <refentrytitle > systemd-udevd.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2020-04-20 23:18:33 +03:00
<citerefentry > <refentrytitle > sd-hwdb</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd-hwdb</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
</para>
</refsect1>
</refentry>