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'>
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>
13 <refname>dbus-run-session</refname>
14 <refpurpose>start a process as a new D-Bus session</refpurpose>
16 <!-- body begins here -->
17 <refsynopsisdiv id='synopsis'>
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>
27 <command>dbus-run-session</command> <arg choice='plain'>--help </arg>
30 <command>dbus-run-session</command> <arg choice='plain'>--version </arg>
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>
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>
49 <para> dbus-run-session -- bash</para>
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>
54 <para> exec dbus-run-session -- bash</para>
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>
60 <para> dbus-run-session -- make check</para>
63 <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>):</para>
65 <literallayout remap='.nf'>
66 AM_TESTS_ENVIRONMENT = export MY_DEBUG=all;
67 LOG_COMPILER = dbus-run-session
69 </literallayout></refsect1>
71 <refsect1 id='options'><title>OPTIONS</title>
72 <variablelist remap='TP'>
74 <term><option>--config-file=</option><replaceable>FILENAME</replaceable>, <option>--config-file</option> <replaceable>FILENAME</replaceable></term>
77 <option>--config-file=</option><replaceable>FILENAME</replaceable>
78 to the bus daemon, instead of passing it the
79 <option>--session</option>
81 <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
85 <term><option>--dbus-daemon=</option><replaceable>BINARY</replaceable>, <option>--dbus-daemon</option> <replaceable>BINARY</replaceable></term>
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>
92 <term><option>--help</option></term>
94 <para>Print usage information and exit.</para>
98 <term><option>--version</option></term>
100 <para>Print the version of dbus-run-session and exit.</para>
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>,
111 <option>--help</option> or <option>--version</option>
112 options were used, 127 on an error within
113 <command>dbus-run-session</command>
115 128+<emphasis remap='I'>n</emphasis>
117 <emphasis remap='I'>PROGRAM</emphasis>
119 <emphasis remap='I'>n</emphasis>.</para>
122 <refsect1 id='environment'><title>ENVIRONMENT</title>
123 <para><envar>PATH</envar>
125 <emphasis remap='I'>PROGRAM</emphasis>,
126 and (if the --dbus-daemon option is not used or its argument does not
128 <emphasis remap='B'>/</emphasis> character) to find <emphasis remap='B'>dbus-daemon</emphasis>.</para>
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>
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>
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='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
148 <refsect1 id='see_also'><title>SEE ALSO</title>
149 <para><citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
150 <citerefentry><refentrytitle>dbus-launch</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>