From c8a43176133df2b5c60faca83aee3c2a606981bc Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Mon, 27 Feb 2023 13:46:17 +0100 Subject: [PATCH 1/2] spec: Mention the well-known fallback path for the session bus Multiple implementations (including `dbus` itself and `zbus` use the path `$XDG_RUNTIME_DIR/bus` when `$DBUS_SESSION_BUS_ADDRESS` is unset. This fallback path is quite convenient, but not documented as part of the specification. This changeset adds a mention of this de-fact standard fallback. Fixes: https://gitlab.freedesktop.org/dbus/dbus/-/issues/449 --- doc/dbus-specification.xml | 75 +++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 18 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 8ebe7a8d..91f6a429 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -5554,28 +5554,67 @@ The address of the login session message bus is given in the DBUS_SESSION_BUS_ADDRESS environment - variable. If that variable is not set, applications may - also try to read the address from the X Window System root - window property _DBUS_SESSION_BUS_ADDRESS. - The root window property must have type STRING. - The environment variable should have precedence over the - root window property. + variable. If DBUS_SESSION_BUS_ADDRESS is not set, + or if it's set to the string autolaunch:, the + system should use platform-specific methods of locating a running + D-Bus session server, or starting one if a running instance cannot be + found. + + + On Unix-like systems, if DBUS_SESSION_BUS_ADDRESS + is not set, a recommended platform-specific method is to use a + default socket path based on the XDG_RUNTIME_DIR. See the section below + for details. + + + On Unix-like systems, if the above default path cannot be used, + another recommended platform-specific fallback is to carry out X11 autolaunching as + described below. + + + On Windows systems, the recommended platform-specific fallback is to + carry out Windows autolaunching as described by the + autolaunch transport. - The address of the login session message bus is given in the - DBUS_SESSION_BUS_ADDRESS environment variable. If - DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string - "autolaunch:", the system should use platform-specific methods of - locating a running D-Bus session server, or starting one if a running - instance cannot be found. Note that this mechanism is not recommended - for attempting to determine if a daemon is running. It is inherently - racy to attempt to make this determination, since the bus daemon may - be started just before or just after the determination is made. - Therefore, it is recommended that applications do not try to make this - determination for their functionality purposes, and instead they - should attempt to start the server. + + Default path for session bus on Unix-like platforms + + This mechanism should only be used if the + DBUS_SESSION_BUS_ADDRESS environment variable is + not defined, if the XDG_RUNTIME_DIR + environment variable is defined and the directory specified in + XDG_RUNTIME_DIR exists and is suitable for use + (with appropriate security checks on permissions and ownership as + defined by the + XDG Base Directory Specification) + + + The implementation should attempt to communicate with the bus at + the well-known socket address + $XDG_RUNTIME_DIR/bus as though it had been + specified as a unix:path=... address. If the + environment variable XDG_RUNTIME_DIR is + undefined or if no socket exists at the specified path, the + implementation MUST conclude that there is no D-Bus server + discoverable via this mechanism, and MAY try other, lower-priority + mechanisms such as X11 autolaunching instead. + + X Windowing System + + Note that X11 autolaunching is not recommended for attempting to + determine if a daemon is running. It is inherently racy to attempt to + make this determination, since the bus daemon may be started just + before or just after the determination is made. Therefore, it is + recommended that applications do not try to make this determination + for their functionality purposes, and instead they should attempt to + start the server. + For the X Windowing System, the application must locate the window owner of the selection represented by the atom formed by From 89901334708a31dc0350ec127fd5db113ea42192 Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Tue, 24 Oct 2023 13:13:43 +0200 Subject: [PATCH 2/2] squashme?: reword section intro parragraph too --- doc/dbus-specification.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 91f6a429..44ee7529 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -5541,8 +5541,9 @@ Well-known Message Bus Instances - Two standard message bus instances are defined here, along with how - to locate them and where their service files live. + This specification defines two standard instances of the message bus as + well as mechanisms to locate these buses and their respective service + files. Login session message bus