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 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_bus_creds_new_from_pid">
27 <title>sd_bus_creds_new_from_pid</title>
28 <productname>systemd</productname>
32 <contrib>A monkey with a typewriter</contrib>
33 <firstname>Zbigniew</firstname>
34 <surname>Jędrzejewski-Szmek</surname>
35 <email>zbyszek@in.waw.pl</email>
41 <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_bus_creds_new_from_pid</refname>
47 <refname>sd_bus_creds_get_mask</refname>
48 <refname>sd_bus_creds_get_augmented_mask</refname>
49 <refname>sd_bus_creds_ref</refname>
50 <refname>sd_bus_creds_unref</refname>
51 <refname>sd_bus_creds_unrefp</refname>
53 <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
58 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
61 <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
62 <paramdef>pid_t <parameter>pid</parameter></paramdef>
63 <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
64 <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
68 <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
69 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
73 <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
74 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
78 <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
79 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
83 <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
84 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
88 <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
89 <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
94 <constant>SD_BUS_CREDS_PID</constant>,
95 <constant>SD_BUS_CREDS_PPID</constant>,
96 <constant>SD_BUS_CREDS_TID</constant>,
97 <constant>SD_BUS_CREDS_UID</constant>,
98 <constant>SD_BUS_CREDS_EUID</constant>,
99 <constant>SD_BUS_CREDS_SUID</constant>,
100 <constant>SD_BUS_CREDS_FSUID</constant>,
101 <constant>SD_BUS_CREDS_GID</constant>,
102 <constant>SD_BUS_CREDS_EGID</constant>,
103 <constant>SD_BUS_CREDS_SGID</constant>,
104 <constant>SD_BUS_CREDS_FSGID</constant>,
105 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
106 <constant>SD_BUS_CREDS_COMM</constant>,
107 <constant>SD_BUS_CREDS_TID_COMM</constant>,
108 <constant>SD_BUS_CREDS_EXE</constant>,
109 <constant>SD_BUS_CREDS_CMDLINE</constant>,
110 <constant>SD_BUS_CREDS_CGROUP</constant>,
111 <constant>SD_BUS_CREDS_UNIT</constant>,
112 <constant>SD_BUS_CREDS_SLICE</constant>,
113 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
114 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
115 <constant>SD_BUS_CREDS_SESSION</constant>,
116 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
117 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
118 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
119 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
120 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
121 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
122 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
123 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
124 <constant>SD_BUS_CREDS_TTY</constant>,
125 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
126 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
127 <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
128 <constant>SD_BUS_CREDS_AUGMENT</constant>,
129 <constant>_SD_BUS_CREDS_ALL</constant>
134 <title>Description</title>
136 <para><function>sd_bus_creds_new_from_pid()</function> creates a
137 new credentials object and fills it with information about the
138 process <parameter>pid</parameter>. The pointer to this object
139 will be stored in the <parameter>ret</parameter> pointer. Note that
140 credential objects may also be created and retrieved via
141 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
142 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
144 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
146 <para>The information that will be stored is determined by
147 <parameter>creds_mask</parameter>. It may contain a subset of ORed
148 constants <constant>SD_BUS_CREDS_PID</constant>,
149 <constant>SD_BUS_CREDS_PPID</constant>,
150 <constant>SD_BUS_CREDS_TID</constant>,
151 <constant>SD_BUS_CREDS_UID</constant>,
152 <constant>SD_BUS_CREDS_EUID</constant>,
153 <constant>SD_BUS_CREDS_SUID</constant>,
154 <constant>SD_BUS_CREDS_FSUID</constant>,
155 <constant>SD_BUS_CREDS_GID</constant>,
156 <constant>SD_BUS_CREDS_EGID</constant>,
157 <constant>SD_BUS_CREDS_SGID</constant>,
158 <constant>SD_BUS_CREDS_FSGID</constant>,
159 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
160 <constant>SD_BUS_CREDS_COMM</constant>,
161 <constant>SD_BUS_CREDS_TID_COMM</constant>,
162 <constant>SD_BUS_CREDS_EXE</constant>,
163 <constant>SD_BUS_CREDS_CMDLINE</constant>,
164 <constant>SD_BUS_CREDS_CGROUP</constant>,
165 <constant>SD_BUS_CREDS_UNIT</constant>,
166 <constant>SD_BUS_CREDS_SLICE</constant>,
167 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
168 <constant>SD_BUS_CREDS_USER_SLICE</constant>,
169 <constant>SD_BUS_CREDS_SESSION</constant>,
170 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
171 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
172 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
173 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
174 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
175 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
176 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
177 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
178 <constant>SD_BUS_CREDS_TTY</constant>,
179 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
180 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
181 <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
182 value <constant>_SD_BUS_CREDS_ALL</constant> to request all
183 supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
184 constant may not be ORed into the mask for invocations of
185 <function>sd_bus_creds_new_from_pid()</function>.</para>
187 <para>Fields can be retrieved from the credentials object using
188 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
189 and other functions which correspond directly to the constants
192 <para>A mask of fields which were actually successfully retrieved
193 can be retrieved with
194 <function>sd_bus_creds_get_mask()</function>. If the credentials
195 object was created with
196 <function>sd_bus_creds_new_from_pid()</function>, this will be a
197 subset of fields requested in <parameter>creds_mask</parameter>.
200 <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
201 function <function>sd_bus_creds_get_augmented_mask()</function>
202 returns a bitmask of field constants. The mask indicates which
203 credential fields have been retrieved in a non-atomic fashion. For
204 credential objects created via
205 <function>sd_bus_creds_new_from_pid()</function>, this mask will be
206 identical to the mask returned by
207 <function>sd_bus_creds_get_mask()</function>. However, for
208 credential objects retrieved via
209 <function>sd_bus_get_name_creds()</function>, this mask will be set
210 for the credential fields that could not be determined atomically
211 at peer connection time, and which were later added by reading
212 augmenting credential data from
213 <filename>/proc</filename>. Similarly, for credential objects
214 retrieved via <function>sd_bus_get_owner_creds()</function>, the
215 mask is set for the fields that could not be determined atomically
216 at bus creation time, but have been augmented. Similarly, for
217 credential objects retrieved via
218 <function>sd_bus_message_get_creds()</function>, the mask is set
219 for the fields that could not be determined atomically at message
220 sending time, but have been augmented. The mask returned by
221 <function>sd_bus_creds_get_augmented_mask()</function> is always a
222 subset of (or identical to) the mask returned by
223 <function>sd_bus_creds_get_mask()</function> for the same
224 object. The latter call hence returns all credential fields
225 available in the credential object, the former then marks the
226 subset of those that have been augmented. Note that augmented
227 fields are unsuitable for authorization decisions, as they may be
228 retrieved at different times, thus being subject to races. Hence,
229 augmented fields should be used exclusively for informational
233 <para><function>sd_bus_creds_ref()</function> creates a new
234 reference to the credentials object <parameter>c</parameter>. This
235 object will not be destroyed until
236 <function>sd_bus_creds_unref()</function> has been called as many
237 times plus once more. Once the reference count has dropped to zero,
238 <parameter>c</parameter> cannot be used anymore, so further
239 calls to <function>sd_bus_creds_ref(c)</function> or
240 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
242 <para><function>sd_bus_creds_unref()</function> destroys a reference
243 to <parameter>c</parameter>.</para>
245 <para><function>sd_bus_creds_unrefp()</function> is similar to
246 <function>sd_bus_creds_unref()</function> but takes a pointer to a
247 pointer to an <type>sd_bus_creds</type> object. This call is useful in
248 conjunction with GCC's and LLVM's <ulink
249 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
250 Variable Attribute</ulink>. Note that this function is defined as
251 inline function.</para>
253 <para><function>sd_bus_creds_ref()</function>,
254 <function>sd_bus_creds_unref()</function> and
255 <function>sd_bus_creds_unrefp()</function> execute no operation if
256 the passed in bus credentials object is
257 <constant>NULL</constant>.</para>
262 <title>Return Value</title>
264 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
265 returns 0 or a positive integer. On failure, it returns a negative
266 errno-style error code.</para>
268 <para><function>sd_bus_creds_get_mask()</function> returns the
269 mask of successfully acquired fields.</para>
271 <para><function>sd_bus_creds_get_augmented_mask()</function>
272 returns the mask of fields that have been augmented from data in
273 <filename>/proc</filename>, and are thus not suitable for
274 authorization decisions.</para>
276 <para><function>sd_bus_creds_ref()</function> always returns the
279 <para><function>sd_bus_creds_unref()</function> always returns
280 <constant>NULL</constant>.</para>
284 <title>Reference ownership</title>
286 <para>Function <function>sd_bus_creds_new_from_pid()</function>
287 creates a new object and the caller owns the sole reference. When
288 not needed anymore, this reference should be destroyed with
289 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
294 <title>Errors</title>
296 <para>Returned errors may indicate the following problems:</para>
301 <term><constant>-ESRCH</constant></term>
303 <listitem><para>Specified <parameter>pid</parameter> could not
304 be found.</para></listitem>
308 <term><constant>-EINVAL</constant></term>
310 <listitem><para>Specified parameter is invalid
311 (<constant>NULL</constant> in case of output
312 parameters).</para></listitem>
316 <term><constant>-ENOMEM</constant></term>
318 <listitem><para>Memory allocation failed.</para></listitem>
322 <term><constant>-EOPNOTSUPP</constant></term>
324 <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
332 <para><function>sd_bus_creds_new_from_pid()</function> and the
333 other calls described here are available as a shared library,
334 which can be compiled and linked to with the
335 <constant>libelogind</constant> <citerefentry
336 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
341 <title>See Also</title>
344 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
348 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
349 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>