]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_bus_creds_get_pid.xml
journal-remote: remove unnecessary gnutls includes (#3895)
[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
479050b3
LP
409 <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by
410 <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it
411 was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry
412 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the
413 <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in
cd6d5e1c
ZJS
414 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
415 </para>
416
b7ea3f3e
LP
417 <para><function>sd_bus_creds_has_permitted_cap()</function> is
418 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
419 but will check the permitted capabilities mask.</para>
420
b7ea3f3e
LP
421 <para><function>sd_bus_creds_has_inheritable_cap()</function> is
422 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
423 but will check the inheritable capabilities mask.</para>
424
b7ea3f3e
LP
425 <para><function>sd_bus_creds_has_bounding_cap()</function> is
426 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
427 but will check the bounding capabilities mask.</para>
428
b7ea3f3e 429 <para><function>sd_bus_creds_get_selinux_context()</function> will
82adf6af 430 retrieve the SELinux security context (label) of the process.</para>
cd6d5e1c 431
52d7c4dc
LP
432 <para><function>sd_bus_creds_get_audit_session_id()</function>
433 will retrieve the audit session identifier of the process. Returns
434 -ENXIO for processes that are not part of an audit session.</para>
cd6d5e1c 435
b7ea3f3e 436 <para><function>sd_bus_creds_get_audit_login_uid()</function> will
cd6d5e1c 437 retrieve the audit user login identifier (the identifier of the
52d7c4dc
LP
438 user who is "responsible" for the session). Returns -ENXIO for
439 processes that are not part of an audit session.</para>
440
441 <para><function>sd_bus_creds_get_tty()</function> will retrieve
f6f7a984
LP
442 the controlling TTY, without the prefixing "/dev/". Returns -ENXIO
443 for processes that have no controlling TTY.</para>
cd6d5e1c 444
b7ea3f3e 445 <para><function>sd_bus_creds_get_unique_name()</function> will
cd6d5e1c
ZJS
446 retrieve the D-Bus unique name. See <ulink
447 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
448 D-Bus specification</ulink>.</para>
449
b7ea3f3e 450 <para><function>sd_bus_creds_get_well_known_names()</function> will
cd6d5e1c
ZJS
451 retrieve the set of D-Bus well-known names. See <ulink
452 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
453 D-Bus specification</ulink>.</para>
454
52d7c4dc 455 <para><function>sd_bus_creds_get_description()</function> will
5c20a8bc
LP
456 retrieve a descriptive name of the bus connection of the
457 peer. This name is useful to discern multiple bus connections by
458 the same peer, and may be altered by the peer with the
52d7c4dc 459 <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
5c20a8bc
LP
460 call.</para>
461
cd6d5e1c
ZJS
462 <para>All functions that take a <parameter>const
463 char**</parameter> parameter will store the answer there as an
464 address of a NUL-terminated string. It will be valid as long as
465 <parameter>c</parameter> remains valid, and should not be freed or
466 modified by the caller.</para>
467
468 <para>All functions that take a <parameter>char***</parameter>
7f3fdb7f 469 parameter will store the answer there as an address of an array
ff9b60f3 470 of strings. Each individual string is NUL-terminated, and the
cd6d5e1c
ZJS
471 array is NULL-terminated as a whole. It will be valid as long as
472 <parameter>c</parameter> remains valid, and should not be freed or
473 modified by the caller.</para>
474 </refsect1>
475
476 <refsect1>
477 <title>Return Value</title>
478
479 <para>On success, these calls return 0 or a positive integer. On
480 failure, these calls return a negative errno-style error code.
481 </para>
482 </refsect1>
483
484 <refsect1>
485 <title>Errors</title>
486
487 <para>Returned errors may indicate the following problems:</para>
488
489 <variablelist>
490 <varlistentry>
8474b70c 491 <term><constant>-ENODATA</constant></term>
cd6d5e1c 492
a8eaaee7 493 <listitem><para>The given field is not available in the
52d7c4dc 494 credentials object <parameter>c</parameter>.</para>
b200a92c 495 </listitem>
cd6d5e1c
ZJS
496 </varlistentry>
497
498 <varlistentry>
52d7c4dc 499 <term><constant>-ENXIO</constant></term>
cd6d5e1c 500
a8eaaee7 501 <listitem><para>The given field is not specified for the described
52d7c4dc
LP
502 process or peer. This will be returned by
503 <function>sd_bus_get_unit()</function>,
b7ea3f3e 504 <function>sd_bus_get_slice()</function>,
f6f7a984
LP
505 <function>sd_bus_get_user_unit()</function>,
506 <function>sd_bus_get_user_slice()</function>,
b7ea3f3e 507 <function>sd_bus_get_session()</function>, and
52d7c4dc
LP
508 <function>sd_bus_get_owner_uid()</function> if the process is
509 not part of a systemd system unit, systemd user unit, systemd
510 slice, or logind session. It will also be returned by
511 <function>sd_bus_creds_get_exe()</function> and
512 <function>sd_bus_creds_get_cmdline()</function> for kernel
a8eaaee7
JE
513 threads (since these are not started from an executable binary,
514 nor have a command line), and by
52d7c4dc
LP
515 <function>sd_bus_creds_get_audit_session_id()</function> and
516 <function>sd_bus_creds_get_audit_login_uid()</function> when
517 the process is not part of an audit session, and
518 <function>sd_bus_creds_get_tty()</function> if the process has
519 no controlling TTY.
520 </para>
b200a92c 521 </listitem>
cd6d5e1c
ZJS
522 </varlistentry>
523
524 <varlistentry>
8474b70c 525 <term><constant>-EINVAL</constant></term>
cd6d5e1c
ZJS
526
527 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
528 </para></listitem>
529 </varlistentry>
530
531 <varlistentry>
8474b70c 532 <term><constant>-ENOMEM</constant></term>
cd6d5e1c
ZJS
533
534 <listitem><para>Memory allocation failed.</para></listitem>
535 </varlistentry>
536 </variablelist>
537 </refsect1>
538
539 <refsect1>
540 <title>Notes</title>
541
f6f7a984
LP
542 <para><function>sd_bus_creds_get_pid()</function> and the other
543 functions described here are available as a shared library, which
544 can be compiled and linked to with the
545 <constant>libsystemd</constant> <citerefentry
546 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
cd6d5e1c
ZJS
547 file.</para>
548 </refsect1>
549
550 <refsect1>
551 <title>See Also</title>
552
553 <para>
554 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
555 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a984
LP
556 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
557 <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
558 <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
5aded369
ZJS
559 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
560 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
561 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e530ed5e 562 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
cd6d5e1c
ZJS
563 </para>
564 </refsect1>
565
566</refentry>