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