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 <refentrytitle>sd_bus_creds_new_from_pid
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_bus_creds_new_from_pid
</refname>
23 <refname>sd_bus_creds_get_mask
</refname>
24 <refname>sd_bus_creds_get_augmented_mask
</refname>
25 <refname>sd_bus_creds_ref
</refname>
26 <refname>sd_bus_creds_unref
</refname>
27 <refname>sd_bus_creds_unrefp
</refname>
29 <refpurpose>Retrieve credentials object for the specified PID
</refpurpose>
34 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
37 <funcdef>int
<function>sd_bus_creds_new_from_pid
</function></funcdef>
38 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
39 <paramdef>uint64_t
<parameter>creds_mask
</parameter></paramdef>
40 <paramdef>sd_bus_creds **
<parameter>ret
</parameter></paramdef>
44 <funcdef>uint64_t
<function>sd_bus_creds_get_mask
</function></funcdef>
45 <paramdef>sd_bus_creds *
<parameter>c
</parameter></paramdef>
49 <funcdef>uint64_t
<function>sd_bus_creds_get_augmented_mask
</function></funcdef>
50 <paramdef>sd_bus_creds *
<parameter>c
</parameter></paramdef>
54 <funcdef>sd_bus_creds *
<function>sd_bus_creds_ref
</function></funcdef>
55 <paramdef>sd_bus_creds *
<parameter>c
</parameter></paramdef>
59 <funcdef>sd_bus_creds *
<function>sd_bus_creds_unref
</function></funcdef>
60 <paramdef>sd_bus_creds *
<parameter>c
</parameter></paramdef>
64 <funcdef>void
<function>sd_bus_creds_unrefp
</function></funcdef>
65 <paramdef>sd_bus_creds **
<parameter>c
</parameter></paramdef>
70 <constant>SD_BUS_CREDS_PID
</constant>,
71 <constant>SD_BUS_CREDS_PPID
</constant>,
72 <constant>SD_BUS_CREDS_TID
</constant>,
73 <constant>SD_BUS_CREDS_UID
</constant>,
74 <constant>SD_BUS_CREDS_EUID
</constant>,
75 <constant>SD_BUS_CREDS_SUID
</constant>,
76 <constant>SD_BUS_CREDS_FSUID
</constant>,
77 <constant>SD_BUS_CREDS_GID
</constant>,
78 <constant>SD_BUS_CREDS_EGID
</constant>,
79 <constant>SD_BUS_CREDS_SGID
</constant>,
80 <constant>SD_BUS_CREDS_FSGID
</constant>,
81 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS
</constant>,
82 <constant>SD_BUS_CREDS_COMM
</constant>,
83 <constant>SD_BUS_CREDS_TID_COMM
</constant>,
84 <constant>SD_BUS_CREDS_EXE
</constant>,
85 <constant>SD_BUS_CREDS_CMDLINE
</constant>,
86 <constant>SD_BUS_CREDS_CGROUP
</constant>,
87 <constant>SD_BUS_CREDS_UNIT
</constant>,
88 <constant>SD_BUS_CREDS_SLICE
</constant>,
89 <constant>SD_BUS_CREDS_USER_UNIT
</constant>,
90 <constant>SD_BUS_CREDS_USER_SLICE
</constant>,
91 <constant>SD_BUS_CREDS_SESSION
</constant>,
92 <constant>SD_BUS_CREDS_OWNER_UID
</constant>,
93 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS
</constant>,
94 <constant>SD_BUS_CREDS_PERMITTED_CAPS
</constant>,
95 <constant>SD_BUS_CREDS_INHERITABLE_CAPS
</constant>,
96 <constant>SD_BUS_CREDS_BOUNDING_CAPS
</constant>,
97 <constant>SD_BUS_CREDS_SELINUX_CONTEXT
</constant>,
98 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID
</constant>,
99 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID
</constant>,
100 <constant>SD_BUS_CREDS_TTY
</constant>,
101 <constant>SD_BUS_CREDS_UNIQUE_NAME
</constant>,
102 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES
</constant>,
103 <constant>SD_BUS_CREDS_DESCRIPTION
</constant>,
104 <constant>SD_BUS_CREDS_AUGMENT
</constant>,
105 <constant>_SD_BUS_CREDS_ALL
</constant>
110 <title>Description
</title>
112 <para><function>sd_bus_creds_new_from_pid()
</function> creates a
113 new credentials object and fills it with information about the
114 process
<parameter>pid
</parameter>. The pointer to this object
115 will be stored in the
<parameter>ret
</parameter> pointer. Note that
116 credential objects may also be created and retrieved via
117 <citerefentry><refentrytitle>sd_bus_get_name_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
118 <citerefentry><refentrytitle>sd_bus_get_owner_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
120 <citerefentry><refentrytitle>sd_bus_message_get_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
122 <para>The information that will be stored is determined by
123 <parameter>creds_mask
</parameter>. It may contain a subset of ORed
124 constants
<constant>SD_BUS_CREDS_PID
</constant>,
125 <constant>SD_BUS_CREDS_PPID
</constant>,
126 <constant>SD_BUS_CREDS_TID
</constant>,
127 <constant>SD_BUS_CREDS_UID
</constant>,
128 <constant>SD_BUS_CREDS_EUID
</constant>,
129 <constant>SD_BUS_CREDS_SUID
</constant>,
130 <constant>SD_BUS_CREDS_FSUID
</constant>,
131 <constant>SD_BUS_CREDS_GID
</constant>,
132 <constant>SD_BUS_CREDS_EGID
</constant>,
133 <constant>SD_BUS_CREDS_SGID
</constant>,
134 <constant>SD_BUS_CREDS_FSGID
</constant>,
135 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS
</constant>,
136 <constant>SD_BUS_CREDS_COMM
</constant>,
137 <constant>SD_BUS_CREDS_TID_COMM
</constant>,
138 <constant>SD_BUS_CREDS_EXE
</constant>,
139 <constant>SD_BUS_CREDS_CMDLINE
</constant>,
140 <constant>SD_BUS_CREDS_CGROUP
</constant>,
141 <constant>SD_BUS_CREDS_UNIT
</constant>,
142 <constant>SD_BUS_CREDS_SLICE
</constant>,
143 <constant>SD_BUS_CREDS_USER_UNIT
</constant>,
144 <constant>SD_BUS_CREDS_USER_SLICE
</constant>,
145 <constant>SD_BUS_CREDS_SESSION
</constant>,
146 <constant>SD_BUS_CREDS_OWNER_UID
</constant>,
147 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS
</constant>,
148 <constant>SD_BUS_CREDS_PERMITTED_CAPS
</constant>,
149 <constant>SD_BUS_CREDS_INHERITABLE_CAPS
</constant>,
150 <constant>SD_BUS_CREDS_BOUNDING_CAPS
</constant>,
151 <constant>SD_BUS_CREDS_SELINUX_CONTEXT
</constant>,
152 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID
</constant>,
153 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID
</constant>,
154 <constant>SD_BUS_CREDS_TTY
</constant>,
155 <constant>SD_BUS_CREDS_UNIQUE_NAME
</constant>,
156 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES
</constant>, and
157 <constant>SD_BUS_CREDS_DESCRIPTION
</constant>. Use the special
158 value
<constant>_SD_BUS_CREDS_ALL
</constant> to request all
159 supported fields. The
<constant>SD_BUS_CREDS_AUGMENT
</constant>
160 constant may not be ORed into the mask for invocations of
161 <function>sd_bus_creds_new_from_pid()
</function>.
</para>
163 <para>Fields can be retrieved from the credentials object using
164 <citerefentry><refentrytitle>sd_bus_creds_get_pid
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
165 and other functions which correspond directly to the constants
168 <para>A mask of fields which were actually successfully retrieved
169 can be retrieved with
170 <function>sd_bus_creds_get_mask()
</function>. If the credentials
171 object was created with
172 <function>sd_bus_creds_new_from_pid()
</function>, this will be a
173 subset of fields requested in
<parameter>creds_mask
</parameter>.
176 <para>Similar to
<function>sd_bus_creds_get_mask()
</function>, the
177 function
<function>sd_bus_creds_get_augmented_mask()
</function>
178 returns a bitmask of field constants. The mask indicates which
179 credential fields have been retrieved in a non-atomic fashion. For
180 credential objects created via
181 <function>sd_bus_creds_new_from_pid()
</function>, this mask will be
182 identical to the mask returned by
183 <function>sd_bus_creds_get_mask()
</function>. However, for
184 credential objects retrieved via
185 <function>sd_bus_get_name_creds()
</function>, this mask will be set
186 for the credential fields that could not be determined atomically
187 at peer connection time, and which were later added by reading
188 augmenting credential data from
189 <filename>/proc
</filename>. Similarly, for credential objects
190 retrieved via
<function>sd_bus_get_owner_creds()
</function>, the
191 mask is set for the fields that could not be determined atomically
192 at bus creation time, but have been augmented. Similarly, for
193 credential objects retrieved via
194 <function>sd_bus_message_get_creds()
</function>, the mask is set
195 for the fields that could not be determined atomically at message
196 sending time, but have been augmented. The mask returned by
197 <function>sd_bus_creds_get_augmented_mask()
</function> is always a
198 subset of (or identical to) the mask returned by
199 <function>sd_bus_creds_get_mask()
</function> for the same
200 object. The latter call hence returns all credential fields
201 available in the credential object, the former then marks the
202 subset of those that have been augmented. Note that augmented
203 fields are unsuitable for authorization decisions, as they may be
204 retrieved at different times, thus being subject to races. Hence,
205 augmented fields should be used exclusively for informational
209 <para><function>sd_bus_creds_ref()
</function> creates a new
210 reference to the credentials object
<parameter>c
</parameter>. This
211 object will not be destroyed until
212 <function>sd_bus_creds_unref()
</function> has been called as many
213 times plus once more. Once the reference count has dropped to zero,
214 <parameter>c
</parameter> cannot be used anymore, so further
215 calls to
<function>sd_bus_creds_ref(c)
</function> or
216 <function>sd_bus_creds_unref(c)
</function> are illegal.
</para>
218 <para><function>sd_bus_creds_unref()
</function> destroys a reference
219 to
<parameter>c
</parameter>.
</para>
221 <para><function>sd_bus_creds_unrefp()
</function> is similar to
222 <function>sd_bus_creds_unref()
</function> but takes a pointer to a
223 pointer to an
<type>sd_bus_creds
</type> object. This call is useful in
224 conjunction with GCC's and LLVM's
<ulink
225 url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
226 Variable Attribute
</ulink>. Note that this function is defined as
227 inline function.
</para>
229 <para><function>sd_bus_creds_ref()
</function>,
230 <function>sd_bus_creds_unref()
</function> and
231 <function>sd_bus_creds_unrefp()
</function> execute no operation if
232 the passed in bus credentials object is
233 <constant>NULL
</constant>.
</para>
238 <title>Return Value
</title>
240 <para>On success,
<function>sd_bus_creds_new_from_pid()
</function>
241 returns
0 or a positive integer. On failure, it returns a negative
242 errno-style error code.
</para>
244 <para><function>sd_bus_creds_get_mask()
</function> returns the
245 mask of successfully acquired fields.
</para>
247 <para><function>sd_bus_creds_get_augmented_mask()
</function>
248 returns the mask of fields that have been augmented from data in
249 <filename>/proc
</filename>, and are thus not suitable for
250 authorization decisions.
</para>
252 <para><function>sd_bus_creds_ref()
</function> always returns the
255 <para><function>sd_bus_creds_unref()
</function> always returns
256 <constant>NULL
</constant>.
</para>
260 <title>Reference ownership
</title>
262 <para>Function
<function>sd_bus_creds_new_from_pid()
</function>
263 creates a new object and the caller owns the sole reference. When
264 not needed anymore, this reference should be destroyed with
265 <citerefentry><refentrytitle>sd_bus_creds_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
270 <title>Errors
</title>
272 <para>Returned errors may indicate the following problems:
</para>
277 <term><constant>-ESRCH
</constant></term>
279 <listitem><para>Specified
<parameter>pid
</parameter> could not
280 be found.
</para></listitem>
284 <term><constant>-EINVAL
</constant></term>
286 <listitem><para>Specified parameter is invalid
287 (
<constant>NULL
</constant> in case of output
288 parameters).
</para></listitem>
292 <term><constant>-ENOMEM
</constant></term>
294 <listitem><para>Memory allocation failed.
</para></listitem>
298 <term><constant>-EOPNOTSUPP
</constant></term>
300 <listitem><para>One of the requested fields is unknown to the local system.
</para></listitem>
305 <xi:include href=
"libsystemd-pkgconfig.xml" />
308 <title>See Also
</title>
311 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
313 <citerefentry><refentrytitle>sd_bus_creds_get_pid
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>sd_bus_get_name_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
315 <citerefentry><refentrytitle>sd_bus_get_owner_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
316 <citerefentry><refentrytitle>sd_bus_message_get_creds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>