man/sd_bus_creds_get_pid.xml

   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">
   4
   5 <!--
   6 This file is part of systemd.
   7
   8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  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.
  14
  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.
  19
  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/>.
  22 -->
  23
  24 <refentry id="sd_bus_creds_get_pid">
  25
  26   <refentryinfo>
  27     <title>sd_bus_creds_get_pid</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  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>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_bus_creds_get_pid</refname>
  47     <refname>sd_bus_creds_get_pid_starttime</refname>
  48     <refname>sd_bus_creds_get_tid</refname>
  49     <refname>sd_bus_creds_get_uid</refname>
  50     <refname>sd_bus_creds_get_gid</refname>
  51     <refname>sd_bus_creds_get_comm</refname>
  52     <refname>sd_bus_creds_get_tid_comm</refname>
  53     <refname>sd_bus_creds_get_exe</refname>
  54     <refname>sd_bus_creds_get_cmdline</refname>
  55     <refname>sd_bus_creds_get_cgroup</refname>
  56     <refname>sd_bus_creds_get_unit</refname>
  57     <refname>sd_bus_creds_get_user_unit</refname>
  58     <refname>sd_bus_creds_get_slice</refname>
  59     <refname>sd_bus_creds_get_session</refname>
  60     <refname>sd_bus_creds_get_owner_uid</refname>
  61     <refname>sd_bus_creds_has_effective_cap</refname>
  62     <refname>sd_bus_creds_has_permitted_cap</refname>
  63     <refname>sd_bus_creds_has_inheritable_cap</refname>
  64     <refname>sd_bus_creds_has_bounding_cap</refname>
  65     <refname>sd_bus_creds_get_selinux_context</refname>
  66     <refname>sd_bus_creds_get_audit_session_id</refname>
  67     <refname>sd_bus_creds_get_audit_login_uid</refname>
  68     <refname>sd_bus_creds_get_unique_name</refname>
  69     <refname>sd_bus_creds_get_well_known_names</refname>
  70
  71     <refpurpose>Retrieve fields from a credentials object</refpurpose>
  72   </refnamediv>
  73
  74   <refsynopsisdiv>
  75     <funcsynopsis>
  76       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  77
  78       <funcprototype>
  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>
  82       </funcprototype>
  83
  84       <funcprototype>
  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>
  88       </funcprototype>
  89
  90       <funcprototype>
  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>
  94       </funcprototype>
  95
  96       <funcprototype>
  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>
 100       </funcprototype>
 101
 102       <funcprototype>
 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>
 106       </funcprototype>
 107
 108       <funcprototype>
 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>
 112       </funcprototype>
 113
 114       <funcprototype>
 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>
 118       </funcprototype>
 119
 120       <funcprototype>
 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>
 124       </funcprototype>
 125
 126       <funcprototype>
 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>
 130       </funcprototype>
 131
 132       <funcprototype>
 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>
 136       </funcprototype>
 137
 138       <funcprototype>
 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>
 142       </funcprototype>
 143
 144       <funcprototype>
 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>
 148       </funcprototype>
 149
 150       <funcprototype>
 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>
 154       </funcprototype>
 155
 156       <funcprototype>
 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>
 160       </funcprototype>
 161
 162       <funcprototype>
 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>
 166       </funcprototype>
 167
 168       <funcprototype>
 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>
 172       </funcprototype>
 173
 174       <funcprototype>
 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>
 178       </funcprototype>
 179
 180       <funcprototype>
 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>
 184       </funcprototype>
 185
 186       <funcprototype>
 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>
 190       </funcprototype>
 191
 192       <funcprototype>
 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>
 196       </funcprototype>
 197
 198       <funcprototype>
 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>
 202       </funcprototype>
 203
 204       <funcprototype>
 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>
 208       </funcprototype>
 209
 210       <funcprototype>
 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>
 214       </funcprototype>
 215
 216       <funcprototype>
 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>
 220       </funcprototype>
 221
 222     </funcsynopsis>
 223   </refsynopsisdiv>
 224
 225   <refsect1>
 226     <title>Description</title>
 227
 228     <para>Those 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
 232     created by
 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
 235     of a connection.
 236     </para>
 237
 238     <para><function>sd_bus_creds_get_pid</function> will retrieve the
 239     PID (process identifier).</para>
 240
 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>
 244
 245     <para><function>sd_bus_creds_get_tid</function> will retrieve the
 246     TID (thread identifier).</para>
 247
 248     <para><function>sd_bus_creds_get_uid</function> will retrieve the
 249     UID (user identifier).</para>
 250
 251     <para><function>sd_bus_creds_get_gid</function> will retrieve the
 252     GID (group identifier).</para>
 253
 254     <para><function>sd_bus_creds_get_comm</function> will retrieve the
 255     comm field (name of the executable, as stored in
 256     <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
 257     </para>
 258
 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>).
 262     </para>
 263
 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).
 268     </para>
 269
 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>).
 273     </para>
 274
 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>.
 278     </para>
 279
 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>.
 284     </para>
 285
 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>.
 290     </para>
 291
 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>.
 296     </para>
 297
 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>.
 301     </para>
 302
 303     <para><function>sd_bus_creds_get_owner_uid</function> will retrieve
 304     the 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>
 307     <!-- and
 308     <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
 309     </para>
 310
 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 were
 315     set, zero means that it was not set, and a negative return
 316     value signifies an error. See
 317     <citerefentry><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>.
 321     </para>
 322
 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>
 326
 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>
 330
 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>
 334
 335     <para><function>sd_bus_creds_get_selinux_context</function> will
 336     retrieve the SELinux security context (label) of the process.</para>
 337
 338     <para><function>sd_bus_creds_get_audit_session_id</function> will
 339     retrieve the audit session identifier of the process.</para>
 340
 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>
 344
 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>
 349
 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>
 354
 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>
 360
 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>
 367   </refsect1>
 368
 369   <refsect1>
 370     <title>Return Value</title>
 371
 372     <para>On success, these calls return 0 or a positive integer. On
 373     failure, these calls return a negative errno-style error code.
 374     </para>
 375   </refsect1>
 376
 377   <refsect1>
 378     <title>Errors</title>
 379
 380     <para>Returned errors may indicate the following problems:</para>
 381
 382     <variablelist>
 383       <varlistentry>
 384         <term><varname>-ENODATA</varname></term>
 385
 386         <listitem><para>Given field is not available in
 387         <parameter>c</parameter>.</para>
 388         </listitem>
 389       </varlistentry>
 390
 391       <varlistentry>
 392         <term><varname>-ENOENT</varname></term>
 393
 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>
 402         </listitem>
 403       </varlistentry>
 404
 405       <varlistentry>
 406         <term><varname>-ENXIO</varname></term>
 407
 408         <listitem><para>An error occured in parsing cgroup paths.
 409         <filename>libsystemd</filename> might be out of sync with
 410         the running systemd version.</para></listitem>
 411       </varlistentry>
 412
 413       <varlistentry>
 414         <term><varname>-EINVAL</varname></term>
 415
 416         <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
 417         </para></listitem>
 418       </varlistentry>
 419
 420       <varlistentry>
 421         <term><varname>-ENOMEM</varname></term>
 422
 423         <listitem><para>Memory allocation failed.</para></listitem>
 424       </varlistentry>
 425     </variablelist>
 426   </refsect1>
 427
 428   <refsect1>
 429     <title>Notes</title>
 430
 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><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 435     file.</para>
 436   </refsect1>
 437
 438   <refsect1>
 439     <title>See Also</title>
 440
 441     <para>
 442       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 443       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 444       <citerefentry><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 445       <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 446       <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 447       <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 448       <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 449       <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 450     </para>
 451   </refsect1>
 452
 453 </refentry>