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 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" conditional="ENABLE_KDBUS">
  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_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>
  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_tid</function></funcdef>
  86         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  87         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
  88       </funcprototype>
  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>uid_t *<parameter>uid</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  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>
 100       </funcprototype>
 101
 102       <funcprototype>
 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>
 106       </funcprototype>
 107
 108       <funcprototype>
 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>
 112       </funcprototype>
 113
 114       <funcprototype>
 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>
 118       </funcprototype>
 119
 120       <funcprototype>
 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>
 124       </funcprototype>
 125
 126       <funcprototype>
 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>
 130       </funcprototype>
 131
 132       <funcprototype>
 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>
 136       </funcprototype>
 137
 138       <funcprototype>
 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>
 142       </funcprototype>
 143
 144       <funcprototype>
 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>
 148       </funcprototype>
 149
 150       <funcprototype>
 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>
 154       </funcprototype>
 155
 156       <funcprototype>
 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>
 160       </funcprototype>
 161
 162       <funcprototype>
 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>
 166       </funcprototype>
 167
 168       <funcprototype>
 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>
 172       </funcprototype>
 173
 174       <funcprototype>
 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>
 178       </funcprototype>
 179
 180       <funcprototype>
 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>
 184       </funcprototype>
 185
 186       <funcprototype>
 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>
 190       </funcprototype>
 191
 192       <funcprototype>
 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>
 196       </funcprototype>
 197
 198       <funcprototype>
 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>
 202       </funcprototype>
 203
 204       <funcprototype>
 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>
 208       </funcprototype>
 209
 210       <funcprototype>
 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>
 214       </funcprototype>
 215
 216       <funcprototype>
 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>
 220       </funcprototype>
 221
 222     </funcsynopsis>
 223   </refsynopsisdiv>
 224
 225   <refsect1>
 226     <title>Description</title>
 227
 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
 232     created by
 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
 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_tid()</function> will retrieve the
 242     TID (thread identifier).</para>
 243
 244     <para><function>sd_bus_creds_get_uid()</function> will retrieve the
 245     numeric UID (user identifier).</para>
 246
 247     <para><function>sd_bus_creds_get_gid()</function> will retrieve the
 248     numeric GID (group identifier).</para>
 249
 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>).
 253     </para>
 254
 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>).
 258     </para>
 259
 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).
 264     </para>
 265
 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>).
 269     </para>
 270
 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>.
 274     </para>
 275
 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>.
 280     </para>
 281
 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>.
 286     </para>
 287
 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>.
 292     </para>
 293
 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>.
 297     </para>
 298
 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>
 303     <!-- and
 304     <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
 305     </para>
 306
 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>.
 317     </para>
 318
 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>
 322
 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>
 326
 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>
 330
 331     <para><function>sd_bus_creds_get_selinux_context()</function> will
 332     retrieve the SELinux security context (label) of the process.</para>
 333
 334     <para><function>sd_bus_creds_get_audit_session_id()</function> will
 335     retrieve the audit session identifier of the process.</para>
 336
 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>
 340
 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>
 345
 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>
 350
 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>
 356     call.</para>
 357
 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>
 363
 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>
 370   </refsect1>
 371
 372   <refsect1>
 373     <title>Return Value</title>
 374
 375     <para>On success, these calls return 0 or a positive integer. On
 376     failure, these calls return a negative errno-style error code.
 377     </para>
 378   </refsect1>
 379
 380   <refsect1>
 381     <title>Errors</title>
 382
 383     <para>Returned errors may indicate the following problems:</para>
 384
 385     <variablelist>
 386       <varlistentry>
 387         <term><constant>-ENODATA</constant></term>
 388
 389         <listitem><para>Given field is not available in
 390         <parameter>c</parameter>.</para>
 391         </listitem>
 392       </varlistentry>
 393
 394       <varlistentry>
 395         <term><constant>-ENOENT</constant></term>
 396
 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>
 405         </listitem>
 406       </varlistentry>
 407
 408       <varlistentry>
 409         <term><constant>-ENXIO</constant></term>
 410
 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>
 414       </varlistentry>
 415
 416       <varlistentry>
 417         <term><constant>-EINVAL</constant></term>
 418
 419         <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
 420         </para></listitem>
 421       </varlistentry>
 422
 423       <varlistentry>
 424         <term><constant>-ENOMEM</constant></term>
 425
 426         <listitem><para>Memory allocation failed.</para></listitem>
 427       </varlistentry>
 428     </variablelist>
 429   </refsect1>
 430
 431   <refsect1>
 432     <title>Notes</title>
 433
 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>
 438     file.</para>
 439   </refsect1>
 440
 441   <refsect1>
 442     <title>See Also</title>
 443
 444     <para>
 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>
 453     </para>
 454   </refsect1>
 455
 456 </refentry>