From ba4a31b7a61cc730b7cbc10948d4f1d6d78d93c7 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 14 Dec 2020 13:23:00 +0100
Subject: [PATCH] man: document new ability to connect to user of container

---
 man/sd_bus_default.xml      | 22 ++++++++++++++++++++--
 man/user-system-options.xml | 10 ++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 4ae26414eb..768a386160 100644
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -24,6 +24,7 @@
     <refname>sd_bus_open_with_description</refname>
     <refname>sd_bus_open_user</refname>
     <refname>sd_bus_open_user_with_description</refname>
+    <refname>sd_bus_open_user_machine</refname>
     <refname>sd_bus_open_system</refname>
     <refname>sd_bus_open_system_with_description</refname>
     <refname>sd_bus_open_system_remote</refname>
@@ -73,6 +74,12 @@
         <paramdef>const char *<parameter>description</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_user_machine</function></funcdef>
+        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>machine</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_open_system</function></funcdef>
         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
@@ -187,14 +194,24 @@
     work for the root user on the remote machine.</para>
 
     <para><function>sd_bus_open_system_machine()</function> connects to the system bus in the specified
-    <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local
-    container. See
+    <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local container,
+    possibly prefixed by a user name and a separating <literal>@</literal>. If the container name is
+    specified as the special string <literal>.host</literal> the connection is made to the local system. This
+    is useful to connect to the local system bus as specific user, e.g. <literal>foobar@.host</literal> to
+    connect to the local system bus as local user <literal>foobar</literal>. If the <literal>@</literal>
+    syntax is used either the left-hand side or the right-hand side may be ommited (but not both) in which
+    case the local user name or <literal>.host</literal> is implied. If the <literal>@</literal> syntax is
+    not used the connection is always made as root user. See
     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     for a description of the address syntax, and
     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more
     information about the "machine" concept. Note that connections into local containers are only available
     to privileged processes at this time.</para>
 
+    <para><function>sd_bus_open_user_machine()</function> is similar to
+    <function>sd_bus_open_system_machine()</function>, but connects to the user bus of the root user, or if
+    the <literal>@</literal> syntax is used, of the specified user.</para>
+
     <para>These calls allocate a bus connection object and initiate
     the connection to a well-known bus of some form. An alternative to
     using these high-level calls is to create an unconnected bus
@@ -210,6 +227,7 @@
     <title>Reference ownership</title>
     <para>The functions <function>sd_bus_open()</function>,
     <function>sd_bus_open_user()</function>,
+    <function>sd_bus_open_user_machine()</function>,
     <function>sd_bus_open_system()</function>,
     <function>sd_bus_open_system_remote()</function>, and
     <function>sd_bus_open_system_machine()</function> return a new
diff --git a/man/user-system-options.xml b/man/user-system-options.xml
index 728118e60c..e2c19b2982 100644
--- a/man/user-system-options.xml
+++ b/man/user-system-options.xml
@@ -45,8 +45,14 @@
     <term><option>--machine=</option></term>
 
     <listitem id='machine-text'>
-      <para>Execute operation on a local container. Specify a
-      container name to connect to.</para>
+      <para>Execute operation on a local container. Specify a container name to connect to, optionally
+      prefixed by a user name to connect as and a separating <literal>@</literal> character. If the special
+      string <literal>.host</literal> is used in place of the container name, a connection to the local
+      system is made (which is useful to connect to a specific user's user bus: <literal>--user
+      --machine=lennart@.host</literal>). If the <literal>@</literal> syntax is not used, the connection is
+      made as root user. If the <literal>@</literal> syntax is used either the left hand side or the right hand
+      side may be ommitted (but not both) in which case the local user name and <literal>.host</literal> are
+      implied.</para>
     </listitem>
   </varlistentry>
 </variablelist>