man/sd_pid_get_session.3

   1 '\" t
   2 .TH "SD_PID_GET_SESSION" "3" "" "systemd 214" "sd_pid_get_session"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 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_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
  24 .SH "SYNOPSIS"
  25 .sp
  26 .ft B
  27 .nf
  28 #include <systemd/sd\-login\&.h>
  29 .fi
  30 .ft
  31 .HP \w'int\ sd_pid_get_session('u
  32 .BI "int sd_pid_get_session(pid_t\ " "pid" ", char\ **" "session" ");"
  33 .HP \w'int\ sd_pid_get_unit('u
  34 .BI "int sd_pid_get_unit(pid_t\ " "pid" ", char\ **" "unit" ");"
  35 .HP \w'int\ sd_pid_get_user_unit('u
  36 .BI "int sd_pid_get_user_unit(pid_t\ " "pid" ", char\ **" "unit" ");"
  37 .HP \w'int\ sd_pid_get_owner_uid('u
  38 .BI "int sd_pid_get_owner_uid(pid_t\ " "pid" ", uid_t\ *" "uid" ");"
  39 .HP \w'int\ sd_pid_get_machine_name('u
  40 .BI "int sd_pid_get_machine_name(pid_t\ " "pid" ", char\ **" "name" ");"
  41 .HP \w'int\ sd_pid_get_slice('u
  42 .BI "int sd_pid_get_slice(pid_t\ " "pid" ", char\ **" "slice" ");"
  43 .HP \w'int\ sd_peer_get_session('u
  44 .BI "int sd_peer_get_session(int\ " "fd" ", char\ **" "session" ");"
  45 .HP \w'int\ sd_peer_get_unit('u
  46 .BI "int sd_peer_get_unit(int\ " "fd" ", char\ **" "unit" ");"
  47 .HP \w'int\ sd_peer_get_user_unit('u
  48 .BI "int sd_peer_get_user_unit(int\ " "fd" ", char\ **" "unit" ");"
  49 .HP \w'int\ sd_peer_get_owner_uid('u
  50 .BI "int sd_peer_get_owner_uid(int\ " "fd" ", uid_t\ *" "uid" ");"
  51 .HP \w'int\ sd_peer_get_machine_name('u
  52 .BI "int sd_peer_get_machine_name(int\ " "fd" ", char\ **" "name" ");"
  53 .HP \w'int\ sd_peer_get_slice('u
  54 .BI "int sd_peer_get_slice(int\ " "fd" ", char\ **" "slice" ");"
  55 .SH "DESCRIPTION"
  56 .PP
  57 \fBsd_pid_get_session()\fR
  58 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
  59 \fBfree\fR(3)
  60 call after use\&.
  61 .PP
  62 \fBsd_pid_get_unit()\fR
  63 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
  64 \fBsd_pid_get_user_unit()\fR
  65 for that\&.) The returned string needs to be freed with the libc
  66 \fBfree\fR(3)
  67 call after use\&.
  68 .PP
  69 \fBsd_pid_get_user_unit()\fR
  70 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
  71 \fBsd_pid_get_unit()\fR
  72 but applies to user units instead of system units\&.
  73 .PP
  74 \fBsd_pid_get_owner_uid()\fR
  75 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
  76 \fBsd_pid_get_session()\fR
  77 will fail\&. For processes not being part of a login session and not being a shared process of a user this function will fail\&.
  78 .PP
  79 \fBsd_pid_get_machine_name()\fR
  80 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
  81 \fBfree\fR(3)
  82 call after use\&.
  83 .PP
  84 \fBsd_pid_get_slice()\fR
  85 may be used to determine the slice unit the process is a member of\&. See
  86 \fBsystemd.slice\fR(5)
  87 for details about slices\&. The returned string needs to be freed with the libc
  88 \fBfree\fR(3)
  89 call after use\&.
  90 .PP
  91 If the
  92 \fIpid\fR
  93 parameter of any of these functions is passed as 0, the operation is executed for the calling process\&.
  94 .PP
  95 The
  96 \fBsd_peer_get_session()\fR,
  97 \fBsd_peer_get_unit()\fR,
  98 \fBsd_peer_get_user_unit()\fR,
  99 \fBsd_peer_get_owner_uid()\fR,
 100 \fBsd_peer_get_machine_name()\fR
 101 and
 102 \fBsd_peer_get_slice()\fR
 103 calls operate similar to their PID counterparts, but operate on a connected AF_UNIX socket and retrieve information about the connected peer process\&.
 104 .SH "RETURN VALUE"
 105 .PP
 106 On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
 107 .SH "NOTES"
 108 .PP
 109 The
 110 \fBsd_pid_get_session()\fR,
 111 \fBsd_pid_get_unit()\fR,
 112 \fBsd_pid_get_user_unit()\fR,
 113 \fBsd_pid_get_owner_uid()\fR,
 114 \fBsd_pid_get_machine_name()\fR,
 115 \fBsd_pid_get_slice()\fR,
 116 \fBsd_peer_get_session()\fR,
 117 \fBsd_peer_get_unit()\fR,
 118 \fBsd_peer_get_user_unit()\fR,
 119 \fBsd_peer_get_owner_uid()\fR,
 120 \fBsd_peer_get_machine_name()\fR
 121 and
 122 \fBsd_peer_get_slice()\fR
 123 interfaces are available as a shared library, which can be compiled and linked to with the
 124 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
 125 file\&.
 126 .PP
 127 Note that the login session identifier as returned by
 128 \fBsd_pid_get_session()\fR
 129 is completely unrelated to the process session identifier as returned by
 130 \fBgetsid\fR(2)\&.
 131 .SH "SEE ALSO"
 132 .PP
 133 \fBsystemd\fR(1),
 134 \fBsd-login\fR(3),
 135 \fBsd_session_is_active\fR(3),
 136 \fBgetsid\fR(2),
 137 \fBsystemd.slice\fR(5)