diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/custom-html.xsl | 186 | ||||
| -rw-r--r-- | man/sd-bus-errors.xml | 309 | ||||
| -rw-r--r-- | man/sd_bus_creds_get_pid.xml | 59 | ||||
| -rw-r--r-- | man/sd_bus_creds_new_from_pid.xml | 150 | ||||
| -rw-r--r-- | man/sd_bus_default.xml | 66 | ||||
| -rw-r--r-- | man/sd_bus_error.xml | 344 | ||||
| -rw-r--r-- | man/sd_bus_error_add_map.xml | 173 | ||||
| -rw-r--r-- | man/sd_bus_message_append.xml | 64 | ||||
| -rw-r--r-- | man/sd_bus_message_append_array.xml | 123 | ||||
| -rw-r--r-- | man/sd_bus_message_append_basic.xml | 51 | ||||
| -rw-r--r-- | man/sd_bus_negotiate_fds.xml | 2 | ||||
| -rw-r--r-- | man/sd_bus_new.xml | 16 | ||||
| -rw-r--r-- | man/sd_bus_request_name.xml | 15 | ||||
| -rw-r--r-- | man/sd_pid_get_session.xml | 83 | ||||
| -rw-r--r-- | man/systemd.journal-fields.xml | 1 | ||||
| -rw-r--r-- | man/systemd.netdev.xml | 10 | ||||
| -rw-r--r-- | man/systemd.preset.xml | 2 |
17 files changed, 1175 insertions, 479 deletions
diff --git a/man/custom-html.xsl b/man/custom-html.xsl index b298c216b1..151276362c 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -22,6 +22,16 @@ <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> +<!-- + - The docbook stylesheet injects empty anchor tags into generated HTML, identified by an auto-generated ID. + - Ask the docbook stylesheet to generate reproducible output when generating (these) ID values. + - This makes the output of this stylesheet reproducible across identical invocations on the same input, + - which is an easy and significant win for achieving reproducible builds. + - + - It may be even better to strip the empty anchors from the document output in addition to turning on consistent IDs, + - for this stylesheet contains its own custom ID logic (for generating permalinks) already. + --> +<xsl:param name="generate.consistent.ids" select="1"/> <!-- translate man page references to links to html pages --> <xsl:template match="citerefentry[not(@project)]"> @@ -113,80 +123,122 @@ </a> </xsl:template> -<xsl:template match="refsect1/title|refsect1/info/title"> - <!-- the ID is output in the block.object call for refsect1 --> - <h2> +<!-- + - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template + - this conflict resolution is necessary to prevent malformed HTML ouput (multiple id attributes with the same value) + - and it fixes xsltproc warnings during compilation of HTML man pages + - + - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output. + - It uses two parameters: + templateID the proposed ID string to use which must be checked for conflicts + keyNode the context node which 'produced' the given templateID. + - + - Conflicts are detected solely based on keyNode, templateID is not taken into account for that purpose. + --> +<xsl:template name="generateID"> + <!-- node which generatedID needs to assume as the 'source' of the ID --> + <xsl:param name="keyNode"/> + <!-- suggested value for generatedID output, a contextually meaningful ID string --> + <xsl:param name="templateID"/> + <xsl:variable name="conflictSource" select="preceding::refsect1/title|preceding::refsect1/info/title| + preceding::refsect2/title|preceding::refsect2/info/title| + preceding::varlistentry/term[1]"/> + <xsl:variable name="conflictCount" select="count($conflictSource[. = $keyNode])"/> + <xsl:choose> + <!-- special case conflictCount = 0 to preserve compatibility with URLs generated by previous versions of this XSL stylesheet where possible --> + <xsl:when test="$conflictCount = 0"> + <xsl:value-of select="$templateID"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($templateID, $conflictCount)"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- + - a helper template to abstract over the structure of generated subheading + permalink HTML output + - It helps reduce tedious repetition and groups all actual markup output (as opposed to URL/ID logic) in a single location. + --> +<xsl:template name="permalink"> + <xsl:param name="nodeType"/> <!-- local name of the element node to generate, e.g. 'h2' for <h2></h2> --> + <xsl:param name="nodeContent"/> <!-- nodeset to apply further templates to obtain the content of the subheading/term --> + <xsl:param name="linkTitle"/> <!-- value for title attribute of generated permalink, e.g. 'this is a permalink' --> + + <!-- parameters passed to generateID template, otherwise unused. --> + <xsl:param name="keyNode"/> + <xsl:param name="templateID"/> + + <!-- + - If stable URLs with fragment markers (references to the ID) turn out not to be important: + - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely. + - Alternatively if xsltproc is patched to generate reproducible generate-id() output the same simplifications can be + - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet. + --> + <xsl:variable name="generatedID"> + <xsl:call-template name="generateID"> + <xsl:with-param name="keyNode" select="$keyNode"/> + <xsl:with-param name="templateID" select="$templateID"/> + </xsl:call-template> + </xsl:variable> + + <xsl:element name="{$nodeType}"> <xsl:attribute name="id"> - <xsl:call-template name="inline.charseq"/> + <xsl:value-of select="$generatedID"/> </xsl:attribute> - <xsl:apply-templates/> - <a> - <xsl:attribute name="class"> - <xsl:text>headerlink</xsl:text> - </xsl:attribute> - <xsl:attribute name="title"> - <xsl:text>Permalink to this headline</xsl:text> - </xsl:attribute> - <xsl:attribute name="href"> - <xsl:text>#</xsl:text> - <xsl:call-template name="inline.charseq"/> - </xsl:attribute> - <xsl:text>¶</xsl:text> - </a> - </h2> + <xsl:apply-templates select="$nodeContent"/> + <a class="headerlink" title="{$linkTitle}" href="#{$generatedID}">¶</a> + </xsl:element> </xsl:template> -<xsl:template match="refsect2/title|refsect2/info/title"> - <h3> - <xsl:attribute name="id"> +<!-- simple wrapper around permalink to avoid repeating common info for each level of subheading covered by the permalink logic (h2, h3) --> +<xsl:template name="headerlink"> + <xsl:param name="nodeType"/> + <xsl:call-template name="permalink"> + <xsl:with-param name="nodeType" select="$nodeType"/> + <xsl:with-param name="linkTitle" select="'Permalink to this headline'"/> + <xsl:with-param name="nodeContent" select="node()"/> + <xsl:with-param name="keyNode" select="."/> + <!-- + - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called. + - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text). + - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it. + --> + <xsl:with-param name="templateID"> <xsl:call-template name="inline.charseq"/> - </xsl:attribute> - <xsl:apply-templates/> - <a> - <xsl:attribute name="class"> - <xsl:text>headerlink</xsl:text> - </xsl:attribute> - <xsl:attribute name="title"> - <xsl:text>Permalink to this headline</xsl:text> - </xsl:attribute> - <xsl:attribute name="href"> - <xsl:text>#</xsl:text> - <xsl:call-template name="inline.charseq"/> - </xsl:attribute> - <xsl:text>¶</xsl:text> - </a> - </h3> + </xsl:with-param> + </xsl:call-template> +</xsl:template> + +<xsl:template match="refsect1/title|refsect1/info/title"> + <!-- the ID is output in the block.object call for refsect1 --> + <xsl:call-template name="headerlink"> + <xsl:with-param name="nodeType" select="'h2'"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="refsect2/title|refsect2/info/title"> + <xsl:call-template name="headerlink"> + <xsl:with-param name="nodeType" select="'h3'"/> + </xsl:call-template> </xsl:template> <xsl:template match="varlistentry"> - <dt> - <xsl:attribute name="id"> + <xsl:call-template name="permalink"> + <xsl:with-param name="nodeType" select="'dt'"/> + <xsl:with-param name="linkTitle" select="'Permalink to this term'"/> + <xsl:with-param name="nodeContent" select="term"/> + <xsl:with-param name="keyNode" select="term[1]"/> + <!-- + - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called. + - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text). + - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it. + --> + <xsl:with-param name="templateID"> <xsl:call-template name="inline.charseq"> - <xsl:with-param name="content"> - <xsl:copy-of select="term[position()=1]" /> - </xsl:with-param> + <xsl:with-param name="content" select="term[1]"/> </xsl:call-template> - </xsl:attribute> - <xsl:apply-templates select="term"/> - <a> - <xsl:attribute name="class"> - <xsl:text>headerlink</xsl:text> - </xsl:attribute> - <xsl:attribute name="title"> - <xsl:text>Permalink to this term</xsl:text> - </xsl:attribute> - <xsl:attribute name="href"> - <!-- <xsl:call-template name="href.target.uri" /> --> - <xsl:text>#</xsl:text> - <xsl:call-template name="inline.charseq"> - <xsl:with-param name="content"> - <xsl:copy-of select="term[position()=1]" /> - </xsl:with-param> - </xsl:call-template> - </xsl:attribute> - <xsl:text>¶</xsl:text> - </a> - </dt> + </xsl:with-param> + </xsl:call-template> <dd> <xsl:apply-templates select="listitem"/> </dd> @@ -225,12 +277,6 @@ <xsl:text>systemd.directives.html</xsl:text> </xsl:attribute> <xsl:text>Directives </xsl:text> - </a>· - <a> - <xsl:attribute name="href"> - <xsl:text>../python-systemd/index.html</xsl:text> - </xsl:attribute> - <xsl:text>Python </xsl:text> </a> <span style="float:right"> diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml new file mode 100644 index 0000000000..d6bbd7fbb2 --- /dev/null +++ b/man/sd-bus-errors.xml @@ -0,0 +1,309 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!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 2015 Lennart Poettering + + 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-errors"> + + <refentryinfo> + <title>sd-bus-errors</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-bus-errors</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-bus-errors</refname> + <refname>SD_BUS_ERROR_FAILED</refname> + <refname>SD_BUS_ERROR_NO_MEMORY</refname> + <refname>SD_BUS_ERROR_SERVICE_UNKNOWN</refname> + <refname>SD_BUS_ERROR_NAME_HAS_NO_OWNER</refname> + <refname>SD_BUS_ERROR_NO_REPLY</refname> + <refname>SD_BUS_ERROR_IO_ERROR</refname> + <refname>SD_BUS_ERROR_BAD_ADDRESS</refname> + <refname>SD_BUS_ERROR_NOT_SUPPORTED</refname> + <refname>SD_BUS_ERROR_LIMITS_EXCEEDED</refname> + <refname>SD_BUS_ERROR_ACCESS_DENIED</refname> + <refname>SD_BUS_ERROR_AUTH_FAILED</refname> + <refname>SD_BUS_ERROR_NO_SERVER</refname> + <refname>SD_BUS_ERROR_TIMEOUT</refname> + <refname>SD_BUS_ERROR_NO_NETWORK</refname> + <refname>SD_BUS_ERROR_ADDRESS_IN_USE</refname> + <refname>SD_BUS_ERROR_DISCONNECTED</refname> + <refname>SD_BUS_ERROR_INVALID_ARGS</refname> + <refname>SD_BUS_ERROR_FILE_NOT_FOUND</refname> + <refname>SD_BUS_ERROR_FILE_EXISTS</refname> + <refname>SD_BUS_ERROR_UNKNOWN_METHOD</refname> + <refname>SD_BUS_ERROR_UNKNOWN_OBJECT</refname> + <refname>SD_BUS_ERROR_UNKNOWN_INTERFACE</refname> + <refname>SD_BUS_ERROR_UNKNOWN_PROPERTY</refname> + <refname>SD_BUS_ERROR_PROPERTY_READ_ONLY</refname> + <refname>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</refname> + <refname>SD_BUS_ERROR_INVALID_SIGNATURE</refname> + <refname>SD_BUS_ERROR_INCONSISTENT_MESSAGE</refname> + <refname>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</refname> + <refname>SD_BUS_ERROR_MATCH_RULE_INVALID</refname> + <refname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</refname> + + <refpurpose>Standard D-Bus error names</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + +<funcsynopsisinfo>#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" +#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" +#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" +#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" +#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" +#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" +#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" +#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" +#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" +#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" +#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" +#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" +#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" +#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" +#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" +#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" +#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" +#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" +#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" +#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" +#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" +#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" +#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" +#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" +#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" +#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" +#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" +#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" +#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" +#define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \ + "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired"</funcsynopsisinfo> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>In addition to the error names user programs define, D-Bus + knows a number of generic, standardized error names, that are + listed below.</para> + + <para>In addition to this list, in sd-bus the special error + namespace <literal>System.Error.</literal> is used to map + arbitrary Linux system errors (as defined by <citerefentry + project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + to D-Bus errors and back. For example, the error + <constant>EUCLEAN</constant> is mapped to + <literal>System.Error.EUCLEAN</literal> and back.</para> + + <variablelist> + + <varlistentry> + <term><varname>SD_BUS_ERROR_FAILED</varname></term> + <listitem><para>A generic error indication. See the error + message for further details. This error name should be + avoided, in favour of a more expressive error + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_ERROR_NO_MEMORY</varname></term> + <listitem><para>A memory allocation failed, and the requested + operation could not be completed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_ERROR_SERVICE_UNKNOWN</varname></term> + <listitem><para>The contacted bus service is unknown and + cannot be activated.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_ERROR_NAME_HAS_NO_OWNER</varname></term> + <listitem><para>The specified bus service name currently has + no owner.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_NO_REPLY</varname></term> + <listitem><para>A message did not receive a reply. This error + is usually generated after a timeout.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_IO_ERROR</varname></term> + <listitem><para>Generic input/output error, for example when + accessing a socket or other IO context.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_BAD_ADDRESS</varname></term> + <listitem><para>The specified D-Bus bus address string is + malformed.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_NOT_SUPPORTED</varname></term> + <listitem><para>The requested operation is not supported on + the local system.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_LIMITS_EXCEEDED</varname></term> + <listitem><para>Some limited resource has been + exhausted.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_ACCESS_DENIED</varname></term> + <listitem><para>Access to a resource has bee denied, due to security restrictions.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_AUTH_FAILED</varname></term> + <listitem><para>Authentication did not complete successfully.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_NO_SERVER</varname></term> + <listitem><para>Unable to connect to the specified server.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_TIMEOUT</varname></term> + <listitem><para>An operation timed out. Note that method calls + which timeout generate a + <varname>SD_BUS_ERROR_NO_REPLY</varname>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_NO_NETWORK</varname></term> + <listitem><para>No network available to execute requested network operation on.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_ADDRESS_IN_USE</varname></term> + <listitem><para>The specified network address is already being listened on.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_DISCONNECTED</varname></term> + <listitem><para>The connection has been terminated.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_INVALID_ARGS</varname></term> + <listitem><para>One or more invalid arguments have been passed.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_FILE_NOT_FOUND</varname></term> + <listitem><para>The requested file could not be found.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_FILE_EXISTS</varname></term> + <listitem><para>The requested file exists already.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_UNKNOWN_METHOD</varname></term> + <listitem><para>The requested method does not exist in the selected interface.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_UNKNOWN_OBJECT</varname></term> + <listitem><para>The requested object does not exist in the selected service.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_UNKNOWN_INTERFACE</varname></term> + <listitem><para>The requested interface does not exist on the selected object.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_UNKNOWN_PROPERTY</varname></term> + <listitem><para>The requested property does not exist in the selected interface.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_PROPERTY_READ_ONLY</varname></term> + <listitem><para>A write operation was requested on a read-only property.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</varname></term> + <listitem><para>The requested PID is not known.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_INVALID_SIGNATURE</varname></term> + <listitem><para>The specified message signature is not + valid.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_INCONSISTENT_MESSAGE</varname></term> + <listitem><para>The passed message does not validate + correctly.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</varname></term> + <listitem><para>The specified match rule does not exist.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_MATCH_RULE_INVALID</varname></term> + <listitem><para>The specified match rule is invalid.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</varname></term> + <listitem><para>Access to the requested operation is not + permitted, however, it might be available after interactive + authentication. This is usually returned by method calls + supporting a framework for additional interactive + authorization, when interactive authorization was not enabled + with the + <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the method call message.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><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_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 13f885cd5d..4162fab065 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -61,8 +61,9 @@ <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_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> @@ -193,13 +194,19 @@ </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_slice</function></funcdef> + <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> @@ -288,9 +295,9 @@ <refsect1> <title>Description</title> - <para>These functions return information from an - <parameter>sd_bus_creds</parameter> credential object. Credential - objects may be created with + <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 @@ -301,7 +308,13 @@ 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> + 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). Similar, @@ -374,19 +387,22 @@ <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>. + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similar, + <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 logind session that the process is part of. See + retrieve the identifier of the login session that the process is + part of. See <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 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 session that the process is part of. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + the login session that the process is part of. See + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For processes that are not part of a session returns -ENXIO. </para> @@ -395,7 +411,7 @@ <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that is was set, zero means that it was not set, and a negative return - value signifies an error. See + value indicates an error. See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and <varname>Capabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in @@ -427,8 +443,8 @@ processes that are not part of an audit session.</para> <para><function>sd_bus_creds_get_tty()</function> will retrieve - the controlling TTY. Returns -ENXIO for processes that have no - controlling TTY.</para> + 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 @@ -489,8 +505,9 @@ <listitem><para>Given field is not specified for the described process or peer. 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_user_unit()</function>, + <function>sd_bus_get_user_slice()</function>, <function>sd_bus_get_session()</function>, and <function>sd_bus_get_owner_uid()</function> if the process is not part of a systemd system unit, systemd user unit, systemd @@ -526,10 +543,11 @@ <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</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <para><function>sd_bus_creds_get_pid()</function> and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> @@ -539,8 +557,9 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</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>, diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 8c054a5905..a78d3f5717 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_bus_creds_new_from_pid</refname> <refname>sd_bus_creds_get_mask</refname> + <refname>sd_bus_creds_get_augmented_mask</refname> <refname>sd_bus_creds_ref</refname> <refname>sd_bus_creds_unref</refname> @@ -68,6 +69,11 @@ </funcprototype> <funcprototype> + <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> + <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef> <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> @@ -80,17 +86,26 @@ <para> <constant>SD_BUS_CREDS_PID</constant>, + <constant>SD_BUS_CREDS_PPID</constant>, <constant>SD_BUS_CREDS_TID</constant>, <constant>SD_BUS_CREDS_UID</constant>, + <constant>SD_BUS_CREDS_EUID</constant>, + <constant>SD_BUS_CREDS_SUID</constant>, + <constant>SD_BUS_CREDS_FSUID</constant>, <constant>SD_BUS_CREDS_GID</constant>, + <constant>SD_BUS_CREDS_EGID</constant>, + <constant>SD_BUS_CREDS_SGID</constant>, + <constant>SD_BUS_CREDS_FSGID</constant>, + <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, <constant>SD_BUS_CREDS_COMM</constant>, <constant>SD_BUS_CREDS_TID_COMM</constant>, <constant>SD_BUS_CREDS_EXE</constant>, <constant>SD_BUS_CREDS_CMDLINE</constant>, <constant>SD_BUS_CREDS_CGROUP</constant>, <constant>SD_BUS_CREDS_UNIT</constant>, - <constant>SD_BUS_CREDS_USER_UNIT</constant>, <constant>SD_BUS_CREDS_SLICE</constant>, + <constant>SD_BUS_CREDS_USER_UNIT</constant>, + <constant>SD_BUS_CREDS_USER_SLICE</constant>, <constant>SD_BUS_CREDS_SESSION</constant>, <constant>SD_BUS_CREDS_OWNER_UID</constant>, <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, @@ -100,8 +115,11 @@ <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>, + <constant>SD_BUS_CREDS_DESCRIPTION</constant>, + <constant>SD_BUS_CREDS_AUGMENT</constant>, <constant>_SD_BUS_CREDS_ALL</constant> </para> </refsynopsisdiv> @@ -109,25 +127,39 @@ <refsect1> <title>Description</title> - <para><function>sd_bus_creds_new_from_pid()</function> creates a new - credentials object and fills it with information about the process - <parameter>pid</parameter>. This pointer to this object will - be stored in <parameter>ret</parameter> pointer.</para> + <para><function>sd_bus_creds_new_from_pid()</function> creates a + new credentials object and fills it with information about the + process <parameter>pid</parameter>. The pointer to this object + will be stored in <parameter>ret</parameter> pointer. Note that + credential objects may also be created and retrieved via + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para>The information that will be stored is determined by <parameter>creds_mask</parameter>. It may contain a subset of ORed constants <constant>SD_BUS_CREDS_PID</constant>, + <constant>SD_BUS_CREDS_PPID</constant>, <constant>SD_BUS_CREDS_TID</constant>, <constant>SD_BUS_CREDS_UID</constant>, + <constant>SD_BUS_CREDS_EUID</constant>, + <constant>SD_BUS_CREDS_SUID</constant>, + <constant>SD_BUS_CREDS_FSUID</constant>, <constant>SD_BUS_CREDS_GID</constant>, + <constant>SD_BUS_CREDS_EGID</constant>, + <constant>SD_BUS_CREDS_SGID</constant>, + <constant>SD_BUS_CREDS_FSGID</constant>, + <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, <constant>SD_BUS_CREDS_COMM</constant>, <constant>SD_BUS_CREDS_TID_COMM</constant>, <constant>SD_BUS_CREDS_EXE</constant>, <constant>SD_BUS_CREDS_CMDLINE</constant>, <constant>SD_BUS_CREDS_CGROUP</constant>, <constant>SD_BUS_CREDS_UNIT</constant>, - <constant>SD_BUS_CREDS_USER_UNIT</constant>, <constant>SD_BUS_CREDS_SLICE</constant>, + <constant>SD_BUS_CREDS_USER_UNIT</constant>, + <constant>SD_BUS_CREDS_USER_SLICE</constant>, <constant>SD_BUS_CREDS_SESSION</constant>, <constant>SD_BUS_CREDS_OWNER_UID</constant>, <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, @@ -137,34 +169,71 @@ <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>, - or <constant>_SD_BUS_CREDS_ALL</constant> to indicate - all known fields.</para> + <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> + 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 <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other functions which correspond directly to the constants listed above.</para> - <para>A mask of fields which were actually successfully set - (acquired from <filename>/proc</filename>, etc.) can be retrieved - with <function>sd_bus_creds_get_mask()</function>. If the - credentials object was created with + <para>A mask of fields which were actually successfully retrieved + can be retrieved with + <function>sd_bus_creds_get_mask()</function>. If the credentials + object was created with <function>sd_bus_creds_new_from_pid()</function>, this will be a subset of fields requested in <parameter>creds_mask</parameter>. </para> - <para><function>sd_bus_creds_ref</function> creates a new + <para>Similar to <function>sd_bus_creds_get_mask()</function> the + function <function>sd_bus_creds_get_augmented_mask()</function> + returns a bitmask of field constants. The mask indicates which + credential fields have been retrieved in a non-atomic fashion. For + credential objects created via + <function>sd_bus_creds_new_from_pid()</function> this mask will be + identical to the mask returned by + <function>sd_bus_creds_get_mask()</function>. However, for + credential objects retrieved via + <function>sd_bus_get_name_creds()</function> this mask will be set + for the credential fields that could not be determined atomically + at peer connection time, and which were later added by reading + augmenting credential data from + <filename>/proc</filename>. Similar, for credential objects + retrieved via <function>sd_bus_get_owner_creds()</function> the + mask is set for the fields that could not be determined atomically + at bus creation time, but have been augmented. Similar, for + credential objects retrieved via + <function>sd_bus_message_get_creds()</function> the mask is set + for the fields that could not be determined atomically at message + send 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><function>sd_bus_creds_ref()</function> creates a new reference to the credentials object <parameter>c</parameter>. This object will not be destroyed until - <function>sd_bus_creds_unref</function> has been called as many + <function>sd_bus_creds_unref()</function> has been called as many times plus once more. Once the reference count has dropped to zero, <parameter>c</parameter> cannot be used anymore, so further calls to <function>sd_bus_creds_ref(c)</function> or <function>sd_bus_creds_unref(c)</function> are illegal.</para> - <para><function>sd_bus_creds_unref</function> destroys a reference + <para><function>sd_bus_creds_unref()</function> destroys a reference to <parameter>c</parameter>.</para> </refsect1> @@ -178,10 +247,15 @@ <para><function>sd_bus_creds_get_mask()</function> returns the mask of successfully acquired fields.</para> - <para><function>sd_bus_creds_ref</function> always returns the + <para><function>sd_bus_creds_get_augmented_mask()</function> + returns the mask of fields that have been augmented from data in + <filename>/proc</filename>, and are thus not suitable for + authorization decisions.</para> + + <para><function>sd_bus_creds_ref()</function> always returns the argument.</para> - <para><function>sd_bus_creds_unref</function> always returns + <para><function>sd_bus_creds_unref()</function> always returns <constant>NULL</constant>.</para> </refsect1> @@ -222,16 +296,23 @@ <listitem><para>Memory allocation failed.</para></listitem> </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>One of the requested fields is unknown to the local system.</para></listitem> + </varlistentry> </variablelist> </refsect1> <refsect1> <title>Notes</title> - <para><function>sd_bus_creds_new_from_pid()</function> is - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <para><function>sd_bus_creds_new_from_pid()</function> and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> @@ -241,31 +322,10 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_tid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_gid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_tid_comm</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_exe</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_cmdline</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_cgroup</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_user_unit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_slice</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_has_effective_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_has_permitted_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_has_inheritable_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_has_bounding_cap</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_selinux_context</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_audit_session_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_audit_login_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_unique_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_well_known_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 95b347bdfd..1cf2cb8f9a 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -111,9 +111,9 @@ <para><function>sd_bus_default()</function> acquires a bus connection object to the user bus when invoked in user context, or to the system bus otherwise. The connection object is associated - to the calling thread. Each time the function is invoked from the - same thread the same object is returned, but its reference count - is increased by one, as long as at least one reference is + with the calling thread. Each time the function is invoked from + the same thread the same object is returned, but its reference + count is increased by one, as long as at least one reference is kept. When the last reference to the connection is dropped (using the <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> @@ -121,10 +121,11 @@ not automatically terminated when the associated thread ends. It is important to drop the last reference to the bus connection explicitly before the thread ends or otherwise the connection will - be leaked.</para> + be leaked. Also, queued but unread or unwritten messages keep the + bus referenced, see below.</para> <para><function>sd_bus_default_user()</function> returns a user - bus connection object associated to the calling thread. + bus connection object associated with the calling thread. <function>sd_bus_default_system()</function> is similar, but connects to the system bus. Note that <function>sd_bus_default()</function> is identical to these two @@ -193,32 +194,63 @@ </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>The functions <function>sd_bus_open()</function>, <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 + connection 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>The functions <function>sd_bus_default()</function>, <function>sd_bus_default_user()</function> and <function>sd_bus_default_system()</function> do not necessarily - create a new object, but increase the connection reference by - one. Use + create a new object, but increase the connection reference of an + existing connection object by one. Use <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to drop the reference.</para> + + <para>Queued but unwritten/unread messages also keep a reference + to their bus connection object. For this reason, even if an + application dropped all references to a bus connection it might + not get destroyed right-away. Until all incoming queued + messages are read, and until all outgoing unwritten messages are + written, the bus object will stay + alive. <function>sd_bus_flush()</function> may be used to write + all outgoing queued messages so they drop their references. To + flush the unread incoming messages use + <function>sd_bus_close()</function>, which will also close the bus + connection. When using the default bus logic it is a good idea to + first invoke <function>sd_bus_flush()</function> followed by + <function>sd_bus_close()</function> when a thread or process + terminates, and thus its bus connection object should be + freed.</para> + + <para>The life-cycle of the default bus connection should be the + responsibility of the code that creates/owns the thread the + default bus connection object is associated with. Library code + should neither call <function>sd_bus_flush()</function> nor + <function>sd_bus_close()</function> on default bus objects unless + it does so in its own private, self-allocated thread. Library code + should not use the default bus object in other threads unless it + is clear that the program using it will life-cycle the bus + connection object and flush and close it before exiting from the + thread. In libraries where it is not clear that the calling + program will life-cycle the bus connection object it is hence + recommended to use <function>sd_bus_open_system()</function> + instead of <function>sd_bus_default_system()</function> and + related calls.</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> diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index b8cb339cec..6dc4541eb1 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -44,11 +44,15 @@ <refnamediv> <refname>sd_bus_error</refname> + <refname>SD_BUS_ERROR_MAKE_CONST</refname> + <refname>SD_BUS_ERROR_NULL</refname> <refname>sd_bus_error_free</refname> <refname>sd_bus_error_set</refname> + <refname>sd_bus_error_setf</refname> <refname>sd_bus_error_set_const</refname> <refname>sd_bus_error_set_errno</refname> <refname>sd_bus_error_set_errnof</refname> + <refname>sd_bus_error_set_errnofv</refname> <refname>sd_bus_error_get_errno</refname> <refname>sd_bus_error_copy</refname> <refname>sd_bus_error_is_set</refname> @@ -75,7 +79,7 @@ </para> <funcprototype> - <funcdef>int <function>sd_bus_error_free</function></funcdef> + <funcdef>void <function>sd_bus_error_free</function></funcdef> <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> </funcprototype> @@ -116,6 +120,14 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>va_list ap</paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_error_get_errno</function></funcdef> <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> </funcprototype> @@ -138,234 +150,194 @@ </funcprototype> </funcsynopsis> - <para> - <constant>SD_BUS_ERROR_FAILED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NO_MEMORY</constant> - </para> - <para> - <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NO_REPLY</constant> - </para> - <para> - <constant>SD_BUS_ERROR_IO_ERROR</constant> - </para> - <para> - <constant>SD_BUS_ERROR_BAD_ADDRESS</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_ACCESS_DENIED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_AUTH_FAILED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NO_SERVER</constant> - </para> - <para> - <constant>SD_BUS_ERROR_TIMEOUT</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NO_NETWORK</constant> - </para> - <para> - <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant> - </para> - <para> - <constant>SD_BUS_ERROR_DISCONNECTED</constant> - </para> - <para> - <constant>SD_BUS_ERROR_INVALID_ARGS</constant> - </para> - <para> - <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant> - </para> - <para> - <constant>SD_BUS_ERROR_FILE_EXISTS</constant> - </para> - <para> - <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant> - </para> - <para> - <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant> - </para> - <para> - <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant> - </para> - <para> - <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant> - </para> - <para> - <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant> - </para> - <para> - <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant> - </para> - <para> - <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant> - </para> - <para> - <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant> - </para> - <para> - <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant> - </para> - <para> - <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant> - </para> - </refsynopsisdiv> <refsect1> <title>Description</title> <para>The <structname>sd_bus_error</structname> structure carries - information for a <filename>sd-bus</filename> error. The - functions described below can be used to set and query fields in - this structure. The <structfield>name</structfield> field contains a - short identifier of an error. It should follow the rules for error - names described in the D-Bus specification, subsection <ulink + information about a D-Bus error condition. The functions described + below may be used to set and query fields in this structure. The + <structfield>name</structfield> field contains a short identifier + of an error. It should follow the rules for error names described + in the D-Bus specification, subsection <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid - Names</ulink>. The <structfield>message</structfield> is a human - readable string describing the details. When no longer necessary, - resources held by this structure should be destroyed with - <function>sd_bus_error_free</function>.</para> - - <para><function>sd_bus_error_set</function> will return an - errno-like negative value returned based on parameter - <parameter>name</parameter> (see - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>). - Various well-known D-Bus errors are converted to specific values, - and the remaining ones to <constant>-ENXIO</constant>. Well-known - D-Bus error names are available as constants - <constant>SD_BUS_ERROR_FAILED</constant>, etc., listed above. If + Names</ulink>. A number of common, standardized error names are + described in + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but additional domain-specific errors may be defined by + applications. The <structfield>message</structfield> field usually + contains a human readable string describing the details, but might + be NULL. An unset <structname>sd_bus_error</structname> structure + should have both fields initialized to NULL. Set an error + structure to <constant>SD_BUS_ERROR_NULL</constant> in order to + reset both fields to NULL. When no longer necessary, resources + held by the <structname>sd_bus_error</structname>structure should + be destroyed with <function>sd_bus_error_free()</function>.</para> + + <para><function>sd_bus_error_set()</function> sets an error + structure to the specified name and message strings. The strings + will be copied into internal, newly allocated memory. It is + essential to free the error structure again when it is not + required anymore (see above). The function will return an + <varname>errno</varname>-like negative value (see <citerefentry + project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known <varname>errno</varname> + counterparts, and the other ones to <constant>-EIO</constant>. See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a list of well-known error names. Additional error mappings + may be defined with + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + <parameter>e</parameter> is NULL no error structure is initialized + but the error is still converted into an + <varname>errno</varname>-style error. If <parameter>name</parameter> is <constant>NULL</constant>, it is assumed that no error occurred, and 0 is returned. This means that this function may be conveniently used in a - <function>return</function> statement.</para> - - <para>If <parameter>e</parameter> is not - <constant>NULL</constant>, <structfield>name</structfield> and - <structfield>message</structfield> in the - <structname>sd_bus_error</structname> structure - <parameter>e</parameter> points at will be filled in. As described above, - <parameter>name</parameter> may be <constant>NULL</constant>, - which is treated as no error. Parameter - <parameter>message</parameter> may also be - <constant>NULL</constant>, in which case no message is specified. - <function>sd_bus_error_set</function> will make internal copies of - specified strings.</para> - - <para><function>sd_bus_error_setf</function> is similar to - <function>sd_bus_error_set</function>, but takes a - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - format string and corresponding arguments to generate - <structname>message</structname>.</para> - - <para><function>sd_bus_error_set_const</function> is similar to - <function>sd_bus_error_set</function>, but string parameters are - not copied internally, and must remain valid for the lifetime of - <parameter>e</parameter>.</para> - - <para><function>sd_bus_error_set_errno</function> will set - <structfield>name</structfield> based on an errno-like value. - <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <function>return</function> statement. If + <parameter>message</parameter> is NULL no message is set. This + call can fail if no memory may be allocated for the name and + message strings, in which case an + <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set + instead and -ENOMEM returned. Do not use this call on error + structures that are already initialized. If you intend to reuse an + error structure free the old data stored in it with + <function>sd_bus_error_free()</function> first.</para> + + <para><function>sd_bus_error_setf()</function> is similar to + <function>sd_bus_error_set()</function>, but takes a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string and corresponding arguments to generate the + <structfield>message</structfield> field.</para> + + <para><function>sd_bus_error_set_const()</function> is similar to + <function>sd_bus_error_set()</function>, but the string parameters + are not copied internally, and must hence remain constant and + valid for the lifetime of <parameter>e</parameter>. Use this call + to avoid memory allocations when setting error structures. Since + this call does not allocate memory it will not fail with an + out-of-memory condition, as + <function>sd_bus_error_set()</function> can, as described + above. Alternatively, the + <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used + to generate a literal, constant bus error structure + on-the-fly.</para> + + <para><function>sd_bus_error_set_errno()</function> will set + <structfield>name</structfield> from an + <varname>errno</varname>-like value that is converted to a D-Bus + error. <citerefentry + project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be used to set <structfield>message</structfield>. Well-known D-Bus error names will be used for <structfield>name</structfield> - if available, otherwise a name in the - <literal>System.Error</literal> namespace will be generated. - </para> - - <para><function>sd_bus_error_set_errnof</function> is similar to - <function>sd_bus_error_set_errno</function>, but in addition to - <parameter>name</parameter>, takes a - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - format and corresponding arguments. - <structfield>name</structfield> will be generated from + if applicable, otherwise a name in the + <literal>System.Error.</literal> namespace will be generated. The + sign of the specified error number is ignored. The absolute value + is used implicitly. The call always returns a negative value, for + convenient usage in <function>return</function> statements. This + call might fail due to lack of memory, in which case an + <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead, + and -ENOMEM returned.</para> + + <para><function>sd_bus_error_set_errnof()</function> is similar to + <function>sd_bus_error_set_errno()</function>, but in addition to + <parameter>error</parameter>, takes a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string and corresponding arguments. The + <structfield>message</structfield> field will be generated from <parameter>format</parameter> and the arguments.</para> - <para><function>sd_bus_error_get_errno</function> will convert - <structname>e->name</structname> to an errno-like value using the - same rules as <function>sd_bus_error_set</function>. If + <para><function>sd_bus_error_set_errnofv()</function> is similar to + <function>sd_bus_error_set_errnof()</function> but takes the + format string parameters as <citerefentry + project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry> + parameter list.</para> + + <para><function>sd_bus_error_get_errno()</function> converts the + <structfield>name</structfield> field of an error structure to an + <varname>errno</varname>-like (positive) value using the same + rules as <function>sd_bus_error_set()</function>. If <parameter>e</parameter> is <constant>NULL</constant>, 0 will be returned.</para> - <para><function>sd_bus_error_copy</function> will initialize + <para><function>sd_bus_error_copy()</function> will initialize <parameter>dst</parameter> using the values in <parameter>e</parameter>. If the strings in <parameter>e</parameter> were set using - <function>sd_bus_set_error_const</function>, they will be shared. - Otherwise, they will be copied.</para> + <function>sd_bus_set_error_const()</function>, they will be shared. + Otherwise, they will be copied. Returns a converted + <varname>errno</varname>-like, negative error code.</para> - <para><function>sd_bus_error_is_set</function> will return - <constant>true</constant> if <parameter>e</parameter> is + <para><function>sd_bus_error_is_set()</function> will return a + non-zero value if <parameter>e</parameter> is non-<constant>NULL</constant> and an error has been set, <constant>false</constant> otherwise.</para> - <para><function>sd_bus_error_has_name</function> will return true - if <parameter>e</parameter> is non-<constant>NULL</constant> and - an error with the same <parameter>name</parameter> has been set, + <para><function>sd_bus_error_has_name()</function> will return a + non-zero value if <parameter>e</parameter> is + non-<constant>NULL</constant> and an error with the same + <parameter>name</parameter> has been set, <constant>false</constant> otherwise.</para> - <para><function>sd_bus_error_free</function> will destroy resources - held by <parameter>e</parameter>. The parameter itself will not - be deallocated, and must be - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d - by the caller if necessary.</para> + <para><function>sd_bus_error_free()</function> will destroy + resources held by <parameter>e</parameter>. The parameter itself + will not be deallocated, and must be <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d + by the caller if necessary. The function may also be called safely + on unset errors (error structures with both fields set to NULL), + in which case it performs no operation. This call will reset the + error structure after freeing the data, so that all fields are set + to NULL. The structure may be reused afterwards.</para> </refsect1> <refsect1> <title>Return Value</title> - <para>Functions <function>sd_bus_error_set</function>, - <function>sd_bus_error_setf</function>, - <function>sd_bus_error_set_const</function>, when successful, + <para>The functions <function>sd_bus_error_set()</function>, + <function>sd_bus_error_setf()</function>, + <function>sd_bus_error_set_const()</function>, when successful, return the negative errno value corresponding to the <parameter>name</parameter> parameter. Functions - <function>sd_bus_error_set_errno</function> and - <function>sd_bus_error_set_errnof</function>, when successful, - return the value of the <parameter>errno</parameter> parameter. If - an error occurs, one of the negative error values listed below - will be returned.</para> - - <para><function>sd_bus_error_get_errno</function> returns + <function>sd_bus_error_set_errno()</function>, + <function>sd_bus_error_set_errnof()</function> and + <function>sd_bus_error_set_errnofv()</function>, when successful, + return the negative value of the <parameter>error</parameter> + parameter. If an error occurs, one of the negative error values + listed below will be returned.</para> + + <para><function>sd_bus_error_get_errno()</function> returns <constant>false</constant> when <parameter>e</parameter> is <constant>NULL</constant>, and a positive errno value mapped from <parameter>e->name</parameter> otherwise.</para> - <para><function>sd_bus_error_copy</function> returns 0 or a - positive integer on success, and one of the negative error values - listed below otherwise.</para> + <para><function>sd_bus_error_copy()</function> returns 0 or a + positive integer on success, and a negative error value converted + from the error name otherwise.</para> - <para><function>sd_bus_error_is_set</function> returns - <constant>true</constant> when <parameter>e</parameter> and - <parameter>e->name</parameter> are non-<constant>NULL</constant>, - <constant>false</constant> otherwise.</para> + <para><function>sd_bus_error_is_set()</function> returns a + non-zero value when <parameter>e</parameter> and the + <structfield>name</structfield> field are + non-<constant>NULL</constant>, zero otherwise.</para> - <para><function>sd_bus_error_has_name</function> returns - <constant>true</constant> when <parameter>e</parameter> is - non-<constant>NULL</constant> and <parameter>e->name</parameter> - is equal to <parameter>name</parameter>, - <constant>false</constant> otherwise.</para> + <para><function>sd_bus_error_has_name()</function> returns a + non-zero value when <parameter>e</parameter> is + non-<constant>NULL</constant> and the + <structfield>name</structfield> field is equal to + <parameter>name</parameter>, zero otherwise.</para> </refsect1> <refsect1> <title>Reference ownership</title> <para><structname>sd_bus_error</structname> is not reference counted. Users should destroy resources held by it by calling - <function>sd_bus_error_free</function>.</para> + <function>sd_bus_error_free()</function>. Usually error structures + are allocated on the stack or passed in as function parameters, + but they may also be allocated dynamically, in which case it is + the duty of the caller to <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + the memory held by the structure itself after freeing its contents + with <function>sd_bus_error_free()</function>.</para> </refsect1> <refsect1> @@ -407,8 +379,10 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml new file mode 100644 index 0000000000..3fca63be4a --- /dev/null +++ b/man/sd_bus_error_add_map.xml @@ -0,0 +1,173 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!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 2015 Lennart Poettering + + 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_error_add_map"> + + <refentryinfo> + <title>sd_bus_error_add_map</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_error_add_map</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_error_add_map</refname> + <refname>sd_bus_error_map</refname> + <refname>SD_BUS_ERROR_MAP</refname> + <refname>SD_BUS_ERROR_END</refname> + + <refpurpose>Additional sd-dbus error mappings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcsynopsisinfo>typedef struct { + const char *name; + int code; + ... +} sd_bus_error_map;</funcsynopsisinfo> + + </funcsynopsis> + + <para> + <constant>SD_BUS_ERROR_MAP(<replaceable>name</replaceable>, <replaceable>code</replaceable>)</constant> + </para> + <para> + <constant>SD_BUS_ERROR_MAP_END</constant> + </para> + + <funcprototype> + <funcdef>int <function>sd_bus_error_add_map</function></funcdef> + <paramdef>const sd_bus_map *<parameter>map</parameter></paramdef> + </funcprototype> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_error_add_map()</function> call may be + used to register additional mappings for converting D-Bus errors + to Linux <varname>errno</varname>-style errors. The mappings + defined with this call are consulted by calls such as + <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By + default a number of generic, standardized mappings are known, as + documented in + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use + this call to add further, application-specific mappings.</para> + + <para>The function takes a pointer to an array of + <structname>sd_bus_error_map</structname> structures. A reference + to the specified array is added to the lookup tables for error + mappings. Note that the structure is not copied, it is hence + essential that the array stays available and constant during the + entire remaining runtime of the process.</para> + + <para>The mapping array should be put together with a series of + <constant>SD_BUS_ERROR_MAP()</constant> macro invocations, that + take a literal name string and a (positive) + <varname>errno</varname>-style error number. The last entry of the + array should be an invocation of the + <constant>SD_BUS_ERROR_MAP_END</constant> macro. The array should not be + put together without use of these two macros.</para> + + <para>Note that the call is idempotent: it is safe to invoke it + multiple times with the parameter, which will only add the passed + mapping array once.</para> + + <para>Note that the memory allocated by this call is not intended + to be freed during the lifetime of the process. It should not be + freed explicitly.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_bus_error_add_map()</function> returns a + positive value when the new array was added to the lookup + tables. It returns zero when the same array was already added + before. On error, a negative <varname>errno</varname>-style error + code is returned. See below for known error codes.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The specified mapping array is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><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_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index 7a4bfa4bc4..0ee849dca7 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -46,7 +46,8 @@ <refnamediv> <refname>sd_bus_message_append</refname> - <refpurpose>Attach parts of message based on a format string</refpurpose> + <refpurpose>Attach fields to a D-Bus message based on a type + string</refpurpose> </refnamediv> <refsynopsisdiv> @@ -65,17 +66,20 @@ <refsect1> <title>Description</title> - <para>The <function>sd_bus_message_append</function> function appends - a sequence of items to message <parameter>m</parameter>. The - format string <parameter>types</parameter> describes the types of - arguments that follow.</para> + <para>The <function>sd_bus_message_append()</function> function + appends a sequence of fields to the D-Bus message object + <parameter>m</parameter>. The type string + <parameter>types</parameter> describes the types of the field + arguments that follow. For each type specified in the type string + one or more arguments need to be specified, in the same order as + declared in the type string.</para> - <para>The format string is composed of the elements shown in the + <para>The type string is composed of the elements shown in the table below. It contains zero or more single "complete types". Each complete type may be one of the basic types or a fully - described container type. A container type may be a structure, a - variant type code, an array with its element type, or a dictionary - with its entry type. The format string is + described container type. A container type may be a structure with + the contained types, a variant, an array with its element type, or + a dictionary entry with the contained types. The type string is <constant>NUL</constant>-terminated.</para> <para>In case of a basic type, one argument of the corresponding @@ -88,27 +92,32 @@ rules as if they were not nested.</para> <para>A variant is denoted by <literal>v</literal>. Corresponding - arguments must include a format string denoting a complete type, + arguments must begin with a type string denoting a complete type, and following that, arguments corresponding to the specified type. </para> <para>An array is denoted by <literal>a</literal> followed by a - complete type. Corresponding arguments must include the size of - the array, and then repeated this number of times, arguments - corresponding to the nested type.</para> + complete type. Corresponding arguments must begin with the number of + entries in the array, followed by the entries themselves, + matching the element type of the array.</para> <para>A dictionary is an array of dictionary entries, denoted by <literal>a</literal> followed by a pair of complete types between <literal>{</literal> and <literal>}</literal>. The first of those - types must be a basic type. Corresponding arguments must include - the size of the dictionary, and then repeated this number of - times, arguments corresponding to each of the two nested - types.</para> + types must be a basic type. Corresponding arguments must begin + with the number of dictionary entries, followed by a pair of + values for each entry matching the element type of + the dictionary entries.</para> + + <para>For further details on the D-Bus type system, please consult + the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus + Specification</ulink>.</para> <table> - <title>Item format specifiers</title> + <title>Item type specifiers</title> - <tgroup cols='4'> + <tgroup cols='5'> <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" /> <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" /> @@ -120,6 +129,7 @@ <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> <entry>array</entry> <entry>determined by array type and size</entry> + <entry>int, followed by array contents</entry> </row> <row> @@ -127,6 +137,7 @@ <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> <entry>variant</entry> <entry>determined by the type argument</entry> + <entry>signature string, followed by variant contents</entry> </row> <row> @@ -134,6 +145,7 @@ <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> <entry>array start</entry> <entry morerows="1">determined by the nested types</entry> + <entry morerows="1">structure contents</entry> </row> <row> <entry><literal>)</literal></entry> @@ -146,6 +158,7 @@ <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> <entry>dictionary entry start</entry> <entry morerows="1">determined by the nested types</entry> + <entry morerows="1">dictionary contents</entry> </row> <row> <entry><literal>}</literal></entry> @@ -155,10 +168,11 @@ </tbody> </tgroup> </table> + </refsect1> <refsect1> - <title>Types string grammar</title> + <title>Types String Grammar</title> <programlisting>types ::= complete_type* complete_type ::= basic_type | variant | structure | array | dictionary @@ -194,7 +208,7 @@ uint32_t t = 7; double d = 8.0; sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting> - <para>Append a structure composed of string and a D-Bus path:</para> + <para>Append a structure composed of a string and a D-Bus path:</para> <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path"); </programlisting> @@ -242,12 +256,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting> <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 project='die-net'><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> + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index c2adc6f43d..034466bf9c 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -49,7 +49,8 @@ <refname>sd_bus_message_append_array_iovec</refname> <refname>sd_bus_message_append_array_space</refname> - <refpurpose>Attach an array of items to a message</refpurpose> + <refpurpose>Appaned an array of fields to a D-Bus + message</refpurpose> </refnamediv> <refsynopsisdiv> @@ -69,6 +70,8 @@ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> <paramdef>char <parameter>type</parameter></paramdef> <paramdef>int <parameter>memfd</parameter></paramdef> + <paramdef>uint64_t <parameter>offset</parameter></paramdef> + <paramdef>uint64_t <parameter>size</parameter></paramdef> </funcprototype> <funcprototype> @@ -83,7 +86,7 @@ <funcdef>int sd_bus_message_append_array_space</funcdef> <paramdef>char <parameter>type</parameter></paramdef> <paramdef>size_t <parameter>size</parameter></paramdef> - <paramdef>char void **<parameter>ptr</parameter></paramdef> + <paramdef>void **<parameter>ptr</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -91,18 +94,19 @@ <refsect1> <title>Description</title> - <para>The <function>sd_bus_message_append_array</function> functionc - appends items to message <parameter>m</parameter> as the single - array. A container will be opened, items appended, and the - container closed. Parameter <parameter>type</parameter> determines - how pointer <parameter>p</parameter> is interpreted. + <para>The <function>sd_bus_message_append_array()</function> + function appends an array to a D-Bus message + <parameter>m</parameter>. A container will be opened, the array + contents appended, and the container closed. The parameter + <parameter>type</parameter> determines how the pointer + <parameter>p</parameter> is interpreted. <parameter>type</parameter> must be one of the "trivial" types <literal>y</literal>, <literal>n</literal>, <literal>q</literal>, <literal>i</literal>, <literal>u</literal>, <literal>x</literal>, <literal>t</literal>, <literal>d</literal> (but not - <literal>b</literal>), as defined by the - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic Types</ulink> - section of the D-Bus specification, and listed in + <literal>b</literal>), as defined by the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic + Types</ulink> section of the D-Bus specification, and listed in <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Pointer <parameter>p</parameter> must point to an array of size <parameter>size</parameter> bytes containing items of the @@ -110,50 +114,68 @@ multiple of the size of the type <parameter>type</parameter>. As a special case, <parameter>p</parameter> may be <constant>NULL</constant>, if <parameter>size</parameter> is 0. - </para> - - <para>The memory pointed at by <parameter>p</parameter> is copied - into the memory area containing the message and may be changed - after this call.</para> - - <para>The - <function>sd_bus_message_append_array_memfd</function> function appends - items to message <parameter>m</parameter>, similarly to - <function>sd_bus_message_append_array</function>. Contents of the - memory file descriptor <parameter>memfd</parameter> are used as - the contents of the array. Their size must be a multiple of the - size of the type <parameter>type</parameter>.</para> - - <para>The descriptor specified with <parameter>memfd</parameter> - will be sealed and cannot be modified after this call.</para> - - <para>The - <function>sd_bus_message_append_array_iovec</function> function appends - items to message <parameter>m</parameter>, similarly to - <function>sd_bus_message_append_array</function>. Contents of the - iovec <parameter>iov</parameter> are used as the contents of the - array. The total size of <parameter>iov</parameter> payload (the - sum of <structfield>iov_len</structfield> fields) must be a multiple - of the size of the type <parameter>type</parameter>.</para> - - <para>The <parameter>iov</parameter> argument must point to - <parameter>n</parameter> <structname>struct iovec</structname> - structures. Each structure may have the - <structname>iov_base</structname> field set, in which case the - memory pointed to will be copied into the message, or unset, in - which case a block of zeros of length + The memory pointed to by <parameter>p</parameter> is copied into + the memory area containing the message and stays in possession of + the caller. The caller may hence freely change the data after this + call without affecting the message the array was appended + to.</para> + + <para>The <function>sd_bus_message_append_array_memfd()</function> + function appends an array of a trivial type to message + <parameter>m</parameter>, similar to + <function>sd_bus_message_append_array()</function>. The contents + of the memory file descriptor <parameter>memfd</parameter> + starting at the specified offset and and of the specified size is + used as the contents of the array. The offset and size must be a + multiple of the size of the type + <parameter>type</parameter>. However, as a special exception, if + the offset is specified as zero and the size specified as + UINT64_MAX the full memory file descriptor contents is used. The + memory file descriptor is sealed by this call if it hasn't been + sealed yet, and cannot be modified a after this call. See + <citerefentry + project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about memory file descriptors. Appending arrays with + memory file descriptors enables efficient zero-copy data transfer, + as the memory file descriptor may be passed as-is to the + destination, without copying the memory in it to the destination + process. Not all protocol transports support passing memory file + descriptors between participants, in which case this call will + automatically fall back to copying. Also, as memory file + descriptor passing is inefficient for smaller amounts of data + copying might still be enforced even where memory file descriptor + passing is supported.</para> + + <para>The <function>sd_bus_message_append_array_iovec()</function> + function appends an array of a trivial type to the message + <parameter>m</parameter>, similar to + <function>sd_bus_message_append_array()</function>. Contents of + the IO vector array <parameter>iov</parameter> are used as the + contents of the array. The total size of + <parameter>iov</parameter> payload (the sum of + <structfield>iov_len</structfield> fields) must be a multiple of + the size of the type <parameter>type</parameter>. The + <parameter>iov</parameter> argument must point to + <parameter>n</parameter> IO vector structures. Each structure may + have the <structname>iov_base</structname> field set, in which + case the memory pointed to will be copied into the message, or + unset (set to zero), in which case a block of zeros of length <structname>iov_len</structname> bytes will be inserted. The memory pointed at by <parameter>iov</parameter> may be changed after this call.</para> - <para>The - <function>sd_bus_message_append_array_space</function> function appends - space for an array of items to message <parameter>m</parameter>. - It behaves the same as - <function>sd_bus_message_append_array</function>, but instead - of copying items to the message, it returns a pointer to the - destination area to the caller in pointer <parameter>p</parameter>. - </para> + <para>The <function>sd_bus_message_append_array_space()</function> + function appends space for an array of a trivial type to message + <parameter>m</parameter>. It behaves the same as + <function>sd_bus_message_append_array()</function>, but instead of + copying items to the message, it returns a pointer to the + destination area to the caller in pointer + <parameter>p</parameter>. The caller should subsequently write the + array contents to this memory. Modifications of the memory + pointed to should only occur until the next operation on the bus + message is invoked, most imporantly the memory should not be + altered anymore when another field has been added to the message + or the message has been sealed.</para> </refsect1> <refsect1> @@ -183,6 +205,7 @@ <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> </para> </refsect1> diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml index 91eaf87530..276953af69 100644 --- a/man/sd_bus_message_append_basic.xml +++ b/man/sd_bus_message_append_basic.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>sd_bus_message_append_basic</refname> - <refpurpose>Attach a single part to a message</refpurpose> + <refpurpose>Attach a single field to a message</refpurpose> </refnamediv> <refsynopsisdiv> @@ -56,7 +56,7 @@ <funcdef>int sd_bus_message_append_basic</funcdef> <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>char void *<parameter>p</parameter></paramdef> + <paramdef>const void *<parameter>p</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -64,31 +64,33 @@ <refsect1> <title>Description</title> - <para><function>sd_bus_message_append_basic</function> appends a - single item to the message <parameter>m</parameter>. Parameter - <parameter>type</parameter> determines how pointer + <para><function>sd_bus_message_append_basic()</function> appends a + single field to the message <parameter>m</parameter>. The + parameter <parameter>type</parameter> determines how the pointer <parameter>p</parameter> is interpreted. - <parameter>type</parameter> must be one of the basic types - as defined by the - - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic Types</ulink> - section of the D-Bus specification, and listed in the table below. + <parameter>type</parameter> must be one of the basic types as + defined by the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic + Types</ulink> section of the D-Bus specification, and listed in + the table below. </para> <table id='format-specifiers'> - <title>Item format specifiers</title> + <title>Item type specifiers</title> - <tgroup cols='4'> + <tgroup cols='5'> <colspec colname='specifier' /> <colspec colname='constant' /> <colspec colname='description' /> <colspec colname='size' /> + <colspec colname='ctype' /> <thead> <row> <entry>Specifier</entry> <entry>Constant</entry> <entry>Description</entry> <entry>Size</entry> + <entry>Expected C Type</entry> </row> </thead> <tbody> @@ -97,6 +99,7 @@ <entry><constant>SD_BUS_TYPE_BYTE</constant></entry> <entry>unsigned integer</entry> <entry>1 byte</entry> + <entry>uint8_t</entry> </row> <row> @@ -104,6 +107,7 @@ <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry> <entry>boolean</entry> <entry>4 bytes</entry> + <entry>int</entry> </row> <row> @@ -111,6 +115,7 @@ <entry><constant>SD_BUS_TYPE_INT16</constant></entry> <entry>signed integer</entry> <entry>2 bytes</entry> + <entry>int16_t</entry> </row> <row> @@ -118,6 +123,7 @@ <entry><constant>SD_BUS_TYPE_UINT16</constant></entry> <entry>unsigned integer</entry> <entry>2 bytes</entry> + <entry>uint16_t</entry> </row> <row> @@ -125,6 +131,7 @@ <entry><constant>SD_BUS_TYPE_INT32</constant></entry> <entry>signed integer</entry> <entry>4 bytes</entry> + <entry>int32_t</entry> </row> <row> @@ -132,6 +139,7 @@ <entry><constant>SD_BUS_TYPE_UINT32</constant></entry> <entry>unsigned integer</entry> <entry>4 bytes</entry> + <entry>uint32_t</entry> </row> <row> @@ -139,6 +147,7 @@ <entry><constant>SD_BUS_TYPE_INT64</constant></entry> <entry>signed integer</entry> <entry>8 bytes</entry> + <entry>int64_t</entry> </row> <row> @@ -146,6 +155,7 @@ <entry><constant>SD_BUS_TYPE_UINT64</constant></entry> <entry>unsigned integer</entry> <entry>8 bytes</entry> + <entry>uint64_t</entry> </row> <row> @@ -153,6 +163,7 @@ <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry> <entry>floating-point</entry> <entry>8 bytes</entry> + <entry>double</entry> </row> <row> @@ -160,6 +171,7 @@ <entry><constant>SD_BUS_TYPE_STRING</constant></entry> <entry>Unicode string</entry> <entry>variable</entry> + <entry>char[]</entry> </row> <row> @@ -167,6 +179,7 @@ <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry> <entry>object path</entry> <entry>variable</entry> + <entry>char[]</entry> </row> <row> @@ -174,6 +187,7 @@ <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry> <entry>signature</entry> <entry>variable</entry> + <entry>char[]</entry> </row> <row> @@ -181,16 +195,19 @@ <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry> <entry>UNIX file descriptor</entry> <entry>4 bytes</entry> + <entry>int</entry> </row> </tbody> </tgroup> </table> - <para>The value of the parameter is copied into the memory area - containing the message and may be changed after this call. If - <parameter>type</parameter> is <literal>h</literal> (UNIX file - descriptor), it is always "consumed" by this call, and either - successfully appended to the message or closed.</para> + <para>The value of the parameter is copied into a memory area held + by the message object, stays in the possession of the caller and + may hence be freely changed after this call without affecting the + bus message it has been added to. If <parameter>type</parameter> + is <literal>h</literal> (UNIX file descriptor), the descriptor is + duplicated by this call and the passed descriptor stays in + possession of the caller.</para> <para>For types <literal>s</literal>, <literal>o</literal>, and <literal>g</literal>, the parameter <parameter>p</parameter> is diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index 04042f2136..1be44e2785 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -44,7 +44,7 @@ <refnamediv> <refname>sd_bus_negotiate_fds</refname> - <refname>sd_bus_negotiate_timestamps</refname> + <refname>sd_bus_negotiate_timestamp</refname> <refname>sd_bus_negotiate_creds</refname> <refpurpose>Control feature negotiation on bus connections</refpurpose> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 44744a0029..aff2ed2e83 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -77,8 +77,8 @@ <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. The bus object will not be - connected to any bus initially. To connect it to a bus, make sure + function owns the sole reference and the bus object will not be + connected to any bus. To connect it to a bus, make sure to set an address with <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry> or a related call, and then start the connection with @@ -94,15 +94,13 @@ well-known bus in a single function invocation.</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> + <parameter>bus</parameter>.</para> <para><function>sd_bus_unref()</function> destroys a reference to - <parameter>bus</parameter>.</para> + <parameter>bus</parameter>. 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> </refsect1> <refsect1> diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index 9b0a93d888..f07ae09555 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>sd_bus_request_name</refname> <refname>sd_bus_release_name</refname> - <refpurpose>Request or release a well-known name on a bus</refpurpose> + <refpurpose>Request or release a well-known service name on a bus</refpurpose> </refnamediv> <refsynopsisdiv> @@ -71,9 +71,9 @@ <title>Description</title> <para><function>sd_bus_request_name()</function> requests a - well-known name on a bus. It takes a bus connection, a valid bus - name and a flags parameter. The flags parameter is a combination - of the following flags:</para> + well-known service name on a bus. It takes a bus connection, a + valid bus name and a flags parameter. The flags parameter is a + combination of the following flags:</para> <variablelist> <varlistentry> @@ -166,8 +166,11 @@ <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>A specified parameter is - invalid.</para></listitem> + <listitem><para>A specified parameter is invalid. This is also + generated when the requested name is a special service name + reserved by the D-Bus specification, or when the operation is + requested on a connection that does not refer to a + bus.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index b46d47101b..9c6706caf8 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -49,15 +49,17 @@ <refname>sd_pid_get_owner_uid</refname> <refname>sd_pid_get_machine_name</refname> <refname>sd_pid_get_slice</refname> + <refname>sd_pid_get_user_slice</refname> <refname>sd_peer_get_session</refname> <refname>sd_peer_get_unit</refname> <refname>sd_peer_get_user_unit</refname> <refname>sd_peer_get_owner_uid</refname> <refname>sd_peer_get_machine_name</refname> <refname>sd_peer_get_slice</refname> - <refpurpose>Determine session, service, owner of a - session, container/VM or slice of a specific - PID or socket peer</refpurpose> + <refname>sd_peer_get_user_slice</refname> + <refpurpose>Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer</refpurpose> </refnamediv> <refsynopsisdiv> @@ -101,6 +103,12 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_pid_get_user_slice</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_peer_get_session</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>session</parameter></paramdef> @@ -135,6 +143,12 @@ <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>slice</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_user_slice</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -155,30 +169,29 @@ call after use.</para> <para><function>sd_pid_get_unit()</function> may be used to - determine the systemd system unit (i.e. system service) identifier - of a process identified by the specified PID. The unit name is a - short string, suitable for usage in file system paths. Note that - not all processes are part of a system unit/service (e.g. user - processes, or kernel threads). For processes not being part of a - systemd system unit this function will fail with -ENXIO (More - specifically: this call will not work for processes that are part - of user units, use <function>sd_pid_get_user_unit()</function> for - that.) The returned string needs to be freed with the libc - <citerefentry + determine the systemd system unit (i.e. system service or scope + unit) identifier of a process identified by the specified PID. The + unit name is a short string, suitable for usage in file system + paths. Note that not all processes are part of a system + unit/service (e.g. user processes, or kernel threads). For + processes not being part of a systemd system unit this function + will fail with -ENXIO (More specifically: this call will not work + for kernel threads.) The returned string needs to be freed with + the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> <para><function>sd_pid_get_user_unit()</function> may be used to - determine the systemd user unit (i.e. user service) identifier of - a process identified by the specified PID. This is similar to - <function>sd_pid_get_unit()</function> but applies to user units - instead of system units.</para> + determine the systemd user unit (i.e. user service or scope unit) + identifier of a process identified by the specified PID. This is + similar to <function>sd_pid_get_unit()</function> but applies to + user units instead of system units.</para> <para><function>sd_pid_get_owner_uid()</function> may be used to - determine the Unix user identifier of the owner of the session of - a process identified the specified PID. Note that this function - will succeed for user processes which are shared between multiple - login sessions of the same user, where + determine the Unix UID (user identifier) of the owner of the + session of a process identified the specified PID. Note that this + function will succeed for user processes which are shared between + multiple login sessions of the same user, where <function>sd_pid_get_session()</function> will fail. For processes not being part of a login session and not being a shared process of a user this function will fail with -ENXIO.</para> @@ -200,6 +213,10 @@ <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> + <para>Similar, <function>sd_pid_get_user_slice()</function> + returns the user slice (as managed by the user's systemd instance) + of a process.</para> + <para>If the <varname>pid</varname> parameter of any of these functions is passed as 0, the operation is executed for the calling process.</para> @@ -208,10 +225,14 @@ <function>sd_peer_get_unit()</function>, <function>sd_peer_get_user_unit()</function>, <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function> and - <function>sd_peer_get_slice()</function> calls operate similar to - their PID counterparts, but operate on a connected AF_UNIX socket - and retrieve information about the connected peer process.</para> + <function>sd_peer_get_machine_name()</function>, + <function>sd_peer_get_slice()</function> and + <function>sd_peer_get_user_slice()</function> calls operate + similar to their PID counterparts, but operate on a connected + AF_UNIX socket and retrieve information about the connected peer + process. Note that these fields are retrieved via + <filename>/proc</filename>, and hence are not suitable for + authorization purposes, as they are subject to races.</para> </refsect1> <refsect1> @@ -262,15 +283,17 @@ <function>sd_pid_get_owner_uid()</function>, <function>sd_pid_get_machine_name()</function>, <function>sd_pid_get_slice()</function>, + <function>sd_pid_get_user_slice()</function>, <function>sd_peer_get_session()</function>, <function>sd_peer_get_unit()</function>, <function>sd_peer_get_user_unit()</function>, <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function> and - <function>sd_peer_get_slice()</function> interfaces are - available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <function>sd_peer_get_machine_name()</function>, + <function>sd_peer_get_slice()</function> and + <function>sd_peer_get_user_slice()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> <para>Note that the login session identifier as diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index a101006a7e..afe1200d7e 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -440,7 +440,6 @@ </varlistentry> </variablelist> - </refsect1> <refsect1> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 01c31c5ef5..ff7b85453f 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -563,6 +563,16 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>VnetHeader=</varname></term> + <listitem><para>Takes a boolean argument. Configures + IFF_VNET_HDR flag for a tap device. It allows sending + and receiving larger Generic Segmentation Offload (GSO) + packets. This may increase throughput significantly. + Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>User=</varname></term> <listitem><para>User to grant access to the <filename>/dev/net/tun</filename> device.</para> diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index 2f9add8d6c..b7164014f0 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -106,7 +106,7 @@ one takes precedence over all others.</para> <para>Each preset file shall be named in the style of - <filename><priority>-<program>.conf</filename>. Files + <filename><priority>-<policy-name>.preset</filename>. Files in <filename>/etc/</filename> override files with the same name in <filename>/usr/lib/</filename> and <filename>/run/</filename>. Files in <filename>/run/</filename> override files with the same |