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+
8 Copyright © 2014 Zbigniew Jędrzejewski-Szmek
11 <refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude">
14 <title>sd_bus_creds_new_from_pid</title>
15 <productname>systemd</productname>
19 <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_creds_new_from_pid</refname>
25 <refname>sd_bus_creds_get_mask</refname>
26 <refname>sd_bus_creds_get_augmented_mask</refname>
27 <refname>sd_bus_creds_ref</refname>
28 <refname>sd_bus_creds_unref</refname>
29 <refname>sd_bus_creds_unrefp</refname>
31 <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
36 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
39 <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
40 <paramdef>pid_t <parameter>pid</parameter></paramdef>
41 <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
42 <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
46 <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
47 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
51 <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
52 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
56 <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
57 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
61 <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
62 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
66 <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
67 <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
72 <constant>SD_BUS_CREDS_PID</constant>,
73 <constant>SD_BUS_CREDS_PPID</constant>,
74 <constant>SD_BUS_CREDS_TID</constant>,
75 <constant>SD_BUS_CREDS_UID</constant>,
76 <constant>SD_BUS_CREDS_EUID</constant>,
77 <constant>SD_BUS_CREDS_SUID</constant>,
78 <constant>SD_BUS_CREDS_FSUID</constant>,
79 <constant>SD_BUS_CREDS_GID</constant>,
80 <constant>SD_BUS_CREDS_EGID</constant>,
81 <constant>SD_BUS_CREDS_SGID</constant>,
82 <constant>SD_BUS_CREDS_FSGID</constant>,
83 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
84 <constant>SD_BUS_CREDS_COMM</constant>,
85 <constant>SD_BUS_CREDS_TID_COMM</constant>,
86 <constant>SD_BUS_CREDS_EXE</constant>,
87 <constant>SD_BUS_CREDS_CMDLINE</constant>,
88 <constant>SD_BUS_CREDS_CGROUP</constant>,
89 <constant>SD_BUS_CREDS_UNIT</constant>,
90 <constant>SD_BUS_CREDS_SLICE</constant>,
91 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
92 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
93 <constant>SD_BUS_CREDS_SESSION</constant>,
94 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
95 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
96 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
97 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
98 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
99 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
100 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
101 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
102 <constant>SD_BUS_CREDS_TTY</constant>,
103 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
104 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
105 <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
106 <constant>SD_BUS_CREDS_AUGMENT</constant>,
107 <constant>_SD_BUS_CREDS_ALL</constant>
112 <title>Description</title>
114 <para><function>sd_bus_creds_new_from_pid()</function> creates a
115 new credentials object and fills it with information about the
116 process <parameter>pid</parameter>. The pointer to this object
117 will be stored in the <parameter>ret</parameter> pointer. Note that
118 credential objects may also be created and retrieved via
119 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
120 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
122 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
124 <para>The information that will be stored is determined by
125 <parameter>creds_mask</parameter>. It may contain a subset of ORed
126 constants <constant>SD_BUS_CREDS_PID</constant>,
127 <constant>SD_BUS_CREDS_PPID</constant>,
128 <constant>SD_BUS_CREDS_TID</constant>,
129 <constant>SD_BUS_CREDS_UID</constant>,
130 <constant>SD_BUS_CREDS_EUID</constant>,
131 <constant>SD_BUS_CREDS_SUID</constant>,
132 <constant>SD_BUS_CREDS_FSUID</constant>,
133 <constant>SD_BUS_CREDS_GID</constant>,
134 <constant>SD_BUS_CREDS_EGID</constant>,
135 <constant>SD_BUS_CREDS_SGID</constant>,
136 <constant>SD_BUS_CREDS_FSGID</constant>,
137 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
138 <constant>SD_BUS_CREDS_COMM</constant>,
139 <constant>SD_BUS_CREDS_TID_COMM</constant>,
140 <constant>SD_BUS_CREDS_EXE</constant>,
141 <constant>SD_BUS_CREDS_CMDLINE</constant>,
142 <constant>SD_BUS_CREDS_CGROUP</constant>,
143 <constant>SD_BUS_CREDS_UNIT</constant>,
144 <constant>SD_BUS_CREDS_SLICE</constant>,
145 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
146 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
147 <constant>SD_BUS_CREDS_SESSION</constant>,
148 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
149 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
150 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
151 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
152 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
153 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
154 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
155 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
156 <constant>SD_BUS_CREDS_TTY</constant>,
157 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
158 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
159 <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
160 value <constant>_SD_BUS_CREDS_ALL</constant> to request all
161 supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
162 constant may not be ORed into the mask for invocations of
163 <function>sd_bus_creds_new_from_pid()</function>.</para>
165 <para>Fields can be retrieved from the credentials object using
166 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
167 and other functions which correspond directly to the constants
170 <para>A mask of fields which were actually successfully retrieved
171 can be retrieved with
172 <function>sd_bus_creds_get_mask()</function>. If the credentials
173 object was created with
174 <function>sd_bus_creds_new_from_pid()</function>, this will be a
175 subset of fields requested in <parameter>creds_mask</parameter>.
178 <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
179 function <function>sd_bus_creds_get_augmented_mask()</function>
180 returns a bitmask of field constants. The mask indicates which
181 credential fields have been retrieved in a non-atomic fashion. For
182 credential objects created via
183 <function>sd_bus_creds_new_from_pid()</function>, this mask will be
184 identical to the mask returned by
185 <function>sd_bus_creds_get_mask()</function>. However, for
186 credential objects retrieved via
187 <function>sd_bus_get_name_creds()</function>, this mask will be set
188 for the credential fields that could not be determined atomically
189 at peer connection time, and which were later added by reading
190 augmenting credential data from
191 <filename>/proc</filename>. Similarly, for credential objects
192 retrieved via <function>sd_bus_get_owner_creds()</function>, the
193 mask is set for the fields that could not be determined atomically
194 at bus creation time, but have been augmented. Similarly, for
195 credential objects retrieved via
196 <function>sd_bus_message_get_creds()</function>, the mask is set
197 for the fields that could not be determined atomically at message
198 sending time, but have been augmented. The mask returned by
199 <function>sd_bus_creds_get_augmented_mask()</function> is always a
200 subset of (or identical to) the mask returned by
201 <function>sd_bus_creds_get_mask()</function> for the same
202 object. The latter call hence returns all credential fields
203 available in the credential object, the former then marks the
204 subset of those that have been augmented. Note that augmented
205 fields are unsuitable for authorization decisions, as they may be
206 retrieved at different times, thus being subject to races. Hence,
207 augmented fields should be used exclusively for informational
211 <para><function>sd_bus_creds_ref()</function> creates a new
212 reference to the credentials object <parameter>c</parameter>. This
213 object will not be destroyed until
214 <function>sd_bus_creds_unref()</function> has been called as many
215 times plus once more. Once the reference count has dropped to zero,
216 <parameter>c</parameter> cannot be used anymore, so further
217 calls to <function>sd_bus_creds_ref(c)</function> or
218 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
220 <para><function>sd_bus_creds_unref()</function> destroys a reference
221 to <parameter>c</parameter>.</para>
223 <para><function>sd_bus_creds_unrefp()</function> is similar to
224 <function>sd_bus_creds_unref()</function> but takes a pointer to a
225 pointer to an <type>sd_bus_creds</type> object. This call is useful in
226 conjunction with GCC's and LLVM's <ulink
227 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
228 Variable Attribute</ulink>. Note that this function is defined as
229 inline function.</para>
231 <para><function>sd_bus_creds_ref()</function>,
232 <function>sd_bus_creds_unref()</function> and
233 <function>sd_bus_creds_unrefp()</function> execute no operation if
234 the passed in bus credentials object is
235 <constant>NULL</constant>.</para>
240 <title>Return Value</title>
242 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
243 returns 0 or a positive integer. On failure, it returns a negative
244 errno-style error code.</para>
246 <para><function>sd_bus_creds_get_mask()</function> returns the
247 mask of successfully acquired fields.</para>
249 <para><function>sd_bus_creds_get_augmented_mask()</function>
250 returns the mask of fields that have been augmented from data in
251 <filename>/proc</filename>, and are thus not suitable for
252 authorization decisions.</para>
254 <para><function>sd_bus_creds_ref()</function> always returns the
257 <para><function>sd_bus_creds_unref()</function> always returns
258 <constant>NULL</constant>.</para>
262 <title>Reference ownership</title>
264 <para>Function <function>sd_bus_creds_new_from_pid()</function>
265 creates a new object and the caller owns the sole reference. When
266 not needed anymore, this reference should be destroyed with
267 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
272 <title>Errors</title>
274 <para>Returned errors may indicate the following problems:</para>
279 <term><constant>-ESRCH</constant></term>
281 <listitem><para>Specified <parameter>pid</parameter> could not
282 be found.</para></listitem>
286 <term><constant>-EINVAL</constant></term>
288 <listitem><para>Specified parameter is invalid
289 (<constant>NULL</constant> in case of output
290 parameters).</para></listitem>
294 <term><constant>-ENOMEM</constant></term>
296 <listitem><para>Memory allocation failed.</para></listitem>
300 <term><constant>-EOPNOTSUPP</constant></term>
302 <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
307 <xi:include href="libelogind-pkgconfig.xml" />
310 <title>See Also</title>
313 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
315 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
316 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
317 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
318 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>