chiark / gitweb /
man: add sd_event_add_child(3)
[elogind.git] / man / sd_bus_creds_get_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_get_pid" conditional="ENABLE_KDBUS">
25
26   <refentryinfo>
27     <title>sd_bus_creds_get_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_get_pid</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>sd_bus_creds_get_pid</refname>
47     <refname>sd_bus_creds_get_pid_starttime</refname>
48     <refname>sd_bus_creds_get_tid</refname>
49     <refname>sd_bus_creds_get_uid</refname>
50     <refname>sd_bus_creds_get_gid</refname>
51     <refname>sd_bus_creds_get_comm</refname>
52     <refname>sd_bus_creds_get_tid_comm</refname>
53     <refname>sd_bus_creds_get_exe</refname>
54     <refname>sd_bus_creds_get_cmdline</refname>
55     <refname>sd_bus_creds_get_cgroup</refname>
56     <refname>sd_bus_creds_get_unit</refname>
57     <refname>sd_bus_creds_get_user_unit</refname>
58     <refname>sd_bus_creds_get_slice</refname>
59     <refname>sd_bus_creds_get_session</refname>
60     <refname>sd_bus_creds_get_owner_uid</refname>
61     <refname>sd_bus_creds_has_effective_cap</refname>
62     <refname>sd_bus_creds_has_permitted_cap</refname>
63     <refname>sd_bus_creds_has_inheritable_cap</refname>
64     <refname>sd_bus_creds_has_bounding_cap</refname>
65     <refname>sd_bus_creds_get_selinux_context</refname>
66     <refname>sd_bus_creds_get_audit_session_id</refname>
67     <refname>sd_bus_creds_get_audit_login_uid</refname>
68     <refname>sd_bus_creds_get_unique_name</refname>
69     <refname>sd_bus_creds_get_well_known_names</refname>
70
71     <refpurpose>Retrieve fields from a credentials object</refpurpose>
72   </refnamediv>
73
74   <refsynopsisdiv>
75     <funcsynopsis>
76       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
77
78       <funcprototype>
79         <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
80         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
81         <paramdef>pid_t *<parameter>pid</parameter></paramdef>
82       </funcprototype>
83
84       <funcprototype>
85         <funcdef>int <function>sd_bus_creds_get_pid_starttime</function></funcdef>
86         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
87         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
88       </funcprototype>
89
90       <funcprototype>
91         <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
92         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
93         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
94       </funcprototype>
95
96       <funcprototype>
97         <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
98         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
99         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
100       </funcprototype>
101
102       <funcprototype>
103         <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
104         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
105         <paramdef>gid_t *<parameter>gid</parameter></paramdef>
106       </funcprototype>
107
108       <funcprototype>
109         <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
110         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
111         <paramdef>const char **<parameter>comm</parameter></paramdef>
112       </funcprototype>
113
114       <funcprototype>
115         <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
116         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
117         <paramdef>const char **<parameter>comm</parameter></paramdef>
118       </funcprototype>
119
120       <funcprototype>
121         <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
122         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
123         <paramdef>const char **<parameter>exe</parameter></paramdef>
124       </funcprototype>
125
126       <funcprototype>
127         <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
128         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
129         <paramdef>char ***<parameter>cmdline</parameter></paramdef>
130       </funcprototype>
131
132       <funcprototype>
133         <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
134         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
135         <paramdef>const char **<parameter>cgroup</parameter></paramdef>
136       </funcprototype>
137
138       <funcprototype>
139         <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
140         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
141         <paramdef>const char **<parameter>unit</parameter></paramdef>
142       </funcprototype>
143
144       <funcprototype>
145         <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
146         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
147         <paramdef>const char **<parameter>unit</parameter></paramdef>
148       </funcprototype>
149
150       <funcprototype>
151         <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
152         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
153         <paramdef>const char **<parameter>slice</parameter></paramdef>
154       </funcprototype>
155
156       <funcprototype>
157         <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
158         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
159         <paramdef>const char **<parameter>slice</parameter></paramdef>
160       </funcprototype>
161
162       <funcprototype>
163         <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
164         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
165         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
166       </funcprototype>
167
168       <funcprototype>
169         <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
170         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
171         <paramdef>int <parameter>capability</parameter></paramdef>
172       </funcprototype>
173
174       <funcprototype>
175         <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
176         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
177         <paramdef>int <parameter>capability</parameter></paramdef>
178       </funcprototype>
179
180       <funcprototype>
181         <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
182         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
183         <paramdef>int <parameter>capability</parameter></paramdef>
184       </funcprototype>
185
186       <funcprototype>
187         <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
188         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
189         <paramdef>int <parameter>capability</parameter></paramdef>
190       </funcprototype>
191
192       <funcprototype>
193         <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
194         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
195         <paramdef>const char **<parameter>context</parameter></paramdef>
196       </funcprototype>
197
198       <funcprototype>
199         <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
200         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
201         <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
202       </funcprototype>
203
204       <funcprototype>
205         <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
206         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
207         <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
208       </funcprototype>
209
210       <funcprototype>
211         <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
212         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
213         <paramdef>const char **<parameter>name</parameter></paramdef>
214       </funcprototype>
215
216       <funcprototype>
217         <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
218         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
219         <paramdef>char ***<parameter>name</parameter></paramdef>
220       </funcprototype>
221
222     </funcsynopsis>
223   </refsynopsisdiv>
224
225   <refsect1>
226     <title>Description</title>
227
228     <para>These functions return information from an
229     <parameter>sd_bus_creds</parameter> object. It may be created with
230     <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
231     in which case it will describe the specified process, or it may be
232     created by
233     <citerefentry><refentrytitle>sd_bus_get_peer_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
234     in which case it will describe the process at the other endpoint
235     of a connection.
236     </para>
237
238     <para><function>sd_bus_creds_get_pid</function> will retrieve the
239     PID (process identifier).</para>
240
241     <para><function>sd_bus_creds_get_pid_starttime</function> will
242     retrieve the time since the start of the epoch in microseconds
243     since the process was started.</para>
244
245     <para><function>sd_bus_creds_get_tid</function> will retrieve the
246     TID (thread identifier).</para>
247
248     <para><function>sd_bus_creds_get_uid</function> will retrieve the
249     numeric UID (user identifier).</para>
250
251     <para><function>sd_bus_creds_get_gid</function> will retrieve the
252     numeric GID (group identifier).</para>
253
254     <para><function>sd_bus_creds_get_comm</function> will retrieve the
255     comm field (truncated name of the executable, as stored in
256     <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
257     </para>
258
259     <para><function>sd_bus_creds_get_tid_comm</function> will retrieve
260     the comm field of the thread (as stored in
261     <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
262     </para>
263
264     <para><function>sd_bus_creds_get_exe</function> will retrieve the
265     path to the program (as stored in the
266     <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
267     link, but with <literal> (deleted)</literal> suffix removed).
268     </para>
269
270     <para><function>sd_bus_creds_get_cmdline</function> will retrieve
271     an array of command-line arguments (as stored in
272     <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
273     </para>
274
275     <para><function>sd_bus_creds_get_cgroup</function> will retrieve
276     the cgroup path. See <ulink
277     url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
278     </para>
279
280     <para><function>sd_bus_creds_get_unit</function> will retrieve the
281     systemd unit name (in the system instance of systemd) that the
282     process is part of. See
283     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
284     </para>
285
286     <para><function>sd_bus_creds_get_user_unit</function> will
287     retrieve the systemd unit name (in the user instance of systemd)
288     that the process is part of. See
289     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
290     </para>
291
292     <para><function>sd_bus_creds_get_slice</function> will retrieve
293     the systemd slice (a unit in the system instance of systemd) that
294     the process is part of. See
295     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
296     </para>
297
298     <para><function>sd_bus_creds_get_session</function> will retrieve
299     the logind session that the process is part of. See
300     <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
301     </para>
302
303     <para><function>sd_bus_creds_get_owner_uid</function> will retrieve
304     the numeric UID (user identifier) of the user who owns the slice
305     that the process is part of. See
306     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
307     <!-- and
308     <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
309     </para>
310
311     <para><function>sd_bus_creds_has_effective_cap</function> will
312     check whether the capability specified by
313     <parameter>capability</parameter> was set in the effective
314     capabilities mask. A positive return value means that is was
315     set, zero means that it was not set, and a negative return
316     value signifies an error. See
317     <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
318     and <varname>Capabilities=</varname> and
319     <varname>CapabilityBoundingSet=</varname> settings in
320     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
321     </para>
322
323     <para><function>sd_bus_creds_has_permitted_cap</function> is
324     similar to <function>sd_bus_creds_has_effective_cap</function>,
325     but will check the permitted capabilities mask.</para>
326
327     <para><function>sd_bus_creds_has_inheritable_cap</function> is
328     similar to <function>sd_bus_creds_has_effective_cap</function>,
329     but will check the inheritable capabilities mask.</para>
330
331     <para><function>sd_bus_creds_has_bounding_cap</function> is
332     similar to <function>sd_bus_creds_has_effective_cap</function>,
333     but will check the bounding capabilities mask.</para>
334
335     <para><function>sd_bus_creds_get_selinux_context</function> will
336     retrieve the SELinux security context (label) of the process.</para>
337
338     <para><function>sd_bus_creds_get_audit_session_id</function> will
339     retrieve the audit session identifier of the process.</para>
340
341     <para><function>sd_bus_creds_get_audit_login_uid</function> will
342     retrieve the audit user login identifier (the identifier of the
343     user who is "responsible" for the session).</para>
344
345     <para><function>sd_bus_creds_get_unique_name</function> will
346     retrieve the D-Bus unique name. See <ulink
347     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
348     D-Bus specification</ulink>.</para>
349
350     <para><function>sd_bus_creds_get_well_known_names</function> will
351     retrieve the set of D-Bus well-known names. See <ulink
352     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
353     D-Bus specification</ulink>.</para>
354
355     <para>All functions that take a <parameter>const
356     char**</parameter> parameter will store the answer there as an
357     address of a NUL-terminated string. It will be valid as long as
358     <parameter>c</parameter> remains valid, and should not be freed or
359     modified by the caller.</para>
360
361     <para>All functions that take a <parameter>char***</parameter>
362     parameter will store the answer there as an address of a an array
363     of strings. Each invidividual string is NUL-terminated, and the
364     array is NULL-terminated as a whole. It will be valid as long as
365     <parameter>c</parameter> remains valid, and should not be freed or
366     modified by the caller.</para>
367   </refsect1>
368
369   <refsect1>
370     <title>Return Value</title>
371
372     <para>On success, these calls return 0 or a positive integer. On
373     failure, these calls return a negative errno-style error code.
374     </para>
375   </refsect1>
376
377   <refsect1>
378     <title>Errors</title>
379
380     <para>Returned errors may indicate the following problems:</para>
381
382     <variablelist>
383       <varlistentry>
384         <term><varname>-ENODATA</varname></term>
385
386         <listitem><para>Given field is not available in
387         <parameter>c</parameter>.</para>
388         </listitem>
389       </varlistentry>
390
391       <varlistentry>
392         <term><varname>-ENOENT</varname></term>
393
394         <listitem><para>Given field is not specified for the sender.
395         This will be returned by <function>sd_bus_get_unit</function>,
396         <function>sd_bus_get_user_unit</function>,
397         <function>sd_bus_get_slice</function>,
398         <function>sd_bus_get_session</function>, and
399         <function>sd_bus_get_owner_uid</function> if the sender is not
400         part of a systemd system unit, systemd user unit, systemd
401         slice, logind session, or a systemd user session.</para>
402         </listitem>
403       </varlistentry>
404
405       <varlistentry>
406         <term><varname>-ENXIO</varname></term>
407
408         <listitem><para>An error occurred in parsing cgroup paths.
409         <filename>libsystemd</filename> might be out of sync with
410         the running systemd version.</para></listitem>
411       </varlistentry>
412
413       <varlistentry>
414         <term><varname>-EINVAL</varname></term>
415
416         <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
417         </para></listitem>
418       </varlistentry>
419
420       <varlistentry>
421         <term><varname>-ENOMEM</varname></term>
422
423         <listitem><para>Memory allocation failed.</para></listitem>
424       </varlistentry>
425     </variablelist>
426   </refsect1>
427
428   <refsect1>
429     <title>Notes</title>
430
431     <para><function>sd_bus_open_user()</function> and other functions
432     described here are available as a shared library, which can be
433     compiled and linked to with the
434     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
435     file.</para>
436   </refsect1>
437
438   <refsect1>
439     <title>See Also</title>
440
441     <para>
442       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
443       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
444       <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
445       <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
446       <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
447       <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
448       <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
449       <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
450     </para>
451   </refsect1>
452
453 </refentry>