]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_bus_creds_get_pid.xml
man: generate configured paths in manpages
[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"
681eb9cf
FB
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % entities SYSTEM "custom-entities.ent" >
5%entities;
6]>
cd6d5e1c
ZJS
7
8<!--
5de0ccff 9 This file is part of systemd.
cd6d5e1c 10
5de0ccff 11 Copyright 2014 Zbigniew Jędrzejewski-Szmek
cd6d5e1c 12
5de0ccff
ZJS
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
cd6d5e1c 17
5de0ccff
ZJS
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
cd6d5e1c 22
5de0ccff
ZJS
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
cd6d5e1c
ZJS
25-->
26
7c071fda 27<refentry id="sd_bus_creds_get_pid" conditional="ENABLE_KDBUS">
cd6d5e1c
ZJS
28
29 <refentryinfo>
30 <title>sd_bus_creds_get_pid</title>
31 <productname>systemd</productname>
32
33 <authorgroup>
34 <author>
35 <contrib>A monkey with a typewriter</contrib>
36 <firstname>Zbigniew</firstname>
37 <surname>Jędrzejewski-Szmek</surname>
38 <email>zbyszek@in.waw.pl</email>
39 </author>
40 </authorgroup>
41 </refentryinfo>
42
43 <refmeta>
44 <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
45 <manvolnum>3</manvolnum>
46 </refmeta>
47
48 <refnamediv>
49 <refname>sd_bus_creds_get_pid</refname>
52d7c4dc 50 <refname>sd_bus_creds_get_ppid</refname>
cd6d5e1c
ZJS
51 <refname>sd_bus_creds_get_tid</refname>
52 <refname>sd_bus_creds_get_uid</refname>
52d7c4dc
LP
53 <refname>sd_bus_creds_get_euid</refname>
54 <refname>sd_bus_creds_get_suid</refname>
55 <refname>sd_bus_creds_get_fsuid</refname>
cd6d5e1c 56 <refname>sd_bus_creds_get_gid</refname>
52d7c4dc
LP
57 <refname>sd_bus_creds_get_egid</refname>
58 <refname>sd_bus_creds_get_sgid</refname>
59 <refname>sd_bus_creds_get_fsgid</refname>
60 <refname>sd_bus_creds_get_supplementary_gids</refname>
cd6d5e1c
ZJS
61 <refname>sd_bus_creds_get_comm</refname>
62 <refname>sd_bus_creds_get_tid_comm</refname>
63 <refname>sd_bus_creds_get_exe</refname>
64 <refname>sd_bus_creds_get_cmdline</refname>
65 <refname>sd_bus_creds_get_cgroup</refname>
66 <refname>sd_bus_creds_get_unit</refname>
67 <refname>sd_bus_creds_get_user_unit</refname>
68 <refname>sd_bus_creds_get_slice</refname>
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
198 <funcprototype>
199 <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
8dc385e7 200 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
201 <paramdef>const char **<parameter>unit</parameter></paramdef>
202 </funcprototype>
203
204 <funcprototype>
205 <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
8dc385e7 206 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
207 <paramdef>const char **<parameter>slice</parameter></paramdef>
208 </funcprototype>
209
210 <funcprototype>
211 <funcdef>int <function>sd_bus_creds_get_session</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_owner_uid</function></funcdef>
8dc385e7 218 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
219 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
220 </funcprototype>
221
222 <funcprototype>
223 <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
8dc385e7 224 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
225 <paramdef>int <parameter>capability</parameter></paramdef>
226 </funcprototype>
227
228 <funcprototype>
229 <funcdef>int <function>sd_bus_creds_has_permitted_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_inheritable_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_bounding_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_get_selinux_context</function></funcdef>
8dc385e7 248 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
249 <paramdef>const char **<parameter>context</parameter></paramdef>
250 </funcprototype>
251
252 <funcprototype>
253 <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
8dc385e7 254 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
255 <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
256 </funcprototype>
257
258 <funcprototype>
259 <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
8dc385e7 260 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
261 <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
262 </funcprototype>
263
52d7c4dc
LP
264 <funcprototype>
265 <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef>
266 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
267 <paramdef>const char **<parameter>tty</parameter></paramdef>
268 </funcprototype>
269
cd6d5e1c
ZJS
270 <funcprototype>
271 <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
8dc385e7 272 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
273 <paramdef>const char **<parameter>name</parameter></paramdef>
274 </funcprototype>
275
276 <funcprototype>
277 <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
8dc385e7 278 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
cd6d5e1c
ZJS
279 <paramdef>char ***<parameter>name</parameter></paramdef>
280 </funcprototype>
281
5c20a8bc 282 <funcprototype>
52d7c4dc 283 <funcdef>int <function>sd_bus_creds_get_description</function></funcdef>
5c20a8bc
LP
284 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
285 <paramdef>const char **<parameter>name</parameter></paramdef>
286 </funcprototype>
287
cd6d5e1c
ZJS
288 </funcsynopsis>
289 </refsynopsisdiv>
290
291 <refsect1>
292 <title>Description</title>
293
66f756d4 294 <para>These functions return information from an
52d7c4dc
LP
295 <parameter>sd_bus_creds</parameter> credential object. Credential
296 objects may be created with
cd6d5e1c 297 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
52d7c4dc
LP
298 in which case they describe the credentials of the process
299 identified by the specified PID, with
300 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
301 in which case they describe the credentials of a bus peer
302 identified by the specified bus name, or with
056f95d0 303 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
52d7c4dc
LP
304 in which case they describe the credentials of the creator of a
305 bus.</para>
cd6d5e1c 306
52d7c4dc
LP
307 <para><function>sd_bus_creds_get_pid()</function> will retrieve
308 the PID (process identifier). Similar,
309 <function>sd_bus_creds_get_ppid()</function> will retrieve the
310 parent PID. Note that PID 1 has no parent process, in which case
311 -ENXIO is returned.</para>
cd6d5e1c 312
b7ea3f3e 313 <para><function>sd_bus_creds_get_tid()</function> will retrieve the
cd6d5e1c
ZJS
314 TID (thread identifier).</para>
315
52d7c4dc
LP
316 <para><function>sd_bus_creds_get_uid()</function> will retrieve
317 the numeric UID (user identifier). Similar,
318 <function>sd_bus_creds_get_euid()</function> returns the effective
319 UID, <function>sd_bus_creds_get_suid()</function> the saved UID
320 and <function>sd_bus_creds_get_fsuid()</function> the file system
321 UID.</para>
cd6d5e1c 322
b7ea3f3e 323 <para><function>sd_bus_creds_get_gid()</function> will retrieve the
52d7c4dc
LP
324 numeric GID (group identifier). Similar,
325 <function>sd_bus_creds_get_egid()</function> returns the effective
326 GID, <function>sd_bus_creds_get_sgid()</function> the saved GID
327 and <function>sd_bus_creds_get_fsgid()</function> the file system
328 GID.</para>
329
330 <para><function>sd_bus_creds_get_supplementary_gids()</function>
331 will retrieve the supplementary GIDs list.</para>
cd6d5e1c 332
b7ea3f3e 333 <para><function>sd_bus_creds_get_comm()</function> will retrieve the
dc968941 334 comm field (truncated name of the executable, as stored in
cd6d5e1c
ZJS
335 <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
336 </para>
337
b7ea3f3e 338 <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
cd6d5e1c
ZJS
339 the comm field of the thread (as stored in
340 <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
341 </para>
342
52d7c4dc
LP
343 <para><function>sd_bus_creds_get_exe()</function> will retrieve
344 the path to the program executable (as stored in the
cd6d5e1c 345 <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
52d7c4dc
LP
346 link, but with <literal> (deleted)</literal> suffix removed). Note
347 that kernel threads do not have an executable path, in which case
348 -ENXIO is returned.</para>
cd6d5e1c 349
52d7c4dc
LP
350 <para><function>sd_bus_creds_get_cmdline()</function> will
351 retrieve an array of command line arguments (as stored in
352 <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note
353 that kernel threads do not have a command line, in which case
354 -ENXIO is returned.</para>
cd6d5e1c 355
b7ea3f3e 356 <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
cd6d5e1c
ZJS
357 the cgroup path. See <ulink
358 url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
359 </para>
360
52d7c4dc
LP
361 <para><function>sd_bus_creds_get_unit()</function> will retrieve
362 the systemd unit name (in the system instance of systemd) that the
cd6d5e1c 363 process is part of. See
52d7c4dc
LP
364 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
365 processes that are not part of a unit returns -ENXIO.
cd6d5e1c
ZJS
366 </para>
367
b7ea3f3e 368 <para><function>sd_bus_creds_get_user_unit()</function> will
cd6d5e1c
ZJS
369 retrieve the systemd unit name (in the user instance of systemd)
370 that the process is part of. See
52d7c4dc
LP
371 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
372 processes that are not part of a user unit returns -ENXIO.
cd6d5e1c
ZJS
373 </para>
374
b7ea3f3e 375 <para><function>sd_bus_creds_get_slice()</function> will retrieve
cd6d5e1c
ZJS
376 the systemd slice (a unit in the system instance of systemd) that
377 the process is part of. See
378 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
379 </para>
380
52d7c4dc
LP
381 <para><function>sd_bus_creds_get_session()</function> will
382 retrieve the logind session that the process is part of. See
383 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For
384 processes that are not part of a session returns -ENXIO.
cd6d5e1c
ZJS
385 </para>
386
52d7c4dc
LP
387 <para><function>sd_bus_creds_get_owner_uid()</function> will
388 retrieve the numeric UID (user identifier) of the user who owns
389 the session that the process is part of. See
cd6d5e1c 390 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
52d7c4dc 391 For processes that are not part of a session returns -ENXIO.
cd6d5e1c
ZJS
392 </para>
393
b7ea3f3e 394 <para><function>sd_bus_creds_has_effective_cap()</function> will
5485de1e
ZJS
395 check whether the capability specified by
396 <parameter>capability</parameter> was set in the effective
66f756d4 397 capabilities mask. A positive return value means that is was
5485de1e 398 set, zero means that it was not set, and a negative return
cd6d5e1c 399 value signifies an error. See
5aded369 400 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
cd6d5e1c
ZJS
401 and <varname>Capabilities=</varname> and
402 <varname>CapabilityBoundingSet=</varname> settings in
403 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
404 </para>
405
b7ea3f3e
LP
406 <para><function>sd_bus_creds_has_permitted_cap()</function> is
407 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
408 but will check the permitted capabilities mask.</para>
409
b7ea3f3e
LP
410 <para><function>sd_bus_creds_has_inheritable_cap()</function> is
411 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
412 but will check the inheritable capabilities mask.</para>
413
b7ea3f3e
LP
414 <para><function>sd_bus_creds_has_bounding_cap()</function> is
415 similar to <function>sd_bus_creds_has_effective_cap()</function>,
cd6d5e1c
ZJS
416 but will check the bounding capabilities mask.</para>
417
b7ea3f3e 418 <para><function>sd_bus_creds_get_selinux_context()</function> will
82adf6af 419 retrieve the SELinux security context (label) of the process.</para>
cd6d5e1c 420
52d7c4dc
LP
421 <para><function>sd_bus_creds_get_audit_session_id()</function>
422 will retrieve the audit session identifier of the process. Returns
423 -ENXIO for processes that are not part of an audit session.</para>
cd6d5e1c 424
b7ea3f3e 425 <para><function>sd_bus_creds_get_audit_login_uid()</function> will
cd6d5e1c 426 retrieve the audit user login identifier (the identifier of the
52d7c4dc
LP
427 user who is "responsible" for the session). Returns -ENXIO for
428 processes that are not part of an audit session.</para>
429
430 <para><function>sd_bus_creds_get_tty()</function> will retrieve
431 the controlling TTY. Returns -ENXIO for processes that have no
432 controlling TTY.</para>
cd6d5e1c 433
b7ea3f3e 434 <para><function>sd_bus_creds_get_unique_name()</function> will
cd6d5e1c
ZJS
435 retrieve the D-Bus unique name. See <ulink
436 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
437 D-Bus specification</ulink>.</para>
438
b7ea3f3e 439 <para><function>sd_bus_creds_get_well_known_names()</function> will
cd6d5e1c
ZJS
440 retrieve the set of D-Bus well-known names. See <ulink
441 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
442 D-Bus specification</ulink>.</para>
443
52d7c4dc 444 <para><function>sd_bus_creds_get_description()</function> will
5c20a8bc
LP
445 retrieve a descriptive name of the bus connection of the
446 peer. This name is useful to discern multiple bus connections by
447 the same peer, and may be altered by the peer with the
52d7c4dc 448 <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
5c20a8bc
LP
449 call.</para>
450
cd6d5e1c
ZJS
451 <para>All functions that take a <parameter>const
452 char**</parameter> parameter will store the answer there as an
453 address of a NUL-terminated string. It will be valid as long as
454 <parameter>c</parameter> remains valid, and should not be freed or
455 modified by the caller.</para>
456
457 <para>All functions that take a <parameter>char***</parameter>
458 parameter will store the answer there as an address of a an array
ff9b60f3 459 of strings. Each individual string is NUL-terminated, and the
cd6d5e1c
ZJS
460 array is NULL-terminated as a whole. It will be valid as long as
461 <parameter>c</parameter> remains valid, and should not be freed or
462 modified by the caller.</para>
463 </refsect1>
464
465 <refsect1>
466 <title>Return Value</title>
467
468 <para>On success, these calls return 0 or a positive integer. On
469 failure, these calls return a negative errno-style error code.
470 </para>
471 </refsect1>
472
473 <refsect1>
474 <title>Errors</title>
475
476 <para>Returned errors may indicate the following problems:</para>
477
478 <variablelist>
479 <varlistentry>
8474b70c 480 <term><constant>-ENODATA</constant></term>
cd6d5e1c 481
52d7c4dc
LP
482 <listitem><para>Given field is not available in the
483 credentials object <parameter>c</parameter>.</para>
b200a92c 484 </listitem>
cd6d5e1c
ZJS
485 </varlistentry>
486
487 <varlistentry>
52d7c4dc 488 <term><constant>-ENXIO</constant></term>
cd6d5e1c 489
52d7c4dc
LP
490 <listitem><para>Given field is not specified for the described
491 process or peer. This will be returned by
492 <function>sd_bus_get_unit()</function>,
b7ea3f3e
LP
493 <function>sd_bus_get_user_unit()</function>,
494 <function>sd_bus_get_slice()</function>,
495 <function>sd_bus_get_session()</function>, and
52d7c4dc
LP
496 <function>sd_bus_get_owner_uid()</function> if the process is
497 not part of a systemd system unit, systemd user unit, systemd
498 slice, or logind session. It will also be returned by
499 <function>sd_bus_creds_get_exe()</function> and
500 <function>sd_bus_creds_get_cmdline()</function> for kernel
501 threads (since these aren't started from an executable binary
502 or have a command line),
503 <function>sd_bus_creds_get_audit_session_id()</function> and
504 <function>sd_bus_creds_get_audit_login_uid()</function> when
505 the process is not part of an audit session, and
506 <function>sd_bus_creds_get_tty()</function> if the process has
507 no controlling TTY.
508 </para>
b200a92c 509 </listitem>
cd6d5e1c
ZJS
510 </varlistentry>
511
512 <varlistentry>
8474b70c 513 <term><constant>-EINVAL</constant></term>
cd6d5e1c
ZJS
514
515 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
516 </para></listitem>
517 </varlistentry>
518
519 <varlistentry>
8474b70c 520 <term><constant>-ENOMEM</constant></term>
cd6d5e1c
ZJS
521
522 <listitem><para>Memory allocation failed.</para></listitem>
523 </varlistentry>
524 </variablelist>
525 </refsect1>
526
527 <refsect1>
528 <title>Notes</title>
529
530 <para><function>sd_bus_open_user()</function> and other functions
531 described here are available as a shared library, which can be
532 compiled and linked to with the
5aded369 533 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
cd6d5e1c
ZJS
534 file.</para>
535 </refsect1>
536
537 <refsect1>
538 <title>See Also</title>
539
540 <para>
541 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
542 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
cd6d5e1c
ZJS
543 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
544 <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
5aded369
ZJS
545 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
546 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
547 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e530ed5e 548 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
cd6d5e1c
ZJS
549 </para>
550 </refsect1>
551
552</refentry>