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