1 <?xml version='1.0'?> <!--*-nxml-*-->
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>
71 <refpurpose>Retrieve fields from a credentials object</refpurpose>
76 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
79 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
80 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
81 <paramdef>pid_t *<parameter>pid</parameter></paramdef>
85 <funcdef>int <function>sd_bus_creds_get_pid_starttime</function></funcdef>
86 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
87 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
91 <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
92 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
93 <paramdef>pid_t *<parameter>tid</parameter></paramdef>
97 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
98 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
99 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
103 <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
104 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
105 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
109 <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
110 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
111 <paramdef>const char **<parameter>comm</parameter></paramdef>
115 <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
116 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
117 <paramdef>const char **<parameter>comm</parameter></paramdef>
121 <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
122 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
123 <paramdef>const char **<parameter>exe</parameter></paramdef>
127 <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
128 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
129 <paramdef>char ***<parameter>cmdline</parameter></paramdef>
133 <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
134 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
135 <paramdef>const char **<parameter>cgroup</parameter></paramdef>
139 <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
140 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
141 <paramdef>const char **<parameter>unit</parameter></paramdef>
145 <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
146 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
147 <paramdef>const char **<parameter>unit</parameter></paramdef>
151 <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
152 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
153 <paramdef>const char **<parameter>slice</parameter></paramdef>
157 <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
158 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
159 <paramdef>const char **<parameter>slice</parameter></paramdef>
163 <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
164 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
165 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
169 <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
170 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
171 <paramdef>int <parameter>capability</parameter></paramdef>
175 <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
176 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
177 <paramdef>int <parameter>capability</parameter></paramdef>
181 <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
182 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
183 <paramdef>int <parameter>capability</parameter></paramdef>
187 <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
188 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
189 <paramdef>int <parameter>capability</parameter></paramdef>
193 <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
194 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
195 <paramdef>const char **<parameter>context</parameter></paramdef>
199 <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
200 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
201 <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
205 <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
206 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
207 <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
211 <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
212 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
213 <paramdef>const char **<parameter>name</parameter></paramdef>
217 <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
218 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
219 <paramdef>char ***<parameter>name</parameter></paramdef>
226 <title>Description</title>
228 <para>These functions return information from an
229 <parameter>sd_bus_creds</parameter> object. It may be created with
230 <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
231 in which case it will describe the specified process, or it may be
233 <citerefentry><refentrytitle>sd_bus_get_peer_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
234 in which case it will describe the process at the other endpoint
238 <para><function>sd_bus_creds_get_pid</function> will retrieve the
239 PID (process identifier).</para>
241 <para><function>sd_bus_creds_get_pid_starttime</function> will
242 retrieve the time since the start of the epoch in microseconds
243 since the process was started.</para>
245 <para><function>sd_bus_creds_get_tid</function> will retrieve the
246 TID (thread identifier).</para>
248 <para><function>sd_bus_creds_get_uid</function> will retrieve the
249 numeric UID (user identifier).</para>
251 <para><function>sd_bus_creds_get_gid</function> will retrieve the
252 numeric GID (group identifier).</para>
254 <para><function>sd_bus_creds_get_comm</function> will retrieve the
255 comm field (truncated name of the executable, as stored in
256 <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
259 <para><function>sd_bus_creds_get_tid_comm</function> will retrieve
260 the comm field of the thread (as stored in
261 <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
264 <para><function>sd_bus_creds_get_exe</function> will retrieve the
265 path to the program (as stored in the
266 <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
267 link, but with <literal> (deleted)</literal> suffix removed).
270 <para><function>sd_bus_creds_get_cmdline</function> will retrieve
271 an array of command-line arguments (as stored in
272 <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
275 <para><function>sd_bus_creds_get_cgroup</function> will retrieve
276 the cgroup path. See <ulink
277 url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
280 <para><function>sd_bus_creds_get_unit</function> will retrieve the
281 systemd unit name (in the system instance of systemd) that the
282 process is part of. See
283 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
286 <para><function>sd_bus_creds_get_user_unit</function> will
287 retrieve the systemd unit name (in the user instance of systemd)
288 that the process is part of. See
289 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
292 <para><function>sd_bus_creds_get_slice</function> will retrieve
293 the systemd slice (a unit in the system instance of systemd) that
294 the process is part of. See
295 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
298 <para><function>sd_bus_creds_get_session</function> will retrieve
299 the logind session that the process is part of. See
300 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
303 <para><function>sd_bus_creds_get_owner_uid</function> will retrieve
304 the numeric UID (user identifier) of the user who owns the slice
305 that the process is part of. See
306 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
308 <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
311 <para><function>sd_bus_creds_has_effective_cap</function> will
312 check whether the capability specified by
313 <parameter>capability</parameter> was set in the effective
314 capabilities mask. A positive return value means that is was
315 set, zero means that it was not set, and a negative return
316 value signifies an error. See
317 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
318 and <varname>Capabilities=</varname> and
319 <varname>CapabilityBoundingSet=</varname> settings in
320 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
323 <para><function>sd_bus_creds_has_permitted_cap</function> is
324 similar to <function>sd_bus_creds_has_effective_cap</function>,
325 but will check the permitted capabilities mask.</para>
327 <para><function>sd_bus_creds_has_inheritable_cap</function> is
328 similar to <function>sd_bus_creds_has_effective_cap</function>,
329 but will check the inheritable capabilities mask.</para>
331 <para><function>sd_bus_creds_has_bounding_cap</function> is
332 similar to <function>sd_bus_creds_has_effective_cap</function>,
333 but will check the bounding capabilities mask.</para>
335 <para><function>sd_bus_creds_get_selinux_context</function> will
336 retrieve the SELinux security context (label) of the process.</para>
338 <para><function>sd_bus_creds_get_audit_session_id</function> will
339 retrieve the audit session identifier of the process.</para>
341 <para><function>sd_bus_creds_get_audit_login_uid</function> will
342 retrieve the audit user login identifier (the identifier of the
343 user who is "responsible" for the session).</para>
345 <para><function>sd_bus_creds_get_unique_name</function> will
346 retrieve the D-Bus unique name. See <ulink
347 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
348 D-Bus specification</ulink>.</para>
350 <para><function>sd_bus_creds_get_well_known_names</function> will
351 retrieve the set of D-Bus well-known names. See <ulink
352 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
353 D-Bus specification</ulink>.</para>
355 <para>All functions that take a <parameter>const
356 char**</parameter> parameter will store the answer there as an
357 address of a NUL-terminated string. It will be valid as long as
358 <parameter>c</parameter> remains valid, and should not be freed or
359 modified by the caller.</para>
361 <para>All functions that take a <parameter>char***</parameter>
362 parameter will store the answer there as an address of a an array
363 of strings. Each invidividual string is NUL-terminated, and the
364 array is NULL-terminated as a whole. It will be valid as long as
365 <parameter>c</parameter> remains valid, and should not be freed or
366 modified by the caller.</para>
370 <title>Return Value</title>
372 <para>On success, these calls return 0 or a positive integer. On
373 failure, these calls return a negative errno-style error code.
378 <title>Errors</title>
380 <para>Returned errors may indicate the following problems:</para>
384 <term><constant>-ENODATA</constant></term>
386 <listitem><para>Given field is not available in
387 <parameter>c</parameter>.</para>
392 <term><constant>-ENOENT</constant></term>
394 <listitem><para>Given field is not specified for the sender.
395 This will be returned by <function>sd_bus_get_unit</function>,
396 <function>sd_bus_get_user_unit</function>,
397 <function>sd_bus_get_slice</function>,
398 <function>sd_bus_get_session</function>, and
399 <function>sd_bus_get_owner_uid</function> if the sender is not
400 part of a systemd system unit, systemd user unit, systemd
401 slice, logind session, or a systemd user session.</para>
406 <term><constant>-ENXIO</constant></term>
408 <listitem><para>An error occurred in parsing cgroup paths.
409 <filename>libsystemd</filename> might be out of sync with
410 the running systemd version.</para></listitem>
414 <term><constant>-EINVAL</constant></term>
416 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
421 <term><constant>-ENOMEM</constant></term>
423 <listitem><para>Memory allocation failed.</para></listitem>
431 <para><function>sd_bus_open_user()</function> and other functions
432 described here are available as a shared library, which can be
433 compiled and linked to with the
434 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
439 <title>See Also</title>
442 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
443 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
444 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
445 <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
446 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
447 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
448 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
449 <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>