diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 01bf7dff..63413db7 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -5556,8 +5556,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 @@ -5569,28 +5570,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