picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: add description of all the sd-hwdb funtions

This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2020-04-20 22:18:33 +02:00
parent 21dc5e82ad
commit ec7ea47dae
4 changed files with 313 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
man/rules/meson.build
View File

@ -107,6 +107,7 @@ manpages = [
'SD_WARNING'],
''],
['sd-event', '3', [], ''],
['sd-hwdb', '3', [], ''],
['sd-id128',
'3',
['SD_ID128_CONST_STR',
@ -559,6 +560,8 @@ manpages = [
'3',
['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'],
'HAVE_PAM'],
['sd_hwdb_get', '3', ['sd_hwdb_enumerate', 'sd_hwdb_seek'], ''],
['sd_hwdb_new', '3', ['sd_hwdb_ref', 'sd_hwdb_unref'], ''],
['sd_id128_get_machine',
'3',
['sd_id128_get_boot',

57
man/sd-hwdb.xml Normal file
View File

@ -0,0 +1,57 @@
<?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" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd-hwdb</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd-hwdb</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd-hwdb</refname>
<refpurpose>Read-only access to the hardware description database</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-hwdb.h&gt;</funcsynopsisinfo>
</funcsynopsis>
<cmdsynopsis>
<command>pkg-config --cflags --libs libsystemd</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>sd-hwdb.h</filename> allows read-only access the systemd database of hardware properties.
See <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
<citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry> for more
information about the database.</para>
<para>See <citerefentry><refentrytitle>sd_hwdb_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and <citerefentry><refentrytitle>sd_hwdb_get</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
information about the functions available.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

132
man/sd_hwdb_get.xml Normal file
View File

@ -0,0 +1,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 &lt;systemd/sd-hwdb.h&gt;</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>

121
man/sd_hwdb_new.xml Normal file
View File

@ -0,0 +1,121 @@
<?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_new" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_hwdb_new</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_hwdb_new</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_hwdb_new</refname>
<refname>sd_hwdb_ref</refname>
<refname>sd_hwdb_unref</refname>
<refpurpose>Create a new hwdb object and create or destroy references to it</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-hwdb.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_hwdb_new</function></funcdef>
<paramdef>sd_hwdb **<parameter>hwdb</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_hwdb* <function>sd_hwdb_ref</function></funcdef>
<paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_hwdb* <function>sd_hwdb_unref</function></funcdef>
<paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_hwdb_new()</function> creates a new hwdb object to access the binary hwdb
database. Upon initialization, the file containing the binary representation of the hardware database is
located and opened. The new object is returned in <parameter>hwdb</parameter>.</para>
<para>The <parameter>hwdb</parameter> object is reference counted. <function>sd_hwdb_ref()</function> and
<function>sd_hwdb_unref()</function> may be used to get a new reference or destroy an existing reference
to an object. The caller must dispose of the reference acquired with <function>sd_hwdb_new()</function>
by calling <function>sd_hwdb_unref()</function> when done with the object.</para>
<para>Use
<citerefentry><refentrytitle>sd_hwdb_seek</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_hwdb_get</refentrytitle><manvolnum>3</manvolnum></citerefentry>, and
<citerefentry><refentrytitle>sd_hwdb_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
access entries.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_hwdb_new()</function> returns a non-negative integer. On
failure, it returns a negative errno-style error code.</para>
<para><function>sd_hwdb_ref()</function> always returns the argument.
</para>
<para><function>sd_hwdb_unref()</function> always returns <constant>NULL</constant>.
</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ENOENT</constant></term>
<listitem><para>The binary hardware database file could not be located. See
<citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>The located binary hardware database file is in an incompatible format.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</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>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>