From dddbc69577820e6ecce17d3ac836ad865fcbcde2 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 21:22:56 +0200 Subject: [PATCH] man: document user slice sd-login calls we added a while back --- Makefile-man.am | 10 +++++ man/sd_pid_get_session.xml | 83 ++++++++++++++++++++++++-------------- 2 files changed, 63 insertions(+), 30 deletions(-) diff --git a/Makefile-man.am b/Makefile-man.am index 08d22b344c3..218a299e91d 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -1937,11 +1937,13 @@ MANPAGES_ALIAS += \ man/sd_peer_get_session.3 \ man/sd_peer_get_slice.3 \ man/sd_peer_get_unit.3 \ + man/sd_peer_get_user_slice.3 \ man/sd_peer_get_user_unit.3 \ man/sd_pid_get_machine_name.3 \ man/sd_pid_get_owner_uid.3 \ man/sd_pid_get_slice.3 \ man/sd_pid_get_unit.3 \ + man/sd_pid_get_user_slice.3 \ man/sd_pid_get_user_unit.3 \ man/sd_seat_can_graphical.3 \ man/sd_seat_can_multi_session.3 \ @@ -1979,11 +1981,13 @@ man/sd_peer_get_owner_uid.3: man/sd_pid_get_session.3 man/sd_peer_get_session.3: man/sd_pid_get_session.3 man/sd_peer_get_slice.3: man/sd_pid_get_session.3 man/sd_peer_get_unit.3: man/sd_pid_get_session.3 +man/sd_peer_get_user_slice.3: man/sd_pid_get_session.3 man/sd_peer_get_user_unit.3: man/sd_pid_get_session.3 man/sd_pid_get_machine_name.3: man/sd_pid_get_session.3 man/sd_pid_get_owner_uid.3: man/sd_pid_get_session.3 man/sd_pid_get_slice.3: man/sd_pid_get_session.3 man/sd_pid_get_unit.3: man/sd_pid_get_session.3 +man/sd_pid_get_user_slice.3: man/sd_pid_get_session.3 man/sd_pid_get_user_unit.3: man/sd_pid_get_session.3 man/sd_seat_can_graphical.3: man/sd_seat_get_active.3 man/sd_seat_can_multi_session.3: man/sd_seat_get_active.3 @@ -2049,6 +2053,9 @@ man/sd_peer_get_slice.html: man/sd_pid_get_session.html man/sd_peer_get_unit.html: man/sd_pid_get_session.html $(html-alias) +man/sd_peer_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + man/sd_peer_get_user_unit.html: man/sd_pid_get_session.html $(html-alias) @@ -2064,6 +2071,9 @@ man/sd_pid_get_slice.html: man/sd_pid_get_session.html man/sd_pid_get_unit.html: man/sd_pid_get_session.html $(html-alias) +man/sd_pid_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + man/sd_pid_get_user_unit.html: man/sd_pid_get_session.html $(html-alias) diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index b46d47101b6..9c6706caf81 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -49,15 +49,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 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 + Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer @@ -100,6 +102,12 @@ char **slice + + int sd_pid_get_user_slice + pid_t pid + char **slice + + int sd_peer_get_session int fd @@ -135,6 +143,12 @@ int fd char **slice + + + int sd_peer_get_user_slice + int fd + char **slice + @@ -155,30 +169,29 @@ 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 with -ENXIO (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 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, where 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 with -ENXIO. @@ -200,6 +213,10 @@ free3 call after use. + Similar, sd_pid_get_user_slice() + returns the user slice (as managed by the user's systemd instance) + of a process. + If the pid parameter of any of these functions is passed as 0, the operation is executed for the calling process. @@ -208,10 +225,14 @@ 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 - their PID counterparts, but operate on a connected AF_UNIX socket - and retrieve information about the connected peer process. + sd_peer_get_machine_name(), + sd_peer_get_slice() and + sd_peer_get_user_slice() 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 + /proc, and hence are not suitable for + authorization purposes, as they are subject to races. @@ -262,15 +283,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 - libsystemd 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 libsystemd pkg-config1 file. Note that the login session identifier as -- 2.39.2