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 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
13 <refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude">
16 <title>sd_bus_creds_new_from_pid</title>
17 <productname>systemd</productname>
21 <contrib>A monkey with a typewriter</contrib>
22 <firstname>Zbigniew</firstname>
23 <surname>Jędrzejewski-Szmek</surname>
24 <email>zbyszek@in.waw.pl</email>
30 <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_bus_creds_new_from_pid</refname>
36 <refname>sd_bus_creds_get_mask</refname>
37 <refname>sd_bus_creds_get_augmented_mask</refname>
38 <refname>sd_bus_creds_ref</refname>
39 <refname>sd_bus_creds_unref</refname>
40 <refname>sd_bus_creds_unrefp</refname>
42 <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
47 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
50 <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
51 <paramdef>pid_t <parameter>pid</parameter></paramdef>
52 <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
53 <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
57 <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
58 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
62 <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
63 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
67 <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
68 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
72 <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
73 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
77 <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
78 <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
83 <constant>SD_BUS_CREDS_PID</constant>,
84 <constant>SD_BUS_CREDS_PPID</constant>,
85 <constant>SD_BUS_CREDS_TID</constant>,
86 <constant>SD_BUS_CREDS_UID</constant>,
87 <constant>SD_BUS_CREDS_EUID</constant>,
88 <constant>SD_BUS_CREDS_SUID</constant>,
89 <constant>SD_BUS_CREDS_FSUID</constant>,
90 <constant>SD_BUS_CREDS_GID</constant>,
91 <constant>SD_BUS_CREDS_EGID</constant>,
92 <constant>SD_BUS_CREDS_SGID</constant>,
93 <constant>SD_BUS_CREDS_FSGID</constant>,
94 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
95 <constant>SD_BUS_CREDS_COMM</constant>,
96 <constant>SD_BUS_CREDS_TID_COMM</constant>,
97 <constant>SD_BUS_CREDS_EXE</constant>,
98 <constant>SD_BUS_CREDS_CMDLINE</constant>,
99 <constant>SD_BUS_CREDS_CGROUP</constant>,
100 <constant>SD_BUS_CREDS_UNIT</constant>,
101 <constant>SD_BUS_CREDS_SLICE</constant>,
102 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
103 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
104 <constant>SD_BUS_CREDS_SESSION</constant>,
105 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
106 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
107 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
108 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
109 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
110 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
111 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
112 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
113 <constant>SD_BUS_CREDS_TTY</constant>,
114 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
115 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
116 <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
117 <constant>SD_BUS_CREDS_AUGMENT</constant>,
118 <constant>_SD_BUS_CREDS_ALL</constant>
123 <title>Description</title>
125 <para><function>sd_bus_creds_new_from_pid()</function> creates a
126 new credentials object and fills it with information about the
127 process <parameter>pid</parameter>. The pointer to this object
128 will be stored in the <parameter>ret</parameter> pointer. Note that
129 credential objects may also be created and retrieved via
130 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
131 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
133 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
135 <para>The information that will be stored is determined by
136 <parameter>creds_mask</parameter>. It may contain a subset of ORed
137 constants <constant>SD_BUS_CREDS_PID</constant>,
138 <constant>SD_BUS_CREDS_PPID</constant>,
139 <constant>SD_BUS_CREDS_TID</constant>,
140 <constant>SD_BUS_CREDS_UID</constant>,
141 <constant>SD_BUS_CREDS_EUID</constant>,
142 <constant>SD_BUS_CREDS_SUID</constant>,
143 <constant>SD_BUS_CREDS_FSUID</constant>,
144 <constant>SD_BUS_CREDS_GID</constant>,
145 <constant>SD_BUS_CREDS_EGID</constant>,
146 <constant>SD_BUS_CREDS_SGID</constant>,
147 <constant>SD_BUS_CREDS_FSGID</constant>,
148 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
149 <constant>SD_BUS_CREDS_COMM</constant>,
150 <constant>SD_BUS_CREDS_TID_COMM</constant>,
151 <constant>SD_BUS_CREDS_EXE</constant>,
152 <constant>SD_BUS_CREDS_CMDLINE</constant>,
153 <constant>SD_BUS_CREDS_CGROUP</constant>,
154 <constant>SD_BUS_CREDS_UNIT</constant>,
155 <constant>SD_BUS_CREDS_SLICE</constant>,
156 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
157 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
158 <constant>SD_BUS_CREDS_SESSION</constant>,
159 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
160 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
161 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
162 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
163 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
164 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
165 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
166 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
167 <constant>SD_BUS_CREDS_TTY</constant>,
168 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
169 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
170 <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
171 value <constant>_SD_BUS_CREDS_ALL</constant> to request all
172 supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
173 constant may not be ORed into the mask for invocations of
174 <function>sd_bus_creds_new_from_pid()</function>.</para>
176 <para>Fields can be retrieved from the credentials object using
177 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
178 and other functions which correspond directly to the constants
181 <para>A mask of fields which were actually successfully retrieved
182 can be retrieved with
183 <function>sd_bus_creds_get_mask()</function>. If the credentials
184 object was created with
185 <function>sd_bus_creds_new_from_pid()</function>, this will be a
186 subset of fields requested in <parameter>creds_mask</parameter>.
189 <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
190 function <function>sd_bus_creds_get_augmented_mask()</function>
191 returns a bitmask of field constants. The mask indicates which
192 credential fields have been retrieved in a non-atomic fashion. For
193 credential objects created via
194 <function>sd_bus_creds_new_from_pid()</function>, this mask will be
195 identical to the mask returned by
196 <function>sd_bus_creds_get_mask()</function>. However, for
197 credential objects retrieved via
198 <function>sd_bus_get_name_creds()</function>, this mask will be set
199 for the credential fields that could not be determined atomically
200 at peer connection time, and which were later added by reading
201 augmenting credential data from
202 <filename>/proc</filename>. Similarly, for credential objects
203 retrieved via <function>sd_bus_get_owner_creds()</function>, the
204 mask is set for the fields that could not be determined atomically
205 at bus creation time, but have been augmented. Similarly, for
206 credential objects retrieved via
207 <function>sd_bus_message_get_creds()</function>, the mask is set
208 for the fields that could not be determined atomically at message
209 sending time, but have been augmented. The mask returned by
210 <function>sd_bus_creds_get_augmented_mask()</function> is always a
211 subset of (or identical to) the mask returned by
212 <function>sd_bus_creds_get_mask()</function> for the same
213 object. The latter call hence returns all credential fields
214 available in the credential object, the former then marks the
215 subset of those that have been augmented. Note that augmented
216 fields are unsuitable for authorization decisions, as they may be
217 retrieved at different times, thus being subject to races. Hence,
218 augmented fields should be used exclusively for informational
222 <para><function>sd_bus_creds_ref()</function> creates a new
223 reference to the credentials object <parameter>c</parameter>. This
224 object will not be destroyed until
225 <function>sd_bus_creds_unref()</function> has been called as many
226 times plus once more. Once the reference count has dropped to zero,
227 <parameter>c</parameter> cannot be used anymore, so further
228 calls to <function>sd_bus_creds_ref(c)</function> or
229 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
231 <para><function>sd_bus_creds_unref()</function> destroys a reference
232 to <parameter>c</parameter>.</para>
234 <para><function>sd_bus_creds_unrefp()</function> is similar to
235 <function>sd_bus_creds_unref()</function> but takes a pointer to a
236 pointer to an <type>sd_bus_creds</type> object. This call is useful in
237 conjunction with GCC's and LLVM's <ulink
238 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
239 Variable Attribute</ulink>. Note that this function is defined as
240 inline function.</para>
242 <para><function>sd_bus_creds_ref()</function>,
243 <function>sd_bus_creds_unref()</function> and
244 <function>sd_bus_creds_unrefp()</function> execute no operation if
245 the passed in bus credentials object is
246 <constant>NULL</constant>.</para>
251 <title>Return Value</title>
253 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
254 returns 0 or a positive integer. On failure, it returns a negative
255 errno-style error code.</para>
257 <para><function>sd_bus_creds_get_mask()</function> returns the
258 mask of successfully acquired fields.</para>
260 <para><function>sd_bus_creds_get_augmented_mask()</function>
261 returns the mask of fields that have been augmented from data in
262 <filename>/proc</filename>, and are thus not suitable for
263 authorization decisions.</para>
265 <para><function>sd_bus_creds_ref()</function> always returns the
268 <para><function>sd_bus_creds_unref()</function> always returns
269 <constant>NULL</constant>.</para>
273 <title>Reference ownership</title>
275 <para>Function <function>sd_bus_creds_new_from_pid()</function>
276 creates a new object and the caller owns the sole reference. When
277 not needed anymore, this reference should be destroyed with
278 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
283 <title>Errors</title>
285 <para>Returned errors may indicate the following problems:</para>
290 <term><constant>-ESRCH</constant></term>
292 <listitem><para>Specified <parameter>pid</parameter> could not
293 be found.</para></listitem>
297 <term><constant>-EINVAL</constant></term>
299 <listitem><para>Specified parameter is invalid
300 (<constant>NULL</constant> in case of output
301 parameters).</para></listitem>
305 <term><constant>-ENOMEM</constant></term>
307 <listitem><para>Memory allocation failed.</para></listitem>
311 <term><constant>-EOPNOTSUPP</constant></term>
313 <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
318 <xi:include href="libelogind-pkgconfig.xml" />
321 <title>See Also</title>
324 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
325 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
326 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
327 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
328 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
329 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>