]>
Commit | Line | Data |
---|---|---|
14228c0d | 1 | '\" t |
5eef597e | 2 | .TH "SD_PID_GET_SESSION" "3" "" "systemd 217" "sd_pid_get_session" |
14228c0d MB |
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" | |
60f067b4 | 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 |
14228c0d MB |
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 | |
60f067b4 | 32 | .BI "int sd_pid_get_session(pid_t\ " "pid" ", char\ **" "session" ");" |
14228c0d | 33 | .HP \w'int\ sd_pid_get_unit('u |
60f067b4 | 34 | .BI "int sd_pid_get_unit(pid_t\ " "pid" ", char\ **" "unit" ");" |
14228c0d | 35 | .HP \w'int\ sd_pid_get_user_unit('u |
60f067b4 | 36 | .BI "int sd_pid_get_user_unit(pid_t\ " "pid" ", char\ **" "unit" ");" |
14228c0d | 37 | .HP \w'int\ sd_pid_get_owner_uid('u |
60f067b4 | 38 | .BI "int sd_pid_get_owner_uid(pid_t\ " "pid" ", uid_t\ *" "uid" ");" |
14228c0d | 39 | .HP \w'int\ sd_pid_get_machine_name('u |
60f067b4 | 40 | .BI "int sd_pid_get_machine_name(pid_t\ " "pid" ", char\ **" "name" ");" |
14228c0d | 41 | .HP \w'int\ sd_pid_get_slice('u |
60f067b4 JS |
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" ");" | |
14228c0d MB |
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\&. | |
60f067b4 JS |
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\&. | |
14228c0d MB |
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, | |
60f067b4 JS |
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 | |
14228c0d | 121 | and |
60f067b4 JS |
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) | |
14228c0d MB |
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), | |
5eef597e MP |
137 | \fBsystemd.slice\fR(5), |
138 | \fBsystemd-machined.service\fR(8) |