sd-device: get_subsystem - don't complain if a device does not have a subsystem

[elogind.git] / man / sd_pid_get_session.xml

diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml
index f708d0d5e1b9d8b5b9089fd6928b39da7dd7beb0..60bc7ed886e0c0b421c82e7539bae5182612aee9 100644 (file)
--- a/man/sd_pid_get_session.xml
+++ b/man/sd_pid_get_session.xml
@@ -1,6 +1,9 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
 
 <!--
   This file is part of systemd.
@@ -148,9 +151,10 @@
     not all processes are part of a login session (e.g. system service
     processes, user processes that are shared between multiple
     sessions of the same user, or kernel threads). For processes not
-    being part of a login session this function will fail. The
-    returned string needs to be freed with the libc
-    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    being part of a login session this function will fail with
+    -ENXIO. The returned string needs to be freed with the libc
+    <citerefentry
+    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     call after use.</para>
 
     <para><function>sd_pid_get_unit()</function> may be used to
@@ -159,11 +163,12 @@
     short string, suitable for usage in file system paths. Note that
     not all processes are part of a system unit/service (e.g. user
     processes, or kernel threads). For processes not being part of a
-    systemd system unit this function will fail. (More specifically:
-    this call will not work for processes that are part of user units,
-    use <function>sd_pid_get_user_unit()</function> for that.) The
-    returned string needs to be freed with the libc
-    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    systemd system unit this function will fail with -ENXIO (More
+    specifically: this call will not work for processes that are part
+    of user units, use <function>sd_pid_get_user_unit()</function> for
+    that.) The returned string needs to be freed with the libc
+    <citerefentry
+    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     call after use.</para>
 
     <para><function>sd_pid_get_user_unit()</function> may be used to
@@ -179,14 +184,16 @@
     login sessions of the same user, where
     <function>sd_pid_get_session()</function> will fail. For processes
     not being part of a login session and not being a shared process
-    of a user this function will fail.</para>
+    of a user this function will fail with -ENXIO.</para>
 
     <para><function>sd_pid_get_machine_name()</function> may be used
     to determine the name of the VM or container is a member of. The
     machine name is a short string, suitable for usage in file system
     paths. The returned string needs to be freed with the libc
-    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    call after use.</para>
+    <citerefentry
+    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    call after use. For processes not part of a VM or containers this
+    function fails with -ENXIO.</para>
 
     <para><function>sd_pid_get_slice()</function> may be used to
     determine the slice unit the process is a member of. See
@@ -218,6 +225,37 @@
     code.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><constant>-ENXIO</constant></term>
+
+        <listitem><para>Given field is not specified for the described
+        process or peer.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESRCH</constant></term>
+
+        <listitem><para>The specified PID does not refer to a running
+        process.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>Notes</title>
 
@@ -235,7 +273,7 @@
     <function>sd_peer_get_slice()</function> interfaces are
     available as a shared library, which can be compiled
     and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     file.</para>
 
     <para>Note that the login session identifier as