Add dbus-run-session

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=39196
Reviewed-by: Colin Walters <walters@verbum.org>

2 files changed, 102 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 35725696..0c6b6fdf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,6 +15,7 @@ man1_MANS = \
 	dbus-daemon.1 \
 	dbus-launch.1 \
 	dbus-monitor.1 \
+	dbus-run-session.1 \
 	dbus-send.1 \
 	dbus-uuidgen.1
 endif
@@ -24,6 +25,7 @@ MAN_HTML_FILES = \
 	dbus-daemon.1.html \
 	dbus-launch.1.html \
 	dbus-monitor.1.html \
+	dbus-run-session.1.html \
 	dbus-send.1.html \
 	dbus-uuidgen.1.html
 
diff --git a/doc/dbus-run-session.1 b/doc/dbus-run-session.1
new file mode 100644
index 00000000..8b270ebe
--- /dev/null
+++ b/doc/dbus-run-session.1
@@ -0,0 +1,100 @@
+.TH dbus\-run\-session 1
+.SH NAME
+dbus\-run\-session \- start a process as a new D-Bus session
+.SH SYNOPSIS
+.B dbus\-run\-session
+.RB [ \-\-config\-file
+.IR FILENAME ]
+.RB [ \-\-dbus\-daemon
+.IR BINARY ]
+.RB [ \-\- ]
+.IR PROGRAM " [" ARGUMENTS ...]
+.P
+.B dbus\-run\-session \-\-help
+.P
+.B dbus\-run\-session \-\-version
+.SH DESCRIPTION
+.B dbus\-run\-session
+is used to start a session bus instance of
+.B dbus\-daemon
+from a shell script, and start a specified program in that session. The
+.B dbus\-daemon
+will run for as long as the program does, after which it will terminate.
+.P
+One use is to run a shell with its own
+.B dbus\-daemon
+in a text\(hymode or SSH session, and have the
+.B dbus\-daemon
+terminate automatically on leaving the sub\(hyshell, like this:
+.P
+    dbus\-run\-session \-\- bash
+.P
+or to replace the login shell altogether, by combining \fBdbus\-run\-session\fR
+with the \fBexec\fR builtin:
+.P
+    exec dbus\-run\-session \-\- bash
+.P
+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:
+.P
+    dbus\-run\-session \-\- make check
+.P
+or (in
+.BR automake (1)):
+.P
+.nf
+    TESTS_ENVIRONMENT = MY_DEBUG=all dbus\-run\-session \-\-
+.fi
+.P
+.SH OPTIONS
+.TP
+\fB\-\-config\-file=\fIFILENAME\fR, \fB\-\-config\-file\fR \fIFILENAME\fR
+Pass
+.BI \-\-config-file= FILENAME
+to the bus daemon, instead of passing it the
+.B \-\-session
+argument. See
+.BR dbus-daemon (1).
+.TP
+\fB\-\-dbus\-daemon=\fIBINARY\fR, \fB\-\-dbus\-daemon\fR \fIBINARY\fR
+Run \fIBINARY\fR as \fBdbus\-daemon\fR(1), instead of searching the \fBPATH\fR
+in the usual way for an executable called \fBdbus\-daemon\fR.
+.TP
+.B \-\-help
+Print usage information and exit.
+.TP
+.B \-\-version
+Print the version of dbus\-run\-session and exit.
+.SH EXIT STATUS
+.B dbus\-run\-session
+exits with the exit status of
+.IR PROGRAM ,
+0 if the
+.BR \-\-help " or " \-\-version
+options were used, 127 on an error within
+.B dbus\-run\-session
+itself, or
+.RI 128+ n
+if the
+.I PROGRAM
+was killed by signal
+.IR n .
+.SH ENVIRONMENT
+.B PATH
+is searched to find
+.IR PROGRAM ,
+and (if the \-\-dbus\-daemon option is not used or its argument does not
+contain a
+.BR / " character) to find " dbus\-daemon .
+.P
+The session bus' address is made available to
+.I PROGRAM
+in the environment variable
+.BR DBUS_SESSION_BUS_ADDRESS .
+.SH BUGS
+Please send bug reports to the D\-Bus mailing list or bug tracker,
+see http://www.freedesktop.org/software/dbus/
+.SH SEE ALSO
+.BR dbus\-daemon (1),
+.BR dbus\-launch (1)