diff options
Diffstat (limited to 'tools/dbus-launch.1')
| -rw-r--r-- | tools/dbus-launch.1 | 78 |
1 files changed, 68 insertions, 10 deletions
diff --git a/tools/dbus-launch.1 b/tools/dbus-launch.1 index 3c505e7b..bcc30d7c 100644 --- a/tools/dbus-launch.1 +++ b/tools/dbus-launch.1 @@ -7,27 +7,36 @@ dbus-launch \- Utility to start a message bus from a shell script .SH SYNOPSIS .PP -.B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...] +.B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...] .SH DESCRIPTION -The \fIdbus-launch\fP command is used to start \fIdbus-daemon\fP -from a shell script. It would normally be called from a user's login +The \fIdbus-launch\fP command is used to start a session bus +instance of \fIdbus-daemon\fP from a shell script. +It would normally be called from a user's login scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so backticks or the $() construct can be used to read information from \fIdbus-launch\fP. -With no arguments, \fIdbus-launch\fP will simply print the values of -DBUS_SESSION_BUS_ADDRESS and DBUS_SESSION_BUS_PID. +With no arguments, \fIdbus-launch\fP will launch a session bus +instance and print the address and pid of that instance to standard +output. You may specify a program to be run; in this case, \fIdbus-launch\fP -will then set the appropriate environment variables and execute the +will launch a session bus instance, set the appropriate environment +variables so the specified program can find the bus, and then execute the specified program, with the specified arguments. See below for examples. -Finally, you may use the \-\-sh-syntax, \-\-csh-syntax, or -\-\-auto-syntax commands to cause \fIdbus-launch\fP to emit shell code -to set up the environment. This is useful in shell scripts. +If you launch a program, \fIdbus-launch\fP will not print the +information about the new bus to standard output. + +When \fIdbus-launch\fP prints bus information to standard output, by +default it is in a simple key-value pairs format. However, you may +request several alternate syntaxes using the \-\-sh-syntax, \-\-csh-syntax, +\-\-binary-syntax, or +\-\-auto-syntax options. Several of these cause \fIdbus-launch\fP to emit shell code +to set up the environment. With the \-\-auto-syntax option, \fIdbus-launch\fP looks at the value of the SHELL environment variable to determine which shell syntax @@ -67,12 +76,60 @@ dbus-launch gnome-session .fi The above would likely be appropriate for ~/.xsession or ~/.Xclients. +.SH AUTOMATIC LAUNCHING + +.PP +If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use +D-Bus, by default the process will attempt to invoke dbus-launch with +the --autolaunch option to start up a new session bus or find the +existing bus address on the X display or in a file in +~/.dbus/session-bus/ + +.PP +Whenever an autolaunch occurs, the application that had to +start a new bus will be in its own little world; it can effectively +end up starting a whole new session if it tries to use a lot of +bus services. This can be suboptimal or even totally broken, depending +on the app and what it tries to do. + +.PP +There are two common reasons for autolaunch. One is ssh to a remote +machine. The ideal fix for that would be forwarding of +DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded. +In the meantime, you can edit the session.conf config file to +have your session bus listen on TCP, and manually set +DBUS_SESSION_BUS_ADDRESS, if you like. + +.PP +The second common reason for autolaunch is an su to another user, and +display of X applications running as the second user on the display +belonging to the first user. Perhaps the ideal fix in this case +would be to allow the second user to connect to the session bus of the +first user, just as they can connect to the first user's display. +However, a mechanism for that has not been coded. + +.PP +You can always avoid autolaunch by manually setting +DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default +address if none is set is "autolaunch:", so if any other address is +set there will be no autolaunch. You can however include autolaunch in +an explicit session bus address as a fallback, for example +DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if +the first address doesn't work, processes will autolaunch. (The bus +address variable contains a comma-separated list of addresses to try.) + .SH OPTIONS The following options are supported: .TP .I "--auto-syntax" Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable. +.I "--binary-syntax" +Write to stdout a nul-terminated bus address, then the bus PID as a +binary integer of size sizeof(pid_t), then the bus X window ID as a +binary integer of size sizeof(long). Integers are in the machine's +byte order, not network byte order or any other canonical byte order. + .TP .I "--config-file=FILENAME" Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it @@ -90,11 +147,12 @@ server. If this process gets a HUP on stdin or loses its X connection, it kills the message bus daemon. .TP -.I "--autolaunch" +.I "--autolaunch=MACHINEID" This option implies that \fIdbus-launch\fP should scan for a previously-started session and reuse the values found there. If no session is found, it will start a new session. The \-\-exit-with-session option is implied if \-\-autolaunch is given. +This option is used by libdbus, you probably do not want to use it manually. .TP .I "--sh-syntax" |