diff options
Diffstat (limited to 'doc/dbus-run-session.1.xml.in')
| -rw-r--r-- | doc/dbus-run-session.1.xml.in | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/dbus-run-session.1.xml.in b/doc/dbus-run-session.1.xml.in new file mode 100644 index 00000000..5181a8b1 --- /dev/null +++ b/doc/dbus-run-session.1.xml.in @@ -0,0 +1,151 @@ +<?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='dbusrunsession1'> +<refmeta> +<refentrytitle>dbus-run-session</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-run-session</refname> +<refpurpose>start a process as a new D-Bus session</refpurpose> +</refnamediv> +<!-- body begins here --> +<refsynopsisdiv id='synopsis'> +<cmdsynopsis> + <command>dbus-run-session</command> + <arg choice='opt'><arg choice='plain'>--config-file </arg><arg choice='plain'><replaceable>FILENAME</replaceable></arg></arg> + <arg choice='opt'><arg choice='plain'>--dbus-daemon </arg><arg choice='plain'><replaceable>BINARY</replaceable></arg></arg> + <arg choice='opt'>-- </arg> + <arg choice='plain'><replaceable>PROGRAM</replaceable></arg> + <arg choice='opt' rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> +</cmdsynopsis> +<cmdsynopsis> + <command>dbus-run-session</command> <arg choice='plain'>--help </arg> +</cmdsynopsis> +<cmdsynopsis> + <command>dbus-run-session</command> <arg choice='plain'>--version </arg> +</cmdsynopsis> +</refsynopsisdiv> + + +<refsect1 id='description'><title>DESCRIPTION</title> +<para><command>dbus-run-session</command> +is used to start a session bus instance of +<emphasis remap='B'>dbus-daemon</emphasis> +from a shell script, and start a specified program in that session. The +<emphasis remap='B'>dbus-daemon</emphasis> +will run for as long as the program does, after which it will terminate.</para> + +<para>One use is to run a shell with its own +<emphasis remap='B'>dbus-daemon</emphasis> +in a text‐mode or SSH session, and have the +<emphasis remap='B'>dbus-daemon</emphasis> +terminate automatically on leaving the sub‐shell, like this:</para> + +<para> dbus-run-session -- bash</para> + +<para>or to replace the login shell altogether, by combining <command>dbus-run-session</command> +with the <emphasis remap='B'>exec</emphasis> builtin:</para> + +<para> exec dbus-run-session -- bash</para> + +<para>Another use is to run regression tests and similar things in an isolated +D-Bus session, to avoid either interfering with the "real" D-Bus session +or relying on there already being a D-Bus session active, for instance:</para> + +<para> dbus-run-session -- make check</para> + +<para>or (in +<citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>):</para> + +<literallayout remap='.nf'> + TESTS_ENVIRONMENT = MY_DEBUG=all dbus-run-session -- + +</literallayout></refsect1> + +<refsect1 id='options'><title>OPTIONS</title> +<variablelist remap='TP'> + <varlistentry> + <term><option>--config-file=</option><replaceable>FILENAME</replaceable>, <option>--config-file</option> <replaceable>FILENAME</replaceable></term> + <listitem> +<para>Pass +<option>--config-file=</option><replaceable>FILENAME</replaceable> +to the bus daemon, instead of passing it the +<option>--session</option> +argument. See +<citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--dbus-daemon=</option><replaceable>BINARY</replaceable>, <option>--dbus-daemon</option> <replaceable>BINARY</replaceable></term> + <listitem> +<para>Run <emphasis remap='I'>BINARY</emphasis> as <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, instead of searching the <envar>PATH</envar> +in the usual way for an executable called <emphasis remap='B'>dbus-daemon</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> +<para>Print usage information and exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem> +<para>Print the version of dbus-run-session and exit.</para> + </listitem> + </varlistentry> +</variablelist> +</refsect1> + +<refsect1 id='exit_status'><title>EXIT STATUS</title> +<para><command>dbus-run-session</command> +exits with the exit status of +<emphasis remap='I'>PROGRAM</emphasis>, +0 if the +<option>--help</option> or <option>--version</option> +options were used, 127 on an error within +<command>dbus-run-session</command> +itself, or +128+<emphasis remap='I'>n</emphasis> +if the +<emphasis remap='I'>PROGRAM</emphasis> +was killed by signal +<emphasis remap='I'>n</emphasis>.</para> +</refsect1> + +<refsect1 id='environment'><title>ENVIRONMENT</title> +<para><envar>PATH</envar> +is searched to find +<emphasis remap='I'>PROGRAM</emphasis>, +and (if the --dbus-daemon option is not used or its argument does not +contain a +<emphasis remap='B'>/</emphasis> character) to find <emphasis remap='B'>dbus-daemon</emphasis>.</para> + +<para>The session bus' address is made available to +<emphasis remap='I'>PROGRAM</emphasis> +in the environment variable +<emphasis remap='B'>DBUS_SESSION_BUS_ADDRESS</emphasis>.</para> + +<para>The variables + <emphasis remap='B'>DBUS_SESSION_BUS_PID</emphasis>, + <emphasis remap='B'>DBUS_SESSION_BUS_WINDOWID</emphasis>, + <emphasis remap='B'>DBUS_STARTER_BUS_TYPE</emphasis> and + <emphasis remap='B'>DBUS_STARTER_ADDRESS</emphasis> + are removed from the environment, if present.</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> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para><citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>dbus-launch</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> +</refsect1> +</refentry> |