From: Zeeshan Ali <zeeshanak@gnome.org>
Date: Wed, 24 Feb 2021 11:16:08 +0000 (+0100)
Subject: spec: Clarify that Variant's value needs padding
X-Git-Tag: dbus-1.13.20~40^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fcc3455b8972c54480b4ef809af31ea5a8bc7fcf;p=thirdparty%2Fdbus.git

spec: Clarify that Variant's value needs padding
---

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 16bbc2ca2..a43244d3b 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1245,6 +1245,24 @@
         (See <link linkend="message-protocol-marshaling-signature">Valid
         Signatures</link>.)
       </para>
+
+      <para>
+        It should be noted that while a variant itself does not require any
+        alignment padding, the contained value does need to be padded
+        according to the alignment rules of its type.
+      </para>
+
+      <para>
+        For instance, if the current position in the message is at a multiple of
+        8 bytes and the byte-order is big-endian, a variant containing a 64-bit
+        integer 5 would be marshalled as:
+
+        <screen>
+0x01 0x74 0x00                          <lineannotation>signature bytes (length = 1, signature = 't' and trailing nul)</lineannotation>
+               0x00 0x00 0x00 0x00 0x00 <lineannotation>padding to 8-byte boundary</lineannotation>
+0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x05 <lineannotation>8 bytes of contained value</lineannotation>
+        </screen>
+      </para>
     </sect2>
 
     <sect2>