From 964b3f8ed1047c99a11efc42cf8a8e3b7c283128 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 11 Mar 2011 23:44:52 +0100
Subject: [PATCH] spec: document exec transports

This adds a specification text for the new exec: transport.
---
 doc/dbus-specification.xml |   68 ++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 65 insertions(+), 3 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index ee5aac5..31d091e 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -2466,9 +2466,10 @@
       [FIXME we need to specify in detail each transport and its possible arguments]
     
       Current transports include: unix domain sockets (including 
-      abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport
-      using in-process pipes. Future possible transports include one that
-      tunnels over X11 protocol.
+      abstract namespace on linux), launchd, TCP/IP, an executed
+      subprocess and a debug/testing transport using in-process
+      pipes. Future possible transports include one that tunnels over
+      X11 protocol.
     </para>
   
     <sect2 id="transports-unix-domain-sockets">
@@ -2702,6 +2703,67 @@
        </informaltable>
       </sect3>
     </sect2>
+    <sect2 id="transports-exec">
+      <title>Executed Subprocesses on Unix</title>
+      <para>
+        This transport forks off a process and connects its standard
+        input and standard output with an anonymous Unix domain
+        socket. This socket is then used for communication by the
+        transport. This transport may be used to use out-of-process
+        forwarder programs as basis for the D-Bus protocol.
+      </para>
+      <para>
+        The forked process will inherit the standard error output and
+        process group from the parent process.
+      </para>
+      <para>
+        Executed subprocesses are not available on windows.
+      </para>
+      <sect3 id="transports-exec-addresses">
+        <title>Server Address Format</title>
+        <para>
+          Executed subprocess addresses are identified by the "exec:" prefix
+          and support the following key/value pairs:
+        </para>
+        <informaltable>
+         <tgroup cols="3">
+          <thead>
+           <row>
+            <entry>Name</entry>
+            <entry>Values</entry>
+            <entry>Description</entry>
+           </row>
+          </thead>
+          <tbody>
+           <row>
+            <entry>path</entry>
+            <entry>(path)</entry>
+            <entry>Path of the binary to execute, either an absolute
+            path or a binary name that is searched for in the default
+            search path of the OS. This corresponds to the first
+            argument of execlp(). This key is mandatory.</entry>
+          </row>
+          <row>
+            <entry>argv0</entry>
+            <entry>(string)</entry>
+            <entry>The program name to use when executing the
+            binary. If omitted the same value as specified for path=
+            will be used. This corresponds to the second argument of
+            execlp().</entry>
+          </row>
+          <row>
+            <entry>argv1, argv2, ...</entry>
+            <entry>(string)</entry>
+            <entry>Arguments to pass to the binary. This corresponds
+            to the third and later arguments of execlp(). If a
+            specific argvX is not specified no further argvY for Y > X
+            are taken into account.</entry>
+          </row>
+        </tbody>
+        </tgroup>
+       </informaltable>
+      </sect3>
+    </sect2>
    </sect1>
    <sect1 id="meta-transports">
     <title>Meta Transports</title>
-- 
1.7.4.1