1SD_BUS_CREDS_GET_PID(3) sd_bus_creds_get_pid SD_BUS_CREDS_GET_PID(3)
2
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
25 #include <systemd/sd-bus.h>
26 int sd_bus_creds_get_pid(sd_bus_creds *c, pid_t *pid);
28 int sd_bus_creds_get_ppid(sd_bus_creds *c, pid_t *ppid);
30 int sd_bus_creds_get_tid(sd_bus_creds *c, pid_t *tid);
32 int sd_bus_creds_get_uid(sd_bus_creds *c, uid_t *uid);
34 int sd_bus_creds_get_euid(sd_bus_creds *c, uid_t *uid);
36 int sd_bus_creds_get_suid(sd_bus_creds *c, uid_t *uid);
38 int sd_bus_creds_get_fsuid(sd_bus_creds *c, uid_t *uid);
40 int sd_bus_creds_get_gid(sd_bus_creds *c, gid_t *gid);
42 int sd_bus_creds_get_egid(sd_bus_creds *c, gid_t *gid);
44 int sd_bus_creds_get_sgid(sd_bus_creds *c, gid_t *gid);
46 int sd_bus_creds_get_fsgid(sd_bus_creds *c, gid_t *gid);
48 int sd_bus_creds_get_supplementary_gids(sd_bus_creds *c,
50 const gid_t **gids);
51 int sd_bus_creds_get_comm(sd_bus_creds *c, const char **comm);
53 int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **comm);
55 int sd_bus_creds_get_exe(sd_bus_creds *c, const char **exe);
57 int sd_bus_creds_get_cmdline(sd_bus_creds *c, char ***cmdline);
59 int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **cgroup);
61 int sd_bus_creds_get_unit(sd_bus_creds *c, const char **unit);
63 int sd_bus_creds_get_slice(sd_bus_creds *c, const char **slice);
65 int sd_bus_creds_get_user_unit(sd_bus_creds *c, const char **unit);
67 int sd_bus_creds_get_user_slice(sd_bus_creds *c, const char **slice);
69 int sd_bus_creds_get_session(sd_bus_creds *c, const char **slice);
71 int sd_bus_creds_get_owner_uid(sd_bus_creds *c, uid_t *uid);
73 int sd_bus_creds_has_effective_cap(sd_bus_creds *c, int capability);
75 int sd_bus_creds_has_permitted_cap(sd_bus_creds *c, int capability);
77 int sd_bus_creds_has_inheritable_cap(sd_bus_creds *c, int capability);
79 int sd_bus_creds_has_bounding_cap(sd_bus_creds *c, int capability);
81 int sd_bus_creds_get_selinux_context(sd_bus_creds *c,
83 const char **context);
84 int sd_bus_creds_get_audit_session_id(sd_bus_creds *c,
86 uint32_t *sessionid);
87 int sd_bus_creds_get_audit_login_uid(sd_bus_creds *c, uid_t *loginuid);
89 int sd_bus_creds_get_tty(sd_bus_creds *c, const char **tty);
91 int sd_bus_creds_get_unique_name(sd_bus_creds *c, const char **name);
93 int sd_bus_creds_get_well_known_names(sd_bus_creds *c, char ***name);
95 int sd_bus_creds_get_description(sd_bus_creds *c, const char **name);
97
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 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 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 sd_bus_creds_get_tid() will retrieve the TID (thread identifier).
117 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 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 sd_bus_creds_get_supplementary_gids() will retrieve the supplementary
129 GIDs list.
130 sd_bus_creds_get_comm() will retrieve the comm field (truncated name of
132 the executable, as stored in /proc/pid/comm).
133 sd_bus_creds_get_tid_comm() will retrieve the comm field of the thread
135 (as stored in /proc/pid/task/tid/comm).
136 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 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 sd_bus_creds_get_cgroup() will retrieve the control group path. See
153 Control Groups v2[1].
154 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 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 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 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 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 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 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 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 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 sd_bus_creds_get_selinux_context() will retrieve the SELinux security
203 context (label) of the process.
204 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 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 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 sd_bus_creds_get_unique_name() will retrieve the D-Bus unique name. See
219 The D-Bus specification[2].
220 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 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 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 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
241 On success, these calls return 0 or a positive integer. On failure,
242 these calls return a negative errno-style error code.
243 Errors
245 Returned errors may indicate the following problems:
246 -ENODATA
248 The given field is not available in the credentials object c.
249 -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 -EINVAL
267 Specified pointer parameter is NULL.
268 -ENOMEM
270 Memory allocation failed.
271
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
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
281 1. Control Groups v2
282 https://docs.kernel.org/admin-guide/cgroup-v2.html
283 2. The D-Bus specification
285 https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
286systemd 253 SD_BUS_CREDS_GET_PID(3)