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   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='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
 146 </refsect1>
 147
 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>
 151 </refsect1>
 152 </refentry>