man/sd_bus_creds_get_pid.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_bus_creds_get_pid">
  27
  28   <refentryinfo>
  29     <title>sd_bus_creds_get_pid</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>A monkey with a typewriter</contrib>
  35         <firstname>Zbigniew</firstname>
  36         <surname>Jędrzejewski-Szmek</surname>
  37         <email>zbyszek@in.waw.pl</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_bus_creds_get_pid</refname>
  49     <refname>sd_bus_creds_get_ppid</refname>
  50     <refname>sd_bus_creds_get_tid</refname>
  51     <refname>sd_bus_creds_get_uid</refname>
  52     <refname>sd_bus_creds_get_euid</refname>
  53     <refname>sd_bus_creds_get_suid</refname>
  54     <refname>sd_bus_creds_get_fsuid</refname>
  55     <refname>sd_bus_creds_get_gid</refname>
  56     <refname>sd_bus_creds_get_egid</refname>
  57     <refname>sd_bus_creds_get_sgid</refname>
  58     <refname>sd_bus_creds_get_fsgid</refname>
  59     <refname>sd_bus_creds_get_supplementary_gids</refname>
  60     <refname>sd_bus_creds_get_comm</refname>
  61     <refname>sd_bus_creds_get_tid_comm</refname>
  62     <refname>sd_bus_creds_get_exe</refname>
  63     <refname>sd_bus_creds_get_cmdline</refname>
  64     <refname>sd_bus_creds_get_cgroup</refname>
  65     <refname>sd_bus_creds_get_unit</refname>
  66     <refname>sd_bus_creds_get_slice</refname>
  67     <refname>sd_bus_creds_get_user_unit</refname>
  68     <refname>sd_bus_creds_get_user_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>
  78     <refname>sd_bus_creds_get_tty</refname>
  79     <refname>sd_bus_creds_get_unique_name</refname>
  80     <refname>sd_bus_creds_get_well_known_names</refname>
  81     <refname>sd_bus_creds_get_description</refname>
  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>
  92         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  93         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
  94       </funcprototype>
  95
  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
 102       <funcprototype>
 103         <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
 104         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 105         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
 106       </funcprototype>
 107
 108       <funcprototype>
 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>
 128         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 129         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 130       </funcprototype>
 131
 132       <funcprototype>
 133         <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
 134         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 135         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 136       </funcprototype>
 137
 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
 162       <funcprototype>
 163         <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
 164         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 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>
 170         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 171         <paramdef>const char **<parameter>comm</parameter></paramdef>
 172       </funcprototype>
 173
 174       <funcprototype>
 175         <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
 176         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 177         <paramdef>const char **<parameter>exe</parameter></paramdef>
 178       </funcprototype>
 179
 180       <funcprototype>
 181         <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
 182         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 183         <paramdef>char ***<parameter>cmdline</parameter></paramdef>
 184       </funcprototype>
 185
 186       <funcprototype>
 187         <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
 188         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 189         <paramdef>const char **<parameter>cgroup</parameter></paramdef>
 190       </funcprototype>
 191
 192       <funcprototype>
 193         <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
 194         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 195         <paramdef>const char **<parameter>unit</parameter></paramdef>
 196       </funcprototype>
 197
 198       <funcprototype>
 199         <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
 200         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 201         <paramdef>const char **<parameter>slice</parameter></paramdef>
 202       </funcprototype>
 203
 204       <funcprototype>
 205         <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
 206         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 207         <paramdef>const char **<parameter>unit</parameter></paramdef>
 208       </funcprototype>
 209
 210       <funcprototype>
 211         <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef>
 212         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 213         <paramdef>const char **<parameter>slice</parameter></paramdef>
 214       </funcprototype>
 215
 216       <funcprototype>
 217         <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
 218         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 219         <paramdef>const char **<parameter>slice</parameter></paramdef>
 220       </funcprototype>
 221
 222       <funcprototype>
 223         <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
 224         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 225         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 226       </funcprototype>
 227
 228       <funcprototype>
 229         <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
 230         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 231         <paramdef>int <parameter>capability</parameter></paramdef>
 232       </funcprototype>
 233
 234       <funcprototype>
 235         <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
 236         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 237         <paramdef>int <parameter>capability</parameter></paramdef>
 238       </funcprototype>
 239
 240       <funcprototype>
 241         <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
 242         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 243         <paramdef>int <parameter>capability</parameter></paramdef>
 244       </funcprototype>
 245
 246       <funcprototype>
 247         <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
 248         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 249         <paramdef>int <parameter>capability</parameter></paramdef>
 250       </funcprototype>
 251
 252       <funcprototype>
 253         <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
 254         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 255         <paramdef>const char **<parameter>context</parameter></paramdef>
 256       </funcprototype>
 257
 258       <funcprototype>
 259         <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
 260         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 261         <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
 262       </funcprototype>
 263
 264       <funcprototype>
 265         <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
 266         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 267         <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
 268       </funcprototype>
 269
 270       <funcprototype>
 271         <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef>
 272         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 273         <paramdef>const char **<parameter>tty</parameter></paramdef>
 274       </funcprototype>
 275
 276       <funcprototype>
 277         <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
 278         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 279         <paramdef>const char **<parameter>name</parameter></paramdef>
 280       </funcprototype>
 281
 282       <funcprototype>
 283         <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
 284         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 285         <paramdef>char ***<parameter>name</parameter></paramdef>
 286       </funcprototype>
 287
 288       <funcprototype>
 289         <funcdef>int <function>sd_bus_creds_get_description</function></funcdef>
 290         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 291         <paramdef>const char **<parameter>name</parameter></paramdef>
 292       </funcprototype>
 293
 294     </funcsynopsis>
 295   </refsynopsisdiv>
 296
 297   <refsect1>
 298     <title>Description</title>
 299
 300     <para>These functions return credential information from an
 301     <parameter>sd_bus_creds</parameter> object. Credential objects may
 302     be created with
 303     <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 304     in which case they describe the credentials of the process
 305     identified by the specified PID, with
 306     <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 307     in which case they describe the credentials of a bus peer
 308     identified by the specified bus name, with
 309     <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 310     in which case they describe the credentials of the creator of a
 311     bus, or with
 312     <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 313     in which case they describe the credentials of the sender of the
 314     message.</para>
 315
 316     <para>Not all credential fields are part of every
 317     <literal>sd_bus_creds</literal> object. Use
 318     <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 319     to determine the mask of fields available.</para>
 320
 321     <para><function>sd_bus_creds_get_pid()</function> will retrieve
 322     the PID (process identifier). Similarly,
 323     <function>sd_bus_creds_get_ppid()</function> will retrieve the
 324     parent PID. Note that PID 1 has no parent process, in which case
 325     -ENXIO is returned.</para>
 326
 327     <para><function>sd_bus_creds_get_tid()</function> will retrieve the
 328     TID (thread identifier).</para>
 329
 330     <para><function>sd_bus_creds_get_uid()</function> will retrieve
 331     the numeric UID (user identifier). Similarly,
 332     <function>sd_bus_creds_get_euid()</function> returns the effective
 333     UID, <function>sd_bus_creds_get_suid()</function> the saved UID
 334     and <function>sd_bus_creds_get_fsuid()</function> the file system
 335     UID.</para>
 336
 337     <para><function>sd_bus_creds_get_gid()</function> will retrieve the
 338     numeric GID (group identifier). Similarly,
 339     <function>sd_bus_creds_get_egid()</function> returns the effective
 340     GID, <function>sd_bus_creds_get_sgid()</function> the saved GID
 341     and <function>sd_bus_creds_get_fsgid()</function> the file system
 342     GID.</para>
 343
 344     <para><function>sd_bus_creds_get_supplementary_gids()</function>
 345     will retrieve the supplementary GIDs list.</para>
 346
 347     <para><function>sd_bus_creds_get_comm()</function> will retrieve the
 348     comm field (truncated name of the executable, as stored in
 349     <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
 350     </para>
 351
 352     <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
 353     the comm field of the thread (as stored in
 354     <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
 355     </para>
 356
 357     <para><function>sd_bus_creds_get_exe()</function> will retrieve
 358     the path to the program executable (as stored in the
 359     <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
 360     link, but with the <literal> (deleted)</literal> suffix removed). Note
 361     that kernel threads do not have an executable path, in which case
 362     -ENXIO is returned.</para>
 363
 364     <para><function>sd_bus_creds_get_cmdline()</function> will
 365     retrieve an array of command line arguments (as stored in
 366     <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note
 367     that kernel threads do not have a command line, in which case
 368     -ENXIO is returned.</para>
 369
 370     <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
 371     the control group path. See <ulink
 372     url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>.
 373     </para>
 374
 375     <para><function>sd_bus_creds_get_unit()</function> will retrieve
 376     the systemd unit name (in the system instance of systemd) that the
 377     process is a part of. See
 378     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
 379     processes that are not part of a unit, returns -ENXIO.
 380     </para>
 381
 382     <para><function>sd_bus_creds_get_user_unit()</function> will
 383     retrieve the systemd unit name (in the user instance of systemd)
 384     that the process is a part of. See
 385     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
 386     processes that are not part of a user unit, returns -ENXIO.
 387     </para>
 388
 389     <para><function>sd_bus_creds_get_slice()</function> will retrieve
 390     the systemd slice (a unit in the system instance of systemd) that
 391     the process is a part of. See
 392     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly,
 393     <function>sd_bus_creds_get_user_slice()</function> retrieves the
 394     systemd slice of the process, in the user instance of systemd.
 395     </para>
 396
 397     <para><function>sd_bus_creds_get_session()</function> will
 398     retrieve the identifier of the login session that the process is
 399     a part of. Please note the login session may be limited to a stub
 400     process or two.  User processes may instead be started from their
 401     systemd user manager, e.g. GUI applications started using DBus
 402     activation, as well as service processes which are shared between
 403     multiple logins of the same user. For processes that are not part
 404     of a session, returns -ENXIO.</para>
 405
 406     <para><function>sd_bus_creds_get_owner_uid()</function> will
 407     retrieve the numeric UID (user identifier) of the user who owns
 408     the user unit or login session that the process is a part of. See
 409     <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 410     For processes that are not part of a user unit or session, returns
 411     -ENXIO.
 412     </para>
 413
 414     <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by
 415     <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it
 416     was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry
 417     project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the
 418     <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in
 419     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 420     </para>
 421
 422     <para><function>sd_bus_creds_has_permitted_cap()</function> is
 423     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 424     but will check the permitted capabilities mask.</para>
 425
 426     <para><function>sd_bus_creds_has_inheritable_cap()</function> is
 427     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 428     but will check the inheritable capabilities mask.</para>
 429
 430     <para><function>sd_bus_creds_has_bounding_cap()</function> is
 431     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 432     but will check the bounding capabilities mask.</para>
 433
 434     <para><function>sd_bus_creds_get_selinux_context()</function> will
 435     retrieve the SELinux security context (label) of the process.</para>
 436
 437     <para><function>sd_bus_creds_get_audit_session_id()</function>
 438     will retrieve the audit session identifier of the process. Returns
 439     -ENXIO for processes that are not part of an audit session.</para>
 440
 441     <para><function>sd_bus_creds_get_audit_login_uid()</function> will
 442     retrieve the audit user login identifier (the identifier of the
 443     user who is "responsible" for the session). Returns -ENXIO for
 444     processes that are not part of an audit session.</para>
 445
 446     <para><function>sd_bus_creds_get_tty()</function> will retrieve
 447     the controlling TTY, without the prefixing "/dev/". Returns -ENXIO
 448     for processes that have no controlling TTY.</para>
 449
 450     <para><function>sd_bus_creds_get_unique_name()</function> will
 451     retrieve the D-Bus unique name. See <ulink
 452     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 453     D-Bus specification</ulink>.</para>
 454
 455     <para><function>sd_bus_creds_get_well_known_names()</function> will
 456     retrieve the set of D-Bus well-known names. See <ulink
 457     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 458     D-Bus specification</ulink>.</para>
 459
 460     <para><function>sd_bus_creds_get_description()</function> will
 461     retrieve a descriptive name of the bus connection of the
 462     peer. This name is useful to discern multiple bus connections by
 463     the same peer, and may be altered by the peer with the
 464     <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 465     call.</para>
 466
 467     <para>All functions that take a <parameter>const
 468     char**</parameter> parameter will store the answer there as an
 469     address of a NUL-terminated string. It will be valid as long as
 470     <parameter>c</parameter> remains valid, and should not be freed or
 471     modified by the caller.</para>
 472
 473     <para>All functions that take a <parameter>char***</parameter>
 474     parameter will store the answer there as an address of an array
 475     of strings. Each individual string is NUL-terminated, and the
 476     array is NULL-terminated as a whole. It will be valid as long as
 477     <parameter>c</parameter> remains valid, and should not be freed or
 478     modified by the caller.</para>
 479   </refsect1>
 480
 481   <refsect1>
 482     <title>Return Value</title>
 483
 484     <para>On success, these calls return 0 or a positive integer. On
 485     failure, these calls return a negative errno-style error code.
 486     </para>
 487   </refsect1>
 488
 489   <refsect1>
 490     <title>Errors</title>
 491
 492     <para>Returned errors may indicate the following problems:</para>
 493
 494     <variablelist>
 495       <varlistentry>
 496         <term><constant>-ENODATA</constant></term>
 497
 498         <listitem><para>The given field is not available in the
 499         credentials object <parameter>c</parameter>.</para>
 500         </listitem>
 501       </varlistentry>
 502
 503       <varlistentry>
 504         <term><constant>-ENXIO</constant></term>
 505
 506         <listitem><para>The given field is not specified for the described
 507         process or peer. This will be returned by
 508         <function>sd_bus_creds_get_unit()</function>,
 509         <function>sd_bus_creds_get_slice()</function>,
 510         <function>sd_bus_creds_get_user_unit()</function>,
 511         <function>sd_bus_creds_get_user_slice()</function>, and
 512         <function>sd_bus_creds_get_session()</function> if the process is
 513         not part of a systemd system unit, systemd user unit, systemd
 514         slice, or logind session. It will be returned by
 515         <function>sd_bus_creds_get_owner_uid()</function> if the process is
 516         not part of a systemd user unit or logind session. It will also be
 517         returned by <function>sd_bus_creds_get_exe()</function> and
 518         <function>sd_bus_creds_get_cmdline()</function> for kernel
 519         threads (since these are not started from an executable binary,
 520         nor have a command line), and by
 521         <function>sd_bus_creds_get_audit_session_id()</function> and
 522         <function>sd_bus_creds_get_audit_login_uid()</function> when
 523         the process is not part of an audit session, and
 524         <function>sd_bus_creds_get_tty()</function> if the process has
 525         no controlling TTY.
 526         </para>
 527         </listitem>
 528       </varlistentry>
 529
 530       <varlistentry>
 531         <term><constant>-EINVAL</constant></term>
 532
 533         <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
 534         </para></listitem>
 535       </varlistentry>
 536
 537       <varlistentry>
 538         <term><constant>-ENOMEM</constant></term>
 539
 540         <listitem><para>Memory allocation failed.</para></listitem>
 541       </varlistentry>
 542     </variablelist>
 543   </refsect1>
 544
 545   <refsect1>
 546     <title>Notes</title>
 547
 548     <para><function>sd_bus_creds_get_pid()</function> and the other
 549     functions described here are available as a shared library, which
 550     can be compiled and linked to with the
 551     <constant>libsystemd</constant> <citerefentry
 552     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 553     file.</para>
 554   </refsect1>
 555
 556   <refsect1>
 557     <title>See Also</title>
 558
 559     <para>
 560       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 561       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 562       <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 563       <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 564       <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 565       <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 566       <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 567       <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 568       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 569     </para>
 570   </refsect1>
 571
 572 </refentry>