From 05ea18897aeafa1f2d47c5eae6c43bdd6ff71b9d Mon Sep 17 00:00:00 2001
From: Yonathan Randolph <yonathan@gmail.com>
Date: Sun, 26 Dec 2021 17:12:00 -0800
Subject: [PATCH] man: clarify Environmentfile format
Remove incorrect claim that C escapes (such as \t and \n) are recognized and that control characters are disallowed. Specify the allowed characters and escapes with single quotes, with double quotes, and without quotes.
(cherry picked from commit 4bbcde8498eb59557ebddd7830efb47c0297ff4b)
Related: #2017035
---
man/systemd.exec.xml | 51 ++++++++++++++++++++++++++++----------------
1 file changed, 33 insertions(+), 18 deletions(-)
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index cd21d5b28d..69858d5e59 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -2485,18 +2485,39 @@ SystemCallErrorNumber=EPERM</programlisting>
<varlistentry>
<term><varname>EnvironmentFile=</varname></term>
- <listitem><para>Similar to <varname>Environment=</varname> but reads the environment variables from a text
- file. The text file should contain new-line-separated variable assignments. Empty lines, lines without an
- <literal>=</literal> separator, or lines starting with ; or # will be ignored, which may be used for
- commenting. A line ending with a backslash will be concatenated with the following one, allowing multiline
- variable definitions. The parser strips leading and trailing whitespace from the values of assignments, unless
- you use double quotes (").</para>
-
- <para><ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C escapes</ulink>
- are supported, but not
- <ulink url="https://en.wikipedia.org/wiki/Control_character#In_ASCII">most control characters</ulink>.
- <literal>\t</literal> and <literal>\n</literal> can be used to insert tabs and newlines within
- <varname>EnvironmentFile=</varname>.</para>
+ <listitem><para>Similar to <varname>Environment=</varname> but reads the environment variables from a text file.
+ The text file should contain newline-separated variable assignments. Empty lines, lines without an
+ <literal>=</literal> separator, or lines starting with <literal>;</literal> or <literal>#</literal> will be
+ ignored, which may be used for commenting. The file must be UTF-8 encoded. Valid characters are <ulink
+ url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink> other than <ulink
+ url="https://www.unicode.org/glossary/#noncharacter">noncharacters</ulink>, U+0000 NUL, and U+FEFF <ulink
+ url="https://www.unicode.org/glossary/#byte_order_mark">byte order mark</ulink>. Control codes other than NUL
+ are allowed.</para>
+
+ <para>In the file, an unquoted value after the <literal>=</literal> is parsed with the same backslash-escape
+ rules as <ulink
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">unquoted
+ text</ulink> in a POSIX shell, but unlike in a shell, interior whitespace is preserved and quotes after the
+ first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is
+ discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be
+ continued to the following one, with the newline itself discarded. A backslash
+ <literal>\</literal> followed by any character other than newline will preserve the following character, so that
+ <literal>\\</literal> will become the value <literal>\</literal>.</para>
+
+ <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span multiple lines
+ and contain any character verbatim other than single quote, like <ulink
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">single-quoted
+ text</ulink> in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace
+ outside of the single quotes is discarded.</para>
+
+ <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span multiple lines,
+ and the same escape sequences are recognized as in <ulink
+ url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">double-quoted
+ text</ulink> of a POSIX shell. Backslash (<literal>\</literal>) followed by any of <literal>"\`$</literal> will
+ preserve that character. A backslash followed by newline is a line continuation, and the newline itself is
+ discarded. A backslash followed by any other character is ignored; both the backslash and the following
+ character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is
+ discarded.</para>
<para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
<literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or
@@ -2529,12 +2550,6 @@ SystemCallErrorNumber=EPERM</programlisting>
<para>Variables set for invoked processes due to this setting are subject to being overridden by those
configured with <varname>Environment=</varname> or <varname>EnvironmentFile=</varname>.</para>
- <para><ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C escapes</ulink>
- are supported, but not
- <ulink url="https://en.wikipedia.org/wiki/Control_character#In_ASCII">most control characters</ulink>.
- <literal>\t</literal> and <literal>\n</literal> can be used to insert tabs and newlines within
- <varname>EnvironmentFile=</varname>.</para>
-
<para>Example:
<programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting>
passes three variables <literal>VAR1</literal>,