chiark / gitweb /
man: updates to the passive target section
[elogind.git] / man / sd_bus_creds_new_from_pid.xml
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">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="sd_bus_creds_new_from_pid" conditional="ENABLE_KDBUS">
25
26   <refentryinfo>
27     <title>sd_bus_creds_new_from_pid</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
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>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
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>
50
51     <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
52   </refnamediv>
53
54   <refsynopsisdiv>
55     <funcsynopsis>
56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
57
58       <funcprototype>
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>
63       </funcprototype>
64
65       <funcprototype>
66         <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
67         <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef>
68       </funcprototype>
69
70       <funcprototype>
71         <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
72         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
73       </funcprototype>
74
75       <funcprototype>
76         <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
77         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
78       </funcprototype>
79     </funcsynopsis>
80
81     <para>
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>
107     </para>
108   </refsynopsisdiv>
109
110   <refsect1>
111     <title>Description</title>
112
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>
117
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>
146
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
150     listed above.</para>
151
152     <para>A mask of fields which were actually sucessfully 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>.
158     </para>
159
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 futher
166     calls to <function>sd_bus_creds_ref(c)</function> or
167     <function>sd_bus_creds_unref(c)</function> are illegal.</para>
168
169     <para><function>sd_bus_creds_unref</function> destroys a reference
170     to <parameter>c</parameter>.</para>
171   </refsect1>
172
173   <refsect1>
174     <title>Return Value</title>
175
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>
179
180     <para><function>sd_bus_creds_get_mask()</function> returns the
181     mask of successfully acquired fields.</para>
182
183     <para><function>sd_bus_creds_ref</function> always returns the
184     argument.</para>
185
186     <para><function>sd_bus_creds_unref</function> always returns
187     <constant>NULL</constant>.</para>
188   </refsect1>
189
190   <refsect1>
191     <title>Reference ownership</title>
192
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>.
197     </para>
198   </refsect1>
199
200   <refsect1>
201     <title>Errors</title>
202
203     <para>Returned errors may indicate the following problems:</para>
204
205     <variablelist>
206
207       <varlistentry>
208         <term><varname>-ESRCH</varname></term>
209
210         <listitem><para>Specified <parameter>pid</parameter> could not
211         be found.</para></listitem>
212       </varlistentry>
213
214       <varlistentry>
215         <term><varname>-EINVAL</varname></term>
216
217         <listitem><para>Specified parameter is invalid
218         (<constant>NULL</constant> in case of output
219         parameters).</para></listitem>
220       </varlistentry>
221
222       <varlistentry>
223         <term><varname>-ENOMEM</varname></term>
224
225         <listitem><para>Memory allocation failed.</para></listitem>
226       </varlistentry>
227     </variablelist>
228   </refsect1>
229
230   <refsect1>
231     <title>Notes</title>
232
233     <para><function>sd_bus_creds_new_from_pid()</function> is
234     available as a shared library, which can be compiled and linked to
235     with the
236     <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
237     file.</para>
238   </refsect1>
239
240   <refsect1>
241     <title>See Also</title>
242
243     <para>
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>
272     </para>
273   </refsect1>
274
275 </refentry>