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=9a1b1997d96ac3da5a82f6d1f0d9f35ffd1ac16e;hb=91d60274701a12d2bbcd2b8e40f8b8abe00be0e7;hpb=5430f7f2bc7330f3088b894166bf3524a067e3d8 diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index 9a1b1997d..dc269b538 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -1,6 +1,6 @@ - + + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - - sd_pid_get_session - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - sd_pid_get_session - 3 - - - - sd_pid_get_session - sd_pid_get_unit - sd_pid_get_owner_uid - Determine session, service or owner of a session of a specific PID - - - - - #include <systemd/sd-login.h> - - - int sd_pid_get_session - pid_t pid - char** session - - - - int sd_pid_get_unit - pid_t pid - char** unit - - - - int sd_pid_get_owner_uid - pid_t pid - uid_t* uid - - - - - - Description - - sd_pid_get_session() 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. Note that 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 - call after use. - - sd_pid_get_unit() may be - used to determine the systemd unit (i.e. system - service) identifier of a process identified by the - specified process identifier. The unit name is a short - string, suitable for usage in file system paths. Note - that not all processes are part of a unit/service - (e.g. user processes, or kernel threads). For - processes not being part of a systemd unit/system - service this function will fail. The returned string - needs to be freed with the libc - free3 - call after use. - - 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 - 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. - - If the pid paramater of any - of these functions is passed as 0 the operation is - executed for the calling process. - - - - Return Value - - On success these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code. - - - - Notes - - The sd_pid_get_session(), - sd_pid_get_pid(), and - sd_pid_get_owner_uid() interfaces - are available as shared library, which can be compiled - and linked to with the - libsystemd-login - pkg-config1 - file. - - Note that the login session identifier as - returned by sd_pid_get_session() - is completely unrelated to the process session - identifier as returned by - getsid2. - - - - See Also - - - systemd1, - sd-login7, - sd_session_is_active3, - getsid2 - - + + + + sd_pid_get_session + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_pid_get_session + 3 + + + + sd_pid_get_session + sd_pid_get_unit + sd_pid_get_user_unit + 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 + 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 + + + + + #include <systemd/sd-login.h> + + + int sd_pid_get_session + pid_t pid + char **session + + + + int sd_pid_get_unit + pid_t pid + char **unit + + + + int sd_pid_get_user_unit + pid_t pid + char **unit + + + + int sd_pid_get_owner_uid + pid_t pid + uid_t *uid + + + + int sd_pid_get_machine_name + pid_t pid + char **name + + + + int sd_pid_get_slice + pid_t pid + 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 + char **session + + + + int sd_peer_get_unit + int fd + char **unit + + + + int sd_peer_get_user_unit + int fd + char **unit + + + + int sd_peer_get_owner_uid + int fd + uid_t *uid + + + + int sd_peer_get_machine_name + int fd + char **name + + + + int sd_peer_get_slice + int fd + char **slice + + + + int sd_peer_get_user_slice + int fd + char **slice + + + + int sd_peer_get_cgroup + int fd + char **cgroup + + + + + + Description + + sd_pid_get_session() 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. Note that + 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 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 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 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 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 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. 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 + systemd.slice5 + for details about slices. The returned string needs to be freed + with the libc + 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. + + The 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(), + 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. Note + that these fields are retrieved via /proc, + and hence are not suitable for authorization purposes, as they are + subject to races. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + 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 + + The sd_pid_get_session(), + sd_pid_get_unit(), + sd_pid_get_user_unit(), + 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() 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 + returned by sd_pid_get_session() + is completely unrelated to the process session + identifier as returned by + getsid2. + + + + See Also + + + systemd1, + sd-login3, + sd_session_is_active3, + getsid2, + systemd.slice5, + systemd-machined.service8 + +