309 lines
12 KiB
XML
309 lines
12 KiB
XML
<?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'>--exit-with-x11 </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='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/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-mode 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-x11</option></term>
|
|
<listitem>
|
|
<para>If this option is provided, a persistent "babysitter" process
|
|
will be created, and will connect to the X server. If it cannot
|
|
do so, launching fails. If the "babysitter" process loses its
|
|
X connection, it kills the message bus daemon, disconnecting
|
|
all of its clients (which should exit in response). This avoids
|
|
having leftover daemon processes from a user X session, after
|
|
the X session has ended.</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, as if for --exit-with-x11. If it cannot connect to
|
|
the X server, it will monitor the terminal from which dbus-launch
|
|
was started instead, and if it gets a HUP on stdin, the message
|
|
bus daemon will be killed. This option is not recommended, since
|
|
it will consume input from the terminal where it was started;
|
|
it is mainly provided for backwards compatibility.
|
|
</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='https://dbus.freedesktop.org/doc/AUTHORS'>https://dbus.freedesktop.org/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='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink></para>
|
|
</refsect1>
|
|
</refentry>
|