1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
24 <refentry id="sd_bus_creds_get_pid" conditional="ENABLE_KDBUS">
27 <title>sd_bus_creds_get_pid</title>
28 <productname>systemd</productname>
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>
41 <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_bus_creds_get_pid</refname>
47 <refname>sd_bus_creds_get_pid_starttime</refname>
48 <refname>sd_bus_creds_get_tid</refname>
49 <refname>sd_bus_creds_get_uid</refname>
50 <refname>sd_bus_creds_get_gid</refname>
51 <refname>sd_bus_creds_get_comm</refname>
52 <refname>sd_bus_creds_get_tid_comm</refname>
53 <refname>sd_bus_creds_get_exe</refname>
54 <refname>sd_bus_creds_get_cmdline</refname>
55 <refname>sd_bus_creds_get_cgroup</refname>
56 <refname>sd_bus_creds_get_unit</refname>
57 <refname>sd_bus_creds_get_user_unit</refname>
58 <refname>sd_bus_creds_get_slice</refname>
59 <refname>sd_bus_creds_get_session</refname>
60 <refname>sd_bus_creds_get_owner_uid</refname>
61 <refname>sd_bus_creds_has_effective_cap</refname>
62 <refname>sd_bus_creds_has_permitted_cap</refname>
63 <refname>sd_bus_creds_has_inheritable_cap</refname>
64 <refname>sd_bus_creds_has_bounding_cap</refname>
65 <refname>sd_bus_creds_get_selinux_context</refname>
66 <refname>sd_bus_creds_get_audit_session_id</refname>
67 <refname>sd_bus_creds_get_audit_login_uid</refname>
68 <refname>sd_bus_creds_get_unique_name</refname>
69 <refname>sd_bus_creds_get_well_known_names</refname>
70 <refname>sd_bus_creds_get_connection_name</refname>
72 <refpurpose>Retrieve fields from a credentials object</refpurpose>
77 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
80 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
81 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
82 <paramdef>pid_t *<parameter>pid</parameter></paramdef>
86 <funcdef>int <function>sd_bus_creds_get_pid_starttime</function></funcdef>
87 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
88 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
92 <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
93 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
94 <paramdef>pid_t *<parameter>tid</parameter></paramdef>
98 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
99 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
100 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
104 <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
105 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
106 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
110 <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
111 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
112 <paramdef>const char **<parameter>comm</parameter></paramdef>
116 <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
117 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
118 <paramdef>const char **<parameter>comm</parameter></paramdef>
122 <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
123 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
124 <paramdef>const char **<parameter>exe</parameter></paramdef>
128 <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
129 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
130 <paramdef>char ***<parameter>cmdline</parameter></paramdef>
134 <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
135 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
136 <paramdef>const char **<parameter>cgroup</parameter></paramdef>
140 <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
141 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
142 <paramdef>const char **<parameter>unit</parameter></paramdef>
146 <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
147 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
148 <paramdef>const char **<parameter>unit</parameter></paramdef>
152 <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
153 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
154 <paramdef>const char **<parameter>slice</parameter></paramdef>
158 <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
159 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
160 <paramdef>const char **<parameter>slice</parameter></paramdef>
164 <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
165 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
166 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
170 <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
171 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
172 <paramdef>int <parameter>capability</parameter></paramdef>
176 <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
177 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
178 <paramdef>int <parameter>capability</parameter></paramdef>
182 <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
183 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
184 <paramdef>int <parameter>capability</parameter></paramdef>
188 <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
189 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
190 <paramdef>int <parameter>capability</parameter></paramdef>
194 <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
195 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
196 <paramdef>const char **<parameter>context</parameter></paramdef>
200 <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
201 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
202 <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
206 <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
207 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
208 <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
212 <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
213 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
214 <paramdef>const char **<parameter>name</parameter></paramdef>
218 <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
219 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
220 <paramdef>char ***<parameter>name</parameter></paramdef>
224 <funcdef>int <function>sd_bus_creds_get_connection_name</function></funcdef>
225 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
226 <paramdef>const char **<parameter>name</parameter></paramdef>
233 <title>Description</title>
235 <para>These functions return information from an
236 <parameter>sd_bus_creds</parameter> object. It may be created with
237 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
238 in which case it will describe the specified process, or it may be
240 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
241 in which case it will describe the process at the other endpoint
245 <para><function>sd_bus_creds_get_pid()</function> will retrieve the
246 PID (process identifier).</para>
248 <para><function>sd_bus_creds_get_pid_starttime()</function> will
249 retrieve the time since the start of the epoch in microseconds
250 since the process was started.</para>
252 <para><function>sd_bus_creds_get_tid()</function> will retrieve the
253 TID (thread identifier).</para>
255 <para><function>sd_bus_creds_get_uid()</function> will retrieve the
256 numeric UID (user identifier).</para>
258 <para><function>sd_bus_creds_get_gid()</function> will retrieve the
259 numeric GID (group identifier).</para>
261 <para><function>sd_bus_creds_get_comm()</function> will retrieve the
262 comm field (truncated name of the executable, as stored in
263 <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
266 <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
267 the comm field of the thread (as stored in
268 <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
271 <para><function>sd_bus_creds_get_exe()</function> will retrieve the
272 path to the program (as stored in the
273 <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
274 link, but with <literal> (deleted)</literal> suffix removed).
277 <para><function>sd_bus_creds_get_cmdline()</function> will retrieve
278 an array of command line arguments (as stored in
279 <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
282 <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
283 the cgroup path. See <ulink
284 url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
287 <para><function>sd_bus_creds_get_unit()</function> will retrieve the
288 systemd unit name (in the system instance of systemd) that the
289 process is part of. See
290 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
293 <para><function>sd_bus_creds_get_user_unit()</function> will
294 retrieve the systemd unit name (in the user instance of systemd)
295 that the process is part of. See
296 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
299 <para><function>sd_bus_creds_get_slice()</function> will retrieve
300 the systemd slice (a unit in the system instance of systemd) that
301 the process is part of. See
302 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
305 <para><function>sd_bus_creds_get_session()</function> will retrieve
306 the logind session that the process is part of. See
307 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
310 <para><function>sd_bus_creds_get_owner_uid()</function> will retrieve
311 the numeric UID (user identifier) of the user who owns the slice
312 that the process is part of. See
313 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
315 <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
318 <para><function>sd_bus_creds_has_effective_cap()</function> will
319 check whether the capability specified by
320 <parameter>capability</parameter> was set in the effective
321 capabilities mask. A positive return value means that is was
322 set, zero means that it was not set, and a negative return
323 value signifies an error. See
324 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
325 and <varname>Capabilities=</varname> and
326 <varname>CapabilityBoundingSet=</varname> settings in
327 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
330 <para><function>sd_bus_creds_has_permitted_cap()</function> is
331 similar to <function>sd_bus_creds_has_effective_cap()</function>,
332 but will check the permitted capabilities mask.</para>
334 <para><function>sd_bus_creds_has_inheritable_cap()</function> is
335 similar to <function>sd_bus_creds_has_effective_cap()</function>,
336 but will check the inheritable capabilities mask.</para>
338 <para><function>sd_bus_creds_has_bounding_cap()</function> is
339 similar to <function>sd_bus_creds_has_effective_cap()</function>,
340 but will check the bounding capabilities mask.</para>
342 <para><function>sd_bus_creds_get_selinux_context()</function> will
343 retrieve the SELinux security context (label) of the process.</para>
345 <para><function>sd_bus_creds_get_audit_session_id()</function> will
346 retrieve the audit session identifier of the process.</para>
348 <para><function>sd_bus_creds_get_audit_login_uid()</function> will
349 retrieve the audit user login identifier (the identifier of the
350 user who is "responsible" for the session).</para>
352 <para><function>sd_bus_creds_get_unique_name()</function> will
353 retrieve the D-Bus unique name. See <ulink
354 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
355 D-Bus specification</ulink>.</para>
357 <para><function>sd_bus_creds_get_well_known_names()</function> will
358 retrieve the set of D-Bus well-known names. See <ulink
359 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
360 D-Bus specification</ulink>.</para>
362 <para><function>sd_bus_creds_get_connection_name()</function> will
363 retrieve a descriptive name of the bus connection of the
364 peer. This name is useful to discern multiple bus connections by
365 the same peer, and may be altered by the peer with the
366 <citerefentry><refentrytitle>sd_bus_set_name()</refentrytitle><manvolnum>3</manvolnum></citerefentry>
369 <para>All functions that take a <parameter>const
370 char**</parameter> parameter will store the answer there as an
371 address of a NUL-terminated string. It will be valid as long as
372 <parameter>c</parameter> remains valid, and should not be freed or
373 modified by the caller.</para>
375 <para>All functions that take a <parameter>char***</parameter>
376 parameter will store the answer there as an address of a an array
377 of strings. Each invidividual string is NUL-terminated, and the
378 array is NULL-terminated as a whole. It will be valid as long as
379 <parameter>c</parameter> remains valid, and should not be freed or
380 modified by the caller.</para>
384 <title>Return Value</title>
386 <para>On success, these calls return 0 or a positive integer. On
387 failure, these calls return a negative errno-style error code.
392 <title>Errors</title>
394 <para>Returned errors may indicate the following problems:</para>
398 <term><constant>-ENODATA</constant></term>
400 <listitem><para>Given field is not available in
401 <parameter>c</parameter>.</para>
406 <term><constant>-ENOENT</constant></term>
408 <listitem><para>Given field is not specified for the sender.
409 This will be returned by <function>sd_bus_get_unit()</function>,
410 <function>sd_bus_get_user_unit()</function>,
411 <function>sd_bus_get_slice()</function>,
412 <function>sd_bus_get_session()</function>, and
413 <function>sd_bus_get_name_creds_uid()</function> if the sender is not
414 part of a systemd system unit, systemd user unit, systemd
415 slice, logind session, or a systemd user session.</para>
420 <term><constant>-ENXIO</constant></term>
422 <listitem><para>An error occurred in parsing cgroup paths.
423 <filename>libsystemd</filename> might be out of sync with
424 the running systemd version.</para></listitem>
428 <term><constant>-EINVAL</constant></term>
430 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
435 <term><constant>-ENOMEM</constant></term>
437 <listitem><para>Memory allocation failed.</para></listitem>
445 <para><function>sd_bus_open_user()</function> and other functions
446 described here are available as a shared library, which can be
447 compiled and linked to with the
448 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
453 <title>See Also</title>
456 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
457 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
458 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
459 <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
460 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
461 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
462 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
463 <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>