dbus-launch

dbus-launch(1)                                                  dbus-launch(1)



NAME
       dbus-launch - Utility to start a message bus from a shell script

SYNOPSIS
       dbus-launch  [--version]  [--sh-syntax]  [--csh-syntax] [--auto-syntax]
       [--exit-with-session] [--autolaunch=MACHINEID] [--config-file=FILENAME]
       [PROGRAM] [ARGS...]


DESCRIPTION
       The  dbus-launch  command  is  used  to start a session bus instance of
       dbus-daemon from a shell script.  It would normally be  called  from  a
       user's  login  scripts. Unlike the daemon itself, dbus-launch exits, so
       backticks or the $() construct can be used  to  read  information  from
       dbus-launch.

       With  no  arguments, dbus-launch 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,  dbus-launch  will
       launch  a  session  bus instance, set the appropriate environment vari‐
       ables so the specified program can find the bus, and then  execute  the
       specified  program,  with the specified arguments.  See below for exam‐
       ples.

       If you launch a program, dbus-launch will  not  print  the  information
       about the new bus to standard output.

       When  dbus-launch prints bus information to standard output, by default
       it is in a simple key-value pairs format. However, you may request sev‐
       eral  alternate syntaxes using the --sh-syntax, --csh-syntax, --binary-
       syntax, or --auto-syntax options. Several of these cause dbus-launch to
       emit shell code to set up the environment.

       With  the  --auto-syntax  option, dbus-launch 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-syn‐
       tax,  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.


       See  http://www.freedesktop.org/software/dbus/  for  more   information
       about D-Bus. See also the man page for dbus-daemon.


       Here  is  an  example  of  how to use dbus-launch with an sh-compatible
       shell to start the per-session bus daemon:

         ## 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

       You might run something like that in your login scripts.


       Another way to use dbus-launch is to run  your  main  session  program,
       like so:

       dbus-launch gnome-session

       The above would likely be appropriate for ~/.xsession or ~/.Xclients.


AUTOMATIC LAUNCHING
       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/


       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.


       There  are  two  common  reasons for autolaunch. One is ssh to a remote
       machine. The ideal fix  for  that  would  be  forwarding  of  DBUS_SES‐
       SION_BUS_ADDRESS  in  the  same  way that DISPLAY is forwarded.  In the
       meantime, you can edit the session.conf config file to have  your  ses‐
       sion  bus  listen on TCP, and manually set DBUS_SESSION_BUS_ADDRESS, if
       you like.


       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.


       You   can   always  avoid  autolaunch  by  manually  setting  DBUS_SES‐
       SION_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_SES‐
       SION_BUS_ADDRESS="something:,autolaunch:" - in that case if  the  first
       address doesn't work, processes will autolaunch. (The bus address vari‐
       able contains a comma-separated list of addresses to try.)


       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.


OPTIONS
       The following options are supported:

       --auto-syntax
              Choose --csh-syntax or --sh-syntax based on the  SHELL  environ‐
              ment variable.

              --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.


       --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.


       --config-file=FILENAME
              Pass --config-file=FILENAME to the bus daemon, instead of  pass‐
              ing it the --session argument. See the man page for dbus-daemon


       --csh-syntax
              Emit csh compatible code to set up environment variables.


       --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.


       --autolaunch=MACHINEID
              This option implies that dbus-launch should scan  for  a  previ‐
              ously-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.


       --sh-syntax
              Emit  Bourne-shell  compatible  code to set up environment vari‐
              ables.


       --version
              Print the version of dbus-launch


AUTHOR
       See http://www.freedesktop.org/software/dbus/doc/AUTHORS


BUGS
       Please send bug reports to the D-Bus mailing list or bug  tracker,  see
       http://www.freedesktop.org/software/dbus/



                                                                dbus-launch(1)