man: document some sd-bus functions (#3567)
* sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
This commit is contained in:
mahkoh
Lennart Poettering
parent
7351ded5b9
commit
e382c49f1d
|
|
@ -31,11 +31,13 @@ MANPAGES += \
|
|||
man/sd-id128.3 \
|
||||
man/sd-journal.3 \
|
||||
man/sd_booted.3 \
|
||||
man/sd_bus_add_match.3 \
|
||||
man/sd_bus_creds_get_pid.3 \
|
||||
man/sd_bus_creds_new_from_pid.3 \
|
||||
man/sd_bus_default.3 \
|
||||
man/sd_bus_error.3 \
|
||||
man/sd_bus_error_add_map.3 \
|
||||
man/sd_bus_get_fd.3 \
|
||||
man/sd_bus_message_append.3 \
|
||||
man/sd_bus_message_append_array.3 \
|
||||
man/sd_bus_message_append_basic.3 \
|
||||
|
|
@ -43,9 +45,11 @@ MANPAGES += \
|
|||
man/sd_bus_message_append_strv.3 \
|
||||
man/sd_bus_message_get_cookie.3 \
|
||||
man/sd_bus_message_get_monotonic_usec.3 \
|
||||
man/sd_bus_message_read_basic.3 \
|
||||
man/sd_bus_negotiate_fds.3 \
|
||||
man/sd_bus_new.3 \
|
||||
man/sd_bus_path_encode.3 \
|
||||
man/sd_bus_process.3 \
|
||||
man/sd_bus_request_name.3 \
|
||||
man/sd_event_add_child.3 \
|
||||
man/sd_event_add_defer.3 \
|
||||
|
|
@ -2522,11 +2526,13 @@ EXTRA_DIST += \
|
|||
man/sd-journal.xml \
|
||||
man/sd-login.xml \
|
||||
man/sd_booted.xml \
|
||||
man/sd_bus_add_match.xml \
|
||||
man/sd_bus_creds_get_pid.xml \
|
||||
man/sd_bus_creds_new_from_pid.xml \
|
||||
man/sd_bus_default.xml \
|
||||
man/sd_bus_error.xml \
|
||||
man/sd_bus_error_add_map.xml \
|
||||
man/sd_bus_get_fd.xml \
|
||||
man/sd_bus_message_append.xml \
|
||||
man/sd_bus_message_append_array.xml \
|
||||
man/sd_bus_message_append_basic.xml \
|
||||
|
|
@ -2534,9 +2540,11 @@ EXTRA_DIST += \
|
|||
man/sd_bus_message_append_strv.xml \
|
||||
man/sd_bus_message_get_cookie.xml \
|
||||
man/sd_bus_message_get_monotonic_usec.xml \
|
||||
man/sd_bus_message_read_basic.xml \
|
||||
man/sd_bus_negotiate_fds.xml \
|
||||
man/sd_bus_new.xml \
|
||||
man/sd_bus_path_encode.xml \
|
||||
man/sd_bus_process.xml \
|
||||
man/sd_bus_request_name.xml \
|
||||
man/sd_event_add_child.xml \
|
||||
man/sd_event_add_defer.xml \
|
||||
|
|
|
|||
|
|
@ -0,0 +1,119 @@
|
|||
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2016 Julian Orth
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="sd_bus_add_match">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_add_match</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Julian</firstname>
|
||||
<surname>Orth</surname>
|
||||
<email>ju.orth@gmail.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_add_match</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_add_match</refname>
|
||||
|
||||
<refpurpose>Add a match rule for message dispatching</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_add_match</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>match</parameter></paramdef>
|
||||
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
|
||||
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
|
||||
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
||||
<paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<function>sd_bus_add_match()</function> adds a match rule used to dispatch
|
||||
incoming messages. The syntax of the rule passed in
|
||||
<parameter>match</parameter> is described in the
|
||||
<ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The message <parameter>m</parameter> passed to the callback is only
|
||||
borrowed, that is, the callback should not call
|
||||
<citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
on it. If the callback wants to hold on to the message beyond the lifetime
|
||||
of the callback, it needs to call
|
||||
<citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
to create a new reference.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If an error occurs during the callback invocation, the callback should
|
||||
return a negative error number. If it wants other callbacks that match the
|
||||
same rule to be called, it should return 0. Otherwise it should return a
|
||||
positive integer.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>
|
||||
On success, <function>sd_bus_add_match()</function> returns 0 or a
|
||||
positive integer. On failure, it returns a negative errno-style error
|
||||
code.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -0,0 +1,101 @@
|
|||
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2016 Julian Orth
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="sd_bus_get_fd">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_get_fd</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Julian</firstname>
|
||||
<surname>Orth</surname>
|
||||
<email>ju.orth@gmail.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_get_fd</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_get_fd</refname>
|
||||
|
||||
<refpurpose>Get the file descriptor connected to the message bus</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_get_fd</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<function>sd_bus_get_fd()</function> returns the file descriptor used to
|
||||
communicate with the message bus. This descriptor can be used with
|
||||
<citerefentry
|
||||
project='die-net'><refentrytitle>select</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry
|
||||
project='die-net'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
or similar functions to wait for incmming messages.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the bus was created with the
|
||||
<citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
function, then the <parameter>input_fd</parameter> used in that call is
|
||||
returned.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>
|
||||
Returns the file descriptor used for incoming messages from the message
|
||||
bus.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2016 Julian Orth
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="sd_bus_message_read_basic">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_message_read_basic</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Julian</firstname>
|
||||
<surname>Orth</surname>
|
||||
<email>ju.orth@gmail.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_message_read_basic</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_message_read_basic</refname>
|
||||
|
||||
<refpurpose>Read a basic type from a message</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_message_read_basic</function></funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
|
||||
<paramdef>char <parameter>type</parameter></paramdef>
|
||||
<paramdef>void *<parameter>p</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<function>sd_bus_message_read_basic()</function> reads a basic type from a
|
||||
message and advances the read position in the message. The set of basic
|
||||
types and their ascii codes passed in <parameter>type</parameter> are
|
||||
described in the <ulink
|
||||
url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
|
||||
Specification</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If <parameter>p</parameter> is not NULL, it should contain a pointer to an
|
||||
appropriate object. For example, if <parameter>type</parameter> is
|
||||
<constant>'y'</constant>, the object passed in <parameter>p</parameter>
|
||||
should have type <code>uint8_t *</code>. If <parameter>type</parameter>
|
||||
is <constant>'s'</constant>, the object passed in <parameter>p</parameter>
|
||||
should have type <code>const char **</code>. Note that, if the basic type
|
||||
is a pointer (e.g., <code>const char *</code> in the case of a string),
|
||||
the pointer is only borrowed and the contents must be copied if they are
|
||||
to be used after the end of the messages lifetime. Similarly, during the
|
||||
lifetime of such a pointer, the message must not be modified.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If there is no object of the specified type at the current position in the
|
||||
message, an error is returned.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>
|
||||
On success, <function>sd_bus_message_read_basic()</function> returns 0 or
|
||||
a positive integer. On failure, it returns a negative errno-style error
|
||||
code.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
Copyright 2016 Julian Orth
|
||||
|
||||
systemd is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as published by
|
||||
the Free Software Foundation; either version 2.1 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
systemd is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="sd_bus_process">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_process</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Julian</firstname>
|
||||
<surname>Orth</surname>
|
||||
<email>ju.orth@gmail.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_process</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_process</refname>
|
||||
|
||||
<refpurpose>Drive the connection</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_process</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>sd_bus_message **<parameter>r</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<function>sd_bus_process()</function> drives the connection between the
|
||||
message bus and the client. That is, it handles connecting,
|
||||
authentication, and message processing. It should be called in a loop
|
||||
until no further progress can be made or an error occurs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Once no further progress can be made,
|
||||
<citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
should be called. Alternatively the user can wait for incoming data on
|
||||
the file descriptor returned by
|
||||
<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>sd_bus_process</function> processes at most one incoming
|
||||
message per call. If the parameter <parameter>r</parameter> is not NULL
|
||||
and the call processed a message, <code>*r</code> is set to this message.
|
||||
The caller owns a reference to this message and should call
|
||||
<citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
when the message is no longer needed. If <parameter>r</parameter> is not
|
||||
NULL, progress was made, but no message was processed, <code>*r</code> is
|
||||
set to NULL.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>
|
||||
If progress was made, a positive integer is returned. If no progress was
|
||||
made, 0 is returned. If an error occurs, a negative errno-style error code
|
||||
is returned.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
Loading…
Reference in New Issue