X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_pid_get_session.xml;h=dc269b538b6cc06baadb72490a56921b17e15394;hp=c18b9b102af57844d49b844050873d0232322f21;hb=91d60274701a12d2bbcd2b8e40f8b8abe00be0e7;hpb=7586a2e532d8dcb2428edd4e98c3534fc6f22061
diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml
index c18b9b102..dc269b538 100644
--- a/man/sd_pid_get_session.xml
+++ b/man/sd_pid_get_session.xml
@@ -1,4 +1,4 @@
-
+
@@ -49,15 +49,19 @@
sd_pid_get_owner_uid
sd_pid_get_machine_name
sd_pid_get_slice
+ sd_pid_get_user_slice
+ sd_pid_get_cgroup
sd_peer_get_session
sd_peer_get_unit
sd_peer_get_user_unit
sd_peer_get_owner_uid
sd_peer_get_machine_name
sd_peer_get_slice
- Determine session, service, owner of a
- session, container/VM or slice of a specific
- PID or socket peer
+ sd_peer_get_user_slice
+ sd_peer_get_cgroup
+ Determine session, unit, owner of a session,
+ container/VM or slice of a specific PID or socket
+ peer
@@ -100,6 +104,18 @@
char **slice
+
+ int sd_pid_get_user_slice
+ pid_t pid
+ char **slice
+
+
+
+ int sd_pid_get_cgroup
+ pid_t pid
+ char **cgroup
+
+
int sd_peer_get_session
int fd
@@ -135,6 +151,18 @@
int fd
char **slice
+
+
+ int sd_peer_get_user_slice
+ int fd
+ char **slice
+
+
+
+ int sd_peer_get_cgroup
+ int fd
+ char **cgroup
+
@@ -148,45 +176,48 @@
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
- free3
+ being part of a login session, this function will fail with
+ -ENODATA. The returned string needs to be freed with the libc
+ free3
call after use.
sd_pid_get_unit() may be used to
- determine the systemd system unit (i.e. system service) 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 (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 sd_pid_get_user_unit() for that.) The
- returned string needs to be freed with the libc
- free3
+ 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 (e.g. user processes, or kernel threads). For
+ processes not being part of a systemd system unit, this function
+ will fail with -ENODATA. (More specifically, this call will not
+ work for kernel threads.) The returned string needs to be freed
+ with the libc free3
call after use.
sd_pid_get_user_unit() may be used to
- determine the systemd user unit (i.e. user service) identifier of
- a process identified by the specified PID. This is similar to
- sd_pid_get_unit() but applies to user units
- instead of system units.
+ determine the systemd user unit (i.e. user service or scope unit)
+ identifier of a process identified by the specified PID. This is
+ similar to sd_pid_get_unit(), but applies to
+ user units instead of system units.
sd_pid_get_owner_uid() may be used to
- determine the Unix user identifier of the owner of the session of
- a process identified the specified PID. Note that this function
- will succeed for user processes which are shared between multiple
- login sessions of the same user, where
+ determine the Unix UID (user identifier) of the owner of the
+ session of a process identified the specified PID. Note that this
+ function will succeed for user processes which are shared between
+ multiple login sessions of the same user, whereas
sd_pid_get_session() will fail. For processes
not being part of a login session and not being a shared process
- of a user this function will fail.
+ of a user, this function will fail with -ENODATA.
sd_pid_get_machine_name() 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
- free3
- call after use.
+ free3
+ call after use. For processes not part of a VM or containers, this
+ function fails with -ENODATA.
sd_pid_get_slice() may be used to
determine the slice unit the process is a member of. See
@@ -196,6 +227,21 @@
free3
call after use.
+ Similarly, sd_pid_get_user_slice()
+ returns the user slice (as managed by the user's systemd instance)
+ of a process.
+
+ sd_pid_get_cgroup() 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
+ /sys/fs/cgroup/ (if the unified control group
+ setup is used), or
+ /sys/fs/cgroup/HIERARCHY/
+ (if the legacy multi-hierarchy control group setup is used).
+
If the pid parameter of any of these
functions is passed as 0, the operation is executed for the
calling process.
@@ -204,10 +250,15 @@
sd_peer_get_unit(),
sd_peer_get_user_unit(),
sd_peer_get_owner_uid(),
- sd_peer_get_machine_name() and
- sd_peer_get_slice() calls operate similar to
+ sd_peer_get_machine_name(),
+ sd_peer_get_slice(),
+ sd_peer_get_user_slice() and
+ sd_peer_get_cgroup() calls operate similar to
their PID counterparts, but operate on a connected AF_UNIX socket
- and retrieve information about the connected peer process.
+ and retrieve information about the connected peer process. Note
+ that these fields are retrieved via /proc,
+ and hence are not suitable for authorization purposes, as they are
+ subject to races.
@@ -218,6 +269,51 @@
code.
+
+ Errors
+
+ Returned errors may indicate the following problems:
+
+
+
+
+ -ESRCH
+
+ The specified PID does not refer to a running
+ process.
+
+
+
+
+ -BADF
+
+ The specified socket file descriptor was
+ invalid.
+
+
+
+ -ENODATA
+
+ The given field is not specified for the described
+ process or peer.
+
+
+
+
+ -EINVAL
+
+ An input parameter was invalid (out of range,
+ or NULL, where that is not accepted).
+
+
+
+ -ENOMEM
+
+ Memory allocation failed.
+
+
+
+
Notes
@@ -227,15 +323,17 @@
sd_pid_get_owner_uid(),
sd_pid_get_machine_name(),
sd_pid_get_slice(),
+ sd_pid_get_user_slice(),
sd_peer_get_session(),
sd_peer_get_unit(),
sd_peer_get_user_unit(),
sd_peer_get_owner_uid(),
- sd_peer_get_machine_name() and
- sd_peer_get_slice() interfaces are
- available as a shared library, which can be compiled
- and linked to with the
- libelogind pkg-config1
+ sd_peer_get_machine_name(),
+ sd_peer_get_slice() and
+ sd_peer_get_user_slice() interfaces are
+ available as a shared library, which can be compiled and linked to
+ with the libelogind pkg-config1
file.
Note that the login session identifier as