1 files changed, 183 insertions, 0 deletions
diff --git a/tools/dbus-launch.1 b/tools/dbus-launch.1
new file mode 100644
index 00000000..0ea19495
--- /dev/null
+++ b/tools/dbus-launch.1
@@ -0,0 +1,183 @@
+.\" 
+.\" dbus-launch manual page.
+.\" Copyright (C) 2003 Red Hat, Inc.
+.\"
+.TH dbus-launch 1
+.SH NAME
+dbus-launch \- Utility to start a message bus from a shell script
+.SH SYNOPSIS
+.PP
+.B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...]
+
+.SH DESCRIPTION
+
+The \fIdbus-launch\fP command is used to start a session bus 
+instance of \fIdbus-daemon\fP from a shell script.
+It would normally be called from a user's login
+scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so
+backticks or the $() construct can be used to read information from
+\fIdbus-launch\fP.
+
+With no arguments, \fIdbus-launch\fP 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, \fIdbus-launch\fP
+will launch a session bus instance, set the appropriate environment
+variables so the specified program can find the bus, and then execute the
+specified program, with the specified arguments.  See below for
+examples.
+
+If you launch a program, \fIdbus-launch\fP will not print the
+information about the new bus to standard output.
+
+When \fIdbus-launch\fP prints bus information to standard output, by
+default it is in a simple key-value pairs format. However, you may 
+request several alternate syntaxes using the \-\-sh-syntax, \-\-csh-syntax,
+\-\-binary-syntax, or
+\-\-auto-syntax options. Several of these cause \fIdbus-launch\fP to emit shell code
+to set up the environment.
+
+With the \-\-auto-syntax option, \fIdbus-launch\fP 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-syntax, 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.
+
+.PP
+See http://www.freedesktop.org/software/dbus/ for more information
+about D-Bus. See also the man page for \fIdbus-daemon\fP.
+
+.PP
+Here is an example of how to use \fIdbus-launch\fP with an 
+sh-compatible shell to start the per-session bus daemon:
+.nf
+
+  ## 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
+
+.fi
+You might run something like that in your login scripts.
+
+.PP
+Another way to use \fIdbus-launch\fP is to run your main session
+program, like so:
+.nf
+
+dbus-launch gnome-session
+
+.fi
+The above would likely be appropriate for ~/.xsession or ~/.Xclients.
+
+.SH AUTOMATIC LAUNCHING
+
+.PP
+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/
+
+.PP
+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.
+
+.PP
+There are two common reasons for autolaunch. One is ssh to a remote
+machine. The ideal fix for that would be forwarding of
+DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded.
+In the meantime, you can edit the session.conf config file to 
+have your session bus listen on TCP, and manually set
+DBUS_SESSION_BUS_ADDRESS, if you like.
+
+.PP
+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.
+
+.PP
+You can always avoid autolaunch by manually setting
+DBUS_SESSION_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_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if
+the first address doesn't work, processes will autolaunch. (The bus
+address variable contains a comma-separated list of addresses to try.)
+
+.PP
+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.
+
+.SH OPTIONS
+The following options are supported:
+.TP
+.I "--auto-syntax"
+Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable.
+
+.I "--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.
+
+.TP
+.I "--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.
+
+.TP
+.I "--config-file=FILENAME"
+Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it 
+the \-\-session argument. See the man page for dbus-daemon
+
+.TP
+.I "--csh-syntax"
+Emit csh compatible code to set up environment variables.
+
+.TP
+.I "--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.
+
+.TP
+.I "--autolaunch=MACHINEID"
+This option implies that \fIdbus-launch\fP should scan for a
+previously-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.
+
+.TP
+.I "--sh-syntax"
+Emit Bourne-shell compatible code to set up environment variables.
+
+.TP
+.I "--version"
+Print the version of dbus-launch
+
+.SH AUTHOR
+See http://www.freedesktop.org/software/dbus/doc/AUTHORS
+
+.SH BUGS
+Please send bug reports to the D-Bus mailing list or bug tracker,
+see http://www.freedesktop.org/software/dbus/