sd-login: add new sd_pid_get_cgroup() API

[thirdparty/systemd.git] / man / sd_pid_get_session.xml

diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml
index 903c143f364543dc2e431e92525551ad0417a516..035effcaa90f1ded4c26aa6c3f5c66d3ac2c428e 100644 (file)
--- a/man/sd_pid_get_session.xml
+++ b/man/sd_pid_get_session.xml
@@ -50,6 +50,7 @@
     <refname>sd_pid_get_machine_name</refname>
     <refname>sd_pid_get_slice</refname>
     <refname>sd_pid_get_user_slice</refname>
+    <refname>sd_pid_get_cgroup</refname>
     <refname>sd_peer_get_session</refname>
     <refname>sd_peer_get_unit</refname>
     <refname>sd_peer_get_user_unit</refname>
@@ -57,6 +58,7 @@
     <refname>sd_peer_get_machine_name</refname>
     <refname>sd_peer_get_slice</refname>
     <refname>sd_peer_get_user_slice</refname>
+    <refname>sd_peer_get_cgroup</refname>
     <refpurpose>Determine session, unit, owner of a session,
     container/VM or slice of a specific PID or socket
     peer</refpurpose>
@@ -108,6 +110,12 @@
         <paramdef>char **<parameter>slice</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_pid_get_cgroup</function></funcdef>
+        <paramdef>pid_t <parameter>pid</parameter></paramdef>
+        <paramdef>char **<parameter>cgroup</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_peer_get_session</function></funcdef>
         <paramdef>int <parameter>fd</parameter></paramdef>
@@ -149,6 +157,12 @@
         <paramdef>int <parameter>fd</parameter></paramdef>
         <paramdef>char **<parameter>slice</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
+        <paramdef>int <parameter>fd</parameter></paramdef>
+        <paramdef>char **<parameter>cgroup</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -217,6 +231,17 @@
     returns the user slice (as managed by the user's systemd instance)
     of a process.</para>
 
+    <para><function>sd_pid_get_cgroup()</function> returns the control
+    group path of the specified process, relative to the root of the
+    hierarchy. Returns the path without trailing slash, except for
+    processes located in the root control group, where "/" is
+    returned. To find the actual control group path in the file system
+    the returned path needs to be prefixed with
+    <filename>/sys/fs/cgroup/</filename> (if the unified control group
+    setup is used), or
+    <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
+    (if the legacy multi-hierarchy control group setup is used).</para>
+
     <para>If the <varname>pid</varname> parameter of any of these
     functions is passed as 0, the operation is executed for the
     calling process.</para>
@@ -226,13 +251,14 @@
     <function>sd_peer_get_user_unit()</function>,
     <function>sd_peer_get_owner_uid()</function>,
     <function>sd_peer_get_machine_name()</function>,
-    <function>sd_peer_get_slice()</function> and
-    <function>sd_peer_get_user_slice()</function> calls operate
-    similar to their PID counterparts, but operate on a connected
-    AF_UNIX socket and retrieve information about the connected peer
-    process. Note that these fields are retrieved via
-    <filename>/proc</filename>, and hence are not suitable for
-    authorization purposes, as they are subject to races.</para>
+    <function>sd_peer_get_slice()</function>,
+    <function>sd_peer_get_user_slice()</function> and
+    <function>sd_peer_get_cgroup()</function> calls operate similar to
+    their PID counterparts, but operate on a connected AF_UNIX socket
+    and retrieve information about the connected peer process. Note
+    that these fields are retrieved via <filename>/proc</filename>,
+    and hence are not suitable for authorization purposes, as they are
+    subject to races.</para>
   </refsect1>
 
   <refsect1>