From 971a0a8b84b0891f0e4e56f25e4c5ae283e1a4c8 Mon Sep 17 00:00:00 2001
From: Mikhail Gusarov <dottedmag@dottedmag.net>
Date: Fri, 10 Dec 2021 12:44:44 +0100
Subject: [PATCH] doc: Clarify position of file descriptors in the stream

The specification left the position and order of file
descriptors unspecified. Specify that

- order of file descriptors is maintained
- position of file descriptors is bounded, but loose

Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
---
 doc/publican/sources/Protocol.xml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 97e9ba2..0b27082 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -194,6 +194,21 @@
 	</varlistentry>
       </variablelist>
     </para>
+    <para>
+      The protocol does not specify the exact position of the ancillary data
+      in the stream, except that the order of file descriptors is the same as
+      the order of messages and <code>fd</code> arguments within messages on
+      the wire.
+    </para>
+    <para>
+      In particular, it means that any byte of the stream, even the message
+      header, may carry the ancillary data with file descriptors.
+    </para>
+    <para>
+      Clients and compositors should queue incoming data until they have
+      whole messages to process, as file descriptors may arrive earlier
+      or later than the corresponding data bytes.
+    </para>
   </section>
   <xi:include href="ProtocolInterfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
   <section id="sect-Protocol-Versioning">
-- 
2.7.4