Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_creds_get_pid.3

raw
1 '\" t
2 .TH "SD_BUS_CREDS_GET_PID" "3" "" "systemd 261~rc3" "sd_bus_creds_get_pid"
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_bus_creds_get_pid, sd_bus_creds_get_pidfd_dup, sd_bus_creds_get_ppid, sd_bus_creds_get_tid, sd_bus_creds_get_uid, sd_bus_creds_get_euid, sd_bus_creds_get_suid, sd_bus_creds_get_fsuid, sd_bus_creds_get_gid, sd_bus_creds_get_egid, sd_bus_creds_get_sgid, sd_bus_creds_get_fsgid, sd_bus_creds_get_supplementary_gids, sd_bus_creds_get_comm, sd_bus_creds_get_tid_comm, sd_bus_creds_get_exe, sd_bus_creds_get_cmdline, sd_bus_creds_get_cgroup, sd_bus_creds_get_unit, sd_bus_creds_get_slice, sd_bus_creds_get_user_unit, sd_bus_creds_get_user_slice, sd_bus_creds_get_session, sd_bus_creds_get_owner_uid, sd_bus_creds_has_effective_cap, sd_bus_creds_has_permitted_cap, sd_bus_creds_has_inheritable_cap, sd_bus_creds_has_bounding_cap, sd_bus_creds_get_selinux_context, sd_bus_creds_get_audit_session_id, sd_bus_creds_get_audit_login_uid, sd_bus_creds_get_tty, sd_bus_creds_get_unique_name, sd_bus_creds_get_well_known_names, sd_bus_creds_get_description \- Retrieve fields from a credentials object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_creds_get_pid('u
32 .BI "int sd_bus_creds_get_pid(sd_bus_creds\ *" "c" ", pid_t\ *" "pid" ");"
33 .HP \w'int\ sd_bus_creds_get_pidfd_dup('u
34 .BI "int sd_bus_creds_get_pidfd_dup(sd_bus_creds\ *" "c" ", int\ *" "ret_fd" ");"
35 .HP \w'int\ sd_bus_creds_get_ppid('u
36 .BI "int sd_bus_creds_get_ppid(sd_bus_creds\ *" "c" ", pid_t\ *" "ppid" ");"
37 .HP \w'int\ sd_bus_creds_get_tid('u
38 .BI "int sd_bus_creds_get_tid(sd_bus_creds\ *" "c" ", pid_t\ *" "tid" ");"
39 .HP \w'int\ sd_bus_creds_get_uid('u
40 .BI "int sd_bus_creds_get_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
41 .HP \w'int\ sd_bus_creds_get_euid('u
42 .BI "int sd_bus_creds_get_euid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
43 .HP \w'int\ sd_bus_creds_get_suid('u
44 .BI "int sd_bus_creds_get_suid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
45 .HP \w'int\ sd_bus_creds_get_fsuid('u
46 .BI "int sd_bus_creds_get_fsuid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
47 .HP \w'int\ sd_bus_creds_get_gid('u
48 .BI "int sd_bus_creds_get_gid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
49 .HP \w'int\ sd_bus_creds_get_egid('u
50 .BI "int sd_bus_creds_get_egid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
51 .HP \w'int\ sd_bus_creds_get_sgid('u
52 .BI "int sd_bus_creds_get_sgid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
53 .HP \w'int\ sd_bus_creds_get_fsgid('u
54 .BI "int sd_bus_creds_get_fsgid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
55 .HP \w'int\ sd_bus_creds_get_supplementary_gids('u
56 .BI "int sd_bus_creds_get_supplementary_gids(sd_bus_creds\ *" "c" ", const\ gid_t\ **" "gids" ");"
57 .HP \w'int\ sd_bus_creds_get_comm('u
58 .BI "int sd_bus_creds_get_comm(sd_bus_creds\ *" "c" ", const\ char\ **" "comm" ");"
59 .HP \w'int\ sd_bus_creds_get_tid_comm('u
60 .BI "int sd_bus_creds_get_tid_comm(sd_bus_creds\ *" "c" ", const\ char\ **" "comm" ");"
61 .HP \w'int\ sd_bus_creds_get_exe('u
62 .BI "int sd_bus_creds_get_exe(sd_bus_creds\ *" "c" ", const\ char\ **" "exe" ");"
63 .HP \w'int\ sd_bus_creds_get_cmdline('u
64 .BI "int sd_bus_creds_get_cmdline(sd_bus_creds\ *" "c" ", char\ ***" "cmdline" ");"
65 .HP \w'int\ sd_bus_creds_get_cgroup('u
66 .BI "int sd_bus_creds_get_cgroup(sd_bus_creds\ *" "c" ", const\ char\ **" "cgroup" ");"
67 .HP \w'int\ sd_bus_creds_get_unit('u
68 .BI "int sd_bus_creds_get_unit(sd_bus_creds\ *" "c" ", const\ char\ **" "unit" ");"
69 .HP \w'int\ sd_bus_creds_get_slice('u
70 .BI "int sd_bus_creds_get_slice(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
71 .HP \w'int\ sd_bus_creds_get_user_unit('u
72 .BI "int sd_bus_creds_get_user_unit(sd_bus_creds\ *" "c" ", const\ char\ **" "unit" ");"
73 .HP \w'int\ sd_bus_creds_get_user_slice('u
74 .BI "int sd_bus_creds_get_user_slice(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
75 .HP \w'int\ sd_bus_creds_get_session('u
76 .BI "int sd_bus_creds_get_session(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
77 .HP \w'int\ sd_bus_creds_get_owner_uid('u
78 .BI "int sd_bus_creds_get_owner_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
79 .HP \w'int\ sd_bus_creds_has_effective_cap('u
80 .BI "int sd_bus_creds_has_effective_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
81 .HP \w'int\ sd_bus_creds_has_permitted_cap('u
82 .BI "int sd_bus_creds_has_permitted_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
83 .HP \w'int\ sd_bus_creds_has_inheritable_cap('u
84 .BI "int sd_bus_creds_has_inheritable_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
85 .HP \w'int\ sd_bus_creds_has_bounding_cap('u
86 .BI "int sd_bus_creds_has_bounding_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
87 .HP \w'int\ sd_bus_creds_get_selinux_context('u
88 .BI "int sd_bus_creds_get_selinux_context(sd_bus_creds\ *" "c" ", const\ char\ **" "context" ");"
89 .HP \w'int\ sd_bus_creds_get_audit_session_id('u
90 .BI "int sd_bus_creds_get_audit_session_id(sd_bus_creds\ *" "c" ", uint32_t\ *" "sessionid" ");"
91 .HP \w'int\ sd_bus_creds_get_audit_login_uid('u
92 .BI "int sd_bus_creds_get_audit_login_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "loginuid" ");"
93 .HP \w'int\ sd_bus_creds_get_tty('u
94 .BI "int sd_bus_creds_get_tty(sd_bus_creds\ *" "c" ", const\ char\ **" "tty" ");"
95 .HP \w'int\ sd_bus_creds_get_unique_name('u
96 .BI "int sd_bus_creds_get_unique_name(sd_bus_creds\ *" "c" ", const\ char\ **" "name" ");"
97 .HP \w'int\ sd_bus_creds_get_well_known_names('u
98 .BI "int sd_bus_creds_get_well_known_names(sd_bus_creds\ *" "c" ", char\ ***" "name" ");"
99 .HP \w'int\ sd_bus_creds_get_description('u
100 .BI "int sd_bus_creds_get_description(sd_bus_creds\ *" "c" ", const\ char\ **" "name" ");"
101 .SH "DESCRIPTION"
102 .PP
103 These functions return credential information from an
104 \fIsd_bus_creds\fR
105 object\&. Credential objects may be created with
106 \fBsd_bus_creds_new_from_pid\fR(3), in which case they describe the credentials of the process identified by the specified PID, with
107 \fBsd_bus_get_name_creds\fR(3), in which case they describe the credentials of a bus peer identified by the specified bus name, with
108 \fBsd_bus_get_owner_creds\fR(3), in which case they describe the credentials of the creator of a bus, or with
109 \fBsd_bus_message_get_creds\fR(3), in which case they describe the credentials of the sender of the message\&.
110 .PP
111 Not all credential fields are part of every
112 "sd_bus_creds"
113 object\&. Use
114 \fBsd_bus_creds_get_mask\fR(3)
115 to determine the mask of fields available\&.
116 .PP
117 \fBsd_bus_creds_get_pid()\fR
118 will retrieve the PID (process identifier)\&. Similarly,
119 \fBsd_bus_creds_get_ppid()\fR
120 will retrieve the parent PID\&. Note that PID 1 has no parent process, in which case \-ENXIO is returned\&.
121 .PP
122 \fBsd_bus_creds_get_pidfd_dup()\fR
123 will retrieve the PID file descriptor (pidfd), see
124 \fBpidfd_open\fR(2)
125 for details\&. The file descriptor is duplicated and thus must be closed by the caller\&.
126 .PP
127 \fBsd_bus_creds_get_tid()\fR
128 will retrieve the TID (thread identifier)\&.
129 .PP
130 \fBsd_bus_creds_get_uid()\fR
131 will retrieve the numeric UID (user identifier)\&. Similarly,
132 \fBsd_bus_creds_get_euid()\fR
133 returns the effective UID,
134 \fBsd_bus_creds_get_suid()\fR
135 the saved UID and
136 \fBsd_bus_creds_get_fsuid()\fR
137 the file system UID\&.
138 .PP
139 \fBsd_bus_creds_get_gid()\fR
140 will retrieve the numeric GID (group identifier)\&. Similarly,
141 \fBsd_bus_creds_get_egid()\fR
142 returns the effective GID,
143 \fBsd_bus_creds_get_sgid()\fR
144 the saved GID and
145 \fBsd_bus_creds_get_fsgid()\fR
146 the file system GID\&.
147 .PP
148 \fBsd_bus_creds_get_supplementary_gids()\fR
149 will retrieve the supplementary GIDs list\&.
150 .PP
151 \fBsd_bus_creds_get_comm()\fR
152 will retrieve the comm field (truncated name of the executable, as stored in
153 /proc/\fIpid\fR/comm)\&.
154 .PP
155 \fBsd_bus_creds_get_tid_comm()\fR
156 will retrieve the comm field of the thread (as stored in
157 /proc/\fIpid\fR/task/\fItid\fR/comm)\&.
158 .PP
159 \fBsd_bus_creds_get_exe()\fR
160 will retrieve the path to the program executable (as stored in the
161 /proc/\fIpid\fR/exe
162 link, but with the
163 " (deleted)"
164 suffix removed)\&. Note that kernel threads do not have an executable path, in which case \-ENXIO is returned\&. Note that this property should not be used for more than explanatory information, in particular it should not be used for security\-relevant decisions\&. That\*(Aqs because the executable might have been replaced or removed by the time the value can be processed\&. Moreover, the kernel exports this information in an ambiguous way (i\&.e\&. a deleted executable cannot be safely distinguished from one whose name suffix is
165 " (deleted)")\&.
166 .PP
167 \fBsd_bus_creds_get_cmdline()\fR
168 will retrieve an array of command line arguments (as stored in
169 /proc/\fIpid\fR/cmdline)\&. Note that kernel threads do not have a command line, in which case \-ENXIO is returned\&.
170 .PP
171 \fBsd_bus_creds_get_cgroup()\fR
172 will retrieve the control group path\&. See
173 \m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[1]\d\s+2\&.
174 .PP
175 \fBsd_bus_creds_get_unit()\fR
176 will retrieve the systemd unit name (in the system instance of systemd) that the process is a part of\&. See
177 \fBsystemd.unit\fR(5)\&. For processes that are not part of a unit, returns \-ENXIO\&.
178 .PP
179 \fBsd_bus_creds_get_user_unit()\fR
180 will retrieve the systemd unit name (in the user instance of systemd) that the process is a part of\&. See
181 \fBsystemd.unit\fR(5)\&. For processes that are not part of a user unit, returns \-ENXIO\&.
182 .PP
183 \fBsd_bus_creds_get_slice()\fR
184 will retrieve the systemd slice (a unit in the system instance of systemd) that the process is a part of\&. See
185 \fBsystemd.slice\fR(5)\&. Similarly,
186 \fBsd_bus_creds_get_user_slice()\fR
187 retrieves the systemd slice of the process, in the user instance of systemd\&.
188 .PP
189 \fBsd_bus_creds_get_session()\fR
190 will retrieve the identifier of the login session that the process is a part of\&. Please note the login session may be limited to a stub process or two\&. User processes may instead be started from their systemd user manager, e\&.g\&. GUI applications started using DBus activation, as well as service processes which are shared between multiple logins of the same user\&. For processes that are not part of a session, returns \-ENXIO\&.
191 .PP
192 \fBsd_bus_creds_get_owner_uid()\fR
193 will retrieve the numeric UID (user identifier) of the user who owns the user unit or login session that the process is a part of\&. See
194 \fBsystemd-logind.service\fR(8)\&. For processes that are not part of a user unit or session, returns \-ENXIO\&.
195 .PP
196 \fBsd_bus_creds_has_effective_cap()\fR
197 will check whether the capability specified by
198 \fIcapability\fR
199 was set in the effective capabilities mask\&. A positive return value means that it was set, zero means that it was not set, and a negative return value indicates an error\&. See
200 \fBcapabilities\fR(7)
201 and the
202 \fIAmbientCapabilities=\fR
203 and
204 \fICapabilityBoundingSet=\fR
205 settings in
206 \fBsystemd.exec\fR(5)\&.
207 .PP
208 \fBsd_bus_creds_has_permitted_cap()\fR
209 is similar to
210 \fBsd_bus_creds_has_effective_cap()\fR, but will check the permitted capabilities mask\&.
211 .PP
212 \fBsd_bus_creds_has_inheritable_cap()\fR
213 is similar to
214 \fBsd_bus_creds_has_effective_cap()\fR, but will check the inheritable capabilities mask\&.
215 .PP
216 \fBsd_bus_creds_has_bounding_cap()\fR
217 is similar to
218 \fBsd_bus_creds_has_effective_cap()\fR, but will check the bounding capabilities mask\&.
219 .PP
220 \fBsd_bus_creds_get_selinux_context()\fR
221 will retrieve the SELinux security context (label) of the process\&.
222 .PP
223 \fBsd_bus_creds_get_audit_session_id()\fR
224 will retrieve the audit session identifier of the process\&. Returns \-ENXIO for processes that are not part of an audit session\&.
225 .PP
226 \fBsd_bus_creds_get_audit_login_uid()\fR
227 will retrieve the audit user login identifier (the identifier of the user who is "responsible" for the session)\&. Returns \-ENXIO for processes that are not part of an audit session\&.
228 .PP
229 \fBsd_bus_creds_get_tty()\fR
230 will retrieve the controlling TTY, without the prefixing "/dev/"\&. Returns \-ENXIO for processes that have no controlling TTY\&.
231 .PP
232 \fBsd_bus_creds_get_unique_name()\fR
233 will retrieve the D\-Bus unique name\&. See
234 \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
235 .PP
236 \fBsd_bus_creds_get_well_known_names()\fR
237 will retrieve the set of D\-Bus well\-known names\&. See
238 \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
239 .PP
240 \fBsd_bus_creds_get_description()\fR
241 will retrieve a descriptive name of the bus connection of the peer\&. This name is useful to discern multiple bus connections by the same peer, and may be altered by the peer with the
242 \fBsd_bus_set_description\fR(3)
243 call\&.
244 .PP
245 All functions that take a
246 \fIconst char**\fR
247 parameter will store the answer there as an address of a
248 \fBNUL\fR\-terminated string\&. It will be valid as long as
249 \fIc\fR
250 remains valid, and should not be freed or modified by the caller\&.
251 .PP
252 All functions that take a
253 \fIchar***\fR
254 parameter will store the answer there as an address of an array of strings\&. Each individual string is
255 \fBNUL\fR\-terminated, and the array is
256 \fBNULL\fR\-terminated as a whole\&. It will be valid as long as
257 \fIc\fR
258 remains valid, and should not be freed or modified by the caller\&.
259 .SH "RETURN VALUE"
260 .PP
261 On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
262 .SS "Errors"
263 .PP
264 Returned errors may indicate the following problems:
265 .PP
266 \fB\-ENODATA\fR
267 .RS 4
268 The given field is not available in the credentials object
269 \fIc\fR\&.
270 .RE
271 .PP
272 \fB\-ENXIO\fR
273 .RS 4
274 The given field is not specified for the described process or peer\&. This will be returned by
275 \fBsd_bus_creds_get_unit()\fR,
276 \fBsd_bus_creds_get_slice()\fR,
277 \fBsd_bus_creds_get_user_unit()\fR,
278 \fBsd_bus_creds_get_user_slice()\fR, and
279 \fBsd_bus_creds_get_session()\fR
280 if the process is not part of a systemd system unit, systemd user unit, systemd slice, or logind session\&. It will be returned by
281 \fBsd_bus_creds_get_owner_uid()\fR
282 if the process is not part of a systemd user unit or logind session\&. It will also be returned by
283 \fBsd_bus_creds_get_exe()\fR
284 and
285 \fBsd_bus_creds_get_cmdline()\fR
286 for kernel threads (since these are not started from an executable binary, nor have a command line), and by
287 \fBsd_bus_creds_get_audit_session_id()\fR
288 and
289 \fBsd_bus_creds_get_audit_login_uid()\fR
290 when the process is not part of an audit session, and
291 \fBsd_bus_creds_get_tty()\fR
292 if the process has no controlling TTY\&.
293 .RE
294 .PP
295 \fB\-EINVAL\fR
296 .RS 4
297 Specified pointer parameter is
298 \fBNULL\fR\&.
299 .RE
300 .PP
301 \fB\-ENOMEM\fR
302 .RS 4
303 Memory allocation failed\&.
304 .RE
305 .SH "NOTES"
306 .PP
307 Functions described here are available as a shared library, which can be compiled against and linked to with the
308 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
309 file\&.
310 .PP
311 The code described here uses
312 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
313 \fBsetenv\fR(3)
314 from a parallel thread\&. It is recommended to only do calls to
315 \fBsetenv()\fR
316 from an early phase of the program when no other threads have been started\&.
317 .SH "HISTORY"
318 .PP
319 \fBsd_bus_creds_get_pid()\fR,
320 \fBsd_bus_creds_get_tid()\fR,
321 \fBsd_bus_creds_get_gid()\fR,
322 \fBsd_bus_creds_get_comm()\fR,
323 \fBsd_bus_creds_get_tid_comm()\fR,
324 \fBsd_bus_creds_get_exe()\fR,
325 \fBsd_bus_creds_get_cmdline()\fR,
326 \fBsd_bus_creds_get_cgroup()\fR,
327 \fBsd_bus_creds_get_unit()\fR,
328 \fBsd_bus_creds_get_user_unit()\fR,
329 \fBsd_bus_creds_get_slice()\fR,
330 \fBsd_bus_creds_get_session()\fR,
331 \fBsd_bus_creds_get_owner_uid()\fR,
332 \fBsd_bus_creds_has_effective_cap()\fR,
333 \fBsd_bus_creds_has_permitted_cap()\fR,
334 \fBsd_bus_creds_has_inheritable_cap()\fR,
335 \fBsd_bus_creds_has_bounding_cap()\fR,
336 \fBsd_bus_creds_get_selinux_context()\fR,
337 \fBsd_bus_creds_get_audit_session_id()\fR,
338 \fBsd_bus_creds_get_audit_login_uid()\fR,
339 \fBsd_bus_creds_get_unique_name()\fR,
340 \fBsd_bus_creds_get_well_known_names()\fR,
341 \fBsd_bus_creds_get_ppid()\fR,
342 \fBsd_bus_creds_get_uid()\fR,
343 \fBsd_bus_creds_get_euid()\fR,
344 \fBsd_bus_creds_get_suid()\fR,
345 \fBsd_bus_creds_get_fsuid()\fR,
346 \fBsd_bus_creds_get_egid()\fR,
347 \fBsd_bus_creds_get_sgid()\fR,
348 \fBsd_bus_creds_get_fsgid()\fR,
349 \fBsd_bus_creds_get_supplementary_gids()\fR,
350 \fBsd_bus_creds_get_tty()\fR,
351 \fBsd_bus_creds_get_description()\fR, and
352 \fBsd_bus_creds_get_user_slice()\fR
353 were added in version 221\&.
354 .PP
355 \fBsd_bus_creds_get_pidfd_dup()\fR
356 was added in version 256\&.
357 .SH "SEE ALSO"
358 .PP
359 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_creds_new_from_pid\fR(3), \fBfork\fR(2), \fBexecve\fR(2), \fBcredentials\fR(7), \fBfree\fR(3), \fBproc\fR(5), \fBsystemd.journal-fields\fR(7)
360 .SH "NOTES"
361 .IP " 1." 4
362 Control Groups v2
363 .RS 4
364 \%https://docs.kernel.org/admin-guide/cgroup-v2.html
365 .RE
366 .IP " 2." 4
367 The D-Bus specification
368 .RS 4
369 \%https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
370 .RE