man/sd_bus_creds_get_pid.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_creds_get_pid" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_creds_get_pid</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_creds_get_pid</refname>
  20     <refname>sd_bus_creds_get_pidfd_dup</refname>
  21     <refname>sd_bus_creds_get_ppid</refname>
  22     <refname>sd_bus_creds_get_tid</refname>
  23     <refname>sd_bus_creds_get_uid</refname>
  24     <refname>sd_bus_creds_get_euid</refname>
  25     <refname>sd_bus_creds_get_suid</refname>
  26     <refname>sd_bus_creds_get_fsuid</refname>
  27     <refname>sd_bus_creds_get_gid</refname>
  28     <refname>sd_bus_creds_get_egid</refname>
  29     <refname>sd_bus_creds_get_sgid</refname>
  30     <refname>sd_bus_creds_get_fsgid</refname>
  31     <refname>sd_bus_creds_get_supplementary_gids</refname>
  32     <refname>sd_bus_creds_get_comm</refname>
  33     <refname>sd_bus_creds_get_tid_comm</refname>
  34     <refname>sd_bus_creds_get_exe</refname>
  35     <refname>sd_bus_creds_get_cmdline</refname>
  36     <refname>sd_bus_creds_get_cgroup</refname>
  37     <refname>sd_bus_creds_get_unit</refname>
  38     <refname>sd_bus_creds_get_slice</refname>
  39     <refname>sd_bus_creds_get_user_unit</refname>
  40     <refname>sd_bus_creds_get_user_slice</refname>
  41     <refname>sd_bus_creds_get_session</refname>
  42     <refname>sd_bus_creds_get_owner_uid</refname>
  43     <refname>sd_bus_creds_has_effective_cap</refname>
  44     <refname>sd_bus_creds_has_permitted_cap</refname>
  45     <refname>sd_bus_creds_has_inheritable_cap</refname>
  46     <refname>sd_bus_creds_has_bounding_cap</refname>
  47     <refname>sd_bus_creds_get_selinux_context</refname>
  48     <refname>sd_bus_creds_get_audit_session_id</refname>
  49     <refname>sd_bus_creds_get_audit_login_uid</refname>
  50     <refname>sd_bus_creds_get_tty</refname>
  51     <refname>sd_bus_creds_get_unique_name</refname>
  52     <refname>sd_bus_creds_get_well_known_names</refname>
  53     <refname>sd_bus_creds_get_description</refname>
  54
  55     <refpurpose>Retrieve fields from a credentials object</refpurpose>
  56   </refnamediv>
  57
  58   <refsynopsisdiv>
  59     <funcsynopsis>
  60       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  61
  62       <funcprototype>
  63         <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
  64         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  65         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>int <function>sd_bus_creds_get_pidfd_dup</function></funcdef>
  70         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  71         <paramdef>int *<parameter>ret_fd</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef>
  76         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  77         <paramdef>pid_t *<parameter>ppid</parameter></paramdef>
  78       </funcprototype>
  79
  80       <funcprototype>
  81         <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
  82         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  83         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
  84       </funcprototype>
  85
  86       <funcprototype>
  87         <funcdef>int <function>sd_bus_creds_get_uid</function></funcdef>
  88         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  89         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  90       </funcprototype>
  91
  92       <funcprototype>
  93         <funcdef>int <function>sd_bus_creds_get_euid</function></funcdef>
  94         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  95         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  96       </funcprototype>
  97
  98       <funcprototype>
  99         <funcdef>int <function>sd_bus_creds_get_suid</function></funcdef>
 100         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 101         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 102       </funcprototype>
 103
 104       <funcprototype>
 105         <funcdef>int <function>sd_bus_creds_get_fsuid</function></funcdef>
 106         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 107         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 108       </funcprototype>
 109
 110       <funcprototype>
 111         <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
 112         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 113         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 114       </funcprototype>
 115
 116       <funcprototype>
 117         <funcdef>int <function>sd_bus_creds_get_egid</function></funcdef>
 118         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 119         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 120       </funcprototype>
 121
 122       <funcprototype>
 123         <funcdef>int <function>sd_bus_creds_get_sgid</function></funcdef>
 124         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 125         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 126       </funcprototype>
 127
 128       <funcprototype>
 129         <funcdef>int <function>sd_bus_creds_get_fsgid</function></funcdef>
 130         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 131         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 132       </funcprototype>
 133
 134       <funcprototype>
 135         <funcdef>int <function>sd_bus_creds_get_supplementary_gids</function></funcdef>
 136         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 137         <paramdef>const gid_t **<parameter>gids</parameter></paramdef>
 138       </funcprototype>
 139
 140       <funcprototype>
 141         <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
 142         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 143         <paramdef>const char **<parameter>comm</parameter></paramdef>
 144       </funcprototype>
 145
 146       <funcprototype>
 147         <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
 148         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 149         <paramdef>const char **<parameter>comm</parameter></paramdef>
 150       </funcprototype>
 151
 152       <funcprototype>
 153         <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
 154         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 155         <paramdef>const char **<parameter>exe</parameter></paramdef>
 156       </funcprototype>
 157
 158       <funcprototype>
 159         <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
 160         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 161         <paramdef>char ***<parameter>cmdline</parameter></paramdef>
 162       </funcprototype>
 163
 164       <funcprototype>
 165         <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
 166         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 167         <paramdef>const char **<parameter>cgroup</parameter></paramdef>
 168       </funcprototype>
 169
 170       <funcprototype>
 171         <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
 172         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 173         <paramdef>const char **<parameter>unit</parameter></paramdef>
 174       </funcprototype>
 175
 176       <funcprototype>
 177         <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
 178         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 179         <paramdef>const char **<parameter>slice</parameter></paramdef>
 180       </funcprototype>
 181
 182       <funcprototype>
 183         <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
 184         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 185         <paramdef>const char **<parameter>unit</parameter></paramdef>
 186       </funcprototype>
 187
 188       <funcprototype>
 189         <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef>
 190         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 191         <paramdef>const char **<parameter>slice</parameter></paramdef>
 192       </funcprototype>
 193
 194       <funcprototype>
 195         <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
 196         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 197         <paramdef>const char **<parameter>slice</parameter></paramdef>
 198       </funcprototype>
 199
 200       <funcprototype>
 201         <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
 202         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 203         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 204       </funcprototype>
 205
 206       <funcprototype>
 207         <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
 208         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 209         <paramdef>int <parameter>capability</parameter></paramdef>
 210       </funcprototype>
 211
 212       <funcprototype>
 213         <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
 214         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 215         <paramdef>int <parameter>capability</parameter></paramdef>
 216       </funcprototype>
 217
 218       <funcprototype>
 219         <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
 220         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 221         <paramdef>int <parameter>capability</parameter></paramdef>
 222       </funcprototype>
 223
 224       <funcprototype>
 225         <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
 226         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 227         <paramdef>int <parameter>capability</parameter></paramdef>
 228       </funcprototype>
 229
 230       <funcprototype>
 231         <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
 232         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 233         <paramdef>const char **<parameter>context</parameter></paramdef>
 234       </funcprototype>
 235
 236       <funcprototype>
 237         <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
 238         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 239         <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
 240       </funcprototype>
 241
 242       <funcprototype>
 243         <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
 244         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 245         <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
 246       </funcprototype>
 247
 248       <funcprototype>
 249         <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef>
 250         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 251         <paramdef>const char **<parameter>tty</parameter></paramdef>
 252       </funcprototype>
 253
 254       <funcprototype>
 255         <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
 256         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 257         <paramdef>const char **<parameter>name</parameter></paramdef>
 258       </funcprototype>
 259
 260       <funcprototype>
 261         <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
 262         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 263         <paramdef>char ***<parameter>name</parameter></paramdef>
 264       </funcprototype>
 265
 266       <funcprototype>
 267         <funcdef>int <function>sd_bus_creds_get_description</function></funcdef>
 268         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 269         <paramdef>const char **<parameter>name</parameter></paramdef>
 270       </funcprototype>
 271
 272     </funcsynopsis>
 273   </refsynopsisdiv>
 274
 275   <refsect1>
 276     <title>Description</title>
 277
 278     <para>These functions return credential information from an
 279     <parameter>sd_bus_creds</parameter> object. Credential objects may
 280     be created with
 281     <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 282     in which case they describe the credentials of the process
 283     identified by the specified PID, with
 284     <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 285     in which case they describe the credentials of a bus peer
 286     identified by the specified bus name, with
 287     <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 288     in which case they describe the credentials of the creator of a
 289     bus, or with
 290     <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 291     in which case they describe the credentials of the sender of the
 292     message.</para>
 293
 294     <para>Not all credential fields are part of every
 295     <literal>sd_bus_creds</literal> object. Use
 296     <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 297     to determine the mask of fields available.</para>
 298
 299     <para><function>sd_bus_creds_get_pid()</function> will retrieve the PID (process identifier). Similarly,
 300     <function>sd_bus_creds_get_ppid()</function> will retrieve the parent PID. Note that PID 1 has no parent
 301     process, in which case -ENXIO is returned.</para>
 302
 303     <para><function>sd_bus_creds_get_pidfd_dup()</function> will retrieve the PID file descriptor (pidfd),
 304     see <citerefentry
 305     project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
 306     details. The file descriptor is duplicated and thus must be closed by the caller.</para>
 307
 308     <para><function>sd_bus_creds_get_tid()</function> will retrieve the
 309     TID (thread identifier).</para>
 310
 311     <para><function>sd_bus_creds_get_uid()</function> will retrieve
 312     the numeric UID (user identifier). Similarly,
 313     <function>sd_bus_creds_get_euid()</function> returns the effective
 314     UID, <function>sd_bus_creds_get_suid()</function> the saved UID
 315     and <function>sd_bus_creds_get_fsuid()</function> the file system
 316     UID.</para>
 317
 318     <para><function>sd_bus_creds_get_gid()</function> will retrieve the
 319     numeric GID (group identifier). Similarly,
 320     <function>sd_bus_creds_get_egid()</function> returns the effective
 321     GID, <function>sd_bus_creds_get_sgid()</function> the saved GID
 322     and <function>sd_bus_creds_get_fsgid()</function> the file system
 323     GID.</para>
 324
 325     <para><function>sd_bus_creds_get_supplementary_gids()</function>
 326     will retrieve the supplementary GIDs list.</para>
 327
 328     <para><function>sd_bus_creds_get_comm()</function> will retrieve the
 329     comm field (truncated name of the executable, as stored in
 330     <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
 331     </para>
 332
 333     <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
 334     the comm field of the thread (as stored in
 335     <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
 336     </para>
 337
 338     <para><function>sd_bus_creds_get_exe()</function> will retrieve the path to the program executable (as
 339     stored in the <filename>/proc/<replaceable>pid</replaceable>/exe</filename> link, but with the <literal>
 340     (deleted)</literal> suffix removed). Note that kernel threads do not have an executable path, in which
 341     case -ENXIO is returned. Note that this property should not be used for more than explanatory
 342     information, in particular it should not be used for security-relevant decisions. That's because the
 343     executable might have been replaced or removed by the time the value can be processed. Moreover, the
 344     kernel exports this information in an ambiguous way (i.e. a deleted executable cannot be safely
 345     distinguished from one whose name suffix is <literal> (deleted)</literal>).</para>
 346
 347     <para><function>sd_bus_creds_get_cmdline()</function> will
 348     retrieve an array of command line arguments (as stored in
 349     <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note
 350     that kernel threads do not have a command line, in which case
 351     -ENXIO is returned.</para>
 352
 353     <para><function>sd_bus_creds_get_cgroup()</function> will retrieve the control group path. See <ulink
 354     url="https://docs.kernel.org/admin-guide/cgroup-v2.html">Control Groups v2</ulink>.
 355     </para>
 356
 357     <para><function>sd_bus_creds_get_unit()</function> will retrieve
 358     the systemd unit name (in the system instance of systemd) that the
 359     process is a part of. See
 360     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
 361     processes that are not part of a unit, returns -ENXIO.
 362     </para>
 363
 364     <para><function>sd_bus_creds_get_user_unit()</function> will
 365     retrieve the systemd unit name (in the user instance of systemd)
 366     that the process is a part of. See
 367     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
 368     processes that are not part of a user unit, returns -ENXIO.
 369     </para>
 370
 371     <para><function>sd_bus_creds_get_slice()</function> will retrieve
 372     the systemd slice (a unit in the system instance of systemd) that
 373     the process is a part of. See
 374     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly,
 375     <function>sd_bus_creds_get_user_slice()</function> retrieves the
 376     systemd slice of the process, in the user instance of systemd.
 377     </para>
 378
 379     <para><function>sd_bus_creds_get_session()</function> will
 380     retrieve the identifier of the login session that the process is
 381     a part of. Please note the login session may be limited to a stub
 382     process or two.  User processes may instead be started from their
 383     systemd user manager, e.g. GUI applications started using DBus
 384     activation, as well as service processes which are shared between
 385     multiple logins of the same user. For processes that are not part
 386     of a session, returns -ENXIO.</para>
 387
 388     <para><function>sd_bus_creds_get_owner_uid()</function> will
 389     retrieve the numeric UID (user identifier) of the user who owns
 390     the user unit or login session that the process is a part of. See
 391     <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 392     For processes that are not part of a user unit or session, returns
 393     -ENXIO.
 394     </para>
 395
 396     <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by
 397     <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it
 398     was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry
 399     project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the
 400     <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in
 401     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 402     </para>
 403
 404     <para><function>sd_bus_creds_has_permitted_cap()</function> is
 405     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 406     but will check the permitted capabilities mask.</para>
 407
 408     <para><function>sd_bus_creds_has_inheritable_cap()</function> is
 409     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 410     but will check the inheritable capabilities mask.</para>
 411
 412     <para><function>sd_bus_creds_has_bounding_cap()</function> is
 413     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 414     but will check the bounding capabilities mask.</para>
 415
 416     <para><function>sd_bus_creds_get_selinux_context()</function> will
 417     retrieve the SELinux security context (label) of the process.</para>
 418
 419     <para><function>sd_bus_creds_get_audit_session_id()</function>
 420     will retrieve the audit session identifier of the process. Returns
 421     -ENXIO for processes that are not part of an audit session.</para>
 422
 423     <para><function>sd_bus_creds_get_audit_login_uid()</function> will
 424     retrieve the audit user login identifier (the identifier of the
 425     user who is "responsible" for the session). Returns -ENXIO for
 426     processes that are not part of an audit session.</para>
 427
 428     <para><function>sd_bus_creds_get_tty()</function> will retrieve
 429     the controlling TTY, without the prefixing "/dev/". Returns -ENXIO
 430     for processes that have no controlling TTY.</para>
 431
 432     <para><function>sd_bus_creds_get_unique_name()</function> will
 433     retrieve the D-Bus unique name. See <ulink
 434     url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 435     D-Bus specification</ulink>.</para>
 436
 437     <para><function>sd_bus_creds_get_well_known_names()</function> will
 438     retrieve the set of D-Bus well-known names. See <ulink
 439     url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 440     D-Bus specification</ulink>.</para>
 441
 442     <para><function>sd_bus_creds_get_description()</function> will
 443     retrieve a descriptive name of the bus connection of the
 444     peer. This name is useful to discern multiple bus connections by
 445     the same peer, and may be altered by the peer with the
 446     <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 447     call.</para>
 448
 449     <para>All functions that take a <parameter>const
 450     char**</parameter> parameter will store the answer there as an
 451     address of a <constant>NUL</constant>-terminated string. It will be valid as long as
 452     <parameter>c</parameter> remains valid, and should not be freed or
 453     modified by the caller.</para>
 454
 455     <para>All functions that take a <parameter>char***</parameter>
 456     parameter will store the answer there as an address of an array
 457     of strings. Each individual string is <constant>NUL</constant>-terminated, and the
 458     array is <constant>NULL</constant>-terminated as a whole. It will be valid as long as
 459     <parameter>c</parameter> remains valid, and should not be freed or
 460     modified by the caller.</para>
 461   </refsect1>
 462
 463   <refsect1>
 464     <title>Return Value</title>
 465
 466     <para>On success, these calls return 0 or a positive integer. On
 467     failure, these calls return a negative errno-style error code.
 468     </para>
 469
 470     <refsect2>
 471       <title>Errors</title>
 472
 473       <para>Returned errors may indicate the following problems:</para>
 474
 475       <variablelist>
 476         <varlistentry>
 477           <term><constant>-ENODATA</constant></term>
 478
 479           <listitem><para>The given field is not available in the credentials object
 480           <parameter>c</parameter>.</para>
 481           </listitem>
 482         </varlistentry>
 483
 484         <varlistentry>
 485           <term><constant>-ENXIO</constant></term>
 486
 487           <listitem><para>The given field is not specified for the described process or peer. This will be
 488           returned by <function>sd_bus_creds_get_unit()</function>,
 489           <function>sd_bus_creds_get_slice()</function>, <function>sd_bus_creds_get_user_unit()</function>,
 490           <function>sd_bus_creds_get_user_slice()</function>, and
 491           <function>sd_bus_creds_get_session()</function> if the process is not part of a systemd system
 492           unit, systemd user unit, systemd slice, or logind session. It will be returned by
 493           <function>sd_bus_creds_get_owner_uid()</function> if the process is not part of a systemd user unit
 494           or logind session. It will also be returned by <function>sd_bus_creds_get_exe()</function> and
 495           <function>sd_bus_creds_get_cmdline()</function> for kernel threads (since these are not started
 496           from an executable binary, nor have a command line), and by
 497           <function>sd_bus_creds_get_audit_session_id()</function> and
 498           <function>sd_bus_creds_get_audit_login_uid()</function> when the process is not part of an audit
 499           session, and <function>sd_bus_creds_get_tty()</function> if the process has no controlling
 500           TTY.</para></listitem>
 501         </varlistentry>
 502
 503         <varlistentry>
 504           <term><constant>-EINVAL</constant></term>
 505
 506           <listitem><para>Specified pointer parameter is <constant>NULL</constant>.</para></listitem>
 507         </varlistentry>
 508
 509         <varlistentry>
 510           <term><constant>-ENOMEM</constant></term>
 511
 512           <listitem><para>Memory allocation failed.</para></listitem>
 513         </varlistentry>
 514       </variablelist>
 515     </refsect2>
 516   </refsect1>
 517
 518   <xi:include href="libsystemd-pkgconfig.xml" />
 519
 520   <refsect1>
 521     <title>History</title>
 522     <para><function>sd_bus_creds_get_pid()</function>,
 523     <function>sd_bus_creds_get_tid()</function>,
 524     <function>sd_bus_creds_get_gid()</function>,
 525     <function>sd_bus_creds_get_comm()</function>,
 526     <function>sd_bus_creds_get_tid_comm()</function>,
 527     <function>sd_bus_creds_get_exe()</function>,
 528     <function>sd_bus_creds_get_cmdline()</function>,
 529     <function>sd_bus_creds_get_cgroup()</function>,
 530     <function>sd_bus_creds_get_unit()</function>,
 531     <function>sd_bus_creds_get_user_unit()</function>,
 532     <function>sd_bus_creds_get_slice()</function>,
 533     <function>sd_bus_creds_get_session()</function>,
 534     <function>sd_bus_creds_get_owner_uid()</function>,
 535     <function>sd_bus_creds_has_effective_cap()</function>,
 536     <function>sd_bus_creds_has_permitted_cap()</function>,
 537     <function>sd_bus_creds_has_inheritable_cap()</function>,
 538     <function>sd_bus_creds_has_bounding_cap()</function>,
 539     <function>sd_bus_creds_get_selinux_context()</function>,
 540     <function>sd_bus_creds_get_audit_session_id()</function>,
 541     <function>sd_bus_creds_get_audit_login_uid()</function>,
 542     <function>sd_bus_creds_get_unique_name()</function>,
 543     <function>sd_bus_creds_get_well_known_names()</function>,
 544     <function>sd_bus_creds_get_ppid()</function>,
 545     <function>sd_bus_creds_get_uid()</function>,
 546     <function>sd_bus_creds_get_euid()</function>,
 547     <function>sd_bus_creds_get_suid()</function>,
 548     <function>sd_bus_creds_get_fsuid()</function>,
 549     <function>sd_bus_creds_get_egid()</function>,
 550     <function>sd_bus_creds_get_sgid()</function>,
 551     <function>sd_bus_creds_get_fsgid()</function>,
 552     <function>sd_bus_creds_get_supplementary_gids()</function>,
 553     <function>sd_bus_creds_get_tty()</function>,
 554     <function>sd_bus_creds_get_description()</function>, and
 555     <function>sd_bus_creds_get_user_slice()</function> were added in version 221.</para>
 556     <para><function>sd_bus_creds_get_pidfd_dup()</function> was added in version 256.</para>
 557   </refsect1>
 558
 559   <refsect1>
 560     <title>See Also</title>
 561
 562     <para><simplelist type="inline">
 563       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 564       <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 565       <member><citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
 566       <member><citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
 567       <member><citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
 568       <member><citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 569       <member><citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 570       <member><citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 571       <member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 572     </simplelist></para>
 573   </refsect1>
 574
 575 </refentry>