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 elogind.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
10 elogind 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 elogind 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 elogind; 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>elogind</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 <elogind/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>const sd_bus_creds *<parameter>c</parameter></paramdef>
73 <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
74 <paramdef>const 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_SESSION</constant>,
112 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
113 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
114 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
115 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
116 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
117 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
118 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
119 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
120 <constant>SD_BUS_CREDS_TTY</constant>,
121 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
122 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
123 <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
124 <constant>SD_BUS_CREDS_AUGMENT</constant>,
125 <constant>_SD_BUS_CREDS_ALL</constant>
130 <title>Description</title>
132 <para><function>sd_bus_creds_new_from_pid()</function> creates a
133 new credentials object and fills it with information about the
134 process <parameter>pid</parameter>. The pointer to this object
135 will be stored in the <parameter>ret</parameter> pointer. Note that
136 credential objects may also be created and retrieved via
137 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
140 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
142 <para>The information that will be stored is determined by
143 <parameter>creds_mask</parameter>. It may contain a subset of ORed
144 constants <constant>SD_BUS_CREDS_PID</constant>,
145 <constant>SD_BUS_CREDS_PPID</constant>,
146 <constant>SD_BUS_CREDS_TID</constant>,
147 <constant>SD_BUS_CREDS_UID</constant>,
148 <constant>SD_BUS_CREDS_EUID</constant>,
149 <constant>SD_BUS_CREDS_SUID</constant>,
150 <constant>SD_BUS_CREDS_FSUID</constant>,
151 <constant>SD_BUS_CREDS_GID</constant>,
152 <constant>SD_BUS_CREDS_EGID</constant>,
153 <constant>SD_BUS_CREDS_SGID</constant>,
154 <constant>SD_BUS_CREDS_FSGID</constant>,
155 <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
156 <constant>SD_BUS_CREDS_COMM</constant>,
157 <constant>SD_BUS_CREDS_TID_COMM</constant>,
158 <constant>SD_BUS_CREDS_EXE</constant>,
159 <constant>SD_BUS_CREDS_CMDLINE</constant>,
160 <constant>SD_BUS_CREDS_CGROUP</constant>,
161 <constant>SD_BUS_CREDS_SESSION</constant>,
162 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
163 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
164 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
165 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
166 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
167 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
168 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
169 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
170 <constant>SD_BUS_CREDS_TTY</constant>,
171 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
172 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
173 <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
174 value <constant>_SD_BUS_CREDS_ALL</constant> to request all
175 supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
176 constant may not be ORed into the mask for invocations of
177 <function>sd_bus_creds_new_from_pid()</function>.</para>
179 <para>Fields can be retrieved from the credentials object using
180 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
181 and other functions which correspond directly to the constants
184 <para>A mask of fields which were actually successfully retrieved
185 can be retrieved with
186 <function>sd_bus_creds_get_mask()</function>. If the credentials
187 object was created with
188 <function>sd_bus_creds_new_from_pid()</function>, this will be a
189 subset of fields requested in <parameter>creds_mask</parameter>.
192 <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
193 function <function>sd_bus_creds_get_augmented_mask()</function>
194 returns a bitmask of field constants. The mask indicates which
195 credential fields have been retrieved in a non-atomic fashion. For
196 credential objects created via
197 <function>sd_bus_creds_new_from_pid()</function>, this mask will be
198 identical to the mask returned by
199 <function>sd_bus_creds_get_mask()</function>. However, for
200 credential objects retrieved via
201 <function>sd_bus_get_name_creds()</function>, this mask will be set
202 for the credential fields that could not be determined atomically
203 at peer connection time, and which were later added by reading
204 augmenting credential data from
205 <filename>/proc</filename>. Similarly, for credential objects
206 retrieved via <function>sd_bus_get_owner_creds()</function>, the
207 mask is set for the fields that could not be determined atomically
208 at bus creation time, but have been augmented. Similarly, for
209 credential objects retrieved via
210 <function>sd_bus_message_get_creds()</function>, the mask is set
211 for the fields that could not be determined atomically at message
212 sending time, but have been augmented. The mask returned by
213 <function>sd_bus_creds_get_augmented_mask()</function> is always a
214 subset of (or identical to) the mask returned by
215 <function>sd_bus_creds_get_mask()</function> for the same
216 object. The latter call hence returns all credential fields
217 available in the credential object, the former then marks the
218 subset of those that have been augmented. Note that augmented
219 fields are unsuitable for authorization decisions, as they may be
220 retrieved at different times, thus being subject to races. Hence,
221 augmented fields should be used exclusively for informational
225 <para><function>sd_bus_creds_ref()</function> creates a new
226 reference to the credentials object <parameter>c</parameter>. This
227 object will not be destroyed until
228 <function>sd_bus_creds_unref()</function> has been called as many
229 times plus once more. Once the reference count has dropped to zero,
230 <parameter>c</parameter> cannot be used anymore, so further
231 calls to <function>sd_bus_creds_ref(c)</function> or
232 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
234 <para><function>sd_bus_creds_unref()</function> destroys a reference
235 to <parameter>c</parameter>.</para>
237 <para><function>sd_bus_creds_unrefp()</function> is similar to
238 <function>sd_bus_creds_unref()</function> but takes a pointer to a
239 pointer to an <type>sd_bus_creds</type> object. This call is useful in
240 conjunction with GCC's and LLVM's <ulink
241 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
242 Variable Attribute</ulink>. Note that this function is defined as
243 inline function.</para>
245 <para><function>sd_bus_creds_ref()</function>,
246 <function>sd_bus_creds_unref()</function> and
247 <function>sd_bus_creds_unrefp()</function> execute no operation if
248 the passed in bus credentials object is
249 <constant>NULL</constant>.</para>
254 <title>Return Value</title>
256 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
257 returns 0 or a positive integer. On failure, it returns a negative
258 errno-style error code.</para>
260 <para><function>sd_bus_creds_get_mask()</function> returns the
261 mask of successfully acquired fields.</para>
263 <para><function>sd_bus_creds_get_augmented_mask()</function>
264 returns the mask of fields that have been augmented from data in
265 <filename>/proc</filename>, and are thus not suitable for
266 authorization decisions.</para>
268 <para><function>sd_bus_creds_ref()</function> always returns the
271 <para><function>sd_bus_creds_unref()</function> always returns
272 <constant>NULL</constant>.</para>
276 <title>Reference ownership</title>
278 <para>Function <function>sd_bus_creds_new_from_pid()</function>
279 creates a new object and the caller owns the sole reference. When
280 not needed anymore, this reference should be destroyed with
281 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
286 <title>Errors</title>
288 <para>Returned errors may indicate the following problems:</para>
293 <term><constant>-ESRCH</constant></term>
295 <listitem><para>Specified <parameter>pid</parameter> could not
296 be found.</para></listitem>
300 <term><constant>-EINVAL</constant></term>
302 <listitem><para>Specified parameter is invalid
303 (<constant>NULL</constant> in case of output
304 parameters).</para></listitem>
308 <term><constant>-ENOMEM</constant></term>
310 <listitem><para>Memory allocation failed.</para></listitem>
314 <term><constant>-EOPNOTSUPP</constant></term>
316 <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
324 <para><function>sd_bus_creds_new_from_pid()</function> and the
325 other calls described here are available as a shared library,
326 which can be compiled and linked to with the
327 <constant>libelogind</constant> <citerefentry
328 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
333 <title>See Also</title>
336 <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
337 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
338 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
339 <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>