1 <?xml version='1.0'?> <!--*-nxml-*-->
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" conditional="ENABLE_KDBUS">
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_ref</refname>
49 <refname>sd_bus_creds_unref</refname>
51 <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
56 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
59 <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
60 <paramdef>pid_t <parameter>pid</parameter></paramdef>
61 <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
62 <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
66 <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
67 <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef>
71 <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
72 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
76 <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
77 <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
82 <constant>SD_BUS_CREDS_PID</constant>,
83 <constant>SD_BUS_CREDS_PID_STARTTIME</constant>,
84 <constant>SD_BUS_CREDS_TID</constant>,
85 <constant>SD_BUS_CREDS_UID</constant>,
86 <constant>SD_BUS_CREDS_GID</constant>,
87 <constant>SD_BUS_CREDS_COMM</constant>,
88 <constant>SD_BUS_CREDS_TID_COMM</constant>,
89 <constant>SD_BUS_CREDS_EXE</constant>,
90 <constant>SD_BUS_CREDS_CMDLINE</constant>,
91 <constant>SD_BUS_CREDS_CGROUP</constant>,
92 <constant>SD_BUS_CREDS_UNIT</constant>,
93 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
94 <constant>SD_BUS_CREDS_SLICE</constant>,
95 <constant>SD_BUS_CREDS_SESSION</constant>,
96 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
97 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
98 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
99 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
100 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
101 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
102 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
103 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
104 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
105 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
106 <constant>_SD_BUS_CREDS_ALL</constant>
111 <title>Description</title>
113 <para><function>sd_bus_creds_new_from_pid()</function> creates a new
114 credentials object and fills it with information about the process
115 <parameter>pid</parameter>. This pointer to this object will
116 be stored in <parameter>ret</parameter> pointer.</para>
118 <para>The information that will be stored is determined by
119 <parameter>creds_mask</parameter>. It may contain a subset of ORed
120 constants <constant>SD_BUS_CREDS_PID</constant>,
121 <constant>SD_BUS_CREDS_PID_STARTTIME</constant>,
122 <constant>SD_BUS_CREDS_TID</constant>,
123 <constant>SD_BUS_CREDS_UID</constant>,
124 <constant>SD_BUS_CREDS_GID</constant>,
125 <constant>SD_BUS_CREDS_COMM</constant>,
126 <constant>SD_BUS_CREDS_TID_COMM</constant>,
127 <constant>SD_BUS_CREDS_EXE</constant>,
128 <constant>SD_BUS_CREDS_CMDLINE</constant>,
129 <constant>SD_BUS_CREDS_CGROUP</constant>,
130 <constant>SD_BUS_CREDS_UNIT</constant>,
131 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
132 <constant>SD_BUS_CREDS_SLICE</constant>,
133 <constant>SD_BUS_CREDS_SESSION</constant>,
134 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
135 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
136 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
137 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
138 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
139 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
140 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
141 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
142 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
143 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
144 or <constant>_SD_BUS_CREDS_ALL</constant> to indicate
145 all known fields.</para>
147 <para>Fields can be retrieved from the credentials object using
148 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
149 and other functions which correspond directly to the constants
152 <para>A mask of fields which were actually successfully set
153 (acquired from <filename>/proc</filename>, etc.) can be retrieved
154 with <function>sd_bus_creds_get_mask()</function>. If the
155 credentials object was created with
156 <function>sd_bus_creds_new_from_pid()</function>, this will be a
157 subset of fields requested in <parameter>creds_mask</parameter>.
160 <para><function>sd_bus_creds_ref</function> creates a new
161 reference to the credentials object <parameter>c</parameter>. This
162 object will not be destroyed until
163 <function>sd_bus_creds_unref</function> has been called as many
164 times plus once more. Once the reference count has dropped to zero,
165 <parameter>c</parameter> cannot be used anymore, so further
166 calls to <function>sd_bus_creds_ref(c)</function> or
167 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
169 <para><function>sd_bus_creds_unref</function> destroys a reference
170 to <parameter>c</parameter>.</para>
174 <title>Return Value</title>
176 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
177 returns 0 or a positive integer. On failure, it returns a negative
178 errno-style error code.</para>
180 <para><function>sd_bus_creds_get_mask()</function> returns the
181 mask of successfully acquired fields.</para>
183 <para><function>sd_bus_creds_ref</function> always returns the
186 <para><function>sd_bus_creds_unref</function> always returns
187 <constant>NULL</constant>.</para>
191 <title>Reference ownership</title>
193 <para>Function <function>sd_bus_creds_new_from_pid()</function>
194 creates a new object and the caller owns the sole reference. When
195 not needed anymore, this reference should be destroyed with
196 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
201 <title>Errors</title>
203 <para>Returned errors may indicate the following problems:</para>
208 <term><constant>-ESRCH</constant></term>
210 <listitem><para>Specified <parameter>pid</parameter> could not
211 be found.</para></listitem>
215 <term><constant>-EINVAL</constant></term>
217 <listitem><para>Specified parameter is invalid
218 (<constant>NULL</constant> in case of output
219 parameters).</para></listitem>
223 <term><constant>-ENOMEM</constant></term>
225 <listitem><para>Memory allocation failed.</para></listitem>
233 <para><function>sd_bus_creds_new_from_pid()</function> is
234 available as a shared library, which can be compiled and linked to
236 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
241 <title>See Also</title>
244 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
245 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
246 <citerefentry><refentrytitle>sd_bus_creds_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
247 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
248 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
249 <citerefentry><refentrytitle>sd_bus_creds_get_pid_starttime</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
250 <citerefentry><refentrytitle>sd_bus_creds_get_tid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
251 <citerefentry><refentrytitle>sd_bus_creds_get_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>sd_bus_creds_get_gid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>sd_bus_creds_get_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>sd_bus_creds_get_tid_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>sd_bus_creds_get_exe</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
256 <citerefentry><refentrytitle>sd_bus_creds_get_cmdline</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
257 <citerefentry><refentrytitle>sd_bus_creds_get_cgroup</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
258 <citerefentry><refentrytitle>sd_bus_creds_get_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>sd_bus_creds_get_user_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
260 <citerefentry><refentrytitle>sd_bus_creds_get_slice</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>sd_bus_creds_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>sd_bus_creds_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>sd_bus_creds_has_effective_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>sd_bus_creds_has_permitted_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
265 <citerefentry><refentrytitle>sd_bus_creds_has_inheritable_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>sd_bus_creds_has_bounding_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>sd_bus_creds_get_selinux_context</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
268 <citerefentry><refentrytitle>sd_bus_creds_get_audit_session_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
269 <citerefentry><refentrytitle>sd_bus_creds_get_audit_login_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
270 <citerefentry><refentrytitle>sd_bus_creds_get_unique_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
271 <citerefentry><refentrytitle>sd_bus_creds_get_well_known_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>