tools/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] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...]
  11
  12 .SH DESCRIPTION
  13
  14 The \fIdbus-launch\fP command is used to start \fIdbus-daemon\fP
  15 from a shell script. It would normally be called from a user's login
  16 scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so
  17 backticks or the $() construct can be used to read information from
  18 \fIdbus-launch\fP.
  19
  20 With no arguments, \fIdbus-launch\fP will simply print the values of
  21 DBUS_SESSION_BUS_ADDRESS and DBUS_SESSION_BUS_PID.
  22
  23 You may specify a program to be run; in this case, \fIdbus-launch\fP
  24 will then set the appropriate environment variables and execute the
  25 specified program, with the specified arguments.  See below for
  26 examples.
  27
  28 Finally, you may use the \-\-sh-syntax, \-\-csh-syntax, or
  29 \-\-auto-syntax commands to cause \fIdbus-launch\fP to emit shell code
  30 to set up the environment.  This is useful in shell scripts.
  31
  32 With the \-\-auto-syntax option, \fIdbus-launch\fP looks at the value
  33 of the SHELL environment variable to determine which shell syntax
  34 should be used.  If SHELL ends in "csh", then csh-compatible code is
  35 emitted; otherwise Bourne shell code is emitted.  Instead of passing
  36 \-\-auto-syntax, you may explicity specify a particular one by using
  37 \-\-sh-syntax for Bourne syntax, or \-\-csh-syntax for csh syntax.
  38 In scripts, it's more robust to avoid \-\-auto-syntax and you hopefully
  39 know which shell your script is written in.
  40
  41 .PP
  42 See http://www.freedesktop.org/software/dbus/ for more information
  43 about D-BUS. See also the man page for \fIdbus-daemon\fP.
  44
  45 .PP
  46 Here is an example of how to use \fIdbus-launch\fP with an
  47 sh-compatible shell to start the per-session bus daemon:
  48 .nf
  49
  50   ## test for an existing bus daemon, just to be safe
  51   if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
  52       ## if not found, launch a new one
  53       eval `dbus-launch --sh-syntax --exit-with-session`
  54       echo "D-BUS per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
  55   fi
  56
  57 .fi
  58 You might run something like that in your login scripts.
  59
  60 .PP
  61 Another way to use \fIdbus-launch\fP is to run your main session
  62 program, like so:
  63 .nf
  64
  65 dbus-launch gnome-session
  66
  67 .fi
  68 The above would likely be appropriate for ~/.xsession or ~/.Xclients.
  69
  70 .SH OPTIONS
  71 The following options are supported:
  72 .TP
  73 .I "--auto-syntax"
  74 Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable.
  75
  76 .TP
  77 .I "--config-file=FILENAME"
  78 Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it
  79 the \-\-session argument. See the man page for dbus-daemon
  80
  81 .TP
  82 .I "--csh-syntax"
  83 Emit csh compatible code to set up environment variables.
  84
  85 .TP
  86 .I "--exit-with-session"
  87 If this option is provided, a persistent "babysitter" process will be
  88 created that watches stdin for HUP and tries to connect to the X
  89 server. If this process gets a HUP on stdin or loses its X connection,
  90 it kills the message bus daemon.
  91
  92 .TP
  93 .I "--sh-syntax"
  94 Emit Bourne-shell compatible code to set up environment variables.
  95
  96 .TP
  97 .I "--version"
  98 Print the version of dbus-launch
  99
 100 .SH AUTHOR
 101 See http://www.freedesktop.org/software/dbus/doc/AUTHORS
 102
 103 .SH BUGS
 104 Please send bug reports to the D-BUS mailing list or bug tracker,
 105 see http://www.freedesktop.org/software/dbus/