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">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude">
12 <title>sd_bus_creds_new_from_pid</title>
13 <productname>systemd</productname>
17 <contrib>A monkey with a typewriter</contrib>
18 <firstname>Zbigniew</firstname>
19 <surname>Jędrzejewski-Szmek</surname>
20 <email>zbyszek@in.waw.pl</email>
26 <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>sd_bus_creds_new_from_pid</refname>
32 <refname>sd_bus_creds_get_mask</refname>
33 <refname>sd_bus_creds_get_augmented_mask</refname>
34 <refname>sd_bus_creds_ref</refname>
35 <refname>sd_bus_creds_unref</refname>
36 <refname>sd_bus_creds_unrefp</refname>
38 <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
43 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
46 <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
47 <paramdef>pid_t <parameter>pid</parameter></paramdef>
48 <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
49 <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
53 <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
54 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
58 <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
59 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
63 <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
64 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
68 <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
69 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
73 <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
74 <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
79 <constant>SD_BUS_CREDS_PID</constant>,
80 <constant>SD_BUS_CREDS_PPID</constant>,
81 <constant>SD_BUS_CREDS_TID</constant>,
82 <constant>SD_BUS_CREDS_UID</constant>,
83 <constant>SD_BUS_CREDS_EUID</constant>,
84 <constant>SD_BUS_CREDS_SUID</constant>,
85 <constant>SD_BUS_CREDS_FSUID</constant>,
86 <constant>SD_BUS_CREDS_GID</constant>,
87 <constant>SD_BUS_CREDS_EGID</constant>,
88 <constant>SD_BUS_CREDS_SGID</constant>,
89 <constant>SD_BUS_CREDS_FSGID</constant>,
90 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
91 <constant>SD_BUS_CREDS_COMM</constant>,
92 <constant>SD_BUS_CREDS_TID_COMM</constant>,
93 <constant>SD_BUS_CREDS_EXE</constant>,
94 <constant>SD_BUS_CREDS_CMDLINE</constant>,
95 <constant>SD_BUS_CREDS_CGROUP</constant>,
96 <constant>SD_BUS_CREDS_UNIT</constant>,
97 <constant>SD_BUS_CREDS_SLICE</constant>,
98 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
99 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
100 <constant>SD_BUS_CREDS_SESSION</constant>,
101 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
102 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
103 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
104 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
105 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
106 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
107 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
108 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
109 <constant>SD_BUS_CREDS_TTY</constant>,
110 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
111 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
112 <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
113 <constant>SD_BUS_CREDS_AUGMENT</constant>,
114 <constant>_SD_BUS_CREDS_ALL</constant>
119 <title>Description</title>
121 <para><function>sd_bus_creds_new_from_pid()</function> creates a
122 new credentials object and fills it with information about the
123 process <parameter>pid</parameter>. The pointer to this object
124 will be stored in the <parameter>ret</parameter> pointer. Note that
125 credential objects may also be created and retrieved via
126 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
127 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
129 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
131 <para>The information that will be stored is determined by
132 <parameter>creds_mask</parameter>. It may contain a subset of ORed
133 constants <constant>SD_BUS_CREDS_PID</constant>,
134 <constant>SD_BUS_CREDS_PPID</constant>,
135 <constant>SD_BUS_CREDS_TID</constant>,
136 <constant>SD_BUS_CREDS_UID</constant>,
137 <constant>SD_BUS_CREDS_EUID</constant>,
138 <constant>SD_BUS_CREDS_SUID</constant>,
139 <constant>SD_BUS_CREDS_FSUID</constant>,
140 <constant>SD_BUS_CREDS_GID</constant>,
141 <constant>SD_BUS_CREDS_EGID</constant>,
142 <constant>SD_BUS_CREDS_SGID</constant>,
143 <constant>SD_BUS_CREDS_FSGID</constant>,
144 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
145 <constant>SD_BUS_CREDS_COMM</constant>,
146 <constant>SD_BUS_CREDS_TID_COMM</constant>,
147 <constant>SD_BUS_CREDS_EXE</constant>,
148 <constant>SD_BUS_CREDS_CMDLINE</constant>,
149 <constant>SD_BUS_CREDS_CGROUP</constant>,
150 <constant>SD_BUS_CREDS_UNIT</constant>,
151 <constant>SD_BUS_CREDS_SLICE</constant>,
152 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
153 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
154 <constant>SD_BUS_CREDS_SESSION</constant>,
155 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
156 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
157 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
158 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
159 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
160 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
161 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
162 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
163 <constant>SD_BUS_CREDS_TTY</constant>,
164 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
165 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
166 <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
167 value <constant>_SD_BUS_CREDS_ALL</constant> to request all
168 supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
169 constant may not be ORed into the mask for invocations of
170 <function>sd_bus_creds_new_from_pid()</function>.</para>
172 <para>Fields can be retrieved from the credentials object using
173 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
174 and other functions which correspond directly to the constants
177 <para>A mask of fields which were actually successfully retrieved
178 can be retrieved with
179 <function>sd_bus_creds_get_mask()</function>. If the credentials
180 object was created with
181 <function>sd_bus_creds_new_from_pid()</function>, this will be a
182 subset of fields requested in <parameter>creds_mask</parameter>.
185 <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
186 function <function>sd_bus_creds_get_augmented_mask()</function>
187 returns a bitmask of field constants. The mask indicates which
188 credential fields have been retrieved in a non-atomic fashion. For
189 credential objects created via
190 <function>sd_bus_creds_new_from_pid()</function>, this mask will be
191 identical to the mask returned by
192 <function>sd_bus_creds_get_mask()</function>. However, for
193 credential objects retrieved via
194 <function>sd_bus_get_name_creds()</function>, this mask will be set
195 for the credential fields that could not be determined atomically
196 at peer connection time, and which were later added by reading
197 augmenting credential data from
198 <filename>/proc</filename>. Similarly, for credential objects
199 retrieved via <function>sd_bus_get_owner_creds()</function>, the
200 mask is set for the fields that could not be determined atomically
201 at bus creation time, but have been augmented. Similarly, for
202 credential objects retrieved via
203 <function>sd_bus_message_get_creds()</function>, the mask is set
204 for the fields that could not be determined atomically at message
205 sending time, but have been augmented. The mask returned by
206 <function>sd_bus_creds_get_augmented_mask()</function> is always a
207 subset of (or identical to) the mask returned by
208 <function>sd_bus_creds_get_mask()</function> for the same
209 object. The latter call hence returns all credential fields
210 available in the credential object, the former then marks the
211 subset of those that have been augmented. Note that augmented
212 fields are unsuitable for authorization decisions, as they may be
213 retrieved at different times, thus being subject to races. Hence,
214 augmented fields should be used exclusively for informational
218 <para><function>sd_bus_creds_ref()</function> creates a new
219 reference to the credentials object <parameter>c</parameter>. This
220 object will not be destroyed until
221 <function>sd_bus_creds_unref()</function> has been called as many
222 times plus once more. Once the reference count has dropped to zero,
223 <parameter>c</parameter> cannot be used anymore, so further
224 calls to <function>sd_bus_creds_ref(c)</function> or
225 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
227 <para><function>sd_bus_creds_unref()</function> destroys a reference
228 to <parameter>c</parameter>.</para>
230 <para><function>sd_bus_creds_unrefp()</function> is similar to
231 <function>sd_bus_creds_unref()</function> but takes a pointer to a
232 pointer to an <type>sd_bus_creds</type> object. This call is useful in
233 conjunction with GCC's and LLVM's <ulink
234 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
235 Variable Attribute</ulink>. Note that this function is defined as
236 inline function.</para>
238 <para><function>sd_bus_creds_ref()</function>,
239 <function>sd_bus_creds_unref()</function> and
240 <function>sd_bus_creds_unrefp()</function> execute no operation if
241 the passed in bus credentials object is
242 <constant>NULL</constant>.</para>
247 <title>Return Value</title>
249 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
250 returns 0 or a positive integer. On failure, it returns a negative
251 errno-style error code.</para>
253 <para><function>sd_bus_creds_get_mask()</function> returns the
254 mask of successfully acquired fields.</para>
256 <para><function>sd_bus_creds_get_augmented_mask()</function>
257 returns the mask of fields that have been augmented from data in
258 <filename>/proc</filename>, and are thus not suitable for
259 authorization decisions.</para>
261 <para><function>sd_bus_creds_ref()</function> always returns the
264 <para><function>sd_bus_creds_unref()</function> always returns
265 <constant>NULL</constant>.</para>
269 <title>Reference ownership</title>
271 <para>Function <function>sd_bus_creds_new_from_pid()</function>
272 creates a new object and the caller owns the sole reference. When
273 not needed anymore, this reference should be destroyed with
274 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
279 <title>Errors</title>
281 <para>Returned errors may indicate the following problems:</para>
286 <term><constant>-ESRCH</constant></term>
288 <listitem><para>Specified <parameter>pid</parameter> could not
289 be found.</para></listitem>
293 <term><constant>-EINVAL</constant></term>
295 <listitem><para>Specified parameter is invalid
296 (<constant>NULL</constant> in case of output
297 parameters).</para></listitem>
301 <term><constant>-ENOMEM</constant></term>
303 <listitem><para>Memory allocation failed.</para></listitem>
307 <term><constant>-EOPNOTSUPP</constant></term>
309 <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
314 <xi:include href="libelogind-pkgconfig.xml" />
317 <title>See Also</title>
320 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
322 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
323 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
324 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
325 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>