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

sd-bus: Add sd_bus_reply_method_return docs + cleanups

This commit is contained in:
Daan De Meyer 2020-03-19 19:52:54 +01:00 committed by Zbigniew Jędrzejewski-Szmek
parent 4bd859be95
commit 60ef094297
5 changed files with 171 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
man/rules/meson.build
View File

@ -325,6 +325,7 @@ manpages = [
'sd_bus_reply_method_errnof',
'sd_bus_reply_method_errorf'],
''],
['sd_bus_reply_method_return', '3', [], ''],
['sd_bus_request_name',
'3',
['sd_bus_release_name',

1
man/sd-bus.xml
View File

@ -86,6 +86,7 @@
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

99
man/sd_bus_message_append.xml
View File

@ -20,8 +20,7 @@
<refname>sd_bus_message_append</refname>
<refname>sd_bus_message_appendv</refname>
<refpurpose>Attach fields to a D-Bus message based on a type
string</refpurpose>
<refpurpose>Attach fields to a D-Bus message based on a type string</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -36,10 +35,10 @@
</funcprototype>
<funcprototype>
<funcdef>int sd_bus_message_appendv</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>const char *<parameter>types</parameter></paramdef>
<paramdef>va_list <parameter>ap</parameter></paramdef>
<funcdef>int sd_bus_message_appendv</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>const char *<parameter>types</parameter></paramdef>
<paramdef>va_list <parameter>ap</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@ -48,60 +47,49 @@
<refsect1>
<title>Description</title>
<para>The <function>sd_bus_message_append()</function> function
appends a sequence of fields to the D-Bus message object
<parameter>m</parameter>. The type string
<parameter>types</parameter> describes the types of the field
arguments that follow. For each type specified in the type string,
one or more arguments need to be specified, in the same order as
declared in the type string.</para>
<para>The <function>sd_bus_message_append()</function> function appends a sequence of fields to
the D-Bus message object <parameter>m</parameter>. The type string <parameter>types</parameter>
describes the types of the field arguments that follow. For each type specified in the type
string, one or more arguments need to be specified, in the same order as declared in the type
string.</para>
<para>The type string is composed of the elements shown in the
table below. It contains zero or more single "complete types".
Each complete type may be one of the basic types or a fully
described container type. A container type may be a structure with
the contained types, a variant, an array with its element type, or
a dictionary entry with the contained types. The type string is
<constant>NUL</constant>-terminated.</para>
<para>The type string is composed of the elements shown in the table below. It contains zero or
more single "complete types". Each complete type may be one of the basic types or a fully
described container type. A container type may be a structure with the contained types, a
variant, an array with its element type, or a dictionary entry with the contained types. The
type string is <constant>NUL</constant>-terminated.</para>
<para>In case of a basic type, one argument of the corresponding
type is expected.</para>
<para>In case of a basic type, one argument of the corresponding type is expected.</para>
<para>A structure is denoted by a sequence of complete types
between <literal>(</literal> and <literal>)</literal>. This
sequence cannot be empty — it must contain at least one type.
Arguments corresponding to this nested sequence follow the same
rules as if they were not nested.</para>
<para>A structure is denoted by a sequence of complete types between <literal>(</literal> and
<literal>)</literal>. This sequence cannot be empty — it must contain at least one type.
Arguments corresponding to this nested sequence follow the same rules as if they were not
nested.</para>
<para>A variant is denoted by <literal>v</literal>. Corresponding
arguments must begin with a type string denoting a complete type,
and following that, arguments corresponding to the specified type.
</para>
<para>A variant is denoted by <literal>v</literal>. Corresponding arguments must begin with a
type string denoting a complete type, and following that, arguments corresponding to the
specified type.</para>
<para>An array is denoted by <literal>a</literal> followed by a
complete type. Corresponding arguments must begin with the number of
entries in the array, followed by the entries themselves,
matching the element type of the array.</para>
<para>An array is denoted by <literal>a</literal> followed by a complete type. Corresponding
arguments must begin with the number of entries in the array, followed by the entries
themselves, matching the element type of the array.</para>
<para>A dictionary is an array of dictionary entries, denoted by
<literal>a</literal> followed by a pair of complete types between
<literal>{</literal> and <literal>}</literal>. The first of those
types must be a basic type. Corresponding arguments must begin
with the number of dictionary entries, followed by a pair of
values for each entry matching the element type of
the dictionary entries.</para>
<para>A dictionary is an array of dictionary entries, denoted by <literal>a</literal> followed
by a pair of complete types between <literal>{</literal> and <literal>}</literal>. The first of
those types must be a basic type. Corresponding arguments must begin with the number of
dictionary entries, followed by a pair of values for each entry matching the element type of the
dictionary entries.</para>
<para>The <function>sd_bus_message_appendv()</function> is equivalent to the
<function>sd_bus_message_append()</function>, except that it is called with
a <literal>va_list</literal> instead of a variable number of arguments. This
function does not call the <function>va_end()</function> macro. Because it
invokes the <function>va_arg()</function> macro, the value of
<parameter>ap</parameter> is undefined after the call.</para>
<function>sd_bus_message_append()</function>, except that it is called with a
<literal>va_list</literal> instead of a variable number of arguments. This function does not
call the <function>va_end()</function> macro. Because it invokes the
<function>va_arg()</function> macro, the value of <parameter>ap</parameter> is undefined after
the call.</para>
<para>For further details on the D-Bus type system, please consult
the <ulink
url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus
Specification</ulink>.</para>
<para>For further details on the D-Bus type system, please consult the
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus Specification</ulink>.
</para>
<table>
<title>Item type specifiers</title>
@ -162,7 +150,6 @@
<constant>NULL</constant>, which is equivalent to an empty string. See
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for the precise interpretation of those and other types.</para>
</refsect1>
<refsect1>
@ -205,12 +192,12 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
<para>Append a structure composed of a string and a D-Bus path:</para>
<programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path");
</programlisting>
</programlisting>
<para>Append an array of UNIX file descriptors:</para>
<programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
</programlisting>
</programlisting>
<para>Append a variant, with the real type "g" (signature),
and value "sdbusisgood":</para>
@ -227,8 +214,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative
errno-style error code.</para>
<para>On success, these functions return a non-negative integer. On failure, they return a
negative errno-style error code.</para>
<xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
</refsect1>

26
man/sd_bus_reply_method_error.xml
View File

@ -22,7 +22,7 @@
<refname>sd_bus_reply_method_errno</refname>
<refname>sd_bus_reply_method_errnof</refname>
<refpurpose>Reply with an error to a method call</refpurpose>
<refpurpose>Reply with an error to a D-Bus method call</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -63,12 +63,12 @@
<refsect1>
<title>Description</title>
<para>The <function>sd_bus_reply_method_error()</function> function sends an
error reply to the <parameter>call</parameter> message. The error structure
<parameter>e</parameter> specifies the error to send, and is used as described in
<para>The <function>sd_bus_reply_method_error()</function> function sends an error reply to the
<parameter>call</parameter> message. The error structure <parameter>e</parameter> specifies the
error to send, and is used as described in
<citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If no reply is expected to <parameter>call</parameter>, this function returns
success without sending reply.</para>
If no reply is expected to <parameter>call</parameter>, this function succeeds without sending a
reply.</para>
<para>The <function>sd_bus_reply_method_errorf()</function> is to
<function>sd_bus_reply_method_error()</function> what
@ -89,8 +89,9 @@
<refsect1>
<title>Return Value</title>
<para>These functions return 0 if the error reply was successfully sent or if
none was expected, and a negative errno-style error code otherwise.</para>
<para>This function returns a non-negative integer if the error reply was successfully sent or
if <parameter>call</parameter> does not expect a reply. On failure, it returns a negative
errno-style error code.</para>
<refsect2>
<title>Errors</title>
@ -101,15 +102,14 @@
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>The call message <parameter>call</parameter> is
<listitem><para>The input parameter <parameter>call</parameter> is
<constant>NULL</constant>.</para>
<para>Message <parameter>call</parameter> is not a method call message.
</para>
<para>Message <parameter>call</parameter> is not a method call message.</para>
<para>Message <parameter>call</parameter> is not attached to a bus.</para>
<para>The error <parameter>error</parameter> parameter to
<para>The error parameter <parameter>error</parameter> to
<function>sd_bus_reply_method_error</function> is not set, see
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
@ -137,7 +137,7 @@
</varlistentry>
</variablelist>
<para>In addition, any error message returned by
<para>In addition, any error returned by
<citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
may be returned.</para>
</refsect2>

113
man/sd_bus_reply_method_return.xml Normal file
View File

@ -0,0 +1,113 @@
<?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_bus_reply_method_return"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_reply_method_return</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_reply_method_return</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_reply_method_return</refname>
<refpurpose>Reply to a D-Bus method call</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int sd_bus_reply_method_return</funcdef>
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
<paramdef>const char *<parameter>types</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_reply_method_return()</function> sends a reply to the
<parameter>call</parameter> message. The type string <parameter>types</parameter> and the
arguments that follow it must adhere to the format described in
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If no reply is expected to <parameter>call</parameter>, this function succeeds without sending a
reply.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, this function returns a non-negative integer. 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>The input parameter <parameter>call</parameter> is
<constant>NULL</constant>.</para>
<para>Message <parameter>call</parameter> is not a method call message.
</para>
<para>Message <parameter>call</parameter> is not attached to a bus.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>Message <parameter>call</parameter> has been sealed.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOTCONN</constant></term>
<listitem><para>The bus to which message <parameter>call</parameter> is attached is not
connected.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
<para>In addition, any error returned by
<citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
may be returned.</para>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<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_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>