Merge branch 'master' of git://anonscm.debian.org/pkg-utopia/dbus

Conflicts:
	debian/changelog
	debian/dbus.postinst

1 files changed, 288 insertions, 0 deletions

diff --git a/doc/dbus-launch.1.xml.in b/doc/dbus-launch.1.xml.in
new file mode 100644
index 00000000..31dd6eac
--- /dev/null
+++ b/doc/dbus-launch.1.xml.in
@@ -0,0 +1,288 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<refentry id='dbuslaunch1'>
+
+<!--  dbus&bsol;-launch manual page.
+ Copyright (C) 2003 Red Hat, Inc. -->
+
+<refmeta>
+<refentrytitle>dbus-launch</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+<refmiscinfo class="source">D-Bus</refmiscinfo>
+<refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>dbus-launch</refname>
+<refpurpose>Utility to start a message bus from a shell script</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>dbus-launch</command>
+    <arg choice='opt'>--version </arg>
+    <arg choice='opt'>--help </arg>
+    <arg choice='opt'>--sh-syntax </arg>
+    <arg choice='opt'>--csh-syntax </arg>
+    <arg choice='opt'>--auto-syntax </arg>
+    <arg choice='opt'>--binary-syntax </arg>
+    <arg choice='opt'>--close-stderr </arg>
+    <arg choice='opt'>--exit-with-session </arg>
+    <arg choice='opt'>--autolaunch=<replaceable>MACHINEID</replaceable></arg>
+    <arg choice='opt'>--config-file=<replaceable>FILENAME</replaceable></arg>
+    <arg choice='opt'><replaceable>PROGRAM</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>ARGS</replaceable></arg>
+    <sbr/>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The <command>dbus-launch</command> command is used to start a session bus
+instance of <emphasis remap='I'>dbus-daemon</emphasis> from a shell script.
+It would normally be called from a user's login
+scripts. Unlike the daemon itself, <command>dbus-launch</command> exits, so
+backticks or the $() construct can be used to read information from
+<command>dbus-launch</command>.</para>
+
+<para>With no arguments, <command>dbus-launch</command> will launch a session bus
+instance and print the address and PID of that instance to standard
+output.</para>
+
+<para>You may specify a program to be run; in this case, <command>dbus-launch</command>
+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.</para>
+
+<para>If you launch a program, <command>dbus-launch</command> will not print the
+information about the new bus to standard output.</para>
+
+<para>When <command>dbus-launch</command> 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 <command>dbus-launch</command> to emit shell code
+to set up the environment.</para>
+
+<para>With the --auto-syntax option, <command>dbus-launch</command> 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 explicitly 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.</para>
+
+
+<para>See <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink> for more information
+about D-Bus. See also the man page for <emphasis remap='I'>dbus-daemon</emphasis>.</para>
+
+</refsect1>
+
+<refsect1 id='examples'><title>EXAMPLES</title>
+<para>Distributions running
+<command>dbus-launch</command>
+as part of a standard X session should run
+<emphasis remap='B'>dbus-launch --exit-with-session</emphasis>
+after the X server has started and become available, as a wrapper around
+the "main" X client (typically a session manager or window manager), as in
+these examples:</para>
+
+  <blockquote remap='RS'>
+<para><emphasis remap='B'>dbus-launch --exit-with-session gnome-session</emphasis></para>
+
+<para><emphasis remap='B'>dbus-launch --exit-with-session openbox</emphasis></para>
+
+<para><emphasis remap='B'>dbus-launch --exit-with-session ~/.xsession</emphasis>
+  </para></blockquote> <!-- remap='RE' -->
+
+<para>If your distribution does not do this, you can achieve similar results
+by running your session or window manager in the same way in a script
+run by your X session, such as
+<filename>~/.xsession</filename>,
+<filename>~/.xinitrc</filename>
+or
+<filename>~/.Xclients</filename>.</para>
+
+<para>To start a D-Bus session within a text\(hymode session,
+  do not use <emphasis remap='B'>dbus-launch</emphasis>.
+  Instead, see <citerefentry><refentrytitle>dbus-run-session</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+</para>
+
+<literallayout remap='.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`
+      echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
+  fi
+</literallayout> <!-- .fi -->
+<para>Note that in this case, dbus-launch will exit, and dbus-daemon will not be
+terminated automatically on logout.</para>
+
+</refsect1>
+
+<refsect1 id='automatic_launching'><title>AUTOMATIC LAUNCHING</title>
+<para>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/</para>
+
+
+<para>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.</para>
+
+
+<para>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.</para>
+
+
+<para>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.</para>
+
+
+<para>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.)</para>
+
+
+<para>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.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The following options are supported:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><option>--auto-syntax</option></term>
+  <listitem>
+<para>Choose --csh-syntax or --sh-syntax based on the SHELL environment variable.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--binary-syntax</option></term>
+  <listitem>
+<para>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.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--close-stderr</option></term>
+  <listitem>
+<para>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.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--config-file=FILENAME</option></term>
+  <listitem>
+<para>Pass --config-file=FILENAME to the bus daemon, instead of passing it
+the --session argument. See the man page for dbus-daemon</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--csh-syntax</option></term>
+  <listitem>
+<para>Emit csh compatible code to set up environment variables.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--exit-with-session</option></term>
+  <listitem>
+<para>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.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--autolaunch=MACHINEID</option></term>
+  <listitem>
+<para>This option implies that <command>dbus-launch</command> 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.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--sh-syntax</option></term>
+  <listitem>
+<para>Emit Bourne-shell compatible code to set up environment variables.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--version</option></term>
+  <listitem>
+<para>Print the version of dbus-launch</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--help</option></term>
+  <listitem>
+<para>Print the help info of dbus-launch</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='notes'><title>NOTES</title>
+<para>If you run
+<emphasis remap='B'>dbus-launch myapp</emphasis>
+(with any other options), dbus-daemon will
+<emphasis remap='I'>not</emphasis>
+exit when
+<emphasis remap='B'>myapp</emphasis>
+terminates: this is because
+<emphasis remap='B'>myapp</emphasis>
+is assumed to be part of a larger session, rather than a session in its
+own right.</para>
+
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>See <ulink url='http://www.freedesktop.org/software/dbus/doc/AUTHORS'>http://www.freedesktop.org/software/dbus/doc/AUTHORS</ulink></para>
+
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+<para>Please send bug reports to the D-Bus mailing list or bug tracker,
+see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
+</refsect1>
+</refentry>