doc/dbus-run-session.1.xml.in

   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&hyphen;mode or SSH session, and have the
  46 <emphasis remap='B'>dbus-daemon</emphasis>
  47 terminate automatically on leaving the sub&hyphen;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     TESTS_ENVIRONMENT = MY_DEBUG=all dbus-run-session --
  67
  68 </literallayout></refsect1>
  69
  70 <refsect1 id='options'><title>OPTIONS</title>
  71 <variablelist remap='TP'>
  72   <varlistentry>
  73   <term><option>--config-file=</option><replaceable>FILENAME</replaceable>, <option>--config-file</option> <replaceable>FILENAME</replaceable></term>
  74   <listitem>
  75 <para>Pass
  76 <option>--config-file=</option><replaceable>FILENAME</replaceable>
  77 to the bus daemon, instead of passing it the
  78 <option>--session</option>
  79 argument. See
  80 <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  81   </listitem>
  82   </varlistentry>
  83   <varlistentry>
  84   <term><option>--dbus-daemon=</option><replaceable>BINARY</replaceable>, <option>--dbus-daemon</option> <replaceable>BINARY</replaceable></term>
  85   <listitem>
  86 <para>Run <emphasis remap='I'>BINARY</emphasis> as <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, instead of searching the <envar>PATH</envar>
  87 in the usual way for an executable called <emphasis remap='B'>dbus-daemon</emphasis>.</para>
  88   </listitem>
  89   </varlistentry>
  90   <varlistentry>
  91   <term><option>--help</option></term>
  92   <listitem>
  93 <para>Print usage information and exit.</para>
  94   </listitem>
  95   </varlistentry>
  96   <varlistentry>
  97   <term><option>--version</option></term>
  98   <listitem>
  99 <para>Print the version of dbus-run-session and exit.</para>
 100   </listitem>
 101   </varlistentry>
 102 </variablelist>
 103 </refsect1>
 104
 105 <refsect1 id='exit_status'><title>EXIT STATUS</title>
 106 <para><command>dbus-run-session</command>
 107 exits with the exit status of
 108 <emphasis remap='I'>PROGRAM</emphasis>,
 109 0 if the
 110 <option>--help</option> or <option>--version</option>
 111 options were used, 127 on an error within
 112 <command>dbus-run-session</command>
 113 itself, or
 114 128+<emphasis remap='I'>n</emphasis>
 115 if the
 116 <emphasis remap='I'>PROGRAM</emphasis>
 117 was killed by signal
 118 <emphasis remap='I'>n</emphasis>.</para>
 119 </refsect1>
 120
 121 <refsect1 id='environment'><title>ENVIRONMENT</title>
 122 <para><envar>PATH</envar>
 123 is searched to find
 124 <emphasis remap='I'>PROGRAM</emphasis>,
 125 and (if the --dbus-daemon option is not used or its argument does not
 126 contain a
 127 <emphasis remap='B'>/</emphasis> character) to find <emphasis remap='B'>dbus-daemon</emphasis>.</para>
 128
 129 <para>The session bus' address is made available to
 130 <emphasis remap='I'>PROGRAM</emphasis>
 131 in the environment variable
 132 <emphasis remap='B'>DBUS_SESSION_BUS_ADDRESS</emphasis>.</para>
 133
 134 <para>The variables
 135   <emphasis remap='B'>DBUS_SESSION_BUS_PID</emphasis>,
 136   <emphasis remap='B'>DBUS_SESSION_BUS_WINDOWID</emphasis>,
 137   <emphasis remap='B'>DBUS_STARTER_BUS_TYPE</emphasis> and
 138   <emphasis remap='B'>DBUS_STARTER_ADDRESS</emphasis>
 139   are removed from the environment, if present.</para>
 140 </refsect1>
 141
 142 <refsect1 id='bugs'><title>BUGS</title>
 143 <para>Please send bug reports to the D-Bus mailing list or bug tracker,
 144 see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
 145 </refsect1>
 146
 147 <refsect1 id='see_also'><title>SEE ALSO</title>
 148 <para><citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149 <citerefentry><refentrytitle>dbus-launch</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
 150 </refsect1>
 151 </refentry>