doc/dbus-launch.1

   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] [\-\-exit\-with\-x11] [\-\-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 explicitly 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 .SH EXAMPLES
  55
  56 Distributions running
  57 .B dbus\-launch
  58 as part of a standard X session should run
  59 .B "dbus\-launch \-\-exit\-with\-x11"
  60 after the X server has started and become available, as a wrapper around
  61 the "main" X client (typically a session manager or window manager), as in
  62 these examples:
  63
  64 .RS
  65 .B "dbus\-launch \-\-exit\-with\-x11 gnome\-session"
  66
  67 .B "dbus\-launch \-\-exit\-with\-x11 openbox"
  68
  69 .B "dbus\-launch \-\-exit\-with\-x11 ~/.xsession"
  70 .RE
  71
  72 If your distribution does not do this, you can achieve similar results
  73 by running your session or window manager in the same way in a script
  74 run by your X session, such as
  75 .BR ~/.xsession ,
  76 .B ~/.xinitrc
  77 or
  78 .BR ~/.Xclients .
  79
  80 To start a D-Bus session within a text-mode session, you can run
  81 dbus-launch in the background. For instance, in a sh-compatible shell:
  82
  83 .nf
  84   ## test for an existing bus daemon, just to be safe
  85   if test \-z "$DBUS_SESSION_BUS_ADDRESS" ; then
  86       ## if not found, launch a new one
  87       eval `dbus\-launch \-\-sh\-syntax`
  88       echo "D\-Bus per\-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
  89   fi
  90 .fi
  91 Note that in this case, dbus-launch will exit, and dbus-daemon will not be
  92 terminated automatically on logout.
  93
  94 .SH AUTOMATIC LAUNCHING
  95
  96 .PP
  97 If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use
  98 D\-Bus, by default the process will attempt to invoke dbus\-launch with
  99 the \-\-autolaunch option to start up a new session bus or find the
 100 existing bus address on the X display or in a file in
 101 ~/.dbus/session\-bus/
 102
 103 .PP
 104 Whenever an autolaunch occurs, the application that had to
 105 start a new bus will be in its own little world; it can effectively
 106 end up starting a whole new session if it tries to use a lot of
 107 bus services. This can be suboptimal or even totally broken, depending
 108 on the app and what it tries to do.
 109
 110 .PP
 111 There are two common reasons for autolaunch. One is ssh to a remote
 112 machine. The ideal fix for that would be forwarding of
 113 DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded.
 114 In the meantime, you can edit the session.conf config file to
 115 have your session bus listen on TCP, and manually set
 116 DBUS_SESSION_BUS_ADDRESS, if you like.
 117
 118 .PP
 119 The second common reason for autolaunch is an su to another user, and
 120 display of X applications running as the second user on the display
 121 belonging to the first user. Perhaps the ideal fix in this case
 122 would be to allow the second user to connect to the session bus of the
 123 first user, just as they can connect to the first user's display.
 124 However, a mechanism for that has not been coded.
 125
 126 .PP
 127 You can always avoid autolaunch by manually setting
 128 DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default
 129 address if none is set is "autolaunch:", so if any other address is
 130 set there will be no autolaunch. You can however include autolaunch in
 131 an explicit session bus address as a fallback, for example
 132 DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" \- in that case if
 133 the first address doesn't work, processes will autolaunch. (The bus
 134 address variable contains a comma\-separated list of addresses to try.)
 135
 136 .PP
 137 The \-\-autolaunch option is considered an internal implementation
 138 detail of libdbus, and in fact there are plans to change it. There's
 139 no real reason to use it outside of the libdbus implementation anyhow.
 140
 141 .SH OPTIONS
 142 The following options are supported:
 143 .TP
 144 .I "\-\-auto\-syntax"
 145 Choose \-\-csh\-syntax or \-\-sh\-syntax based on the SHELL environment variable.
 146
 147 .I "\-\-binary\-syntax"
 148 Write to stdout a nul\-terminated bus address, then the bus PID as a
 149 binary integer of size sizeof(pid_t), then the bus X window ID as a
 150 binary integer of size sizeof(long). Integers are in the machine's
 151 byte order, not network byte order or any other canonical byte order.
 152
 153 .TP
 154 .I "\-\-close\-stderr"
 155 Close the standard error output stream before starting the D\-Bus
 156 daemon. This is useful if you want to capture dbus\-launch error
 157 messages but you don't want dbus\-daemon to keep the stream open to
 158 your application.
 159
 160 .TP
 161 .I "\-\-config\-file=FILENAME"
 162 Pass \-\-config\-file=FILENAME to the bus daemon, instead of passing it
 163 the \-\-session argument. See the man page for dbus\-daemon
 164
 165 .TP
 166 .I "\-\-csh\-syntax"
 167 Emit csh compatible code to set up environment variables.
 168
 169 .TP
 170 .I \-\-exit\-with\-x11
 171 If this option is provided, a persistent "babysitter" process will be
 172 created, and will connect to the X server. If it cannot do so, launching
 173 fails. If the "babysitter" process loses its X connection,
 174 it kills the message bus daemon, disconnecting all of its clients (which
 175 should exit in response). This avoids having leftover daemon
 176 processes from a user X session, after the X session has ended.
 177
 178 .TP
 179 .I \-\-exit\-with\-session
 180 If this option is provided, a persistent "babysitter" process will be
 181 created, as if for
 182 .BR \-\-exit\-with\-x11 .
 183 If it cannot connect to the X server, it will monitor the terminal from which
 184 .B dbus-launch
 185 was started instead, and if it gets a HUP on stdin, the message bus daemon
 186 will be killed. This option is not recommended, since it will consume input
 187 from the terminal where it was started; it is mainly provided for
 188 backwards compatibility.
 189
 190 .TP
 191 .I "\-\-autolaunch=MACHINEID"
 192 This option implies that \fIdbus\-launch\fP should scan for a
 193 previously\-started session and reuse the values found there. If no
 194 session is found, it will start a new session. The
 195 \-\-exit\-with\-session option is implied if \-\-autolaunch is given.
 196 This option is for the exclusive use of libdbus, you do not want to
 197 use it manually. It may change in the future.
 198
 199 .TP
 200 .I "\-\-sh\-syntax"
 201 Emit Bourne\-shell compatible code to set up environment variables.
 202
 203 .TP
 204 .I "\-\-version"
 205 Print the version of dbus\-launch
 206
 207 .SH NOTES
 208
 209 If you run
 210 .B "dbus\-launch myapp"
 211 (with any other options), dbus\-daemon will
 212 .I not
 213 exit when
 214 .B myapp
 215 terminates: this is because
 216 .B myapp
 217 is assumed to be part of a larger session, rather than a session in its
 218 own right.
 219
 220 .SH AUTHOR
 221 See http://www.freedesktop.org/software/dbus/doc/AUTHORS
 222
 223 .SH BUGS
 224 Please send bug reports to the D\-Bus mailing list or bug tracker,
 225 see http://www.freedesktop.org/software/dbus/