diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/custom-html.xsl | 180 | ||||
| -rw-r--r-- | man/sd_bus_default.xml | 66 | ||||
| -rw-r--r-- | man/sd_bus_new.xml | 16 | ||||
| -rw-r--r-- | man/systemd.netdev.xml | 23 | ||||
| -rw-r--r-- | man/systemd.network.xml | 6 | ||||
| -rw-r--r-- | man/systemd.preset.xml | 2 |
6 files changed, 202 insertions, 91 deletions
diff --git a/man/custom-html.xsl b/man/custom-html.xsl index 2df12411c7..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> 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_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/systemd.netdev.xml b/man/systemd.netdev.xml index 01c31c5ef5..d15c21be60 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -491,6 +491,19 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>IPv6FlowLabel=</varname></term> + <listitem> + <para>Configures The 20-bit Flow Label (see <ulink url="https://tools.ietf.org/html/rfc6437"> + RFC 6437</ulink>) field in the IPv6 header (see <ulink url="https://tools.ietf.org/html/rfc2460"> + RFC 2460</ulink>), is used by a node to label packets of a flow. + It's only used for IPv6 Tunnels. + A Flow Label of zero is used to indicate packets that have + not been labeled. Takes following values. + When <literal>inherit</literal> it uses the original flowlabel, + or can be configured to any value betwen 0 to 0xFFFFF.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>Mode=</varname></term> <listitem> <para>An <literal>ip6tnl</literal> tunnels can have three @@ -563,6 +576,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.network.xml b/man/systemd.network.xml index ff01da6249..90a0e8fff6 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -589,6 +589,12 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>Hostname=</varname></term> + <listitem> + <para>Hostname is a option to override the machine's hostname that will be sent to the DHCP server</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>UseDomains=</varname></term> <listitem> <para>When true (not the default), the domain name 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 |