summaryrefslogtreecommitdiffstats
path: root/man/sd_pid_get_owner_uid.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/sd_pid_get_owner_uid.xml')
-rw-r--r--man/sd_pid_get_owner_uid.xml321
1 files changed, 321 insertions, 0 deletions
diff --git a/man/sd_pid_get_owner_uid.xml b/man/sd_pid_get_owner_uid.xml
new file mode 100644
index 0000000..f4619b6
--- /dev/null
+++ b/man/sd_pid_get_owner_uid.xml
@@ -0,0 +1,321 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ SPDX-License-Identifier: LGPL-2.1+
+-->
+
+<refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_pid_get_owner_uid</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_pid_get_owner_uid</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_pid_get_owner_uid</refname>
+ <refname>sd_pid_get_session</refname>
+ <refname>sd_pid_get_user_unit</refname>
+ <refname>sd_pid_get_unit</refname>
+ <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_owner_uid</refname>
+ <refname>sd_peer_get_session</refname>
+ <refname>sd_peer_get_user_unit</refname>
+ <refname>sd_peer_get_unit</refname>
+ <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 the owner uid of the user unit or session,
+ or the session, user unit, system unit, container/VM or slice that
+ a specific PID or socket peer belongs to.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>uid_t *<parameter>uid</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_session</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>char **<parameter>session</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>char **<parameter>unit</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_unit</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>char **<parameter>unit</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>char **<parameter>name</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_slice</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <paramdef>char **<parameter>slice</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_pid_get_user_slice</function></funcdef>
+ <paramdef>pid_t <parameter>pid</parameter></paramdef>
+ <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_owner_uid</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>uid_t *<parameter>uid</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_session</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>char **<parameter>session</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>char **<parameter>unit</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_unit</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>char **<parameter>unit</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>char **<parameter>name</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_slice</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>char **<parameter>slice</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_peer_get_user_slice</function></funcdef>
+ <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>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_pid_get_owner_uid()</function> may be used to
+ determine the Unix UID (user identifier) which owns the login
+ session or systemd user unit of a process identified by the
+ specified PID. For processes which are not part of a login session
+ and not managed by a user manager, this function will fail with
+ <constant>-ENODATA</constant>.</para>
+
+ <para><function>sd_pid_get_session()</function> may be used to
+ determine the login session identifier of a process identified by
+ the specified process identifier. The session identifier is a
+ short string, suitable for usage in file system paths. Please
+ note the login session may be limited to a stub process or two.
+ User processes may instead be started from their systemd user
+ manager, e.g. GUI applications started using DBus activation, as
+ well as service processes which are shared between multiple logins
+ of the same user. For processes which are not part of a login
+ session, this function will fail with <constant>-ENODATA</constant>.
+ 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
+ determine the systemd user unit (i.e. user service or scope unit)
+ identifier of a process identified by the specified PID. The
+ unit name is a short string, suitable for usage in file system
+ paths. For processes which are not managed by a user manager, this
+ function will fail with <constant>-ENODATA</constant>. 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
+ determine the systemd system unit (i.e. system service or scope
+ unit) identifier of a process identified by the specified PID. The
+ unit name is a short string, suitable for usage in file system
+ paths. Note that not all processes are part of a system
+ unit/service. For processes not being part of a systemd system
+ unit, this function will fail with <constant>-ENODATA</constant>.
+ (More specifically, this call will not work for kernel threads.)
+ 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_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. For processes not part of a VM or container, this
+ function fails with <constant>-ENODATA</constant>.</para>
+
+ <para><function>sd_pid_get_slice()</function> may be used to
+ determine the slice unit the process is a member of. See
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details about slices. 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>Similarly, <function>sd_pid_get_user_slice()</function>
+ 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>
+
+ <para>The <function>sd_peer_get_owner_uid()</function>,
+ <function>sd_peer_get_session()</function>,
+ <function>sd_peer_get_user_unit()</function>,
+ <function>sd_peer_get_unit()</function>,
+ <function>sd_peer_get_machine_name()</function>,
+ <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>
+ <title>Return Value</title>
+
+ <para>On success, these calls return 0 or a positive integer. On
+ failure, these calls return a negative errno-style error
+ code.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><constant>-ESRCH</constant></term>
+
+ <listitem><para>The specified PID does not refer to a running
+ process.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EBADF</constant></term>
+
+ <listitem><para>The specified socket file descriptor was
+ invalid.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-ENODATA</constant></term>
+
+ <listitem><para>The given field is not specified for the described
+ process or peer.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>An input parameter was invalid (out of range,
+ or NULL, where that is not accepted).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-ENOMEM</constant></term>
+
+ <listitem><para>Memory allocation failed.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+
+ <para>Note that the login session identifier as
+ returned by <function>sd_pid_get_session()</function>
+ is completely unrelated to the process session
+ identifier as returned by
+ <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>