diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in index f2170377..a9a46eef 100644 --- a/doc/dbus-daemon.1.xml.in +++ b/doc/dbus-daemon.1.xml.in @@ -467,15 +467,22 @@ which mechanisms are listed is not meaningful. -Adds a directory to scan for .service files. Directories are -scanned starting with the first to appear in the config file -(the first .service file found that provides a particular -service will be used). + + Adds a directory to search for .service files, which tell the + dbus-daemon how to start a program to provide a particular well-known + bus name. See the D-Bus Specification for more details about the + contents of .service files. + - -Service files tell the bus how to automatically start a program. -They are primarily used with the per-user-session bus, -not the systemwide bus. + + If a particular service is found in more than one <servicedir>, + the first directory listed in the configuration file takes precedence. + If two service files providing the same well-known bus name are found + in the same directory, it is arbitrary which one will be chosen + (this can only happen if at least one of the service files does not + have the recommended name, which is its well-known bus name followed + by ".service"). + @@ -484,17 +491,128 @@ not the systemwide bus. -<standard_session_servicedirs/> is equivalent to specifying a series -of <servicedir/> elements for each of the data directories in the "XDG -Base Directory Specification" with the subdirectory "dbus-1/services", -so for example "/usr/share/dbus-1/services" would be among the -directories searched. + + <standard_session_servicedirs/> requests a standard set of + session service directories. Its effect is similar to specifying a series + of <servicedir/> elements for each of the data directories, + in the order given here. + It is not exactly equivalent, because there is currently no way + to disable directory monitoring or enforce strict service file naming + for a <servicedir/>. + + + As with <servicedir/> elements, if a particular service is found + in more than one service directory, the first directory takes precedence. + If two service files providing the same well-known bus name are found + in the same directory, it is arbitrary which one will be chosen + (this can only happen if at least one of the service files does not + have the recommended name, which is its well-known bus name followed + by ".service"). + + + + On Unix, the standard session service directories are: + + + + $XDG_RUNTIME_DIR/dbus-1/services, + if XDG_RUNTIME_DIR is set (see the XDG Base Directory + Specification for details of XDG_RUNTIME_DIR): + this location is suitable for transient services created at runtime + by systemd generators (see + + systemd.generator + 7 + ), + session managers or other session infrastructure. + It is an extension provided by the reference implementation + of dbus-daemon, and is not standardized in the D-Bus Specification. + + + Unlike the other standard session service directories, this directory + enforces strict naming for the service files: the filename must be + exactly the well-known bus name of the service, followed by + ".service". + + + Also unlike the other standard session service directories, this + directory is never monitored with + + inotify + 7 + + or similar APIs. Programs that create service files in this directory + while a dbus-daemon is running are expected to call the dbus-daemon's + ReloadConfig() method after they have made changes. + + + + + $XDG_DATA_HOME/dbus-1/services, + where XDG_DATA_HOME defaults to ~/.local/share + (see the XDG Base Directory Specification): this location is + specified by the D-Bus Specification, and is suitable for per-user, + locally-installed software. + + + + + directory/dbus-1/services for each + directory in XDG_DATA_DIRS, where XDG_DATA_DIRS defaults to + /usr/local/share:/usr/share + (see the XDG Base Directory Specification): these locations are + specified by the D-Bus Specification. The defaults are suitable + for software installed locally by a system administrator + (/usr/local/share) or for software installed from operating system + packages (/usr/share). Per-user or system-wide configuration that + sets the XDG_DATA_DIRS environment variable can extend this search + path to cover installations in other locations, for example + ~/.local/share/flatpak/exports/share/ and + /var/lib/flatpak/exports/share/ when + + flatpak + 1 + + is used. + + + + + ${datadir}/dbus-1/services + for the ${datadir} that was specified when + dbus was compiled, typically /usr/share: this location is an + extension provided by the reference dbus-daemon implementation, + and is suitable for software stacks installed alongside dbus-daemon. + + + + The "XDG Base Directory Specification" can be found at http://freedesktop.org/wiki/Standards/basedir-spec if it hasn't moved, otherwise try your favorite search engine. + + On Windows, the standard session service directories are: + + + + %CommonProgramFiles%/dbus-1/services + if %CommonProgramFiles% is set: this location is suitable for + system-wide installed software packages + + + + + A share/dbus-1/services directory found in the same + directory hierarchy (prefix) as the dbus-daemon: this location + is suitable for software stacks installed alongside dbus-daemon + + + + + The <standard_session_servicedirs/> option is only relevant to the per-user-session bus daemon defined in @@ -509,9 +627,53 @@ configuration file would probably be nonsense. <standard_system_servicedirs/> specifies the standard system-wide -activation directories that should be searched for service files. -This option defaults to @EXPANDED_DATADIR@/dbus-1/system-services. + activation directories that should be searched for service files. + As with session services, the first directory listed has highest + precedence. + + On Unix, the standard session service directories are: + + + + /usr/local/share/dbus-1/system-services: this location is + specified by the D-Bus Specification, and is suitable for + software installed locally by the system administrator + + + + + /usr/share/dbus-1/system-services: this location is + specified by the D-Bus Specification, and is suitable for + software installed by operating system packages + + + + + ${datadir}/dbus-1/system-services + for the ${datadir} that was specified when + dbus was compiled, typically /usr/share: this location is an + extension provided by the reference dbus-daemon implementation, + and is suitable for software stacks installed alongside dbus-daemon + + + + + /lib/dbus-1/system-services: this location is + specified by the D-Bus Specification, and was intended for + software installed by operating system packages and used during + early boot (but it should be considered deprecated, because + the reference dbus-daemon is not designed to be available during + early boot) + + + + + + + On Windows, there is no standard system bus, so there are no standard + system bus directories either. + The <standard_system_servicedirs/> option is only relevant to the per-system bus daemon defined in