1SD_BUS_CREDS_GET_PID(3)      sd_bus_creds_get_pid      SD_BUS_CREDS_GET_PID(3)
2
3
4

NAME

6       sd_bus_creds_get_pid, sd_bus_creds_get_ppid, sd_bus_creds_get_tid,
7       sd_bus_creds_get_uid, sd_bus_creds_get_euid, sd_bus_creds_get_suid,
8       sd_bus_creds_get_fsuid, sd_bus_creds_get_gid, sd_bus_creds_get_egid,
9       sd_bus_creds_get_sgid, sd_bus_creds_get_fsgid,
10       sd_bus_creds_get_supplementary_gids, sd_bus_creds_get_comm,
11       sd_bus_creds_get_tid_comm, sd_bus_creds_get_exe,
12       sd_bus_creds_get_cmdline, sd_bus_creds_get_cgroup,
13       sd_bus_creds_get_unit, sd_bus_creds_get_slice,
14       sd_bus_creds_get_user_unit, sd_bus_creds_get_user_slice,
15       sd_bus_creds_get_session, sd_bus_creds_get_owner_uid,
16       sd_bus_creds_has_effective_cap, sd_bus_creds_has_permitted_cap,
17       sd_bus_creds_has_inheritable_cap, sd_bus_creds_has_bounding_cap,
18       sd_bus_creds_get_selinux_context, sd_bus_creds_get_audit_session_id,
19       sd_bus_creds_get_audit_login_uid, sd_bus_creds_get_tty,
20       sd_bus_creds_get_unique_name, sd_bus_creds_get_well_known_names,
21       sd_bus_creds_get_description - Retrieve fields from a credentials
22       object
23

SYNOPSIS

25       #include <systemd/sd-bus.h>
26
27       int sd_bus_creds_get_pid(sd_bus_creds *c, pid_t *pid);
28
29       int sd_bus_creds_get_ppid(sd_bus_creds *c, pid_t *ppid);
30
31       int sd_bus_creds_get_tid(sd_bus_creds *c, pid_t *tid);
32
33       int sd_bus_creds_get_uid(sd_bus_creds *c, uid_t *uid);
34
35       int sd_bus_creds_get_euid(sd_bus_creds *c, uid_t *uid);
36
37       int sd_bus_creds_get_suid(sd_bus_creds *c, uid_t *uid);
38
39       int sd_bus_creds_get_fsuid(sd_bus_creds *c, uid_t *uid);
40
41       int sd_bus_creds_get_gid(sd_bus_creds *c, gid_t *gid);
42
43       int sd_bus_creds_get_egid(sd_bus_creds *c, gid_t *gid);
44
45       int sd_bus_creds_get_sgid(sd_bus_creds *c, gid_t *gid);
46
47       int sd_bus_creds_get_fsgid(sd_bus_creds *c, gid_t *gid);
48
49       int sd_bus_creds_get_supplementary_gids(sd_bus_creds *c,
50                                               const gid_t **gids);
51
52       int sd_bus_creds_get_comm(sd_bus_creds *c, const char **comm);
53
54       int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **comm);
55
56       int sd_bus_creds_get_exe(sd_bus_creds *c, const char **exe);
57
58       int sd_bus_creds_get_cmdline(sd_bus_creds *c, char ***cmdline);
59
60       int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **cgroup);
61
62       int sd_bus_creds_get_unit(sd_bus_creds *c, const char **unit);
63
64       int sd_bus_creds_get_slice(sd_bus_creds *c, const char **slice);
65
66       int sd_bus_creds_get_user_unit(sd_bus_creds *c, const char **unit);
67
68       int sd_bus_creds_get_user_slice(sd_bus_creds *c, const char **slice);
69
70       int sd_bus_creds_get_session(sd_bus_creds *c, const char **slice);
71
72       int sd_bus_creds_get_owner_uid(sd_bus_creds *c, uid_t *uid);
73
74       int sd_bus_creds_has_effective_cap(sd_bus_creds *c, int capability);
75
76       int sd_bus_creds_has_permitted_cap(sd_bus_creds *c, int capability);
77
78       int sd_bus_creds_has_inheritable_cap(sd_bus_creds *c, int capability);
79
80       int sd_bus_creds_has_bounding_cap(sd_bus_creds *c, int capability);
81
82       int sd_bus_creds_get_selinux_context(sd_bus_creds *c,
83                                            const char **context);
84
85       int sd_bus_creds_get_audit_session_id(sd_bus_creds *c,
86                                             uint32_t *sessionid);
87
88       int sd_bus_creds_get_audit_login_uid(sd_bus_creds *c, uid_t *loginuid);
89
90       int sd_bus_creds_get_tty(sd_bus_creds *c, const char **tty);
91
92       int sd_bus_creds_get_unique_name(sd_bus_creds *c, const char **name);
93
94       int sd_bus_creds_get_well_known_names(sd_bus_creds *c, char ***name);
95
96       int sd_bus_creds_get_description(sd_bus_creds *c, const char **name);
97

