]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_bus_creds_get_pid.xml
verify: use manager_load_startable_unit_or_warn() to load units for verification
[thirdparty/systemd.git] / man / sd_bus_creds_get_pid.xml
CommitLineData
3802a3d3 1<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
cd6d5e1c 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
cd6d5e1c
ZJS
4
5<!--
572eb058
ZJS
6 SPDX-License-Identifier: LGPL-2.1+
7
5de0ccff 8 This file is part of systemd.
cd6d5e1c 9
5de0ccff 10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
cd6d5e1c 11
5de0ccff
ZJS
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
cd6d5e1c 16
5de0ccff
ZJS
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
cd6d5e1c 21
5de0ccff
ZJS
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
cd6d5e1c
ZJS
24-->
25
48f69d8f 26<refentry id="sd_bus_creds_get_pid">
cd6d5e1c
ZJS
27
28 <refentryinfo>
29 <title>sd_bus_creds_get_pid</title>
30 <productname>systemd</productname>
31
32 <authorgroup>
33 <author>
34 <contrib>A monkey with a typewriter</contrib>
35 <firstname>Zbigniew</firstname>
36 <surname>Jędrzejewski-Szmek</surname>
37 <email>zbyszek@in.waw.pl</email>
38 </author>
39 </authorgroup>
40 </refentryinfo>
41
42 <refmeta>
43 <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
44 <manvolnum>3</manvolnum>
45 </refmeta>
46
47 <refnamediv>
48 <refname>sd_bus_creds_get_pid</refname>
52d7c4dc 49 <refname>sd_bus_creds_get_ppid</refname>
cd6d5e1c
ZJS
50 <refname>sd_bus_creds_get_tid</refname>
51 <refname>sd_bus_creds_get_uid</refname>
52d7c4dc
LP
52 <refname>sd_bus_creds_get_euid</refname>
53 <refname>sd_bus_creds_get_suid</refname>
54 <refname>sd_bus_creds_get_fsuid</refname>
cd6d5e1c 55 <refname>sd_bus_creds_get_gid</refname>
52d7c4dc
LP
56 <refname>sd_bus_creds_get_egid</refname>
57 <refname>sd_bus_creds_get_sgid</refname>
58 <refname>sd_bus_creds_get_fsgid</refname>
59 <refname>sd_bus_creds_get_supplementary_gids</refname>
cd6d5e1c
ZJS
60 <refname>sd_bus_creds_get_comm</refname>
61 <refname>sd_bus_creds_get_tid_comm</refname>
62 <refname>sd_bus_creds_get_exe</refname>
63 <refname>sd_bus_creds_get_cmdline</refname>
64 <refname>sd_bus_creds_get_cgroup</refname>
65 <refname>sd_bus_creds_get_unit</refname>
cd6d5e1c 66 <refname>sd_bus_creds_get_slice</refname>
f6f7a984
LP
67 <refname>sd_bus_creds_get_user_unit</refname>
68 <refname>sd_bus_creds_get_user_slice</refname>
cd6d5e1c
ZJS
69 <refname>sd_bus_creds_get_session</refname>
70 <refname>sd_bus_creds_get_owner_uid</refname>
71 <refname>sd_bus_creds_has_effective_cap</refname>
72 <refname>sd_bus_creds_has_permitted_cap</refname>
73 <refname>sd_bus_creds_has_inheritable_cap</refname>
74 <refname>sd_bus_creds_has_bounding_cap</refname>
75 <refname>sd_bus_creds_get_selinux_context</refname>
76 <refname>sd_bus_creds_get_audit_session_id</refname>
77 <refname>sd_bus_creds_get_audit_login_uid</refname>
52d7c4dc 78 <refname>sd_bus_creds_get_tty</refname>
cd6d5e1c
ZJS
79 <refname>sd_bus_creds_get_unique_name</refname>
80 <refname>sd_bus_creds_get_well_known_names</refname>
52d7c4dc 81 <refname>sd_bus_creds_get_description</refname>
cd6d5e1c
ZJS
82
83 <refpurpose>Retrieve fields from a credentials object</refpurpose>
84 </refnamediv>
85
86 <refsynopsisdiv>
87 <funcsynopsis>
88 <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
89
90 <funcprototype>
91 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
8dc385e7 92 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
93 <paramdef>pid_t *<parameter>pid</parameter></paramdef>
94 </funcprototype>
95
52d7c4dc
LP
96 <funcprototype>
97 <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef>
98 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
99 <paramdef>pid_t *<parameter>ppid</parameter></paramdef>
100 </funcprototype>
101
cd6d5e1c
ZJS
102 <funcprototype>
103 <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
8dc385e7 104 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
105 <paramdef>pid_t *<parameter>tid</parameter></paramdef>
106 </funcprototype>
107
108 <funcprototype>
52d7c4dc
LP
109 <funcdef>int <function>sd_bus_creds_get_uid</function></funcdef>
110 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
111 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
112 </funcprototype>
113
114 <funcprototype>
115 <funcdef>int <function>sd_bus_creds_get_euid</function></funcdef>
116 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
117 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
118 </funcprototype>
119
120 <funcprototype>
121 <funcdef>int <function>sd_bus_creds_get_suid</function></funcdef>
122 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
123 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
124 </funcprototype>
125
126 <funcprototype>
127 <funcdef>int <function>sd_bus_creds_get_fsuid</function></funcdef>
8dc385e7 128 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
129 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
130 </funcprototype>
131
132 <funcprototype>
133 <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
8dc385e7 134 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
135 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
136 </funcprototype>
137
52d7c4dc
LP
138 <funcprototype>
139 <funcdef>int <function>sd_bus_creds_get_egid</function></funcdef>
140 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
141 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
142 </funcprototype>
143
144 <funcprototype>
145 <funcdef>int <function>sd_bus_creds_get_sgid</function></funcdef>
146 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
147 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
148 </funcprototype>
149
150 <funcprototype>
151 <funcdef>int <function>sd_bus_creds_get_fsgid</function></funcdef>
152 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
153 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
154 </funcprototype>
155
156 <funcprototype>
157 <funcdef>int <function>sd_bus_creds_get_supplementary_gids</function></funcdef>
158 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
159 <paramdef>const gid_t **<parameter>gids</parameter></paramdef>
160 </funcprototype>
161
cd6d5e1c
ZJS
162 <funcprototype>
163 <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
8dc385e7 164 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
165 <paramdef>const char **<parameter>comm</parameter></paramdef>
166 </funcprototype>
167
168 <funcprototype>
169 <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
8dc385e7 170 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
171 <paramdef>const char **<parameter>comm</parameter></paramdef>
172 </funcprototype>
173
174 <funcprototype>
175 <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
8dc385e7 176 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
177 <paramdef>const char **<parameter>exe</parameter></paramdef>
178 </funcprototype>
179
180 <funcprototype>
181 <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
8dc385e7 182 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
183 <paramdef>char ***<parameter>cmdline</parameter></paramdef>
184 </funcprototype>
185
186 <funcprototype>
187 <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
8dc385e7 188 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
189 <paramdef>const char **<parameter>cgroup</parameter></paramdef>
190 </funcprototype>
191
192 <funcprototype>
193 <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
8dc385e7 194 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
195 <paramdef>const char **<parameter>unit</parameter></paramdef>
196 </funcprototype>
197
f6f7a984
LP
198 <funcprototype>
199 <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
200 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
201 <paramdef>const char **<parameter>slice</parameter></paramdef>
202 </funcprototype>
203
cd6d5e1c
ZJS
204 <funcprototype>
205 <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
8dc385e7 206 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
207 <paramdef>const char **<parameter>unit</parameter></paramdef>
208 </funcprototype>
209
210 <funcprototype>
f6f7a984 211 <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef>
8dc385e7 212 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
213 <paramdef>const char **<parameter>slice</parameter></paramdef>
214 </funcprototype>
215
216 <funcprototype>
217 <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
8dc385e7 218 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
219 <paramdef>const char **<parameter>slice</parameter></paramdef>
220 </funcprototype>
221
222 <funcprototype>
223 <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
8dc385e7 224 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
225 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
226 </funcprototype>
227
228 <funcprototype>
229 <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
8dc385e7 230 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
231 <paramdef>int <parameter>capability</parameter></paramdef>
232 </funcprototype>
233
234 <funcprototype>
235 <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
8dc385e7 236 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
237 <paramdef>int <parameter>capability</parameter></paramdef>
238 </funcprototype>
239
240 <funcprototype>
241 <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
8dc385e7 242 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
243 <paramdef>int <parameter>capability</parameter></paramdef>
244 </funcprototype>
245
246 <funcprototype>
247 <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
8dc385e7 248 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
249 <paramdef>int <parameter>capability</parameter></paramdef>
250 </funcprototype>
251
252 <funcprototype>
253 <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
8dc385e7 254 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
255 <paramdef>const char **<parameter>context</parameter></paramdef>
256 </funcprototype>
257
258 <funcprototype>
259 <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
8dc385e7 260 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
261 <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
262 </funcprototype>
263
264 <funcprototype>
265 <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
8dc385e7 266 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
267 <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
268 </funcprototype>
269
52d7c4dc
LP
270 <funcprototype>
271 <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef>
272 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
273 <paramdef>const char **<parameter>tty</parameter></paramdef>
274 </funcprototype>
275
cd6d5e1c
ZJS
276 <funcprototype>
277 <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
8dc385e7 278 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
279 <paramdef>const char **<parameter>name</parameter></paramdef>
280 </funcprototype>
281
282 <funcprototype>
283 <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
8dc385e7 284 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
285 <paramdef>char ***<parameter>name</parameter></paramdef>
286 </funcprototype>
287
5c20a8bc 288 <funcprototype>
52d7c4dc 289 <funcdef>int <function>sd_bus_creds_get_description</function></funcdef>
5c20a8bc
LP
290 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
291 <paramdef>const char **<parameter>name</parameter></paramdef>
292 </funcprototype>
293
cd6d5e1c
ZJS
294 </funcsynopsis>
295 </refsynopsisdiv>
296
297 <refsect1>
298 <title>Description</title>
299
f6f7a984
LP
300 <para>These functions return credential information from an
301 <parameter>sd_bus_creds</parameter> object. Credential objects may
302 be created with
cd6d5e1c 303 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
52d7c4dc
LP
304 in which case they describe the credentials of the process
305 identified by the specified PID, with
306 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
307 in which case they describe the credentials of a bus peer
b655a028 308 identified by the specified bus name, with
056f95d0 309 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
52d7c4dc 310 in which case they describe the credentials of the creator of a
b655a028
UTL
311 bus, or with
312 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a984
LP
313 in which case they describe the credentials of the sender of the
314 message.</para>
315
316 <para>Not all credential fields are part of every
317 <literal>sd_bus_creds</literal> object. Use
318 <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry>
319 to determine the mask of fields available.</para>
cd6d5e1c 320
52d7c4dc 321 <para><function>sd_bus_creds_get_pid()</function> will retrieve
a8eaaee7 322 the PID (process identifier). Similarly,
52d7c4dc
LP
323 <function>sd_bus_creds_get_ppid()</function> will retrieve the
324 parent PID. Note that PID 1 has no parent process, in which case
325 -ENXIO is returned.</para>
cd6d5e1c 326
b7ea3f3e 327 <para><function>sd_bus_creds_get_tid()</function> will retrieve the
cd6d5e1c
ZJS
328 TID (thread identifier).</para>
329
52d7c4dc 330 <para><function>sd_bus_creds_get_uid()</function> will retrieve
a8eaaee7 331 the numeric UID (user identifier). Similarly,
52d7c4dc
LP
332 <function>sd_bus_creds_get_euid()</function> returns the effective
333 UID, <function>sd_bus_creds_get_suid()</function> the saved UID
334 and <function>sd_bus_creds_get_fsuid()</function> the file system
335 UID.</para>
cd6d5e1c 336
b7ea3f3e 337 <para><function>sd_bus_creds_get_gid()</function> will retrieve the
a8eaaee7 338 numeric GID (group identifier). Similarly,
52d7c4dc
LP
339 <function>sd_bus_creds_get_egid()</function> returns the effective
340 GID, <function>sd_bus_creds_get_sgid()</function> the saved GID
341 and <function>sd_bus_creds_get_fsgid()</function> the file system
342 GID.</para>
343
344 <para><function>sd_bus_creds_get_supplementary_gids()</function>
345 will retrieve the supplementary GIDs list.</para>
cd6d5e1c 346
b7ea3f3e 347 <para><function>sd_bus_creds_get_comm()</function> will retrieve the
dc968941 348 comm field (truncated name of the executable, as stored in
cd6d5e1c
ZJS
349 <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
350 </para>
351
b7ea3f3e 352 <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
cd6d5e1c
ZJS
353 the comm field of the thread (as stored in
354 <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
355 </para>
356
52d7c4dc
LP
357 <para><function>sd_bus_creds_get_exe()</function> will retrieve
358 the path to the program executable (as stored in the
cd6d5e1c 359 <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
a8eaaee7 360 link, but with the <literal> (deleted)</literal> suffix removed). Note
52d7c4dc
LP
361 that kernel threads do not have an executable path, in which case
362 -ENXIO is returned.</para>
cd6d5e1c 363
52d7c4dc
LP
364 <para><function>sd_bus_creds_get_cmdline()</function> will
365 retrieve an array of command line arguments (as stored in
366 <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note
367 that kernel threads do not have a command line, in which case
368 -ENXIO is returned.</para>
cd6d5e1c 369
b7ea3f3e 370 <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
c7458f93 371 the control group path. See <ulink
3c887f97 372 url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>.
cd6d5e1c
ZJS
373 </para>
374
52d7c4dc
LP
375 <para><function>sd_bus_creds_get_unit()</function> will retrieve
376 the systemd unit name (in the system instance of systemd) that the
a8eaaee7 377 process is a part of. See
52d7c4dc 378 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
b938cb90 379 processes that are not part of a unit, returns -ENXIO.
cd6d5e1c
ZJS
380 </para>
381
b7ea3f3e 382 <para><function>sd_bus_creds_get_user_unit()</function> will
cd6d5e1c 383 retrieve the systemd unit name (in the user instance of systemd)
a8eaaee7 384 that the process is a part of. See
52d7c4dc 385 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
b938cb90 386 processes that are not part of a user unit, returns -ENXIO.
cd6d5e1c
ZJS
387 </para>
388
b7ea3f3e 389 <para><function>sd_bus_creds_get_slice()</function> will retrieve
cd6d5e1c 390 the systemd slice (a unit in the system instance of systemd) that
a8eaaee7
JE
391 the process is a part of. See
392 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly,
f6f7a984
LP
393 <function>sd_bus_creds_get_user_slice()</function> retrieves the
394 systemd slice of the process, in the user instance of systemd.
cd6d5e1c
ZJS
395 </para>
396
52d7c4dc 397 <para><function>sd_bus_creds_get_session()</function> will
f6f7a984 398 retrieve the identifier of the login session that the process is
1c97e2eb
AJ
399 a part of. Please note the login session may be limited to a stub
400 process or two. User processes may instead be started from their
401 systemd user manager, e.g. GUI applications started using DBus
402 activation, as well as service processes which are shared between
403 multiple logins of the same user. For processes that are not part
404 of a session, returns -ENXIO.</para>
cd6d5e1c 405
52d7c4dc
LP
406 <para><function>sd_bus_creds_get_owner_uid()</function> will
407 retrieve the numeric UID (user identifier) of the user who owns
1c97e2eb 408 the user unit or login session that the process is a part of. See
f6f7a984 409 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
1c97e2eb
AJ
410 For processes that are not part of a user unit or session, returns
411 -ENXIO.
cd6d5e1c
ZJS
412 </para>
413
479050b3
LP
414 <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by
415 <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it
416 was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry
417 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the
418 <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in
cd6d5e1c
ZJS
419 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
420 </para>
421
b7ea3f3e
LP
422 <para><function>sd_bus_creds_has_permitted_cap()</function> is
423 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
424 but will check the permitted capabilities mask.</para>
425
b7ea3f3e
LP
426 <para><function>sd_bus_creds_has_inheritable_cap()</function> is
427 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
428 but will check the inheritable capabilities mask.</para>
429
b7ea3f3e
LP
430 <para><function>sd_bus_creds_has_bounding_cap()</function> is
431 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
432 but will check the bounding capabilities mask.</para>
433
b7ea3f3e 434 <para><function>sd_bus_creds_get_selinux_context()</function> will
82adf6af 435 retrieve the SELinux security context (label) of the process.</para>
cd6d5e1c 436
52d7c4dc
LP
437 <para><function>sd_bus_creds_get_audit_session_id()</function>
438 will retrieve the audit session identifier of the process. Returns
439 -ENXIO for processes that are not part of an audit session.</para>
cd6d5e1c 440
b7ea3f3e 441 <para><function>sd_bus_creds_get_audit_login_uid()</function> will
cd6d5e1c 442 retrieve the audit user login identifier (the identifier of the
52d7c4dc
LP
443 user who is "responsible" for the session). Returns -ENXIO for
444 processes that are not part of an audit session.</para>
445
446 <para><function>sd_bus_creds_get_tty()</function> will retrieve
f6f7a984
LP
447 the controlling TTY, without the prefixing "/dev/". Returns -ENXIO
448 for processes that have no controlling TTY.</para>
cd6d5e1c 449
b7ea3f3e 450 <para><function>sd_bus_creds_get_unique_name()</function> will
cd6d5e1c
ZJS
451 retrieve the D-Bus unique name. See <ulink
452 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
453 D-Bus specification</ulink>.</para>
454
b7ea3f3e 455 <para><function>sd_bus_creds_get_well_known_names()</function> will
cd6d5e1c
ZJS
456 retrieve the set of D-Bus well-known names. See <ulink
457 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
458 D-Bus specification</ulink>.</para>
459
52d7c4dc 460 <para><function>sd_bus_creds_get_description()</function> will
5c20a8bc
LP
461 retrieve a descriptive name of the bus connection of the
462 peer. This name is useful to discern multiple bus connections by
463 the same peer, and may be altered by the peer with the
52d7c4dc 464 <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
5c20a8bc
LP
465 call.</para>
466
cd6d5e1c
ZJS
467 <para>All functions that take a <parameter>const
468 char**</parameter> parameter will store the answer there as an
469 address of a NUL-terminated string. It will be valid as long as
470 <parameter>c</parameter> remains valid, and should not be freed or
471 modified by the caller.</para>
472
473 <para>All functions that take a <parameter>char***</parameter>
7f3fdb7f 474 parameter will store the answer there as an address of an array
ff9b60f3 475 of strings. Each individual string is NUL-terminated, and the
cd6d5e1c
ZJS
476 array is NULL-terminated as a whole. It will be valid as long as
477 <parameter>c</parameter> remains valid, and should not be freed or
478 modified by the caller.</para>
479 </refsect1>
480
481 <refsect1>
482 <title>Return Value</title>
483
484 <para>On success, these calls return 0 or a positive integer. On
485 failure, these calls return a negative errno-style error code.
486 </para>
487 </refsect1>
488
489 <refsect1>
490 <title>Errors</title>
491
492 <para>Returned errors may indicate the following problems:</para>
493
494 <variablelist>
495 <varlistentry>
8474b70c 496 <term><constant>-ENODATA</constant></term>
cd6d5e1c 497
a8eaaee7 498 <listitem><para>The given field is not available in the
52d7c4dc 499 credentials object <parameter>c</parameter>.</para>
b200a92c 500 </listitem>
cd6d5e1c
ZJS
501 </varlistentry>
502
503 <varlistentry>
52d7c4dc 504 <term><constant>-ENXIO</constant></term>
cd6d5e1c 505
a8eaaee7 506 <listitem><para>The given field is not specified for the described
52d7c4dc 507 process or peer. This will be returned by
fc47bea6
AJ
508 <function>sd_bus_creds_get_unit()</function>,
509 <function>sd_bus_creds_get_slice()</function>,
510 <function>sd_bus_creds_get_user_unit()</function>,
511 <function>sd_bus_creds_get_user_slice()</function>, and
512 <function>sd_bus_creds_get_session()</function> if the process is
52d7c4dc 513 not part of a systemd system unit, systemd user unit, systemd
1c97e2eb
AJ
514 slice, or logind session. It will be returned by
515 <function>sd_bus_creds_get_owner_uid()</function> if the process is
516 not part of a systemd user unit or logind session. It will also be
517 returned by <function>sd_bus_creds_get_exe()</function> and
52d7c4dc 518 <function>sd_bus_creds_get_cmdline()</function> for kernel
a8eaaee7
JE
519 threads (since these are not started from an executable binary,
520 nor have a command line), and by
52d7c4dc
LP
521 <function>sd_bus_creds_get_audit_session_id()</function> and
522 <function>sd_bus_creds_get_audit_login_uid()</function> when
523 the process is not part of an audit session, and
524 <function>sd_bus_creds_get_tty()</function> if the process has
525 no controlling TTY.
526 </para>
b200a92c 527 </listitem>
cd6d5e1c
ZJS
528 </varlistentry>
529
530 <varlistentry>
8474b70c 531 <term><constant>-EINVAL</constant></term>
cd6d5e1c
ZJS
532
533 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
534 </para></listitem>
535 </varlistentry>
536
537 <varlistentry>
8474b70c 538 <term><constant>-ENOMEM</constant></term>
cd6d5e1c
ZJS
539
540 <listitem><para>Memory allocation failed.</para></listitem>
541 </varlistentry>
542 </variablelist>
543 </refsect1>
544
545 <refsect1>
546 <title>Notes</title>
547
f6f7a984
LP
548 <para><function>sd_bus_creds_get_pid()</function> and the other
549 functions described here are available as a shared library, which
550 can be compiled and linked to with the
551 <constant>libsystemd</constant> <citerefentry
552 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
cd6d5e1c
ZJS
553 file.</para>
554 </refsect1>
555
556 <refsect1>
557 <title>See Also</title>
558
559 <para>
560 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
561 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a984
LP
562 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
563 <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
564 <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
5aded369
ZJS
565 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
566 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
567 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e530ed5e 568 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
cd6d5e1c
ZJS
569 </para>
570 </refsect1>
571
572</refentry>