2006-10-01 Havoc Pennington <hp@redhat.com>

	* tools/dbus-launch.c (print_variables): if no syntax is given,
	don't print something that's sort-of-half-sh-syntax, just print
	a plain key-value pairs thing.

	* tools/dbus-launch-x11.c: use machine ID rather than hostname for
	the local machine representation (but still have the hostname in
	the display). Remove the hostname from the display if it is
	localhost. Change session files to be named
	~/.dbus/session-bus/machine-display. Change X atoms to be
	underscore-prefixed so nobody whines about ICCCM compliance.
	Otherwise name them the same as the env variables.
	Change session file format to include key-value pairs and an
	explanatory comment. Keys are the same as the env variables.
	(set_address_in_x11): X property format can't depend on
	sizeof(pid_t) on a particular machine, fix to always be 32 bits

	* tools/dbus-launch.c: make --autolaunch take a machine id
	argument. If --autolaunch is used with a program to run, complain
	for now (but add a FIXME). Also, don't look for existing bus if
	there's a program to run (but add a FIXME).

	* dbus/dbus-sysdeps-unix.c (_dbus_get_autolaunch_address): pass
	machine uuid to dbus-launch (avoids linking dbus-launch to libdbus
	just to get this, and avoids duplicating uuid-reading code).

	* tools/dbus-launch.1: clarify various things

1 files changed, 68 insertions, 10 deletions

diff --git a/tools/dbus-launch.1 b/tools/dbus-launch.1
index 3c505e7b..bcc30d7c 100644
--- a/tools/dbus-launch.1
+++ b/tools/dbus-launch.1
@@ -7,27 +7,36 @@
 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] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...]
+.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 \fIdbus-daemon\fP
-from a shell script. It would normally be called from a user's login
+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 simply print the values of
-DBUS_SESSION_BUS_ADDRESS and DBUS_SESSION_BUS_PID.
+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 then set the appropriate environment variables and execute the
+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.
 
-Finally, you may use the \-\-sh-syntax, \-\-csh-syntax, or
-\-\-auto-syntax commands to cause \fIdbus-launch\fP to emit shell code
-to set up the environment.  This is useful in shell scripts.
+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
@@ -67,12 +76,60 @@ 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.)
+
 .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 "--config-file=FILENAME"
 Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it 
@@ -90,11 +147,12 @@ server. If this process gets a HUP on stdin or loses its X connection,
 it kills the message bus daemon.
 
 .TP
-.I "--autolaunch"
+.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 used by libdbus, you probably do not want to use it manually.
 
 .TP
 .I "--sh-syntax"