shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-24 06:04:05 +03:00
Code

Merge pull request #15505 from keszybz/man-sd-hwdb-sd-journal

Browse Source 
Document remaining sd-journal and sd-hwdb functions
This commit is contained in:
Lennart Poettering 2020-04-21 13:37:55 +02:00 committed by GitHub
commit ede32a7cff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 454 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
man/hwdb-usb-device.c Normal file
View File

@ -0,0 +1,28 @@
#include <stdio.h>
#include <stdint.h>
#include <sd-hwdb.h>
int print_usb_properties(uint16_t vid, uint16_t pid) {
char match[15];
sd_hwdb *hwdb;
const char *key, *value;
int r;
/* Match this USB vendor and product ID combination */
snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
r = sd_hwdb_new(&hwdb);
if (r < 0)
return r;
SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
printf("%s: \"%s\" → \"%s\"\n", match, key, value);
sd_hwdb_unref(hwdb);
return 0;
}
int main(int argc, char **argv) {
print_usb_properties(0x046D, 0xC534);
return 0;
}

16
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',
@ -563,6 +564,11 @@ manpages = [
'3',
['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'],
'HAVE_PAM'],
['sd_hwdb_get',
'3',
['SD_HWDB_FOREACH_PROPERTY', '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',
@ -641,15 +647,21 @@ manpages = [
'sd_journal_open_directory',
'sd_journal_open_directory_fd',
'sd_journal_open_files',
'sd_journal_open_files_fd'],
'sd_journal_open_files_fd',
'sd_journal_open_namespace'],
''],
['sd_journal_print',
'3',
['SD_JOURNAL_SUPPRESS_LOCATION',
'sd_journal_perror',
'sd_journal_perror_with_location',
'sd_journal_print_with_location',
'sd_journal_printv',
'sd_journal_printv_with_location',
'sd_journal_send',
'sd_journal_sendv'],
'sd_journal_send_with_location',
'sd_journal_sendv',
'sd_journal_sendv_with_location'],
''],
['sd_journal_query_unique',
'3',

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>

157
man/sd_hwdb_get.xml Normal file
View File

@ -0,0 +1,157 @@
<?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>
<refname>SD_HWDB_FOREACH_PROPERTY</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>
<funcprototype>
<funcdef><function>SD_HWDB_FOREACH_PROPERTY</function></funcdef>
<paramdef>hwdb</paramdef>
<paramdef>modalias</paramdef>
<paramdef>key</paramdef>
<paramdef>value</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>
<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
performed and interation simply stops on error. See the example below.</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>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>
<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>

1
man/sd_journal_open.xml
View File

@ -22,6 +22,7 @@
<refname>sd_journal_open_directory_fd</refname>
<refname>sd_journal_open_files</refname>
<refname>sd_journal_open_files_fd</refname>
<refname>sd_journal_open_namespace</refname>
<refname>sd_journal_close</refname>
<refname>sd_journal</refname>
<refname>SD_JOURNAL_LOCAL_ONLY</refname>

88
man/sd_journal_print.xml
View File

@ -22,6 +22,12 @@
<refname>sd_journal_sendv</refname>
<refname>sd_journal_perror</refname>
<refname>SD_JOURNAL_SUPPRESS_LOCATION</refname>
<refname>sd_journal_print_with_location</refname>
<refname>sd_journal_printv_with_location</refname>
<refname>sd_journal_send_with_location</refname>
<refname>sd_journal_sendv_with_location</refname>
<refname>sd_journal_perror_with_location</refname>
<refpurpose>Submit log entries to the journal</refpurpose>
</refnamediv>
@ -60,6 +66,51 @@
<paramdef>const char *<parameter>message</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_print_with_location</function></funcdef>
<paramdef>const char *<parameter>file</parameter></paramdef>
<paramdef>const char *<parameter>line</parameter></paramdef>
<paramdef>const char *<parameter>func</parameter></paramdef>
<paramdef>int <parameter>priority</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>…</paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_printv_with_location</function></funcdef>
<paramdef>int <parameter>priority</parameter></paramdef>
<paramdef>const char *<parameter>file</parameter></paramdef>
<paramdef>const char *<parameter>line</parameter></paramdef>
<paramdef>const char *<parameter>func</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>va_list <parameter>ap</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_send_with_location</function></funcdef>
<paramdef>const char *<parameter>file</parameter></paramdef>
<paramdef>const char *<parameter>line</parameter></paramdef>
<paramdef>const char *<parameter>func</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>…</paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_sendv_with_location</function></funcdef>
<paramdef>const char *<parameter>file</parameter></paramdef>
<paramdef>const char *<parameter>line</parameter></paramdef>
<paramdef>const char *<parameter>func</parameter></paramdef>
<paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
<paramdef>int <parameter>n</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_perror_with_location</function></funcdef>
<paramdef>const char *<parameter>file</parameter></paramdef>
<paramdef>const char *<parameter>line</parameter></paramdef>
<paramdef>const char *<parameter>func</parameter></paramdef>
<paramdef>const char *<parameter>message</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@ -136,11 +187,20 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
"PRIORITY=%i", LOG_INFO,
NULL);</programlisting>
<para>Note that these calls implicitly add fields for the source
file, function name and code line where invoked. This is
implemented with macros. If this is not desired, it can be turned
off by defining SD_JOURNAL_SUPPRESS_LOCATION before including
<filename>sd-journal.h</filename>.</para>
<para>Note that these calls implicitly add fields for the source file, function name and code line where
invoked. This is implemented with macros. If this is not desired, it can be turned off by defining
<constant>SD_JOURNAL_SUPPRESS_LOCATION</constant> before including <filename>sd-journal.h</filename>.
</para>
<para><function>sd_journal_print_with_location</function>,
<function>sd_journal_printv_with_location</function>, <function>sd_journal_send_with_location</function>,
<function>sd_journal_sendv_with_location</function>, and
<function>sd_journal_perror_with_location</function> are similar to their counterparts without
<literal>_with_location</literal>, but accept additional parameters to explicitly set the source file
name, function, and line. Those arguments must contain valid journal entries including the variable name,
e.g. <literal>CODE_FILE=src/foo.c</literal>, <literal>CODE_LINE=666</literal>,
<literal>CODE_FUNC=myfunc</literal>. These variants are primarily useful when writing custom wrappers,
for example in bindings for a different language.</para>
<para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and <function>sd_journal_print()</function> may
@ -163,9 +223,9 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
<refsect1>
<title>Return Value</title>
<para>The five calls return 0 on success or a negative errno-style error code. The <citerefentry
project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> variable itself is
not altered.</para>
<para>The ten functions return 0 on success or a negative errno-style error code. The
<citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
variable itself is not altered.</para>
<para>If
<citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>
@ -178,15 +238,17 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
<xi:include href="threads-aware.xml" xpointer="safe"/>
<para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry
project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
<para><function>sd_journal_sendv()</function> and <function>sd_journal_sendv_with_location()</function>
are "async signal safe" in the meaning of
<citerefentry project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
<para><function>sd_journal_print</function>,
<function>sd_journal_printv</function>,
<function>sd_journal_send</function>, and
<function>sd_journal_perror</function> are
not async signal safe.</para>
<function>sd_journal_send</function>,
<function>sd_journal_perror</function>,
and their counterparts with <literal>_with_location</literal>
are not async signal safe.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />

1
tools/meson-check-api-docs.sh
View File

@ -12,6 +12,7 @@ deprecated="
-e sd_bus_message_get_priority
-e sd_bus_message_set_priority
-e sd_seat_can_multi_session
-e sd_journal_open_container
"
for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv $deprecated | sort -u` ; do