| .\" |
| .\" dbus-launch manual page. |
| .\" Copyright (C) 2003 Red Hat, Inc. |
| .\" |
| .TH dbus-launch 1 |
| .SH NAME |
| 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=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...] |
| |
| .SH DESCRIPTION |
| |
| 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 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 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. |
| |
| 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 |
| should be used. If SHELL ends in "csh", then csh-compatible code is |
| emitted; otherwise Bourne shell code is emitted. Instead of passing |
| \-\-auto-syntax, you may explicity specify a particular one by using |
| \-\-sh-syntax for Bourne syntax, or \-\-csh-syntax for csh syntax. |
| In scripts, it's more robust to avoid \-\-auto-syntax and you hopefully |
| know which shell your script is written in. |
| |
| .PP |
| See http://www.freedesktop.org/software/dbus/ for more information |
| about D-Bus. See also the man page for \fIdbus-daemon\fP. |
| |
| .PP |
| Here is an example of how to use \fIdbus-launch\fP with an |
| sh-compatible shell to start the per-session bus daemon: |
| .nf |
| |
| ## test for an existing bus daemon, just to be safe |
| if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then |
| ## if not found, launch a new one |
| eval `dbus-launch --sh-syntax --exit-with-session` |
| echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS" |
| fi |
| |
| .fi |
| You might run something like that in your login scripts. |
| |
| .PP |
| Another way to use \fIdbus-launch\fP is to run your main session |
| program, like so: |
| .nf |
| |
| 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.) |
| |
| .PP |
| The --autolaunch option is considered an internal implementation |
| detail of libdbus, and in fact there are plans to change it. There's |
| no real reason to use it outside of the libdbus implementation anyhow. |
| |
| .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 "--close-stderr" |
| Close the standard error output stream before starting the D-Bus |
| daemon. This is useful if you want to capture dbus-launch error |
| messages but you don't want dbus-daemon to keep the stream open to |
| your application. |
| |
| .TP |
| .I "--config-file=FILENAME" |
| Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it |
| the \-\-session argument. See the man page for dbus-daemon |
| |
| .TP |
| .I "--csh-syntax" |
| Emit csh compatible code to set up environment variables. |
| |
| .TP |
| .I "--exit-with-session" |
| If this option is provided, a persistent "babysitter" process will be |
| created that watches stdin for HUP and tries to connect to the X |
| server. If this process gets a HUP on stdin or loses its X connection, |
| it kills the message bus daemon. |
| |
| .TP |
| .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 for the exclusive use of libdbus, you do not want to |
| use it manually. It may change in the future. |
| |
| .TP |
| .I "--sh-syntax" |
| Emit Bourne-shell compatible code to set up environment variables. |
| |
| .TP |
| .I "--version" |
| Print the version of dbus-launch |
| |
| .SH AUTHOR |
| See http://www.freedesktop.org/software/dbus/doc/AUTHORS |
| |
| .SH BUGS |
| Please send bug reports to the D-Bus mailing list or bug tracker, |
| see http://www.freedesktop.org/software/dbus/ |