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" 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_TID</constant>,
84 <constant>SD_BUS_CREDS_UID</constant>,
85 <constant>SD_BUS_CREDS_GID</constant>,
86 <constant>SD_BUS_CREDS_COMM</constant>,
87 <constant>SD_BUS_CREDS_TID_COMM</constant>,
88 <constant>SD_BUS_CREDS_EXE</constant>,
89 <constant>SD_BUS_CREDS_CMDLINE</constant>,
90 <constant>SD_BUS_CREDS_CGROUP</constant>,
91 <constant>SD_BUS_CREDS_UNIT</constant>,
92 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
93 <constant>SD_BUS_CREDS_SLICE</constant>,
94 <constant>SD_BUS_CREDS_SESSION</constant>,
95 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
96 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
97 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
98 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
99 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
100 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
101 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
102 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
103 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
104 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
105 <constant>_SD_BUS_CREDS_ALL</constant>
110 <title>Description</title>
112 <para><function>sd_bus_creds_new_from_pid()</function> creates a new
113 credentials object and fills it with information about the process
114 <parameter>pid</parameter>. This pointer to this object will
115 be stored in <parameter>ret</parameter> pointer.</para>
117 <para>The information that will be stored is determined by
118 <parameter>creds_mask</parameter>. It may contain a subset of ORed
119 constants <constant>SD_BUS_CREDS_PID</constant>,
120 <constant>SD_BUS_CREDS_TID</constant>,
121 <constant>SD_BUS_CREDS_UID</constant>,
122 <constant>SD_BUS_CREDS_GID</constant>,
123 <constant>SD_BUS_CREDS_COMM</constant>,
124 <constant>SD_BUS_CREDS_TID_COMM</constant>,
125 <constant>SD_BUS_CREDS_EXE</constant>,
126 <constant>SD_BUS_CREDS_CMDLINE</constant>,
127 <constant>SD_BUS_CREDS_CGROUP</constant>,
128 <constant>SD_BUS_CREDS_UNIT</constant>,
129 <constant>SD_BUS_CREDS_USER_UNIT</constant>,
130 <constant>SD_BUS_CREDS_SLICE</constant>,
131 <constant>SD_BUS_CREDS_SESSION</constant>,
132 <constant>SD_BUS_CREDS_OWNER_UID</constant>,
133 <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
134 <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
135 <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
136 <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
137 <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
138 <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
139 <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
140 <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
141 <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
142 or <constant>_SD_BUS_CREDS_ALL</constant> to indicate
143 all known fields.</para>
145 <para>Fields can be retrieved from the credentials object using
146 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
147 and other functions which correspond directly to the constants
150 <para>A mask of fields which were actually successfully set
151 (acquired from <filename>/proc</filename>, etc.) can be retrieved
152 with <function>sd_bus_creds_get_mask()</function>. If the
153 credentials object was created with
154 <function>sd_bus_creds_new_from_pid()</function>, this will be a
155 subset of fields requested in <parameter>creds_mask</parameter>.
158 <para><function>sd_bus_creds_ref</function> creates a new
159 reference to the credentials object <parameter>c</parameter>. This
160 object will not be destroyed until
161 <function>sd_bus_creds_unref</function> has been called as many
162 times plus once more. Once the reference count has dropped to zero,
163 <parameter>c</parameter> cannot be used anymore, so further
164 calls to <function>sd_bus_creds_ref(c)</function> or
165 <function>sd_bus_creds_unref(c)</function> are illegal.</para>
167 <para><function>sd_bus_creds_unref</function> destroys a reference
168 to <parameter>c</parameter>.</para>
172 <title>Return Value</title>
174 <para>On success, <function>sd_bus_creds_new_from_pid()</function>
175 returns 0 or a positive integer. On failure, it returns a negative
176 errno-style error code.</para>
178 <para><function>sd_bus_creds_get_mask()</function> returns the
179 mask of successfully acquired fields.</para>
181 <para><function>sd_bus_creds_ref</function> always returns the
184 <para><function>sd_bus_creds_unref</function> always returns
185 <constant>NULL</constant>.</para>
189 <title>Reference ownership</title>
191 <para>Function <function>sd_bus_creds_new_from_pid()</function>
192 creates a new object and the caller owns the sole reference. When
193 not needed anymore, this reference should be destroyed with
194 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
199 <title>Errors</title>
201 <para>Returned errors may indicate the following problems:</para>
206 <term><constant>-ESRCH</constant></term>
208 <listitem><para>Specified <parameter>pid</parameter> could not
209 be found.</para></listitem>
213 <term><constant>-EINVAL</constant></term>
215 <listitem><para>Specified parameter is invalid
216 (<constant>NULL</constant> in case of output
217 parameters).</para></listitem>
221 <term><constant>-ENOMEM</constant></term>
223 <listitem><para>Memory allocation failed.</para></listitem>
231 <para><function>sd_bus_creds_new_from_pid()</function> is
232 available as a shared library, which can be compiled and linked to
234 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
239 <title>See Also</title>
242 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
243 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
244 <citerefentry><refentrytitle>sd_bus_creds_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
245 <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
246 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
247 <citerefentry><refentrytitle>sd_bus_creds_get_tid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
248 <citerefentry><refentrytitle>sd_bus_creds_get_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
249 <citerefentry><refentrytitle>sd_bus_creds_get_gid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
250 <citerefentry><refentrytitle>sd_bus_creds_get_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
251 <citerefentry><refentrytitle>sd_bus_creds_get_tid_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>sd_bus_creds_get_exe</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>sd_bus_creds_get_cmdline</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>sd_bus_creds_get_cgroup</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>sd_bus_creds_get_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
256 <citerefentry><refentrytitle>sd_bus_creds_get_user_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
257 <citerefentry><refentrytitle>sd_bus_creds_get_slice</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
258 <citerefentry><refentrytitle>sd_bus_creds_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>sd_bus_creds_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
260 <citerefentry><refentrytitle>sd_bus_creds_has_effective_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>sd_bus_creds_has_permitted_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>sd_bus_creds_has_inheritable_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>sd_bus_creds_has_bounding_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>sd_bus_creds_get_selinux_context</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
265 <citerefentry><refentrytitle>sd_bus_creds_get_audit_session_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>sd_bus_creds_get_audit_login_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>sd_bus_creds_get_unique_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
268 <citerefentry><refentrytitle>sd_bus_creds_get_well_known_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>