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_tid</refname>
48 <refname>sd_bus_creds_get_uid</refname>
49 <refname>sd_bus_creds_get_gid</refname>
50 <refname>sd_bus_creds_get_comm</refname>
51 <refname>sd_bus_creds_get_tid_comm</refname>
52 <refname>sd_bus_creds_get_exe</refname>
53 <refname>sd_bus_creds_get_cmdline</refname>
54 <refname>sd_bus_creds_get_cgroup</refname>
55 <refname>sd_bus_creds_get_unit</refname>
56 <refname>sd_bus_creds_get_user_unit</refname>
57 <refname>sd_bus_creds_get_slice</refname>
58 <refname>sd_bus_creds_get_session</refname>
59 <refname>sd_bus_creds_get_owner_uid</refname>
60 <refname>sd_bus_creds_has_effective_cap</refname>
61 <refname>sd_bus_creds_has_permitted_cap</refname>
62 <refname>sd_bus_creds_has_inheritable_cap</refname>
63 <refname>sd_bus_creds_has_bounding_cap</refname>
64 <refname>sd_bus_creds_get_selinux_context</refname>
65 <refname>sd_bus_creds_get_audit_session_id</refname>
66 <refname>sd_bus_creds_get_audit_login_uid</refname>
67 <refname>sd_bus_creds_get_unique_name</refname>
68 <refname>sd_bus_creds_get_well_known_names</refname>
69 <refname>sd_bus_creds_get_connection_name</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_tid</function></funcdef>
86 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
87 <paramdef>pid_t *<parameter>tid</parameter></paramdef>
91 <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
92 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
93 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
97 <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
98 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
99 <paramdef>gid_t *<parameter>gid</parameter></paramdef>
103 <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
104 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
105 <paramdef>const char **<parameter>comm</parameter></paramdef>
109 <funcdef>int <function>sd_bus_creds_get_tid_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_exe</function></funcdef>
116 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
117 <paramdef>const char **<parameter>exe</parameter></paramdef>
121 <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
122 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
123 <paramdef>char ***<parameter>cmdline</parameter></paramdef>
127 <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
128 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
129 <paramdef>const char **<parameter>cgroup</parameter></paramdef>
133 <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
134 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
135 <paramdef>const char **<parameter>unit</parameter></paramdef>
139 <funcdef>int <function>sd_bus_creds_get_user_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_slice</function></funcdef>
146 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
147 <paramdef>const char **<parameter>slice</parameter></paramdef>
151 <funcdef>int <function>sd_bus_creds_get_session</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_owner_uid</function></funcdef>
158 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
159 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
163 <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
164 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
165 <paramdef>int <parameter>capability</parameter></paramdef>
169 <funcdef>int <function>sd_bus_creds_has_permitted_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_inheritable_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_bounding_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_get_selinux_context</function></funcdef>
188 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
189 <paramdef>const char **<parameter>context</parameter></paramdef>
193 <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
194 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
195 <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
199 <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
200 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
201 <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
205 <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
206 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
207 <paramdef>const char **<parameter>name</parameter></paramdef>
211 <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
212 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
213 <paramdef>char ***<parameter>name</parameter></paramdef>
217 <funcdef>int <function>sd_bus_creds_get_connection_name</function></funcdef>
218 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
219 <paramdef>const 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_owner_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_tid()</function> will retrieve the
242 TID (thread identifier).</para>
244 <para><function>sd_bus_creds_get_uid()</function> will retrieve the
245 numeric UID (user identifier).</para>
247 <para><function>sd_bus_creds_get_gid()</function> will retrieve the
248 numeric GID (group identifier).</para>
250 <para><function>sd_bus_creds_get_comm()</function> will retrieve the
251 comm field (truncated name of the executable, as stored in
252 <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
255 <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
256 the comm field of the thread (as stored in
257 <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
260 <para><function>sd_bus_creds_get_exe()</function> will retrieve the
261 path to the program (as stored in the
262 <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
263 link, but with <literal> (deleted)</literal> suffix removed).
266 <para><function>sd_bus_creds_get_cmdline()</function> will retrieve
267 an array of command line arguments (as stored in
268 <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
271 <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
272 the cgroup path. See <ulink
273 url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
276 <para><function>sd_bus_creds_get_unit()</function> will retrieve the
277 systemd unit name (in the system instance of systemd) that the
278 process is part of. See
279 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
282 <para><function>sd_bus_creds_get_user_unit()</function> will
283 retrieve the systemd unit name (in the user instance of systemd)
284 that the process is part of. See
285 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
288 <para><function>sd_bus_creds_get_slice()</function> will retrieve
289 the systemd slice (a unit in the system instance of systemd) that
290 the process is part of. See
291 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
294 <para><function>sd_bus_creds_get_session()</function> will retrieve
295 the logind session that the process is part of. See
296 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
299 <para><function>sd_bus_creds_get_owner_uid()</function> will retrieve
300 the numeric UID (user identifier) of the user who owns the slice
301 that the process is part of. See
302 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
304 <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
307 <para><function>sd_bus_creds_has_effective_cap()</function> will
308 check whether the capability specified by
309 <parameter>capability</parameter> was set in the effective
310 capabilities mask. A positive return value means that is was
311 set, zero means that it was not set, and a negative return
312 value signifies an error. See
313 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
314 and <varname>Capabilities=</varname> and
315 <varname>CapabilityBoundingSet=</varname> settings in
316 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
319 <para><function>sd_bus_creds_has_permitted_cap()</function> is
320 similar to <function>sd_bus_creds_has_effective_cap()</function>,
321 but will check the permitted capabilities mask.</para>
323 <para><function>sd_bus_creds_has_inheritable_cap()</function> is
324 similar to <function>sd_bus_creds_has_effective_cap()</function>,
325 but will check the inheritable capabilities mask.</para>
327 <para><function>sd_bus_creds_has_bounding_cap()</function> is
328 similar to <function>sd_bus_creds_has_effective_cap()</function>,
329 but will check the bounding capabilities mask.</para>
331 <para><function>sd_bus_creds_get_selinux_context()</function> will
332 retrieve the SELinux security context (label) of the process.</para>
334 <para><function>sd_bus_creds_get_audit_session_id()</function> will
335 retrieve the audit session identifier of the process.</para>
337 <para><function>sd_bus_creds_get_audit_login_uid()</function> will
338 retrieve the audit user login identifier (the identifier of the
339 user who is "responsible" for the session).</para>
341 <para><function>sd_bus_creds_get_unique_name()</function> will
342 retrieve the D-Bus unique name. See <ulink
343 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
344 D-Bus specification</ulink>.</para>
346 <para><function>sd_bus_creds_get_well_known_names()</function> will
347 retrieve the set of D-Bus well-known names. See <ulink
348 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
349 D-Bus specification</ulink>.</para>
351 <para><function>sd_bus_creds_get_connection_name()</function> will
352 retrieve a descriptive name of the bus connection of the
353 peer. This name is useful to discern multiple bus connections by
354 the same peer, and may be altered by the peer with the
355 <citerefentry><refentrytitle>sd_bus_set_name()</refentrytitle><manvolnum>3</manvolnum></citerefentry>
358 <para>All functions that take a <parameter>const
359 char**</parameter> parameter will store the answer there as an
360 address of a NUL-terminated string. It will be valid as long as
361 <parameter>c</parameter> remains valid, and should not be freed or
362 modified by the caller.</para>
364 <para>All functions that take a <parameter>char***</parameter>
365 parameter will store the answer there as an address of a an array
366 of strings. Each invidividual string is NUL-terminated, and the
367 array is NULL-terminated as a whole. It will be valid as long as
368 <parameter>c</parameter> remains valid, and should not be freed or
369 modified by the caller.</para>
373 <title>Return Value</title>
375 <para>On success, these calls return 0 or a positive integer. On
376 failure, these calls return a negative errno-style error code.
381 <title>Errors</title>
383 <para>Returned errors may indicate the following problems:</para>
387 <term><constant>-ENODATA</constant></term>
389 <listitem><para>Given field is not available in
390 <parameter>c</parameter>.</para>
395 <term><constant>-ENOENT</constant></term>
397 <listitem><para>Given field is not specified for the sender.
398 This will be returned by <function>sd_bus_get_unit()</function>,
399 <function>sd_bus_get_user_unit()</function>,
400 <function>sd_bus_get_slice()</function>,
401 <function>sd_bus_get_session()</function>, and
402 <function>sd_bus_get_name_creds_uid()</function> if the sender is not
403 part of a systemd system unit, systemd user unit, systemd
404 slice, logind session, or a systemd user session.</para>
409 <term><constant>-ENXIO</constant></term>
411 <listitem><para>An error occurred in parsing cgroup paths.
412 <filename>libsystemd</filename> might be out of sync with
413 the running systemd version.</para></listitem>
417 <term><constant>-EINVAL</constant></term>
419 <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
424 <term><constant>-ENOMEM</constant></term>
426 <listitem><para>Memory allocation failed.</para></listitem>
434 <para><function>sd_bus_open_user()</function> and other functions
435 described here are available as a shared library, which can be
436 compiled and linked to with the
437 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
442 <title>See Also</title>
445 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
446 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
447 <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
448 <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
449 <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
450 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
451 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
452 <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>