| 1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
| 2 |
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> |
| 4 |
<refentry id='dbusrunsession1'> |
| 5 |
<refmeta> |
| 6 |
<refentrytitle>dbus-run-session</refentrytitle> |
| 7 |
<manvolnum>1</manvolnum> |
| 8 |
<refmiscinfo class="manual">User Commands</refmiscinfo> |
| 9 |
<refmiscinfo class="source">D-Bus</refmiscinfo> |
| 10 |
<refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo> |
| 11 |
</refmeta> |
| 12 |
<refnamediv> |
| 13 |
<refname>dbus-run-session</refname> |
| 14 |
<refpurpose>start a process as a new D-Bus session</refpurpose> |
| 15 |
</refnamediv> |
| 16 |
<!-- body begins here --> |
| 17 |
<refsynopsisdiv id='synopsis'> |
| 18 |
<cmdsynopsis> |
| 19 |
<command>dbus-run-session</command> |
| 20 |
<arg choice='opt'><arg choice='plain'>--config-file </arg><arg choice='plain'><replaceable>FILENAME</replaceable></arg></arg> |
| 21 |
<arg choice='opt'><arg choice='plain'>--dbus-daemon </arg><arg choice='plain'><replaceable>BINARY</replaceable></arg></arg> |
| 22 |
<arg choice='opt'>-- </arg> |
| 23 |
<arg choice='plain'><replaceable>PROGRAM</replaceable></arg> |
| 24 |
<arg choice='opt' rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> |
| 25 |
</cmdsynopsis> |
| 26 |
<cmdsynopsis> |
| 27 |
<command>dbus-run-session</command> <arg choice='plain'>--help </arg> |
| 28 |
</cmdsynopsis> |
| 29 |
<cmdsynopsis> |
| 30 |
<command>dbus-run-session</command> <arg choice='plain'>--version </arg> |
| 31 |
</cmdsynopsis> |
| 32 |
</refsynopsisdiv> |
| 33 |
|
| 34 |
|
| 35 |
<refsect1 id='description'><title>DESCRIPTION</title> |
| 36 |
<para><command>dbus-run-session</command> |
| 37 |
is used to start a session bus instance of |
| 38 |
<emphasis remap='B'>dbus-daemon</emphasis> |
| 39 |
from a shell script, and start a specified program in that session. The |
| 40 |
<emphasis remap='B'>dbus-daemon</emphasis> |
| 41 |
will run for as long as the program does, after which it will terminate.</para> |
| 42 |
|
| 43 |
<para>One use is to run a shell with its own |
| 44 |
<emphasis remap='B'>dbus-daemon</emphasis> |
| 45 |
in a text‐mode or SSH session, and have the |
| 46 |
<emphasis remap='B'>dbus-daemon</emphasis> |
| 47 |
terminate automatically on leaving the sub‐shell, like this:</para> |
| 48 |
|
| 49 |
<para> dbus-run-session -- bash</para> |
| 50 |
|
| 51 |
<para>or to replace the login shell altogether, by combining <command>dbus-run-session</command> |
| 52 |
with the <emphasis remap='B'>exec</emphasis> builtin:</para> |
| 53 |
|
| 54 |
<para> exec dbus-run-session -- bash</para> |
| 55 |
|
| 56 |
<para>Another use is to run regression tests and similar things in an isolated |
| 57 |
D-Bus session, to avoid either interfering with the "real" D-Bus session |
| 58 |
or relying on there already being a D-Bus session active, for instance:</para> |
| 59 |
|
| 60 |
<para> dbus-run-session -- make check</para> |
| 61 |
|
| 62 |
<para>or (in |
| 63 |
<citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>):</para> |
| 64 |
|
| 65 |
<literallayout remap='.nf'> |
| 66 |
AM_TESTS_ENVIRONMENT = export MY_DEBUG=all; |
| 67 |
LOG_COMPILER = dbus-run-session |
| 68 |
AM_LOG_FLAGS = -- |
| 69 |
</literallayout></refsect1> |
| 70 |
|
| 71 |
<refsect1 id='options'><title>OPTIONS</title> |
| 72 |
<variablelist remap='TP'> |
| 73 |
<varlistentry> |
| 74 |
<term><option>--config-file=</option><replaceable>FILENAME</replaceable>, <option>--config-file</option> <replaceable>FILENAME</replaceable></term> |
| 75 |
<listitem> |
| 76 |
<para>Pass |
| 77 |
<option>--config-file=</option><replaceable>FILENAME</replaceable> |
| 78 |
to the bus daemon, instead of passing it the |
| 79 |
<option>--session</option> |
| 80 |
argument. See |
| 81 |
<citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> |
| 82 |
</listitem> |
| 83 |
</varlistentry> |
| 84 |
<varlistentry> |
| 85 |
<term><option>--dbus-daemon=</option><replaceable>BINARY</replaceable>, <option>--dbus-daemon</option> <replaceable>BINARY</replaceable></term> |
| 86 |
<listitem> |
| 87 |
<para>Run <emphasis remap='I'>BINARY</emphasis> as <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, instead of searching the <envar>PATH</envar> |
| 88 |
in the usual way for an executable called <emphasis remap='B'>dbus-daemon</emphasis>.</para> |
| 89 |
</listitem> |
| 90 |
</varlistentry> |
| 91 |
<varlistentry> |
| 92 |
<term><option>--help</option></term> |
| 93 |
<listitem> |
| 94 |
<para>Print usage information and exit.</para> |
| 95 |
</listitem> |
| 96 |
</varlistentry> |
| 97 |
<varlistentry> |
| 98 |
<term><option>--version</option></term> |
| 99 |
<listitem> |
| 100 |
<para>Print the version of dbus-run-session and exit.</para> |
| 101 |
</listitem> |
| 102 |
</varlistentry> |
| 103 |
</variablelist> |
| 104 |
</refsect1> |
| 105 |
|
| 106 |
<refsect1 id='exit_status'><title>EXIT STATUS</title> |
| 107 |
<para><command>dbus-run-session</command> |
| 108 |
exits with the exit status of |
| 109 |
<emphasis remap='I'>PROGRAM</emphasis>, |
| 110 |
0 if the |
| 111 |
<option>--help</option> or <option>--version</option> |
| 112 |
options were used, 127 on an error within |
| 113 |
<command>dbus-run-session</command> |
| 114 |
itself, or |
| 115 |
128+<emphasis remap='I'>n</emphasis> |
| 116 |
if the |
| 117 |
<emphasis remap='I'>PROGRAM</emphasis> |
| 118 |
was killed by signal |
| 119 |
<emphasis remap='I'>n</emphasis>.</para> |
| 120 |
</refsect1> |
| 121 |
|
| 122 |
<refsect1 id='environment'><title>ENVIRONMENT</title> |
| 123 |
<para><envar>PATH</envar> |
| 124 |
is searched to find |
| 125 |
<emphasis remap='I'>PROGRAM</emphasis>, |
| 126 |
and (if the --dbus-daemon option is not used or its argument does not |
| 127 |
contain a |
| 128 |
<emphasis remap='B'>/</emphasis> character) to find <emphasis remap='B'>dbus-daemon</emphasis>.</para> |
| 129 |
|
| 130 |
<para>The session bus' address is made available to |
| 131 |
<emphasis remap='I'>PROGRAM</emphasis> |
| 132 |
in the environment variable |
| 133 |
<emphasis remap='B'>DBUS_SESSION_BUS_ADDRESS</emphasis>.</para> |
| 134 |
|
| 135 |
<para>The variables |
| 136 |
<emphasis remap='B'>DBUS_SESSION_BUS_PID</emphasis>, |
| 137 |
<emphasis remap='B'>DBUS_SESSION_BUS_WINDOWID</emphasis>, |
| 138 |
<emphasis remap='B'>DBUS_STARTER_BUS_TYPE</emphasis> and |
| 139 |
<emphasis remap='B'>DBUS_STARTER_ADDRESS</emphasis> |
| 140 |
are removed from the environment, if present.</para> |
| 141 |
</refsect1> |
| 142 |
|
| 143 |
<refsect1 id='bugs'><title>BUGS</title> |
| 144 |
<para>Please send bug reports to the D-Bus mailing list or bug tracker, |
| 145 |
see <ulink url='https://www.freedesktop.org/wiki/Software/dbus/'>https://www.freedesktop.org/wiki/Software/dbus/</ulink></para> |
| 146 |
</refsect1> |
| 147 |
|
| 148 |
<refsect1 id='author'> |
| 149 |
<title>AUTHOR</title> |
| 150 |
<para>See <ulink url='https://dbus.freedesktop.org/doc/AUTHORS'>https://dbus.freedesktop.org/doc/AUTHORS</ulink></para> |
| 151 |
</refsect1> |
| 152 |
|
| 153 |
<refsect1 id='see_also'><title>SEE ALSO</title> |
| 154 |
<para><citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| 155 |
<citerefentry><refentrytitle>dbus-launch</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> |
| 156 |
</refsect1> |
| 157 |
</refentry> |