shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-03 05:18:09 +03:00
Code

man: document the new APIs

Browse Source
This commit is contained in:
Lennart Poettering 2024-01-26 19:00:43 +01:00
parent 4ac08d8ad6
commit a667107594
3 changed files with 85 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
man/rules/meson.build
View File

@ -202,6 +202,7 @@ manpages = [
'sd_bus_creds_get_fsuid', 'sd_bus_creds_get_fsuid',
'sd_bus_creds_get_gid', 'sd_bus_creds_get_gid',
'sd_bus_creds_get_owner_uid', 'sd_bus_creds_get_owner_uid',
'sd_bus_creds_get_pidfd_dup',
'sd_bus_creds_get_ppid', 'sd_bus_creds_get_ppid',
'sd_bus_creds_get_selinux_context', 'sd_bus_creds_get_selinux_context',
'sd_bus_creds_get_session', 'sd_bus_creds_get_session',
@ -227,6 +228,7 @@ manpages = [
'3', '3',
['sd_bus_creds_get_augmented_mask', ['sd_bus_creds_get_augmented_mask',
'sd_bus_creds_get_mask', 'sd_bus_creds_get_mask',
'sd_bus_creds_new_from_pidfd',
'sd_bus_creds_ref', 'sd_bus_creds_ref',
'sd_bus_creds_unref', 'sd_bus_creds_unref',
'sd_bus_creds_unrefp'], 'sd_bus_creds_unrefp'],

21
man/sd_bus_creds_get_pid.xml
View File

@ -17,6 +17,7 @@
<refnamediv> <refnamediv>
<refname>sd_bus_creds_get_pid</refname> <refname>sd_bus_creds_get_pid</refname>
<refname>sd_bus_creds_get_pidfd_dup</refname>
<refname>sd_bus_creds_get_ppid</refname> <refname>sd_bus_creds_get_ppid</refname>
<refname>sd_bus_creds_get_tid</refname> <refname>sd_bus_creds_get_tid</refname>
<refname>sd_bus_creds_get_uid</refname> <refname>sd_bus_creds_get_uid</refname>
@ -64,6 +65,12 @@
<paramdef>pid_t *<parameter>pid</parameter></paramdef> <paramdef>pid_t *<parameter>pid</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_creds_get_pidfd_dup</function></funcdef>
<paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
<paramdef>int *<parameter>ret_fd</parameter></paramdef>
</funcprototype>
<funcprototype> <funcprototype>
<funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef> <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef>
<paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
@ -289,11 +296,14 @@
<citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to determine the mask of fields available.</para> to determine the mask of fields available.</para>
<para><function>sd_bus_creds_get_pid()</function> will retrieve <para><function>sd_bus_creds_get_pid()</function> will retrieve the PID (process identifier). Similarly,
the PID (process identifier). Similarly, <function>sd_bus_creds_get_ppid()</function> will retrieve the parent PID. Note that PID 1 has no parent
<function>sd_bus_creds_get_ppid()</function> will retrieve the process, in which case -ENXIO is returned.</para>
parent PID. Note that PID 1 has no parent process, in which case
-ENXIO is returned.</para> <para><function>sd_bus_creds_get_pidfd_dup()</function> will retrieve the PID file descriptor (pidfd),
see <citerefentry
project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
details. The file descriptor is duplicated and thus must be closed by the caller.</para>
<para><function>sd_bus_creds_get_tid()</function> will retrieve the <para><function>sd_bus_creds_get_tid()</function> will retrieve the
TID (thread identifier).</para> TID (thread identifier).</para>
@ -543,6 +553,7 @@
<function>sd_bus_creds_get_tty()</function>, and <function>sd_bus_creds_get_tty()</function>, and
<function>sd_bus_creds_get_description()</function> were added in version 220.</para> <function>sd_bus_creds_get_description()</function> were added in version 220.</para>
<para><function>sd_bus_creds_get_user_slice()</function> was added in version 223.</para> <para><function>sd_bus_creds_get_user_slice()</function> was added in version 223.</para>
<para><function>sd_bus_creds_get_pidfd_dup()</function> was added in version 256.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>

150
man/sd_bus_creds_new_from_pid.xml
View File

@ -17,6 +17,7 @@
<refnamediv> <refnamediv>
<refname>sd_bus_creds_new_from_pid</refname> <refname>sd_bus_creds_new_from_pid</refname>
<refname>sd_bus_creds_new_from_pidfd</refname>
<refname>sd_bus_creds_get_mask</refname> <refname>sd_bus_creds_get_mask</refname>
<refname>sd_bus_creds_get_augmented_mask</refname> <refname>sd_bus_creds_get_augmented_mask</refname>
<refname>sd_bus_creds_ref</refname> <refname>sd_bus_creds_ref</refname>
@ -37,6 +38,13 @@
<paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef> <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_creds_new_from_pidfd</function></funcdef>
<paramdef>int <parameter>pidfd</parameter></paramdef>
<paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
<paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
</funcprototype>
<funcprototype> <funcprototype>
<funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
<paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
@ -98,6 +106,7 @@
<constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
<constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
<constant>SD_BUS_CREDS_DESCRIPTION</constant>, <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
<constant>SD_BUS_CREDS_PIDFD</constant>,
<constant>SD_BUS_CREDS_AUGMENT</constant>, <constant>SD_BUS_CREDS_AUGMENT</constant>,
<constant>_SD_BUS_CREDS_ALL</constant> <constant>_SD_BUS_CREDS_ALL</constant>
</para> </para>
@ -116,91 +125,65 @@
and and
<citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>The information that will be stored is determined by <para><function>sd_bus_creds_new_from_pidfd()</function> is identical to
<parameter>creds_mask</parameter>. It may contain a subset of ORed <function>sd_bus_creds_new_from_pid()</function>, but takes a PID file descriptor rather than a numeric
constants <constant>SD_BUS_CREDS_PID</constant>, PID as reference to the process. See <citerefentry
<constant>SD_BUS_CREDS_PPID</constant>, project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
<constant>SD_BUS_CREDS_TID</constant>,
<constant>SD_BUS_CREDS_UID</constant>, <para>The information that will be stored is determined by <parameter>creds_mask</parameter>. It may
<constant>SD_BUS_CREDS_EUID</constant>, contain a subset of ORed constants <constant>SD_BUS_CREDS_PID</constant>,
<constant>SD_BUS_CREDS_SUID</constant>, <constant>SD_BUS_CREDS_PPID</constant>, <constant>SD_BUS_CREDS_TID</constant>,
<constant>SD_BUS_CREDS_FSUID</constant>, <constant>SD_BUS_CREDS_UID</constant>, <constant>SD_BUS_CREDS_EUID</constant>,
<constant>SD_BUS_CREDS_GID</constant>, <constant>SD_BUS_CREDS_SUID</constant>, <constant>SD_BUS_CREDS_FSUID</constant>,
<constant>SD_BUS_CREDS_EGID</constant>, <constant>SD_BUS_CREDS_GID</constant>, <constant>SD_BUS_CREDS_EGID</constant>,
<constant>SD_BUS_CREDS_SGID</constant>, <constant>SD_BUS_CREDS_SGID</constant>, <constant>SD_BUS_CREDS_FSGID</constant>,
<constant>SD_BUS_CREDS_FSGID</constant>, <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, <constant>SD_BUS_CREDS_COMM</constant>,
<constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, <constant>SD_BUS_CREDS_TID_COMM</constant>, <constant>SD_BUS_CREDS_EXE</constant>,
<constant>SD_BUS_CREDS_COMM</constant>, <constant>SD_BUS_CREDS_CMDLINE</constant>, <constant>SD_BUS_CREDS_CGROUP</constant>,
<constant>SD_BUS_CREDS_TID_COMM</constant>, <constant>SD_BUS_CREDS_UNIT</constant>, <constant>SD_BUS_CREDS_SLICE</constant>,
<constant>SD_BUS_CREDS_EXE</constant>, <constant>SD_BUS_CREDS_USER_UNIT</constant>, <constant>SD_BUS_CREDS_USER_SLICE</constant>,
<constant>SD_BUS_CREDS_CMDLINE</constant>, <constant>SD_BUS_CREDS_SESSION</constant>, <constant>SD_BUS_CREDS_OWNER_UID</constant>,
<constant>SD_BUS_CREDS_CGROUP</constant>, <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
<constant>SD_BUS_CREDS_UNIT</constant>, <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
<constant>SD_BUS_CREDS_SLICE</constant>, <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>, <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
<constant>SD_BUS_CREDS_USER_UNIT</constant>, <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, <constant>SD_BUS_CREDS_TTY</constant>,
<constant>SD_BUS_CREDS_USER_SLICE</constant>, <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
<constant>SD_BUS_CREDS_SESSION</constant>, <constant>SD_BUS_CREDS_DESCRIPTION</constant>, and <constant>SD_BUS_CREDS_PIDFD</constant>. Use the
<constant>SD_BUS_CREDS_OWNER_UID</constant>, special value <constant>_SD_BUS_CREDS_ALL</constant> to request all supported fields. The
<constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, <constant>SD_BUS_CREDS_AUGMENT</constant> constant may not be ORed into the mask for invocations of
<constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>, <function>sd_bus_creds_new_from_pid()</function> or
<constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, <function>sd_bus_creds_new_from_pidfd()</function>.</para>
<constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
<constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
<constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
<constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
<constant>SD_BUS_CREDS_TTY</constant>,
<constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
<constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
<constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
value <constant>_SD_BUS_CREDS_ALL</constant> to request all
supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
constant may not be ORed into the mask for invocations of
<function>sd_bus_creds_new_from_pid()</function>.</para>
<para>Fields can be retrieved from the credentials object using <para>Fields can be retrieved from the credentials object using
<citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and other functions which correspond directly to the constants and other functions which correspond directly to the constants
listed above.</para> listed above.</para>
<para>A mask of fields which were actually successfully retrieved <para>A mask of fields which were actually successfully retrieved can be retrieved with
can be retrieved with <function>sd_bus_creds_get_mask()</function>. If the credentials object was created with
<function>sd_bus_creds_get_mask()</function>. If the credentials <function>sd_bus_creds_new_from_pid()</function> or <function>sd_bus_creds_new_from_pidfd()</function>,
object was created with this will be a subset of fields requested in <parameter>creds_mask</parameter>.
<function>sd_bus_creds_new_from_pid()</function>, this will be a
subset of fields requested in <parameter>creds_mask</parameter>.
</para> </para>
<para>Similar to <function>sd_bus_creds_get_mask()</function>, the <para>Similar to <function>sd_bus_creds_get_mask()</function>, the function
function <function>sd_bus_creds_get_augmented_mask()</function> <function>sd_bus_creds_get_augmented_mask()</function> returns a bitmask of field constants. The mask
returns a bitmask of field constants. The mask indicates which indicates which credential fields have been retrieved in a non-atomic fashion. For credential objects
credential fields have been retrieved in a non-atomic fashion. For created via <function>sd_bus_creds_new_from_pid()</function> or
credential objects created via <function>sd_bus_creds_new_from_pidfd()</function>, this mask will be identical to the mask returned by
<function>sd_bus_creds_new_from_pid()</function>, this mask will be <function>sd_bus_creds_get_mask()</function>. However, for credential objects retrieved via
identical to the mask returned by <function>sd_bus_get_name_creds()</function>, this mask will be set for the credential fields that could
<function>sd_bus_creds_get_mask()</function>. However, for not be determined atomically at peer connection time, and which were later added by reading augmenting
credential objects retrieved via credential data from <filename>/proc/</filename>. Similarly, for credential objects retrieved via
<function>sd_bus_get_name_creds()</function>, this mask will be set <function>sd_bus_get_owner_creds()</function>, the mask is set for the fields that could not be
for the credential fields that could not be determined atomically determined atomically at bus creation time, but have been augmented. Similarly, for credential objects
at peer connection time, and which were later added by reading retrieved via <function>sd_bus_message_get_creds()</function>, the mask is set for the fields that could
augmenting credential data from not be determined atomically at message sending time, but have been augmented. The mask returned by
<filename>/proc/</filename>. Similarly, for credential objects <function>sd_bus_creds_get_augmented_mask()</function> is always a subset of (or identical to) the mask
retrieved via <function>sd_bus_get_owner_creds()</function>, the returned by <function>sd_bus_creds_get_mask()</function> for the same object. The latter call hence
mask is set for the fields that could not be determined atomically returns all credential fields available in the credential object, the former then marks the subset of
at bus creation time, but have been augmented. Similarly, for those that have been augmented. Note that augmented fields are unsuitable for authorization decisions, as
credential objects retrieved via they may be retrieved at different times, thus being subject to races. Hence, augmented fields should be
<function>sd_bus_message_get_creds()</function>, the mask is set used exclusively for informational purposes.
for the fields that could not be determined atomically at message
sending time, but have been augmented. The mask returned by
<function>sd_bus_creds_get_augmented_mask()</function> is always a
subset of (or identical to) the mask returned by
<function>sd_bus_creds_get_mask()</function> for the same
object. The latter call hence returns all credential fields
available in the credential object, the former then marks the
subset of those that have been augmented. Note that augmented
fields are unsuitable for authorization decisions, as they may be
retrieved at different times, thus being subject to races. Hence,
augmented fields should be used exclusively for informational
purposes.
</para> </para>
<para><function>sd_bus_creds_ref()</function> creates a new <para><function>sd_bus_creds_ref()</function> creates a new
@ -234,9 +217,9 @@
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para>On success, <function>sd_bus_creds_new_from_pid()</function> <para>On success, <function>sd_bus_creds_new_from_pid()</function> and
returns 0 or a positive integer. On failure, it returns a negative <function>sd_bus_creds_new_from_pidfd()</function> return 0 or a positive integer. On failure, they return
errno-style error code.</para> a negative errno-style error code.</para>
<para><function>sd_bus_creds_get_mask()</function> returns the <para><function>sd_bus_creds_get_mask()</function> returns the
mask of successfully acquired fields.</para> mask of successfully acquired fields.</para>
@ -256,9 +239,9 @@
<refsect1> <refsect1>
<title>Reference ownership</title> <title>Reference ownership</title>
<para>Function <function>sd_bus_creds_new_from_pid()</function> <para>The functions <function>sd_bus_creds_new_from_pid()</function> and
creates a new object and the caller owns the sole reference. When <function>sd_bus_creds_new_from_pidfd()</function> create a new object and the caller owns the sole
not needed anymore, this reference should be destroyed with reference. When not needed anymore, this reference should be destroyed with
<citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para> </para>
@ -307,6 +290,7 @@
<function>sd_bus_creds_unref()</function> were added in version 209.</para> <function>sd_bus_creds_unref()</function> were added in version 209.</para>
<para><function>sd_bus_creds_get_augmented_mask()</function> was added in version 223.</para> <para><function>sd_bus_creds_get_augmented_mask()</function> was added in version 223.</para>
<para><function>sd_bus_creds_unrefp()</function> was added in version 229.</para> <para><function>sd_bus_creds_unrefp()</function> was added in version 229.</para>
<para><function>sd_bus_creds_new_from_pidfd()</function> was added in version 256.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>