| 1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 |
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> |
| 4 |
<refentry id='dbuslaunch1'> |
| 5 |
|
| 6 |
<!-- dbus\-launch manual page. |
| 7 |
Copyright (C) 2003 Red Hat, Inc. --> |
| 8 |
|
| 9 |
<refmeta> |
| 10 |
<refentrytitle>dbus-launch</refentrytitle> |
| 11 |
<manvolnum>1</manvolnum> |
| 12 |
<refmiscinfo class="manual">User Commands</refmiscinfo> |
| 13 |
<refmiscinfo class="source">D-Bus</refmiscinfo> |
| 14 |
<refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo> |
| 15 |
</refmeta> |
| 16 |
<refnamediv> |
| 17 |
<refname>dbus-launch</refname> |
| 18 |
<refpurpose>Utility to start a message bus from a shell script</refpurpose> |
| 19 |
</refnamediv> |
| 20 |
<!-- body begins here --> |
| 21 |
<refsynopsisdiv id='synopsis'> |
| 22 |
<cmdsynopsis> |
| 23 |
<command>dbus-launch</command> |
| 24 |
<arg choice='opt'>--version </arg> |
| 25 |
<arg choice='opt'>--help </arg> |
| 26 |
<arg choice='opt'>--sh-syntax </arg> |
| 27 |
<arg choice='opt'>--csh-syntax </arg> |
| 28 |
<arg choice='opt'>--auto-syntax </arg> |
| 29 |
<arg choice='opt'>--binary-syntax </arg> |
| 30 |
<arg choice='opt'>--close-stderr </arg> |
| 31 |
<arg choice='opt'>--exit-with-session </arg> |
| 32 |
<arg choice='opt'>--exit-with-x11 </arg> |
| 33 |
<arg choice='opt'>--autolaunch=<replaceable>MACHINEID</replaceable></arg> |
| 34 |
<arg choice='opt'>--config-file=<replaceable>FILENAME</replaceable></arg> |
| 35 |
<arg choice='opt'><replaceable>PROGRAM</replaceable></arg> |
| 36 |
<arg choice='opt' rep='repeat'><replaceable>ARGS</replaceable></arg> |
| 37 |
<sbr/> |
| 38 |
</cmdsynopsis> |
| 39 |
</refsynopsisdiv> |
| 40 |
|
| 41 |
|
| 42 |
<refsect1 id='description'><title>DESCRIPTION</title> |
| 43 |
<para>The <command>dbus-launch</command> command is used to start a session bus |
| 44 |
instance of <emphasis remap='I'>dbus-daemon</emphasis> from a shell script. |
| 45 |
It would normally be called from a user's login |
| 46 |
scripts. Unlike the daemon itself, <command>dbus-launch</command> exits, so |
| 47 |
backticks or the $() construct can be used to read information from |
| 48 |
<command>dbus-launch</command>.</para> |
| 49 |
|
| 50 |
<para>With no arguments, <command>dbus-launch</command> will launch a session bus |
| 51 |
instance and print the address and PID of that instance to standard |
| 52 |
output.</para> |
| 53 |
|
| 54 |
<para>You may specify a program to be run; in this case, <command>dbus-launch</command> |
| 55 |
will launch a session bus instance, set the appropriate environment |
| 56 |
variables so the specified program can find the bus, and then execute the |
| 57 |
specified program, with the specified arguments. See below for |
| 58 |
examples.</para> |
| 59 |
|
| 60 |
<para>If you launch a program, <command>dbus-launch</command> will not print the |
| 61 |
information about the new bus to standard output.</para> |
| 62 |
|
| 63 |
<para>When <command>dbus-launch</command> prints bus information to standard output, by |
| 64 |
default it is in a simple key-value pairs format. However, you may |
| 65 |
request several alternate syntaxes using the --sh-syntax, --csh-syntax, |
| 66 |
--binary-syntax, or |
| 67 |
--auto-syntax options. Several of these cause <command>dbus-launch</command> to emit shell code |
| 68 |
to set up the environment.</para> |
| 69 |
|
| 70 |
<para>With the --auto-syntax option, <command>dbus-launch</command> looks at the value |
| 71 |
of the SHELL environment variable to determine which shell syntax |
| 72 |
should be used. If SHELL ends in "csh", then csh-compatible code is |
| 73 |
emitted; otherwise Bourne shell code is emitted. Instead of passing |
| 74 |
--auto-syntax, you may explicitly specify a particular one by using |
| 75 |
--sh-syntax for Bourne syntax, or --csh-syntax for csh syntax. |
| 76 |
In scripts, it's more robust to avoid --auto-syntax and you hopefully |
| 77 |
know which shell your script is written in.</para> |
| 78 |
|
| 79 |
|
| 80 |
<para>See <ulink url='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink> for more information |
| 81 |
about D-Bus. See also the man page for <emphasis remap='I'>dbus-daemon</emphasis>.</para> |
| 82 |
|
| 83 |
</refsect1> |
| 84 |
|
| 85 |
<refsect1 id='examples'><title>EXAMPLES</title> |
| 86 |
<para>Distributions running |
| 87 |
<command>dbus-launch</command> |
| 88 |
as part of a standard X session should run |
| 89 |
<emphasis remap='B'>dbus-launch --exit-with-session</emphasis> |
| 90 |
after the X server has started and become available, as a wrapper around |
| 91 |
the "main" X client (typically a session manager or window manager), as in |
| 92 |
these examples:</para> |
| 93 |
|
| 94 |
<blockquote remap='RS'> |
| 95 |
<para><emphasis remap='B'>dbus-launch --exit-with-session gnome-session</emphasis></para> |
| 96 |
|
| 97 |
<para><emphasis remap='B'>dbus-launch --exit-with-session openbox</emphasis></para> |
| 98 |
|
| 99 |
<para><emphasis remap='B'>dbus-launch --exit-with-session ~/.xsession</emphasis> |
| 100 |
</para></blockquote> <!-- remap='RE' --> |
| 101 |
|
| 102 |
<para>If your distribution does not do this, you can achieve similar results |
| 103 |
by running your session or window manager in the same way in a script |
| 104 |
run by your X session, such as |
| 105 |
<filename>~/.xsession</filename>, |
| 106 |
<filename>~/.xinitrc</filename> |
| 107 |
or |
| 108 |
<filename>~/.Xclients</filename>.</para> |
| 109 |
|
| 110 |
<para>To start a D-Bus session within a text-mode session, |
| 111 |
do not use <emphasis remap='B'>dbus-launch</emphasis>. |
| 112 |
Instead, see <citerefentry><refentrytitle>dbus-run-session</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
| 113 |
</para> |
| 114 |
|
| 115 |
<literallayout remap='.nf'> |
| 116 |
## test for an existing bus daemon, just to be safe |
| 117 |
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then |
| 118 |
## if not found, launch a new one |
| 119 |
eval `dbus-launch --sh-syntax` |
| 120 |
echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS" |
| 121 |
fi |
| 122 |
</literallayout> <!-- .fi --> |
| 123 |
<para>Note that in this case, dbus-launch will exit, and dbus-daemon will not be |
| 124 |
terminated automatically on logout.</para> |
| 125 |
|
| 126 |
</refsect1> |
| 127 |
|
| 128 |
<refsect1 id='automatic_launching'><title>AUTOMATIC LAUNCHING</title> |
| 129 |
<para>If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use |
| 130 |
D-Bus, by default the process will attempt to invoke dbus-launch with |
| 131 |
the --autolaunch option to start up a new session bus or find the |
| 132 |
existing bus address on the X display or in a file in |
| 133 |
~/.dbus/session-bus/</para> |
| 134 |
|
| 135 |
|
| 136 |
<para>Whenever an autolaunch occurs, the application that had to |
| 137 |
start a new bus will be in its own little world; it can effectively |
| 138 |
end up starting a whole new session if it tries to use a lot of |
| 139 |
bus services. This can be suboptimal or even totally broken, depending |
| 140 |
on the app and what it tries to do.</para> |
| 141 |
|
| 142 |
|
| 143 |
<para>There are two common reasons for autolaunch. One is ssh to a remote |
| 144 |
machine. The ideal fix for that would be forwarding of |
| 145 |
DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded. |
| 146 |
In the meantime, you can edit the session.conf config file to |
| 147 |
have your session bus listen on TCP, and manually set |
| 148 |
DBUS_SESSION_BUS_ADDRESS, if you like.</para> |
| 149 |
|
| 150 |
|
| 151 |
<para>The second common reason for autolaunch is an su to another user, and |
| 152 |
display of X applications running as the second user on the display |
| 153 |
belonging to the first user. Perhaps the ideal fix in this case |
| 154 |
would be to allow the second user to connect to the session bus of the |
| 155 |
first user, just as they can connect to the first user's display. |
| 156 |
However, a mechanism for that has not been coded.</para> |
| 157 |
|
| 158 |
|
| 159 |
<para>You can always avoid autolaunch by manually setting |
| 160 |
DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default |
| 161 |
address if none is set is "autolaunch:", so if any other address is |
| 162 |
set there will be no autolaunch. You can however include autolaunch in |
| 163 |
an explicit session bus address as a fallback, for example |
| 164 |
DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if |
| 165 |
the first address doesn't work, processes will autolaunch. (The bus |
| 166 |
address variable contains a comma-separated list of addresses to try.)</para> |
| 167 |
|
| 168 |
|
| 169 |
<para>The --autolaunch option is considered an internal implementation |
| 170 |
detail of libdbus, and in fact there are plans to change it. There's |
| 171 |
no real reason to use it outside of the libdbus implementation anyhow.</para> |
| 172 |
|
| 173 |
</refsect1> |
| 174 |
|
| 175 |
<refsect1 id='options'><title>OPTIONS</title> |
| 176 |
<para>The following options are supported:</para> |
| 177 |
<variablelist remap='TP'> |
| 178 |
<varlistentry> |
| 179 |
<term><option>--auto-syntax</option></term> |
| 180 |
<listitem> |
| 181 |
<para>Choose --csh-syntax or --sh-syntax based on the SHELL environment variable.</para> |
| 182 |
|
| 183 |
</listitem> |
| 184 |
</varlistentry> |
| 185 |
<varlistentry> |
| 186 |
<term><option>--binary-syntax</option></term> |
| 187 |
<listitem> |
| 188 |
<para>Write to stdout a nul-terminated bus address, then the bus PID as a |
| 189 |
binary integer of size sizeof(pid_t), then the bus X window ID as a |
| 190 |
binary integer of size sizeof(long). Integers are in the machine's |
| 191 |
byte order, not network byte order or any other canonical byte order.</para> |
| 192 |
|
| 193 |
</listitem> |
| 194 |
</varlistentry> |
| 195 |
<varlistentry> |
| 196 |
<term><option>--close-stderr</option></term> |
| 197 |
<listitem> |
| 198 |
<para>Close the standard error output stream before starting the D-Bus |
| 199 |
daemon. This is useful if you want to capture dbus-launch error |
| 200 |
messages but you don't want dbus-daemon to keep the stream open to |
| 201 |
your application.</para> |
| 202 |
|
| 203 |
</listitem> |
| 204 |
</varlistentry> |
| 205 |
<varlistentry> |
| 206 |
<term><option>--config-file=FILENAME</option></term> |
| 207 |
<listitem> |
| 208 |
<para>Pass --config-file=FILENAME to the bus daemon, instead of passing it |
| 209 |
the --session argument. See the man page for dbus-daemon</para> |
| 210 |
|
| 211 |
</listitem> |
| 212 |
</varlistentry> |
| 213 |
<varlistentry> |
| 214 |
<term><option>--csh-syntax</option></term> |
| 215 |
<listitem> |
| 216 |
<para>Emit csh compatible code to set up environment variables.</para> |
| 217 |
|
| 218 |
</listitem> |
| 219 |
</varlistentry> |
| 220 |
|
| 221 |
<varlistentry> |
| 222 |
<term><option>--exit-with-x11</option></term> |
| 223 |
<listitem> |
| 224 |
<para>If this option is provided, a persistent "babysitter" process |
| 225 |
will be created, and will connect to the X server. If it cannot |
| 226 |
do so, launching fails. If the "babysitter" process loses its |
| 227 |
X connection, it kills the message bus daemon, disconnecting |
| 228 |
all of its clients (which should exit in response). This avoids |
| 229 |
having leftover daemon processes from a user X session, after |
| 230 |
the X session has ended.</para> |
| 231 |
</listitem> |
| 232 |
</varlistentry> |
| 233 |
|
| 234 |
<varlistentry> |
| 235 |
<term><option>--exit-with-session</option></term> |
| 236 |
<listitem> |
| 237 |
<para> |
| 238 |
If this option is provided, a persistent "babysitter" process will |
| 239 |
be created, as if for --exit-with-x11. If it cannot connect to |
| 240 |
the X server, it will monitor the terminal from which dbus-launch |
| 241 |
was started instead, and if it gets a HUP on stdin, the message |
| 242 |
bus daemon will be killed. This option is not recommended, since |
| 243 |
it will consume input from the terminal where it was started; |
| 244 |
it is mainly provided for backwards compatibility. |
| 245 |
</para> |
| 246 |
</listitem> |
| 247 |
</varlistentry> |
| 248 |
|
| 249 |
<varlistentry> |
| 250 |
<term><option>--autolaunch=MACHINEID</option></term> |
| 251 |
<listitem> |
| 252 |
<para>This option implies that <command>dbus-launch</command> should scan for a |
| 253 |
previously-started session and reuse the values found there. If no |
| 254 |
session is found, it will start a new session. The |
| 255 |
--exit-with-session option is implied if --autolaunch is given. |
| 256 |
This option is for the exclusive use of libdbus, you do not want to |
| 257 |
use it manually. It may change in the future.</para> |
| 258 |
|
| 259 |
</listitem> |
| 260 |
</varlistentry> |
| 261 |
<varlistentry> |
| 262 |
<term><option>--sh-syntax</option></term> |
| 263 |
<listitem> |
| 264 |
<para>Emit Bourne-shell compatible code to set up environment variables.</para> |
| 265 |
|
| 266 |
</listitem> |
| 267 |
</varlistentry> |
| 268 |
<varlistentry> |
| 269 |
<term><option>--version</option></term> |
| 270 |
<listitem> |
| 271 |
<para>Print the version of dbus-launch</para> |
| 272 |
|
| 273 |
</listitem> |
| 274 |
</varlistentry> |
| 275 |
<varlistentry> |
| 276 |
<term><option>--help</option></term> |
| 277 |
<listitem> |
| 278 |
<para>Print the help info of dbus-launch</para> |
| 279 |
|
| 280 |
</listitem> |
| 281 |
</varlistentry> |
| 282 |
</variablelist> |
| 283 |
</refsect1> |
| 284 |
|
| 285 |
<refsect1 id='notes'><title>NOTES</title> |
| 286 |
<para>If you run |
| 287 |
<emphasis remap='B'>dbus-launch myapp</emphasis> |
| 288 |
(with any other options), dbus-daemon will |
| 289 |
<emphasis remap='I'>not</emphasis> |
| 290 |
exit when |
| 291 |
<emphasis remap='B'>myapp</emphasis> |
| 292 |
terminates: this is because |
| 293 |
<emphasis remap='B'>myapp</emphasis> |
| 294 |
is assumed to be part of a larger session, rather than a session in its |
| 295 |
own right.</para> |
| 296 |
|
| 297 |
</refsect1> |
| 298 |
|
| 299 |
<refsect1 id='author'><title>AUTHOR</title> |
| 300 |
<para>See <ulink url='https://dbus.freedesktop.org/doc/AUTHORS'>https://dbus.freedesktop.org/doc/AUTHORS</ulink></para> |
| 301 |
|
| 302 |
</refsect1> |
| 303 |
|
| 304 |
<refsect1 id='bugs'><title>BUGS</title> |
| 305 |
<para>Please send bug reports to the D-Bus mailing list or bug tracker, |
| 306 |
see <ulink url='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink></para> |
| 307 |
</refsect1> |
| 308 |
</refentry> |