Spec: document multiple .service files own the same well known name

In current dbus-daemon(1) implement, system .serivce must named after
its owned name, but this is not the case for session .service.

For session service, the result of multiple .service files own the
same well known name is undefined since readdir(3) doesn't return
dirent in a defined sequence.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=66608
[added some </para><para> -smcv]
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 51d6cb6fb169ed98a3ab4e6d5571a520d49423ff..94de5da76b36f2ebd2061064db61d6f2781a619a 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4689,9 +4689,28 @@
         When an application asks to start a service by name, the bus daemon tries to
         find a service that will own that name. It then tries to spawn the
         executable associated with it. If this fails, it will report an
-        error. [FIXME what happens if two .service files offer the same service;
-        what kind of error is reported, should we have a way for the client to
-        choose one?]
+        error.
+      </para>
+
+      <para>
+        On the well-known system bus, it is not possible for two .service files
+        in the same directory to offer the same service, because they are
+        constrained to have names that match the service name.
+      </para>
+
+      <para>
+        On the well-known session bus, if two .service files in the same
+        directory offer the same service name, the result is undefined.
+        Distributors should avoid this situation, for instance by naming
+        session services' .service files according to their service name.
+      </para>
+
+      <para>
+        If two .service files in different directories offer the same
+        service name, the one in the higher-priority directory is used:
+        for instance, on the system bus, .service files in
+        /usr/local/share/dbus-1/system-services take precedence over those
+        in /usr/share/dbus-1/system-services.
       </para>
       <para>
         The executable launched will have the environment variable