diff options
| -rw-r--r-- | Makefile-man.am | 156 | ||||
| -rw-r--r-- | man/sd_bus_creds_get_pid.xml | 445 | ||||
| -rw-r--r-- | man/sd_bus_new.xml | 145 | ||||
| -rw-r--r-- | man/sd_bus_open_user.xml | 217 | ||||
| -rw-r--r-- | src/libsystemd-bus/sd-bus.c | 2 | ||||
| -rw-r--r-- | src/systemd/sd-bus.h | 10 |
6 files changed, 969 insertions, 6 deletions
diff --git a/Makefile-man.am b/Makefile-man.am index 4a0d339ac2..35174cca5f 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -20,7 +20,10 @@ MANPAGES += \ man/sd-id128.3 \ man/sd-journal.3 \ man/sd_booted.3 \ + man/sd_bus_creds_get_pid.3 \ man/sd_bus_message_get_cookie.3 \ + man/sd_bus_new.3 \ + man/sd_bus_open_user.3 \ man/sd_bus_request_name.3 \ man/sd_id128_get_machine.3 \ man/sd_id128_randomize.3 \ @@ -135,8 +138,38 @@ MANPAGES_ALIAS += \ man/init.1 \ man/poweroff.8 \ man/reboot.8 \ + man/sd_bus_creds_get_audit_login_uid.3 \ + man/sd_bus_creds_get_audit_session_id.3 \ + man/sd_bus_creds_get_cgroup.3 \ + man/sd_bus_creds_get_cmdline.3 \ + man/sd_bus_creds_get_comm.3 \ + man/sd_bus_creds_get_exe.3 \ + man/sd_bus_creds_get_gid.3 \ + man/sd_bus_creds_get_owner_uid.3 \ + man/sd_bus_creds_get_pid_starttime.3 \ + man/sd_bus_creds_get_selinux_context.3 \ + man/sd_bus_creds_get_session.3 \ + man/sd_bus_creds_get_slice.3 \ + man/sd_bus_creds_get_tid.3 \ + man/sd_bus_creds_get_tid_comm.3 \ + man/sd_bus_creds_get_uid.3 \ + man/sd_bus_creds_get_unique_name.3 \ + man/sd_bus_creds_get_unit.3 \ + man/sd_bus_creds_get_user_unit.3 \ + man/sd_bus_creds_get_well_known_names.3 \ + man/sd_bus_creds_has_bounding_cap.3 \ + man/sd_bus_creds_has_effective_cap.3 \ + man/sd_bus_creds_has_inheritable_cap.3 \ + man/sd_bus_creds_has_permitted_cap.3 \ + man/sd_bus_default_system.3 \ + man/sd_bus_default_user.3 \ man/sd_bus_message_get_reply_cookie.3 \ + man/sd_bus_open_system.3 \ + man/sd_bus_open_system_container.3 \ + man/sd_bus_open_system_remote.3 \ + man/sd_bus_ref.3 \ man/sd_bus_release_name.3 \ + man/sd_bus_unref.3 \ man/sd_id128_equal.3 \ man/sd_id128_from_string.3 \ man/sd_id128_get_boot.3 \ @@ -239,8 +272,38 @@ man/SD_WARNING.3: man/sd-daemon.3 man/init.1: man/systemd.1 man/poweroff.8: man/halt.8 man/reboot.8: man/halt.8 +man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_audit_session_id.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_cgroup.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_cmdline.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_comm.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_exe.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_gid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_owner_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_pid_starttime.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_selinux_context.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_session.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_slice.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_tid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_tid_comm.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_unique_name.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_user_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_well_known_names.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_bounding_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_effective_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_inheritable_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_permitted_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_default_system.3: man/sd_bus_open_user.3 +man/sd_bus_default_user.3: man/sd_bus_open_user.3 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 +man/sd_bus_open_system.3: man/sd_bus_open_user.3 +man/sd_bus_open_system_container.3: man/sd_bus_open_user.3 +man/sd_bus_open_system_remote.3: man/sd_bus_open_user.3 +man/sd_bus_ref.3: man/sd_bus_new.3 man/sd_bus_release_name.3: man/sd_bus_request_name.3 +man/sd_bus_unref.3: man/sd_bus_new.3 man/sd_id128_equal.3: man/sd-id128.3 man/sd_id128_from_string.3: man/sd_id128_to_string.3 man/sd_id128_get_boot.3: man/sd_id128_get_machine.3 @@ -399,12 +462,102 @@ man/poweroff.html: man/halt.html man/reboot.html: man/halt.html $(html-alias) +man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_audit_session_id.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_cgroup.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_cmdline.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_comm.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_exe.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_gid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_owner_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_pid_starttime.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_selinux_context.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_session.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_slice.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_tid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_tid_comm.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_unique_name.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_unit.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_user_unit.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_well_known_names.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_bounding_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_effective_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_inheritable_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_permitted_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_default_system.html: man/sd_bus_open_user.html + $(html-alias) + +man/sd_bus_default_user.html: man/sd_bus_open_user.html + $(html-alias) + man/sd_bus_message_get_reply_cookie.html: man/sd_bus_message_get_cookie.html $(html-alias) +man/sd_bus_open_system.html: man/sd_bus_open_user.html + $(html-alias) + +man/sd_bus_open_system_container.html: man/sd_bus_open_user.html + $(html-alias) + +man/sd_bus_open_system_remote.html: man/sd_bus_open_user.html + $(html-alias) + +man/sd_bus_ref.html: man/sd_bus_new.html + $(html-alias) + man/sd_bus_release_name.html: man/sd_bus_request_name.html $(html-alias) +man/sd_bus_unref.html: man/sd_bus_new.html + $(html-alias) + man/sd_id128_equal.html: man/sd-id128.html $(html-alias) @@ -1112,7 +1265,10 @@ EXTRA_DIST += \ man/sd-login.xml \ man/sd-readahead.xml \ man/sd_booted.xml \ + man/sd_bus_creds_get_pid.xml \ man/sd_bus_message_get_cookie.xml \ + man/sd_bus_new.xml \ + man/sd_bus_open_user.xml \ man/sd_bus_request_name.xml \ man/sd_get_seats.xml \ man/sd_id128_get_machine.xml \ diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml new file mode 100644 index 0000000000..9de5001d49 --- /dev/null +++ b/man/sd_bus_creds_get_pid.xml @@ -0,0 +1,445 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- +This file is part of systemd. + +Copyright 2014 Zbigniew Jędrzejewski-Szmek + +systemd is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or +(at your option) any later version. + +systemd is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_creds_get_pid"> + + <refentryinfo> + <title>sd_bus_creds_get_pid</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </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_pid_starttime</refname> + <refname>sd_bus_creds_get_tid</refname> + <refname>sd_bus_creds_get_uid</refname> + <refname>sd_bus_creds_get_gid</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_user_unit</refname> + <refname>sd_bus_creds_get_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_unique_name</refname> + <refname>sd_bus_creds_get_well_known_names</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_pid_starttime</function></funcdef> + <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</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_pid</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_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_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_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_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> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Those functions return information from an + <parameter>sd_bus_creds</parameter> object. It may be created with + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case it will describe the specified process, or it may be + created by + <citerefentry><refentrytitle>sd_bus_get_peer_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case it will describe the process at the other endpoint + of a connection. + </para> + + <para><function>sd_bus_creds_get_pid</function> will retrieve the + PID (process identifier).</para> + + <para><function>sd_bus_creds_get_pid_starttime</function> will + retrieve the time since the start of the epoch in microseconds + since the process was started.</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 + UID (user identifier).</para> + + <para><function>sd_bus_creds_get_gid</function> will retrieve the + GID (group identifier).</para> + + <para><function>sd_bus_creds_get_comm</function> will retrieve the + comm field (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 (as stored in the + <filename>/proc/<replaceable>pid</replaceable>/exe</filename> + link, but with <literal> (deleted)</literal> suffix removed). + </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>). + </para> + + <para><function>sd_bus_creds_get_cgroup</function> will retrieve + the cgroup path. See <ulink + url="https://www.kernel.org/doc/Documentation/cgroups/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 part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </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 part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </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 part of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para><function>sd_bus_creds_get_session</function> will retrieve + the logind session that the process is part of. See + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para><function>sd_bus_creds_get_owner_uid</function> will retrieve + the UID (user identifier) of the user who owns the slice + that the process is part of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <!-- and + <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->. + </para> + + <para><function>sd_bus_creds_has_effective_cap</function> will + check whether all of the capabilities specified by + <parameter>capability</parameter> were set in the effective + capabilities mask. A positive return value means that they were + set, zero means that they were not set, and a negative return + value signifies an error. See + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and <varname>Capabilities=</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 context of the process.</para> + + <para><function>sd_bus_creds_get_audit_session_id</function> will + retrieve the audit session identifier of the process.</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).</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>All functions that take a <parameter>const + char**</parameter> parameter will store the answer there as an + address of a NUL-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 a an array + of strings. Each invidividual string is NUL-terminated, and the + array is NULL-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> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><varname>-ENODATA</varname></term> + + <listitem><para>Given field is not available in + <parameter>c</parameter>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>-ENOENT</varname></term> + + <listitem><para>Given field is not specified for the sender. + This will be returned by <function>sd_bus_get_unit</function>, + <function>sd_bus_get_user_unit</function>, + <function>sd_bus_get_slice</function>, + <function>sd_bus_get_session</function>, and + <function>sd_bus_get_owner_uid</function> if the sender is not + part of a systemd system unit, systemd user unit, systemd + slice, logind session, or a systemd user session.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>-EINVAL</varname></term> + + <listitem><para>Specified pointer parameter is <constant>NULL</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>-ENOMEM</varname></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_open_user()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <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>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml new file mode 100644 index 0000000000..1931424b86 --- /dev/null +++ b/man/sd_bus_new.xml @@ -0,0 +1,145 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- +This file is part of systemd. + +Copyright 2014 Zbigniew Jędrzejewski-Szmek + +systemd is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or +(at your option) any later version. + +systemd is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_new"> + + <refentryinfo> + <title>sd_bus_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_new</refname> + <refname>sd_bus_ref</refname> + <refname>sd_bus_unref</refname> + + <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_new</function></funcdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_ref</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_unref</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_new()</function> creates a new bus + object. This object is reference counted, and will be destroyed + when all references are gone. Initially, the caller of this + function owns the sole reference.</para> + + <para><function>sd_bus_ref()</function> creates a new reference to + <parameter>bus</parameter>. This bus object will not be destroyed + until <function>sd_bus_unref()</function> has been called as many + times plus once more. Once the reference count has dropped to + zero, <parameter>bus</parameter> cannot be used anymore, so + further calls to <function>sd_bus_ref()</function> or + <function>sd_bus_unref()</function> are illegal.</para> + + <para><function>sd_bus_unref()</function> destroyes a reference to + <parameter>bus</parameter>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_new()</function> returns 0 or a + positive integer. On failure, it returns a negative errno-style + error code.</para> + + <para><function>sd_bus_ref</function> always returns the argument. + </para> + + <para><function>sd_bus_unref</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><varname>-ENOMEM</varname></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_new()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <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_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_open_user.xml b/man/sd_bus_open_user.xml new file mode 100644 index 0000000000..62b856993d --- /dev/null +++ b/man/sd_bus_open_user.xml @@ -0,0 +1,217 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- +This file is part of systemd. + +Copyright 2014 Zbigniew Jędrzejewski-Szmek + +systemd is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or +(at your option) any later version. + +systemd is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License +along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_open_user"> + + <refentryinfo> + <title>sd_bus_open_user</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_open_user</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_open_user</refname> + <refname>sd_bus_open_system</refname> + <refname>sd_bus_open_system_remote</refname> + <refname>sd_bus_open_system_container</refname> + + <refname>sd_bus_default_user</refname> + <refname>sd_bus_default_system</refname> + + <refpurpose>Open a connection to the system or user bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_open_user</function></funcdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system</function></funcdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> + <paramdef>const char *<parameter>host</parameter></paramdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_container</function></funcdef> + <paramdef>const char *<parameter>machine</parameter></paramdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_default_user</function></funcdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_default_system</function></funcdef> + <paramdef>sd_bus** <parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_open_user()</function> creates a new bus + object and opens a connection to the the user bus. + <function>sd_bus_open_system()</function> does the same, but + connects to the system bus.</para> + + <para>If <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment + variable is set + (c.f. <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + it will be used as the address of the user bus. This variable can + contain multiple addresses separated by <literal>;</literal>. If + this variable is not set, a suitable default for the default user + D-Bus instance will be used.</para> + + <para>If <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment + variable is set, it will be used as the address of the system + bus. This variable uses the same syntax as + <varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is + not set, a suitable default for the default system D-Bus instance + will be used.</para> + + <para><function>sd_bus_open_system_remote()</function> connects to + the system bus on the specified <parameter>host</parameter> using + SSH. <parameter>host</parameter> consists of an optional user name + followed by the <literal>@</literal> symbol, and the hostname. + </para> + + <para><function>sd_bus_open_system_remote()</function> connects to + the system bus in the specified <parameter>machine</parameter>, + where <parameter>machine</parameter> is the name of a container. + See + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more information about "machines".</para> + + <para><function>sd_bus_default_user()</function> returns a bus + object connected to the user bus. This bus object is shared + per-thread. It is created on the first invocation of + <function>sd_bus_default_user()</function>, and subsequent + invocations returns a reference to the same object.</para> + + <para><function>sd_bus_default_system()</function> is similar to + <function>sd_bus_default_user()</function>, but connects to the + system bus.</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> + </refsect1> + + <refsect1> + <title>Reference ownership</title> + <para>Functions <function>sd_bus_open_user()</function>, + <function>sd_bus_open_system()</function>, + <function>sd_bus_open_system_remote()</function>, and + <function>sd_bus_open_system_machine()</function> return a new + object and the caller owns the sole reference. When not needed + anymore, this reference should be destroyed with + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>Functions <function>sd_bus_default_user()</function> and + <function>sd_bus_default_system()</function> do not create a new + reference.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><varname>-EINVAL</varname></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>-ENOMEM</varname></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + <para>In addition, any further connection-related errors may be + by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_open_user()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/libsystemd-bus/sd-bus.c b/src/libsystemd-bus/sd-bus.c index 61dc0e56a8..c2f77a990f 100644 --- a/src/libsystemd-bus/sd-bus.c +++ b/src/libsystemd-bus/sd-bus.c @@ -1234,7 +1234,7 @@ _public_ void sd_bus_close(sd_bus *bus) { /* We'll leave the fd open in case this is a kernel bus, since * there might still be memblocks around that reference this - * bus, and they might need to invoke the * KDBUS_CMD_FREE + * bus, and they might need to invoke the KDBUS_CMD_FREE * ioctl on the fd when they are freed. */ } diff --git a/src/systemd/sd-bus.h b/src/systemd/sd-bus.h index b3b92ad612..1134b58437 100644 --- a/src/systemd/sd-bus.h +++ b/src/systemd/sd-bus.h @@ -286,11 +286,11 @@ int sd_bus_creds_get_pid_starttime(sd_bus_creds *c, uint64_t *usec); int sd_bus_creds_get_tid(sd_bus_creds *c, pid_t *tid); int sd_bus_creds_get_uid(sd_bus_creds *c, uid_t *uid); int sd_bus_creds_get_gid(sd_bus_creds *c, gid_t *gid); -int sd_bus_creds_get_comm(sd_bus_creds *c, const char **r); -int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **r); -int sd_bus_creds_get_exe(sd_bus_creds *c, const char **r); +int sd_bus_creds_get_comm(sd_bus_creds *c, const char **comm); +int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **comm); +int sd_bus_creds_get_exe(sd_bus_creds *c, const char **exe); int sd_bus_creds_get_cmdline(sd_bus_creds *c, char ***cmdline); -int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **r); +int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **cgroup); int sd_bus_creds_get_unit(sd_bus_creds *c, const char **unit); int sd_bus_creds_get_user_unit(sd_bus_creds *c, const char **unit); int sd_bus_creds_get_slice(sd_bus_creds *c, const char **slice); @@ -300,7 +300,7 @@ int sd_bus_creds_has_effective_cap(sd_bus_creds *c, int capability); int sd_bus_creds_has_permitted_cap(sd_bus_creds *c, int capability); int sd_bus_creds_has_inheritable_cap(sd_bus_creds *c, int capability); int sd_bus_creds_has_bounding_cap(sd_bus_creds *c, int capability); -int sd_bus_creds_get_selinux_context(sd_bus_creds *c, const char **r); +int sd_bus_creds_get_selinux_context(sd_bus_creds *c, const char **context); int sd_bus_creds_get_audit_session_id(sd_bus_creds *c, uint32_t *sessionid); int sd_bus_creds_get_audit_login_uid(sd_bus_creds *c, uid_t *loginuid); int sd_bus_creds_get_unique_name(sd_bus_creds *c, const char **name); |