DESCRIPTION

99       These functions return credential information from an sd_bus_creds
100       object. Credential objects may be created with
101       sd_bus_creds_new_from_pid(3), in which case they describe the
102       credentials of the process identified by the specified PID, with
103       sd_bus_get_name_creds(3), in which case they describe the credentials
104       of a bus peer identified by the specified bus name, with
105       sd_bus_get_owner_creds(3), in which case they describe the credentials
106       of the creator of a bus, or with sd_bus_message_get_creds(3), in which
107       case they describe the credentials of the sender of the message.
108
109       Not all credential fields are part of every "sd_bus_creds" object. Use
110       sd_bus_creds_get_mask(3) to determine the mask of fields available.
111
112       sd_bus_creds_get_pid() will retrieve the PID (process identifier).
113       Similarly, sd_bus_creds_get_ppid() will retrieve the parent PID. Note
114       that PID 1 has no parent process, in which case -ENXIO is returned.
115
116       sd_bus_creds_get_tid() will retrieve the TID (thread identifier).
117
118       sd_bus_creds_get_uid() will retrieve the numeric UID (user identifier).
119       Similarly, sd_bus_creds_get_euid() returns the effective UID,
120       sd_bus_creds_get_suid() the saved UID and sd_bus_creds_get_fsuid() the
121       file system UID.
122
123       sd_bus_creds_get_gid() will retrieve the numeric GID (group
124       identifier). Similarly, sd_bus_creds_get_egid() returns the effective
125       GID, sd_bus_creds_get_sgid() the saved GID and sd_bus_creds_get_fsgid()
126       the file system GID.
127
128       sd_bus_creds_get_supplementary_gids() will retrieve the supplementary
129       GIDs list.
130
131       sd_bus_creds_get_comm() will retrieve the comm field (truncated name of
132       the executable, as stored in /proc/pid/comm).
133
134       sd_bus_creds_get_tid_comm() will retrieve the comm field of the thread
135       (as stored in /proc/pid/task/tid/comm).
136
137       sd_bus_creds_get_exe() will retrieve the path to the program executable
138       (as stored in the /proc/pid/exe link, but with the " (deleted)" suffix
139       removed). Note that kernel threads do not have an executable path, in
140       which case -ENXIO is returned. Note that this property should not be
141       used for more than explanatory information, in particular it should not
142       be used for security-relevant decisions. That's because the executable
143       might have been replaced or removed by the time the value can be
144       processed. Moreover, the kernel exports this information in an
145       ambiguous way (i.e. a deleted executable cannot be safely distinguished
146       from one whose name suffix is " (deleted)").
147
148       sd_bus_creds_get_cmdline() will retrieve an array of command line
149       arguments (as stored in /proc/pid/cmdline). Note that kernel threads do
150       not have a command line, in which case -ENXIO is returned.
151
152       sd_bus_creds_get_cgroup() will retrieve the control group path. See
153       Control Groups v2[1].
154
155       sd_bus_creds_get_unit() will retrieve the systemd unit name (in the
156       system instance of systemd) that the process is a part of. See
157       systemd.unit(5). For processes that are not part of a unit, returns
158       -ENXIO.
159
160       sd_bus_creds_get_user_unit() will retrieve the systemd unit name (in
161       the user instance of systemd) that the process is a part of. See
162       systemd.unit(5). For processes that are not part of a user unit,
163       returns -ENXIO.
164
165       sd_bus_creds_get_slice() will retrieve the systemd slice (a unit in the
166       system instance of systemd) that the process is a part of. See
167       systemd.slice(5). Similarly, sd_bus_creds_get_user_slice() retrieves
168       the systemd slice of the process, in the user instance of systemd.
169
170       sd_bus_creds_get_session() will retrieve the identifier of the login
171       session that the process is a part of. Please note the login session
172       may be limited to a stub process or two. User processes may instead be
173       started from their systemd user manager, e.g. GUI applications started
174       using DBus activation, as well as service processes which are shared
175       between multiple logins of the same user. For processes that are not
176       part of a session, returns -ENXIO.
177
178       sd_bus_creds_get_owner_uid() will retrieve the numeric UID (user
179       identifier) of the user who owns the user unit or login session that
180       the process is a part of. See systemd-logind.service(8). For processes
181       that are not part of a user unit or session, returns -ENXIO.
182
183       sd_bus_creds_has_effective_cap() will check whether the capability
184       specified by capability was set in the effective capabilities mask. A
185       positive return value means that it was set, zero means that it was not
186       set, and a negative return value indicates an error. See
187       capabilities(7) and the AmbientCapabilities= and CapabilityBoundingSet=
188       settings in systemd.exec(5).
189
190       sd_bus_creds_has_permitted_cap() is similar to
191       sd_bus_creds_has_effective_cap(), but will check the permitted
192       capabilities mask.
193
194       sd_bus_creds_has_inheritable_cap() is similar to
195       sd_bus_creds_has_effective_cap(), but will check the inheritable
196       capabilities mask.
197
198       sd_bus_creds_has_bounding_cap() is similar to
199       sd_bus_creds_has_effective_cap(), but will check the bounding
200       capabilities mask.
201
202       sd_bus_creds_get_selinux_context() will retrieve the SELinux security
203       context (label) of the process.
204
205       sd_bus_creds_get_audit_session_id() will retrieve the audit session
206       identifier of the process. Returns -ENXIO for processes that are not
207       part of an audit session.
208
209       sd_bus_creds_get_audit_login_uid() will retrieve the audit user login
210       identifier (the identifier of the user who is "responsible" for the
211       session). Returns -ENXIO for processes that are not part of an audit
212       session.
213
214       sd_bus_creds_get_tty() will retrieve the controlling TTY, without the
215       prefixing "/dev/". Returns -ENXIO for processes that have no
216       controlling TTY.
217
218       sd_bus_creds_get_unique_name() will retrieve the D-Bus unique name. See
219       The D-Bus specification[2].
220
221       sd_bus_creds_get_well_known_names() will retrieve the set of D-Bus
222       well-known names. See The D-Bus specification[2].
223
224       sd_bus_creds_get_description() will retrieve a descriptive name of the
225       bus connection of the peer. This name is useful to discern multiple bus
226       connections by the same peer, and may be altered by the peer with the
227       sd_bus_set_description(3) call.
228
229       All functions that take a const char** parameter will store the answer
230       there as an address of a NUL-terminated string. It will be valid as
231       long as c remains valid, and should not be freed or modified by the
232       caller.
233
234       All functions that take a char*** parameter will store the answer there
235       as an address of an array of strings. Each individual string is
236       NUL-terminated, and the array is NULL-terminated as a whole. It will be
237       valid as long as c remains valid, and should not be freed or modified
238       by the caller.
239

