Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 1 | .\" |
| 2 | .\" dbus-launch manual page. |
| 3 | .\" Copyright (C) 2003 Red Hat, Inc. |
| 4 | .\" |
| 5 | .TH dbus-launch 1 |
| 6 | .SH NAME |
| 7 | dbus-launch \- Utility to start a message bus from a shell script |
| 8 | .SH SYNOPSIS |
| 9 | .PP |
| 10 | .B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...] |
| 11 | |
| 12 | .SH DESCRIPTION |
| 13 | |
| 14 | The \fIdbus-launch\fP command is used to start a session bus |
| 15 | instance of \fIdbus-daemon\fP from a shell script. |
| 16 | It would normally be called from a user's login |
| 17 | scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so |
| 18 | backticks or the $() construct can be used to read information from |
| 19 | \fIdbus-launch\fP. |
| 20 | |
| 21 | With no arguments, \fIdbus-launch\fP will launch a session bus |
| 22 | instance and print the address and pid of that instance to standard |
| 23 | output. |
| 24 | |
| 25 | You may specify a program to be run; in this case, \fIdbus-launch\fP |
| 26 | will launch a session bus instance, set the appropriate environment |
| 27 | variables so the specified program can find the bus, and then execute the |
| 28 | specified program, with the specified arguments. See below for |
| 29 | examples. |
| 30 | |
| 31 | If you launch a program, \fIdbus-launch\fP will not print the |
| 32 | information about the new bus to standard output. |
| 33 | |
| 34 | When \fIdbus-launch\fP prints bus information to standard output, by |
| 35 | default it is in a simple key-value pairs format. However, you may |
| 36 | request several alternate syntaxes using the \-\-sh-syntax, \-\-csh-syntax, |
| 37 | \-\-binary-syntax, or |
| 38 | \-\-auto-syntax options. Several of these cause \fIdbus-launch\fP to emit shell code |
| 39 | to set up the environment. |
| 40 | |
| 41 | With the \-\-auto-syntax option, \fIdbus-launch\fP looks at the value |
| 42 | of the SHELL environment variable to determine which shell syntax |
| 43 | should be used. If SHELL ends in "csh", then csh-compatible code is |
| 44 | emitted; otherwise Bourne shell code is emitted. Instead of passing |
| 45 | \-\-auto-syntax, you may explicity specify a particular one by using |
| 46 | \-\-sh-syntax for Bourne syntax, or \-\-csh-syntax for csh syntax. |
| 47 | In scripts, it's more robust to avoid \-\-auto-syntax and you hopefully |
| 48 | know which shell your script is written in. |
| 49 | |
| 50 | .PP |
| 51 | See http://www.freedesktop.org/software/dbus/ for more information |
| 52 | about D-Bus. See also the man page for \fIdbus-daemon\fP. |
| 53 | |
| 54 | .PP |
| 55 | Here is an example of how to use \fIdbus-launch\fP with an |
| 56 | sh-compatible shell to start the per-session bus daemon: |
| 57 | .nf |
| 58 | |
| 59 | ## test for an existing bus daemon, just to be safe |
| 60 | if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then |
| 61 | ## if not found, launch a new one |
| 62 | eval `dbus-launch --sh-syntax --exit-with-session` |
| 63 | echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS" |
| 64 | fi |
| 65 | |
| 66 | .fi |
| 67 | You might run something like that in your login scripts. |
| 68 | |
| 69 | .PP |
| 70 | Another way to use \fIdbus-launch\fP is to run your main session |
| 71 | program, like so: |
| 72 | .nf |
| 73 | |
| 74 | dbus-launch gnome-session |
| 75 | |
| 76 | .fi |
| 77 | The above would likely be appropriate for ~/.xsession or ~/.Xclients. |
| 78 | |
| 79 | .SH AUTOMATIC LAUNCHING |
| 80 | |
| 81 | .PP |
| 82 | If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use |
| 83 | D-Bus, by default the process will attempt to invoke dbus-launch with |
| 84 | the --autolaunch option to start up a new session bus or find the |
| 85 | existing bus address on the X display or in a file in |
| 86 | ~/.dbus/session-bus/ |
| 87 | |
| 88 | .PP |
| 89 | Whenever an autolaunch occurs, the application that had to |
| 90 | start a new bus will be in its own little world; it can effectively |
| 91 | end up starting a whole new session if it tries to use a lot of |
| 92 | bus services. This can be suboptimal or even totally broken, depending |
| 93 | on the app and what it tries to do. |
| 94 | |
| 95 | .PP |
| 96 | There are two common reasons for autolaunch. One is ssh to a remote |
| 97 | machine. The ideal fix for that would be forwarding of |
| 98 | DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded. |
| 99 | In the meantime, you can edit the session.conf config file to |
| 100 | have your session bus listen on TCP, and manually set |
| 101 | DBUS_SESSION_BUS_ADDRESS, if you like. |
| 102 | |
| 103 | .PP |
| 104 | The second common reason for autolaunch is an su to another user, and |
| 105 | display of X applications running as the second user on the display |
| 106 | belonging to the first user. Perhaps the ideal fix in this case |
| 107 | would be to allow the second user to connect to the session bus of the |
| 108 | first user, just as they can connect to the first user's display. |
| 109 | However, a mechanism for that has not been coded. |
| 110 | |
| 111 | .PP |
| 112 | You can always avoid autolaunch by manually setting |
| 113 | DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default |
| 114 | address if none is set is "autolaunch:", so if any other address is |
| 115 | set there will be no autolaunch. You can however include autolaunch in |
| 116 | an explicit session bus address as a fallback, for example |
| 117 | DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if |
| 118 | the first address doesn't work, processes will autolaunch. (The bus |
| 119 | address variable contains a comma-separated list of addresses to try.) |
| 120 | |
| 121 | .PP |
| 122 | The --autolaunch option is considered an internal implementation |
| 123 | detail of libdbus, and in fact there are plans to change it. There's |
| 124 | no real reason to use it outside of the libdbus implementation anyhow. |
| 125 | |
| 126 | .SH OPTIONS |
| 127 | The following options are supported: |
| 128 | .TP |
| 129 | .I "--auto-syntax" |
| 130 | Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable. |
| 131 | |
| 132 | .I "--binary-syntax" |
| 133 | Write to stdout a nul-terminated bus address, then the bus PID as a |
| 134 | binary integer of size sizeof(pid_t), then the bus X window ID as a |
| 135 | binary integer of size sizeof(long). Integers are in the machine's |
| 136 | byte order, not network byte order or any other canonical byte order. |
| 137 | |
| 138 | .TP |
| 139 | .I "--close-stderr" |
| 140 | Close the standard error output stream before starting the D-Bus |
| 141 | daemon. This is useful if you want to capture dbus-launch error |
| 142 | messages but you don't want dbus-daemon to keep the stream open to |
| 143 | your application. |
| 144 | |
| 145 | .TP |
| 146 | .I "--config-file=FILENAME" |
| 147 | Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it |
| 148 | the \-\-session argument. See the man page for dbus-daemon |
| 149 | |
| 150 | .TP |
| 151 | .I "--csh-syntax" |
| 152 | Emit csh compatible code to set up environment variables. |
| 153 | |
| 154 | .TP |
| 155 | .I "--exit-with-session" |
| 156 | If this option is provided, a persistent "babysitter" process will be |
| 157 | created that watches stdin for HUP and tries to connect to the X |
| 158 | server. If this process gets a HUP on stdin or loses its X connection, |
| 159 | it kills the message bus daemon. |
| 160 | |
| 161 | .TP |
| 162 | .I "--autolaunch=MACHINEID" |
| 163 | This option implies that \fIdbus-launch\fP should scan for a |
| 164 | previously-started session and reuse the values found there. If no |
| 165 | session is found, it will start a new session. The |
| 166 | \-\-exit-with-session option is implied if \-\-autolaunch is given. |
| 167 | This option is for the exclusive use of libdbus, you do not want to |
| 168 | use it manually. It may change in the future. |
| 169 | |
| 170 | .TP |
| 171 | .I "--sh-syntax" |
| 172 | Emit Bourne-shell compatible code to set up environment variables. |
| 173 | |
| 174 | .TP |
| 175 | .I "--version" |
| 176 | Print the version of dbus-launch |
| 177 | |
| 178 | .SH AUTHOR |
| 179 | See http://www.freedesktop.org/software/dbus/doc/AUTHORS |
| 180 | |
| 181 | .SH BUGS |
| 182 | Please send bug reports to the D-Bus mailing list or bug tracker, |
| 183 | see http://www.freedesktop.org/software/dbus/ |