man/sd_bus_creds_unref.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_creds_new_from_pid</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</span><hr><div class="refentry"><a name="sd_bus_creds_new_from_pid"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_creds_new_from_pid, sd_bus_creds_get_mask, sd_bus_creds_ref, sd_bus_creds_unref — Retrieve credentials object for the specified PID</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-bus.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_creds_new_from_pid</b>(</code></td><td>pid_t <var class="pdparam">pid</var>, </td></tr><tr><td> </td><td>uint64_t <var class="pdparam">creds_mask</var>, </td></tr><tr><td> </td><td>sd_bus_creds **<var class="pdparam">ret</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">uint64_t <b class="fsfunc">sd_bus_creds_get_mask</b>(</code></td><td>const sd_bus_creds *<var class="pdparam">c</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">sd_bus_creds *<b class="fsfunc">sd_bus_creds_ref</b>(</code></td><td>sd_bus_creds *<var class="pdparam">c</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">sd_bus_creds *<b class="fsfunc">sd_bus_creds_unref</b>(</code></td><td>sd_bus_creds *<var class="pdparam">c</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
  23       <code class="constant">SD_BUS_CREDS_PID</code>,
  24       <code class="constant">SD_BUS_CREDS_TID</code>,
  25       <code class="constant">SD_BUS_CREDS_UID</code>,
  26       <code class="constant">SD_BUS_CREDS_GID</code>,
  27       <code class="constant">SD_BUS_CREDS_COMM</code>,
  28       <code class="constant">SD_BUS_CREDS_TID_COMM</code>,
  29       <code class="constant">SD_BUS_CREDS_EXE</code>,
  30       <code class="constant">SD_BUS_CREDS_CMDLINE</code>,
  31       <code class="constant">SD_BUS_CREDS_CGROUP</code>,
  32       <code class="constant">SD_BUS_CREDS_UNIT</code>,
  33       <code class="constant">SD_BUS_CREDS_USER_UNIT</code>,
  34       <code class="constant">SD_BUS_CREDS_SLICE</code>,
  35       <code class="constant">SD_BUS_CREDS_SESSION</code>,
  36       <code class="constant">SD_BUS_CREDS_OWNER_UID</code>,
  37       <code class="constant">SD_BUS_CREDS_EFFECTIVE_CAPS</code>,
  38       <code class="constant">SD_BUS_CREDS_PERMITTED_CAPS</code>,
  39       <code class="constant">SD_BUS_CREDS_INHERITABLE_CAPS</code>,
  40       <code class="constant">SD_BUS_CREDS_BOUNDING_CAPS</code>,
  41       <code class="constant">SD_BUS_CREDS_SELINUX_CONTEXT</code>,
  42       <code class="constant">SD_BUS_CREDS_AUDIT_SESSION_ID</code>,
  43       <code class="constant">SD_BUS_CREDS_AUDIT_LOGIN_UID</code>,
  44       <code class="constant">SD_BUS_CREDS_UNIQUE_NAME</code>,
  45       <code class="constant">SD_BUS_CREDS_WELL_KNOWN_NAMES</code>,
  46       <code class="constant">_SD_BUS_CREDS_ALL</code>
  47     </p></div><div class="refsect1"><a name="idm140511734774400"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_bus_creds_new_from_pid()</code> creates a new
  48     credentials object and fills it with information about the process
  49     <em class="parameter"><code>pid</code></em>. This pointer to this object will
  50     be stored in <em class="parameter"><code>ret</code></em> pointer.</p><p>The information that will be stored is determined by
  51     <em class="parameter"><code>creds_mask</code></em>. It may contain a subset of ORed
  52     constants <code class="constant">SD_BUS_CREDS_PID</code>,
  53     <code class="constant">SD_BUS_CREDS_TID</code>,
  54     <code class="constant">SD_BUS_CREDS_UID</code>,
  55     <code class="constant">SD_BUS_CREDS_GID</code>,
  56     <code class="constant">SD_BUS_CREDS_COMM</code>,
  57     <code class="constant">SD_BUS_CREDS_TID_COMM</code>,
  58     <code class="constant">SD_BUS_CREDS_EXE</code>,
  59     <code class="constant">SD_BUS_CREDS_CMDLINE</code>,
  60     <code class="constant">SD_BUS_CREDS_CGROUP</code>,
  61     <code class="constant">SD_BUS_CREDS_UNIT</code>,
  62     <code class="constant">SD_BUS_CREDS_USER_UNIT</code>,
  63     <code class="constant">SD_BUS_CREDS_SLICE</code>,
  64     <code class="constant">SD_BUS_CREDS_SESSION</code>,
  65     <code class="constant">SD_BUS_CREDS_OWNER_UID</code>,
  66     <code class="constant">SD_BUS_CREDS_EFFECTIVE_CAPS</code>,
  67     <code class="constant">SD_BUS_CREDS_PERMITTED_CAPS</code>,
  68     <code class="constant">SD_BUS_CREDS_INHERITABLE_CAPS</code>,
  69     <code class="constant">SD_BUS_CREDS_BOUNDING_CAPS</code>,
  70     <code class="constant">SD_BUS_CREDS_SELINUX_CONTEXT</code>,
  71     <code class="constant">SD_BUS_CREDS_AUDIT_SESSION_ID</code>,
  72     <code class="constant">SD_BUS_CREDS_AUDIT_LOGIN_UID</code>,
  73     <code class="constant">SD_BUS_CREDS_UNIQUE_NAME</code>,
  74     <code class="constant">SD_BUS_CREDS_WELL_KNOWN_NAMES</code>,
  75     or <code class="constant">_SD_BUS_CREDS_ALL</code> to indicate
  76     all known fields.</p><p>Fields can be retrieved from the credentials object using
  77     <a href="sd_bus_creds_get_pid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_pid</span>(3)</span></a>
  78     and other functions which correspond directly to the constants
  79     listed above.</p><p>A mask of fields which were actually successfully set
  80     (acquired from <code class="filename">/proc</code>, etc.) can be retrieved
  81     with <code class="function">sd_bus_creds_get_mask()</code>. If the
  82     credentials object was created with
  83     <code class="function">sd_bus_creds_new_from_pid()</code>, this will be a
  84     subset of fields requested in <em class="parameter"><code>creds_mask</code></em>.
  85     </p><p><code class="function">sd_bus_creds_ref</code> creates a new
  86     reference to the credentials object <em class="parameter"><code>c</code></em>. This
  87     object will not be destroyed until
  88     <code class="function">sd_bus_creds_unref</code> has been called as many
  89     times plus once more. Once the reference count has dropped to zero,
  90     <em class="parameter"><code>c</code></em> cannot be used anymore, so further
  91     calls to <code class="function">sd_bus_creds_ref(c)</code> or
  92     <code class="function">sd_bus_creds_unref(c)</code> are illegal.</p><p><code class="function">sd_bus_creds_unref</code> destroys a reference
  93     to <em class="parameter"><code>c</code></em>.</p></div><div class="refsect1"><a name="idm140511734741680"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success, <code class="function">sd_bus_creds_new_from_pid()</code>
  94     returns 0 or a positive integer. On failure, it returns a negative
  95     errno-style error code.</p><p><code class="function">sd_bus_creds_get_mask()</code> returns the
  96     mask of successfully acquired fields.</p><p><code class="function">sd_bus_creds_ref</code> always returns the
  97     argument.</p><p><code class="function">sd_bus_creds_unref</code> always returns
  98     <code class="constant">NULL</code>.</p></div><div class="refsect1"><a name="idm140511734736320"></a><h2 id="Reference ownership">Reference ownership<a class="headerlink" title="Permalink to this headline" href="#Reference%20ownership">¶</a></h2><p>Function <code class="function">sd_bus_creds_new_from_pid()</code>
  99     creates a new object and the caller owns the sole reference. When
 100     not needed anymore, this reference should be destroyed with
 101     <a href="sd_bus_creds_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_unref</span>(3)</span></a>.
 102     </p></div><div class="refsect1"><a name="idm140511729824272"></a><h2 id="Errors">Errors<a class="headerlink" title="Permalink to this headline" href="#Errors">¶</a></h2><p>Returned errors may indicate the following problems:</p><div class="variablelist"><dl class="variablelist"><dt id="-ESRCH"><span class="term"><code class="constant">-ESRCH</code></span><a class="headerlink" title="Permalink to this term" href="#-ESRCH">¶</a></dt><dd><p>Specified <em class="parameter"><code>pid</code></em> could not
 103         be found.</p></dd><dt id="-EINVAL"><span class="term"><code class="constant">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL">¶</a></dt><dd><p>Specified parameter is invalid
 104         (<code class="constant">NULL</code> in case of output
 105         parameters).</p></dd><dt id="-ENOMEM"><span class="term"><code class="constant">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM">¶</a></dt><dd><p>Memory allocation failed.</p></dd></dl></div></div><div class="refsect1"><a name="idm140511729817504"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p><code class="function">sd_bus_creds_new_from_pid()</code> is
 106     available as a shared library, which can be compiled and linked to
 107     with the
 108     <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
 109     file.</p></div><div class="refsect1"><a name="idm140511729814352"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 110       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 111       <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
 112       <a href="sd_bus_creds_ref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_ref</span>(3)</span></a>,
 113       <a href="sd_bus_creds_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_unref</span>(3)</span></a>,
 114       <a href="sd_bus_creds_get_pid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_pid</span>(3)</span></a>,
 115       <a href="sd_bus_creds_get_tid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_tid</span>(3)</span></a>,
 116       <a href="sd_bus_creds_get_uid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_uid</span>(3)</span></a>,
 117       <a href="sd_bus_creds_get_gid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_gid</span>(3)</span></a>,
 118       <a href="sd_bus_creds_get_comm.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_comm</span>(3)</span></a>,
 119       <a href="sd_bus_creds_get_tid_comm.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_tid_comm</span>(3)</span></a>,
 120       <a href="sd_bus_creds_get_exe.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_exe</span>(3)</span></a>,
 121       <a href="sd_bus_creds_get_cmdline.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_cmdline</span>(3)</span></a>,
 122       <a href="sd_bus_creds_get_cgroup.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_cgroup</span>(3)</span></a>,
 123       <a href="sd_bus_creds_get_unit.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_unit</span>(3)</span></a>,
 124       <a href="sd_bus_creds_get_user_unit.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_user_unit</span>(3)</span></a>,
 125       <a href="sd_bus_creds_get_slice.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_slice</span>(3)</span></a>,
 126       <a href="sd_bus_creds_get_session.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_session</span>(3)</span></a>,
 127       <a href="sd_bus_creds_get_owner_uid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_owner_uid</span>(3)</span></a>,
 128       <a href="sd_bus_creds_has_effective_cap.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_has_effective_cap</span>(3)</span></a>,
 129       <a href="sd_bus_creds_has_permitted_cap.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_has_permitted_cap</span>(3)</span></a>,
 130       <a href="sd_bus_creds_has_inheritable_cap.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_has_inheritable_cap</span>(3)</span></a>,
 131       <a href="sd_bus_creds_has_bounding_cap.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_has_bounding_cap</span>(3)</span></a>,
 132       <a href="sd_bus_creds_get_selinux_context.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_selinux_context</span>(3)</span></a>,
 133       <a href="sd_bus_creds_get_audit_session_id.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_audit_session_id</span>(3)</span></a>,
 134       <a href="sd_bus_creds_get_audit_login_uid.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_audit_login_uid</span>(3)</span></a>,
 135       <a href="sd_bus_creds_get_unique_name.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_unique_name</span>(3)</span></a>,
 136       <a href="sd_bus_creds_get_well_known_names.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_creds_get_well_known_names</span>(3)</span></a>
 137     </p></div></div></body></html>