client: Allow absolute paths in WAYLAND_DISPLAY

In order to support system compositor instances, it is necessary to
allow clients' wl_display_connect() to find the compositor's listening
socket somewhere outside of XDG_RUNTIME_DIR. For a full account, see
the discussion beginning here:

https://lists.freedesktop.org/archives/wayland-devel/2017-November/035664.html

This change adjusts the client-side connection logic so that, if
WAYLAND_DISPLAY is formatted as an absolute pathname, the socket
connection attempt is made to just $WAYLAND_DISPLAY rather than
usual user-private location $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.

This change is based on Davide Bettio's submission of the same concept
at:

https://lists.freedesktop.org/archives/wayland-devel/2015-August/023838.html.

v4 changes:

* Improved internal comments and some boundary-condition
  error checks in test case.
* Refer to compositor as "Wayland server" rather than "Wayland
  display" in wl_display_connect() doxygen comments.
* Remove redundant descriptions of parameter-interpretation
  mechanics from wl_display_connect() manpage. Reworked things
  to make it clear that 'name' and $WAYLAND_DISLAY are each
  capable of encoding absolute server socket paths.
* Remove callout to reference implementation behavior in protocol
  documented. In its place there is now a simple statement that
  implementations can optionally support absolute socket paths.

v3 changes:

* Added test case.
* Clarified documentation to note that 'name' parameter to wl_display_connect()
  can also be an absolute path.

v2 changes:

* Added backward incompatibility note to wl_display_connect() manpage.
* Rephased wl_display_connect() manpage changes to precisely match actual
  changed behavior.
* Added mention of new absolute path behavior in wl_display_connect()
  doxygen comments.
* Mentioned new absolute path interpretation of WAYLAND_DISPLAY in
  protocol documentation.

Signed-off-by: Matt Hoosier <matt.hoosier@gmail.com>
Acked-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

2 files changed, 32 insertions, 5 deletions

diff --git a/doc/man/wl_display_connect.xml b/doc/man/wl_display_connect.xml
index 7e6e05c..dab4ddb 100644
--- a/doc/man/wl_display_connect.xml
+++ b/doc/man/wl_display_connect.xml
@@ -55,15 +55,39 @@
     <title>Description</title>
     <para><function>wl_display_connect</function> connects to a Wayland socket
           that was previously opened by a Wayland server. The server socket must
-          be placed in <envar>XDG_RUNTIME_DIR</envar> for this function to
-          find it. The <varname>name</varname> argument specifies the name of
+          be placed in <envar>XDG_RUNTIME_DIR</envar> when <envar>WAYLAND_DISPLAY</envar>
+	  (or <varname>name</varname>, see below) is a simple name, for this
+	  function to find it. The server socket is also allowed to exist at an
+	  arbitrary path; usage details follow. See below for compatibility issue
+	  details.</para>
+
+    <para>The <varname>name</varname> argument specifies the name of
           the socket or <constant>NULL</constant> to use the default (which is
           <constant>"wayland-0"</constant>). The environment variable
-          <envar>WAYLAND_DISPLAY</envar> replaces the default value. If
-          <envar>WAYLAND_SOCKET</envar> is set, this function behaves like
+          <envar>WAYLAND_DISPLAY</envar> replaces the default value.
+
+	  If <varname>name</varname> is an absolute path, then that path is used
+	  as the Wayland socket to which the connection is attempted. Note that
+	  in combination with the default-value behavior described above, this
+	  implies that setting <envar>WAYLAND_DISPLAY</envar> to an absolute
+	  path will implicitly cause <varname>name</varname> to take on that
+	  absolute path if <varname>name</varname> is <constant>NULL</constant>.
+
+          If <envar>WAYLAND_SOCKET</envar> is set, this function behaves like
           <function>wl_display_connect_to_fd</function> with the file-descriptor
           number taken from the environment variable.</para>
 
+    <para>Support for interpreting <envar>WAYLAND_DISPLAY</envar> as an
+          absolute path is a change in behavior compared to
+          <function>wl_display_connect</function>'s behavior in versions
+          1.14 and older of Wayland. It is no longer guaranteed in versions
+          1.15 and higher that the Wayland socket chosen is equivalent to
+          manually constructing a socket pathname by concatenating
+          <envar>XDG_RUNTIME_DIR</envar> and <envar>WAYLAND_DISPLAY</envar>.
+          Manual construction of the socket path must account for the
+          possibility that <envar>WAYLAND_DISPLAY</envar> contains an absolute
+          path.</para>
+
     <para><function>wl_display_connect_to_fd</function> connects to a Wayland
           socket with an explicit file-descriptor. The file-descriptor is passed
           as argument <varname>fd</varname>.</para>
diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index ba6b5f1..9fdee9a 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -94,7 +94,10 @@
       The protocol is sent over a UNIX domain stream socket, where the endpoint
       usually is named <systemitem class="service">wayland-0</systemitem>
       (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
-      in the environment).
+      in the environment). Beginning in Wayland 1.15, implementations can
+      optionally support server socket endpoints located at arbitrary
+      locations in the filesystem by setting <emphasis>WAYLAND_DISPLAY</emphasis>
+      to the absolute path at which the server endpoint listens.
     </para>
     <para>
       Every message is structured as 32-bit words; values are represented in the