verify: use manager_load_startable_unit_or_warn() to load units for verification

[thirdparty/systemd.git] / man / sd_bus_message_append.xml

diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml
index 0ee849dca7aa5a9c64b44c42eb55425a3f75fe99..3fba2120140e9f8c2e84b5689040e8b07870a8ee 100644 (file)
--- a/man/sd_bus_message_append.xml
+++ b/man/sd_bus_message_append.xml
@@ -3,6 +3,8 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2014 Zbigniew Jędrzejewski-Szmek
@@ -45,6 +47,7 @@
 
   <refnamediv>
     <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>
@@ -58,8 +61,16 @@
         <funcdef>int sd_bus_message_append</funcdef>
         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
         <paramdef>const char *<parameter>types</parameter></paramdef>
-        <paramdef>...</paramdef>
+        <paramdef>…</paramdef>
+      </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>
       </funcprototype>
+
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -70,7 +81,7 @@
     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
+    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>
 
@@ -109,6 +120,14 @@
     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 <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 ap
+    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
@@ -169,6 +188,11 @@
       </tgroup>
     </table>
 
+    <para>For types "s" and "g" (unicode string or signature), the pointer may be
+    <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>
@@ -193,7 +217,7 @@ dictionary ::= "a" "{" basic_type complete_type "}"
     </para>
 
     <programlisting>sd_bus_message *m;
-...
+…
 sd_bus_message_append(m, "s", "a string");</programlisting>
 
     <para>Append all types of integers:</para>
@@ -233,8 +257,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting>
   <refsect1>
     <title>Return Value</title>
 
-    <para>On success, this call returns 0 or a positive
-    integer. On failure, this call returns a negative
+    <para>On success, these functions return 0 or a positive
+    integer. On failure, these functions return a negative
     errno-style error code.</para>
   </refsect1>