RETURN VALUE

241       On success, these calls return 0 or a positive integer. On failure,
242       these calls return a negative errno-style error code.
243
244   Errors
245       Returned errors may indicate the following problems:
246
247       -ENODATA
248           The given field is not available in the credentials object c.
249
250       -ENXIO
251           The given field is not specified for the described process or peer.
252           This will be returned by sd_bus_creds_get_unit(),
253           sd_bus_creds_get_slice(), sd_bus_creds_get_user_unit(),
254           sd_bus_creds_get_user_slice(), and sd_bus_creds_get_session() if
255           the process is not part of a systemd system unit, systemd user
256           unit, systemd slice, or logind session. It will be returned by
257           sd_bus_creds_get_owner_uid() if the process is not part of a
258           systemd user unit or logind session. It will also be returned by
259           sd_bus_creds_get_exe() and sd_bus_creds_get_cmdline() for kernel
260           threads (since these are not started from an executable binary, nor
261           have a command line), and by sd_bus_creds_get_audit_session_id()
262           and sd_bus_creds_get_audit_login_uid() when the process is not part
263           of an audit session, and sd_bus_creds_get_tty() if the process has
264           no controlling TTY.
265
266       -EINVAL
267           Specified pointer parameter is NULL.
268
269       -ENOMEM
270           Memory allocation failed.
271

NOTES

273       These APIs are implemented as a shared library, which can be compiled
274       and linked to with the libsystemd pkg-config(1) file.
275

SEE ALSO

277       systemd(1), sd-bus(3), sd_bus_creds_new_from_pid(2), fork(2),
278       execve(2), credentials(7), free(3), proc(5), systemd.journal-fields(7)
279

NOTES

281        1. Control Groups v2
282           https://docs.kernel.org/admin-guide/cgroup-v2.html
283
284        2. The D-Bus specification
285           https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
286
287
288
289systemd 253                                            SD_BUS_CREDS_GET_PID(3)
Impressum