From 4bbcde8498eb59557ebddd7830efb47c0297ff4b 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. --- man/systemd.exec.xml | 49 +++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 36a884c9f4..2c00c08aff 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -2513,18 +2513,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 ("). + 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. - C escapes - are supported, but not - most control characters. - \t and \n can be used to insert tabs and newlines within - EnvironmentFile=. + 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 @@ -2557,12 +2578,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,