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" 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_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     <refname>sd_bus_creds_get_connection_name</refname>
  71
  72     <refpurpose>Retrieve fields from a credentials object</refpurpose>
  73   </refnamediv>
  74
  75   <refsynopsisdiv>
  76     <funcsynopsis>
  77       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  78
  79       <funcprototype>
  80         <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
  81         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  82         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_bus_creds_get_pid_starttime</function></funcdef>
  87         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  88         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  89       </funcprototype>
  90
  91       <funcprototype>
  92         <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
  93         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  94         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
  95       </funcprototype>
  96
  97       <funcprototype>
  98         <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
  99         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 100         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 101       </funcprototype>
 102
 103       <funcprototype>
 104         <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
 105         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 106         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
 107       </funcprototype>
 108
 109       <funcprototype>
 110         <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
 111         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 112         <paramdef>const char **<parameter>comm</parameter></paramdef>
 113       </funcprototype>
 114
 115       <funcprototype>
 116         <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
 117         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 118         <paramdef>const char **<parameter>comm</parameter></paramdef>
 119       </funcprototype>
 120
 121       <funcprototype>
 122         <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
 123         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 124         <paramdef>const char **<parameter>exe</parameter></paramdef>
 125       </funcprototype>
 126
 127       <funcprototype>
 128         <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
 129         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 130         <paramdef>char ***<parameter>cmdline</parameter></paramdef>
 131       </funcprototype>
 132
 133       <funcprototype>
 134         <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
 135         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 136         <paramdef>const char **<parameter>cgroup</parameter></paramdef>
 137       </funcprototype>
 138
 139       <funcprototype>
 140         <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
 141         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 142         <paramdef>const char **<parameter>unit</parameter></paramdef>
 143       </funcprototype>
 144
 145       <funcprototype>
 146         <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
 147         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 148         <paramdef>const char **<parameter>unit</parameter></paramdef>
 149       </funcprototype>
 150
 151       <funcprototype>
 152         <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
 153         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 154         <paramdef>const char **<parameter>slice</parameter></paramdef>
 155       </funcprototype>
 156
 157       <funcprototype>
 158         <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
 159         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 160         <paramdef>const char **<parameter>slice</parameter></paramdef>
 161       </funcprototype>
 162
 163       <funcprototype>
 164         <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
 165         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 166         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 167       </funcprototype>
 168
 169       <funcprototype>
 170         <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
 171         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 172         <paramdef>int <parameter>capability</parameter></paramdef>
 173       </funcprototype>
 174
 175       <funcprototype>
 176         <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
 177         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 178         <paramdef>int <parameter>capability</parameter></paramdef>
 179       </funcprototype>
 180
 181       <funcprototype>
 182         <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
 183         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 184         <paramdef>int <parameter>capability</parameter></paramdef>
 185       </funcprototype>
 186
 187       <funcprototype>
 188         <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
 189         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 190         <paramdef>int <parameter>capability</parameter></paramdef>
 191       </funcprototype>
 192
 193       <funcprototype>
 194         <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
 195         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 196         <paramdef>const char **<parameter>context</parameter></paramdef>
 197       </funcprototype>
 198
 199       <funcprototype>
 200         <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
 201         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 202         <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
 203       </funcprototype>
 204
 205       <funcprototype>
 206         <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
 207         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 208         <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
 209       </funcprototype>
 210
 211       <funcprototype>
 212         <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
 213         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 214         <paramdef>const char **<parameter>name</parameter></paramdef>
 215       </funcprototype>
 216
 217       <funcprototype>
 218         <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
 219         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 220         <paramdef>char ***<parameter>name</parameter></paramdef>
 221       </funcprototype>
 222
 223       <funcprototype>
 224         <funcdef>int <function>sd_bus_creds_get_connection_name</function></funcdef>
 225         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
 226         <paramdef>const char **<parameter>name</parameter></paramdef>
 227       </funcprototype>
 228
 229     </funcsynopsis>
 230   </refsynopsisdiv>
 231
 232   <refsect1>
 233     <title>Description</title>
 234
 235     <para>These functions return information from an
 236     <parameter>sd_bus_creds</parameter> object. It may be created with
 237     <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 238     in which case it will describe the specified process, or it may be
 239     created by
 240     <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 241     in which case it will describe the process at the other endpoint
 242     of a connection.
 243     </para>
 244
 245     <para><function>sd_bus_creds_get_pid()</function> will retrieve the
 246     PID (process identifier).</para>
 247
 248     <para><function>sd_bus_creds_get_pid_starttime()</function> will
 249     retrieve the time since the start of the epoch in microseconds
 250     since the process was started.</para>
 251
 252     <para><function>sd_bus_creds_get_tid()</function> will retrieve the
 253     TID (thread identifier).</para>
 254
 255     <para><function>sd_bus_creds_get_uid()</function> will retrieve the
 256     numeric UID (user identifier).</para>
 257
 258     <para><function>sd_bus_creds_get_gid()</function> will retrieve the
 259     numeric GID (group identifier).</para>
 260
 261     <para><function>sd_bus_creds_get_comm()</function> will retrieve the
 262     comm field (truncated name of the executable, as stored in
 263     <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
 264     </para>
 265
 266     <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve
 267     the comm field of the thread (as stored in
 268     <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
 269     </para>
 270
 271     <para><function>sd_bus_creds_get_exe()</function> will retrieve the
 272     path to the program (as stored in the
 273     <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
 274     link, but with <literal> (deleted)</literal> suffix removed).
 275     </para>
 276
 277     <para><function>sd_bus_creds_get_cmdline()</function> will retrieve
 278     an array of command-line arguments (as stored in
 279     <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
 280     </para>
 281
 282     <para><function>sd_bus_creds_get_cgroup()</function> will retrieve
 283     the cgroup path. See <ulink
 284     url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
 285     </para>
 286
 287     <para><function>sd_bus_creds_get_unit()</function> will retrieve the
 288     systemd unit name (in the system instance of systemd) that the
 289     process is part of. See
 290     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 291     </para>
 292
 293     <para><function>sd_bus_creds_get_user_unit()</function> will
 294     retrieve the systemd unit name (in the user instance of systemd)
 295     that the process is part of. See
 296     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 297     </para>
 298
 299     <para><function>sd_bus_creds_get_slice()</function> will retrieve
 300     the systemd slice (a unit in the system instance of systemd) that
 301     the process is part of. See
 302     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 303     </para>
 304
 305     <para><function>sd_bus_creds_get_session()</function> will retrieve
 306     the logind session that the process is part of. See
 307     <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 308     </para>
 309
 310     <para><function>sd_bus_creds_get_owner_uid()</function> will retrieve
 311     the numeric UID (user identifier) of the user who owns the slice
 312     that the process is part of. See
 313     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 314     <!-- and
 315     <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
 316     </para>
 317
 318     <para><function>sd_bus_creds_has_effective_cap()</function> will
 319     check whether the capability specified by
 320     <parameter>capability</parameter> was set in the effective
 321     capabilities mask. A positive return value means that is was
 322     set, zero means that it was not set, and a negative return
 323     value signifies an error. See
 324     <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 325     and <varname>Capabilities=</varname> and
 326     <varname>CapabilityBoundingSet=</varname> settings in
 327     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 328     </para>
 329
 330     <para><function>sd_bus_creds_has_permitted_cap()</function> is
 331     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 332     but will check the permitted capabilities mask.</para>
 333
 334     <para><function>sd_bus_creds_has_inheritable_cap()</function> is
 335     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 336     but will check the inheritable capabilities mask.</para>
 337
 338     <para><function>sd_bus_creds_has_bounding_cap()</function> is
 339     similar to <function>sd_bus_creds_has_effective_cap()</function>,
 340     but will check the bounding capabilities mask.</para>
 341
 342     <para><function>sd_bus_creds_get_selinux_context()</function> will
 343     retrieve the SELinux security context (label) of the process.</para>
 344
 345     <para><function>sd_bus_creds_get_audit_session_id()</function> will
 346     retrieve the audit session identifier of the process.</para>
 347
 348     <para><function>sd_bus_creds_get_audit_login_uid()</function> will
 349     retrieve the audit user login identifier (the identifier of the
 350     user who is "responsible" for the session).</para>
 351
 352     <para><function>sd_bus_creds_get_unique_name()</function> will
 353     retrieve the D-Bus unique name. See <ulink
 354     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 355     D-Bus specification</ulink>.</para>
 356
 357     <para><function>sd_bus_creds_get_well_known_names()</function> will
 358     retrieve the set of D-Bus well-known names. See <ulink
 359     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
 360     D-Bus specification</ulink>.</para>
 361
 362     <para><function>sd_bus_creds_get_connection_name()</function> will
 363     retrieve a descriptive name of the bus connection of the
 364     peer. This name is useful to discern multiple bus connections by
 365     the same peer, and may be altered by the peer with the
 366     <citerefentry><refentrytitle>sd_bus_set_name()</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 367     call.</para>
 368
 369     <para>All functions that take a <parameter>const
 370     char**</parameter> parameter will store the answer there as an
 371     address of a NUL-terminated string. It will be valid as long as
 372     <parameter>c</parameter> remains valid, and should not be freed or
 373     modified by the caller.</para>
 374
 375     <para>All functions that take a <parameter>char***</parameter>
 376     parameter will store the answer there as an address of a an array
 377     of strings. Each invidividual string is NUL-terminated, and the
 378     array is NULL-terminated as a whole. It will be valid as long as
 379     <parameter>c</parameter> remains valid, and should not be freed or
 380     modified by the caller.</para>
 381   </refsect1>
 382
 383   <refsect1>
 384     <title>Return Value</title>
 385
 386     <para>On success, these calls return 0 or a positive integer. On
 387     failure, these calls return a negative errno-style error code.
 388     </para>
 389   </refsect1>
 390
 391   <refsect1>
 392     <title>Errors</title>
 393
 394     <para>Returned errors may indicate the following problems:</para>
 395
 396     <variablelist>
 397       <varlistentry>
 398         <term><constant>-ENODATA</constant></term>
 399
 400         <listitem><para>Given field is not available in
 401         <parameter>c</parameter>.</para>
 402         </listitem>
 403       </varlistentry>
 404
 405       <varlistentry>
 406         <term><constant>-ENOENT</constant></term>
 407
 408         <listitem><para>Given field is not specified for the sender.
 409         This will be returned by <function>sd_bus_get_unit()</function>,
 410         <function>sd_bus_get_user_unit()</function>,
 411         <function>sd_bus_get_slice()</function>,
 412         <function>sd_bus_get_session()</function>, and
 413         <function>sd_bus_get_name_creds_uid()</function> if the sender is not
 414         part of a systemd system unit, systemd user unit, systemd
 415         slice, logind session, or a systemd user session.</para>
 416         </listitem>
 417       </varlistentry>
 418
 419       <varlistentry>
 420         <term><constant>-ENXIO</constant></term>
 421
 422         <listitem><para>An error occurred in parsing cgroup paths.
 423         <filename>libsystemd</filename> might be out of sync with
 424         the running systemd version.</para></listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term><constant>-EINVAL</constant></term>
 429
 430         <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
 431         </para></listitem>
 432       </varlistentry>
 433
 434       <varlistentry>
 435         <term><constant>-ENOMEM</constant></term>
 436
 437         <listitem><para>Memory allocation failed.</para></listitem>
 438       </varlistentry>
 439     </variablelist>
 440   </refsect1>
 441
 442   <refsect1>
 443     <title>Notes</title>
 444
 445     <para><function>sd_bus_open_user()</function> and other functions
 446     described here are available as a shared library, which can be
 447     compiled and linked to with the
 448     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 449     file.</para>
 450   </refsect1>
 451
 452   <refsect1>
 453     <title>See Also</title>
 454
 455     <para>
 456       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 457       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 458       <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 459       <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 460       <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 461       <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 462       <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 463       <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 464     </para>
 465   </refsect1>
 466
 467 </refentry>