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

sd-bus: Add sd_bus_reply_method_return docs + cleanups

Browse source
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_errnof',
'sd_bus_reply_method_errorf'], 'sd_bus_reply_method_errorf'],
''], ''],
['sd_bus_reply_method_return', '3', [], ''],
['sd_bus_request_name', ['sd_bus_request_name',
'3', '3',
['sd_bus_release_name', ['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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_path_encode</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_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_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_request_name</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>, <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

87
man/sd_bus_message_append.xml
View file

@ -20,8 +20,7 @@
<refname>sd_bus_message_append</refname> <refname>sd_bus_message_append</refname>
<refname>sd_bus_message_appendv</refname> <refname>sd_bus_message_appendv</refname>
<refpurpose>Attach fields to a D-Bus message based on a type <refpurpose>Attach fields to a D-Bus message based on a type string</refpurpose>
string</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
@ -48,60 +47,49 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para>The <function>sd_bus_message_append()</function> function <para>The <function>sd_bus_message_append()</function> function appends a sequence of fields to
appends a sequence of fields to the D-Bus message object the D-Bus message object <parameter>m</parameter>. The type string <parameter>types</parameter>
<parameter>m</parameter>. The type string describes the types of the field arguments that follow. For each type specified in the type
<parameter>types</parameter> describes the types of the field string, one or more arguments need to be specified, in the same order as declared in the type
arguments that follow. For each type specified in the type string, string.</para>
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 <para>The type string is composed of the elements shown in the table below. It contains zero or
table below. It contains zero or more single "complete types". more single "complete types". Each complete type may be one of the basic types or a fully
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
described container type. A container type may be a structure with variant, an array with its element type, or a dictionary entry with the contained types. The
the contained types, a variant, an array with its element type, or type string is <constant>NUL</constant>-terminated.</para>
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 <para>In case of a basic type, one argument of the corresponding type is expected.</para>
type is expected.</para>
<para>A structure is denoted by a sequence of complete types <para>A structure is denoted by a sequence of complete types between <literal>(</literal> and
between <literal>(</literal> and <literal>)</literal>. This <literal>)</literal>. This sequence cannot be empty — it must contain at least one type.
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
Arguments corresponding to this nested sequence follow the same nested.</para>
rules as if they were not nested.</para>
<para>A variant is denoted by <literal>v</literal>. Corresponding <para>A variant is denoted by <literal>v</literal>. Corresponding arguments must begin with a
arguments must begin with a type string denoting a complete type, type string denoting a complete type, and following that, arguments corresponding to the
and following that, arguments corresponding to the specified type. specified type.</para>
</para>
<para>An array is denoted by <literal>a</literal> followed by a <para>An array is denoted by <literal>a</literal> followed by a complete type. Corresponding
complete type. Corresponding arguments must begin with the number of arguments must begin with the number of entries in the array, followed by the entries
entries in the array, followed by the entries themselves, themselves, matching the element type of the array.</para>
matching the element type of the array.</para>
<para>A dictionary is an array of dictionary entries, denoted by <para>A dictionary is an array of dictionary entries, denoted by <literal>a</literal> followed
<literal>a</literal> followed by a pair of complete types between by a pair of complete types between <literal>{</literal> and <literal>}</literal>. The first of
<literal>{</literal> and <literal>}</literal>. The first of those those types must be a basic type. Corresponding arguments must begin with the number of
types must be a basic type. Corresponding arguments must begin dictionary entries, followed by a pair of values for each entry matching the element type of the
with the number of dictionary entries, followed by a pair of dictionary entries.</para>
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 <para>The <function>sd_bus_message_appendv()</function> is equivalent to the
<function>sd_bus_message_append()</function>, except that it is called with <function>sd_bus_message_append()</function>, except that it is called with a
a <literal>va_list</literal> instead of a variable number of arguments. This <literal>va_list</literal> instead of a variable number of arguments. This function does not
function does not call the <function>va_end()</function> macro. Because it call the <function>va_end()</function> macro. Because it invokes the
invokes the <function>va_arg()</function> macro, the value of <function>va_arg()</function> macro, the value of <parameter>ap</parameter> is undefined after
<parameter>ap</parameter> is undefined after the call.</para> the call.</para>
<para>For further details on the D-Bus type system, please consult <para>For further details on the D-Bus type system, please consult the
the <ulink <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus Specification</ulink>.
url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus </para>
Specification</ulink>.</para>
<table> <table>
<title>Item type specifiers</title> <title>Item type specifiers</title>
@ -162,7 +150,6 @@
<constant>NULL</constant>, which is equivalent to an empty string. See <constant>NULL</constant>, which is equivalent to an empty string. See
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for the precise interpretation of those and other types.</para> for the precise interpretation of those and other types.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -227,8 +214,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative <para>On success, these functions return a non-negative integer. On failure, they return a
errno-style error code.</para> negative errno-style error code.</para>
<xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
</refsect1> </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_errno</refname>
<refname>sd_bus_reply_method_errnof</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> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
@ -63,12 +63,12 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para>The <function>sd_bus_reply_method_error()</function> function sends an <para>The <function>sd_bus_reply_method_error()</function> function sends an error reply to the
error reply to the <parameter>call</parameter> message. The error structure <parameter>call</parameter> message. The error structure <parameter>e</parameter> specifies the
<parameter>e</parameter> specifies the error to send, and is used as described in error to send, and is used as described in
<citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If no reply is expected to <parameter>call</parameter>, this function returns If no reply is expected to <parameter>call</parameter>, this function succeeds without sending a
success without sending reply.</para> reply.</para>
<para>The <function>sd_bus_reply_method_errorf()</function> is to <para>The <function>sd_bus_reply_method_errorf()</function> is to
<function>sd_bus_reply_method_error()</function> what <function>sd_bus_reply_method_error()</function> what
@ -89,8 +89,9 @@
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para>These functions return 0 if the error reply was successfully sent or if <para>This function returns a non-negative integer if the error reply was successfully sent or
none was expected, and a negative errno-style error code otherwise.</para> if <parameter>call</parameter> does not expect a reply. On failure, it returns a negative
errno-style error code.</para>
<refsect2> <refsect2>
<title>Errors</title> <title>Errors</title>
@ -101,15 +102,14 @@
<varlistentry> <varlistentry>
<term><constant>-EINVAL</constant></term> <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> <constant>NULL</constant>.</para>
<para>Message <parameter>call</parameter> is not a method call message. <para>Message <parameter>call</parameter> is not a method call message.</para>
</para>
<para>Message <parameter>call</parameter> is not attached to a bus.</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 <function>sd_bus_reply_method_error</function> is not set, see
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para> </para>
@ -137,7 +137,7 @@
</varlistentry> </varlistentry>
</variablelist> </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> <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
may be returned.</para> may be returned.</para>
</refsect2> </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>