From 05ea18897aeafa1f2d47c5eae6c43bdd6ff71b9d Mon Sep 17 00:00:00 2001 From: Yonathan Randolph 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 EnvironmentFile= - Similar to Environment= but reads the environment variables from a text - file. The text file should contain new-line-separated variable assignments. Empty lines, lines without an - = 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 ("). - - C escapes - are supported, but not - most control characters. - \t and \n can be used to insert tabs and newlines within - EnvironmentFile=. + Similar to Environment= but reads the environment variables from a text file. + The text file should contain newline-separated variable assignments. Empty lines, lines without an + = separator, or lines starting with ; or # will be + ignored, which may be used for commenting. The file must be UTF-8 encoded. Valid characters are unicode scalar values other than noncharacters, U+0000 NUL, and U+FEFF byte order mark. Control codes other than NUL + are allowed. + + In the file, an unquoted value after the = is parsed with the same backslash-escape + rules as unquoted + text 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 + \ followed by any character other than newline will preserve the following character, so that + \\ will become the value \. + + In the file, a '-quoted value after the = can span multiple lines + and contain any character verbatim other than single quote, like single-quoted + text in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace + outside of the single quotes is discarded. + + In the file, a "-quoted value after the = can span multiple lines, + and the same escape sequences are recognized as in double-quoted + text of a POSIX shell. Backslash (\) followed by any of "\`$ 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. The argument passed should be an absolute filename or wildcard expression, optionally prefixed with -, which indicates that if the file does not exist, it will not be read and no error or @@ -2529,12 +2550,6 @@ SystemCallErrorNumber=EPERM Variables set for invoked processes due to this setting are subject to being overridden by those configured with Environment= or EnvironmentFile=. - C escapes - are supported, but not - most control characters. - \t and \n can be used to insert tabs and newlines within - EnvironmentFile=. - Example: PassEnvironment=VAR1 VAR2 VAR3 passes three variables VAR1,