diff options
Diffstat (limited to 'doc/dbus-launch.1.xml.in')
| -rw-r--r-- | doc/dbus-launch.1.xml.in | 288 |
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\-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> |