diff options
Diffstat (limited to 'man/sd_bus_creds_get_pid.xml')
| -rw-r--r-- | man/sd_bus_creds_get_pid.xml | 527 |
1 files changed, 527 insertions, 0 deletions
diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml new file mode 100644 index 0000000..8f5b94e --- /dev/null +++ b/man/sd_bus_creds_get_pid.xml @@ -0,0 +1,527 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="sd_bus_creds_get_pid" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_creds_get_pid</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_creds_get_pid</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_creds_get_pid</refname> + <refname>sd_bus_creds_get_ppid</refname> + <refname>sd_bus_creds_get_tid</refname> + <refname>sd_bus_creds_get_uid</refname> + <refname>sd_bus_creds_get_euid</refname> + <refname>sd_bus_creds_get_suid</refname> + <refname>sd_bus_creds_get_fsuid</refname> + <refname>sd_bus_creds_get_gid</refname> + <refname>sd_bus_creds_get_egid</refname> + <refname>sd_bus_creds_get_sgid</refname> + <refname>sd_bus_creds_get_fsgid</refname> + <refname>sd_bus_creds_get_supplementary_gids</refname> + <refname>sd_bus_creds_get_comm</refname> + <refname>sd_bus_creds_get_tid_comm</refname> + <refname>sd_bus_creds_get_exe</refname> + <refname>sd_bus_creds_get_cmdline</refname> + <refname>sd_bus_creds_get_cgroup</refname> + <refname>sd_bus_creds_get_unit</refname> + <refname>sd_bus_creds_get_slice</refname> + <refname>sd_bus_creds_get_user_unit</refname> + <refname>sd_bus_creds_get_user_slice</refname> + <refname>sd_bus_creds_get_session</refname> + <refname>sd_bus_creds_get_owner_uid</refname> + <refname>sd_bus_creds_has_effective_cap</refname> + <refname>sd_bus_creds_has_permitted_cap</refname> + <refname>sd_bus_creds_has_inheritable_cap</refname> + <refname>sd_bus_creds_has_bounding_cap</refname> + <refname>sd_bus_creds_get_selinux_context</refname> + <refname>sd_bus_creds_get_audit_session_id</refname> + <refname>sd_bus_creds_get_audit_login_uid</refname> + <refname>sd_bus_creds_get_tty</refname> + <refname>sd_bus_creds_get_unique_name</refname> + <refname>sd_bus_creds_get_well_known_names</refname> + <refname>sd_bus_creds_get_description</refname> + + <refpurpose>Retrieve fields from a credentials object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>pid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>ppid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>tid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_euid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_suid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_fsuid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_egid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_sgid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_fsgid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_supplementary_gids</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const gid_t **<parameter>gids</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>comm</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>comm</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>exe</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>char ***<parameter>cmdline</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_session</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>context</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>loginuid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>tty</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>char ***<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_description</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>name</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These functions return credential information from an + <parameter>sd_bus_creds</parameter> object. Credential objects may + be created with + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the process + identified by the specified PID, with + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of a bus peer + identified by the specified bus name, with + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the creator of a + bus, or with + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the sender of the + message.</para> + + <para>Not all credential fields are part of every + <literal>sd_bus_creds</literal> object. Use + <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to determine the mask of fields available.</para> + + <para><function>sd_bus_creds_get_pid()</function> will retrieve + the PID (process identifier). Similarly, + <function>sd_bus_creds_get_ppid()</function> will retrieve the + parent PID. Note that PID 1 has no parent process, in which case + -ENXIO is returned.</para> + + <para><function>sd_bus_creds_get_tid()</function> will retrieve the + TID (thread identifier).</para> + + <para><function>sd_bus_creds_get_uid()</function> will retrieve + the numeric UID (user identifier). Similarly, + <function>sd_bus_creds_get_euid()</function> returns the effective + UID, <function>sd_bus_creds_get_suid()</function> the saved UID + and <function>sd_bus_creds_get_fsuid()</function> the file system + UID.</para> + + <para><function>sd_bus_creds_get_gid()</function> will retrieve the + numeric GID (group identifier). Similarly, + <function>sd_bus_creds_get_egid()</function> returns the effective + GID, <function>sd_bus_creds_get_sgid()</function> the saved GID + and <function>sd_bus_creds_get_fsgid()</function> the file system + GID.</para> + + <para><function>sd_bus_creds_get_supplementary_gids()</function> + will retrieve the supplementary GIDs list.</para> + + <para><function>sd_bus_creds_get_comm()</function> will retrieve the + comm field (truncated name of the executable, as stored in + <filename>/proc/<replaceable>pid</replaceable>/comm</filename>). + </para> + + <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve + the comm field of the thread (as stored in + <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>). + </para> + + <para><function>sd_bus_creds_get_exe()</function> will retrieve the path to the program executable (as + stored in the <filename>/proc/<replaceable>pid</replaceable>/exe</filename> link, but with the <literal> + (deleted)</literal> suffix removed). Note that kernel threads do not have an executable path, in which + case -ENXIO is returned. Note that this property should not be used for more than explanatory + information, in particular it should not be used for security-relevant decisions. That's because the + executable might have been replaced or removed by the time the value can be processed. Moreover, the + kernel exports this information in an ambiguous way (i.e. a deleted executable cannot be safely + distinguished from one whose name suffix is <literal> (deleted)</literal>).</para> + + <para><function>sd_bus_creds_get_cmdline()</function> will + retrieve an array of command line arguments (as stored in + <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note + that kernel threads do not have a command line, in which case + -ENXIO is returned.</para> + + <para><function>sd_bus_creds_get_cgroup()</function> will retrieve + the control group path. See <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>. + </para> + + <para><function>sd_bus_creds_get_unit()</function> will retrieve + the systemd unit name (in the system instance of systemd) that the + process is a part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For + processes that are not part of a unit, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_get_user_unit()</function> will + retrieve the systemd unit name (in the user instance of systemd) + that the process is a part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For + processes that are not part of a user unit, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_get_slice()</function> will retrieve + the systemd slice (a unit in the system instance of systemd) that + the process is a part of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly, + <function>sd_bus_creds_get_user_slice()</function> retrieves the + systemd slice of the process, in the user instance of systemd. + </para> + + <para><function>sd_bus_creds_get_session()</function> will + retrieve the identifier of the login session that the process is + a part of. Please note the login session may be limited to a stub + process or two. User processes may instead be started from their + systemd user manager, e.g. GUI applications started using DBus + activation, as well as service processes which are shared between + multiple logins of the same user. For processes that are not part + of a session, returns -ENXIO.</para> + + <para><function>sd_bus_creds_get_owner_uid()</function> will + retrieve the numeric UID (user identifier) of the user who owns + the user unit or login session that the process is a part of. See + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + For processes that are not part of a user unit or session, returns + -ENXIO. + </para> + + <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by + <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it + was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the + <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para><function>sd_bus_creds_has_permitted_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the permitted capabilities mask.</para> + + <para><function>sd_bus_creds_has_inheritable_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the inheritable capabilities mask.</para> + + <para><function>sd_bus_creds_has_bounding_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the bounding capabilities mask.</para> + + <para><function>sd_bus_creds_get_selinux_context()</function> will + retrieve the SELinux security context (label) of the process.</para> + + <para><function>sd_bus_creds_get_audit_session_id()</function> + will retrieve the audit session identifier of the process. Returns + -ENXIO for processes that are not part of an audit session.</para> + + <para><function>sd_bus_creds_get_audit_login_uid()</function> will + retrieve the audit user login identifier (the identifier of the + user who is "responsible" for the session). Returns -ENXIO for + processes that are not part of an audit session.</para> + + <para><function>sd_bus_creds_get_tty()</function> will retrieve + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY.</para> + + <para><function>sd_bus_creds_get_unique_name()</function> will + retrieve the D-Bus unique name. See <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The + D-Bus specification</ulink>.</para> + + <para><function>sd_bus_creds_get_well_known_names()</function> will + retrieve the set of D-Bus well-known names. See <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The + D-Bus specification</ulink>.</para> + + <para><function>sd_bus_creds_get_description()</function> will + retrieve a descriptive name of the bus connection of the + peer. This name is useful to discern multiple bus connections by + the same peer, and may be altered by the peer with the + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call.</para> + + <para>All functions that take a <parameter>const + char**</parameter> parameter will store the answer there as an + address of a <constant>NUL</constant>-terminated string. It will be valid as long as + <parameter>c</parameter> remains valid, and should not be freed or + modified by the caller.</para> + + <para>All functions that take a <parameter>char***</parameter> + parameter will store the answer there as an address of an array + of strings. Each individual string is <constant>NUL</constant>-terminated, and the + array is <constant>NULL</constant>-terminated as a whole. It will be valid as long as + <parameter>c</parameter> remains valid, and should not be freed or + modified by the caller.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error code. + </para> + + <refsect2> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not available in the credentials object + <parameter>c</parameter>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The given field is not specified for the described process or peer. This will be + returned by <function>sd_bus_creds_get_unit()</function>, + <function>sd_bus_creds_get_slice()</function>, <function>sd_bus_creds_get_user_unit()</function>, + <function>sd_bus_creds_get_user_slice()</function>, and + <function>sd_bus_creds_get_session()</function> if the process is not part of a systemd system + unit, systemd user unit, systemd slice, or logind session. It will be returned by + <function>sd_bus_creds_get_owner_uid()</function> if the process is not part of a systemd user unit + or logind session. It will also be returned by <function>sd_bus_creds_get_exe()</function> and + <function>sd_bus_creds_get_cmdline()</function> for kernel threads (since these are not started + from an executable binary, nor have a command line), and by + <function>sd_bus_creds_get_audit_session_id()</function> and + <function>sd_bus_creds_get_audit_login_uid()</function> when the process is not part of an audit + session, and <function>sd_bus_creds_get_tty()</function> if the process has no controlling + TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified pointer parameter is <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |