summaryrefslogtreecommitdiff
path: root/doc/envfile.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2020-05-26 14:25:08 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2020-05-26 14:25:08 +0000
commit4f7270df65d7c79222ab29b8628f251eee16053b (patch)
tree6709e4fc8e8c3a50c0f4aec557cc212ef0c6c14f /doc/envfile.html
parent5650f7f506466eab8e318f80eb6c3a341dc6afd9 (diff)
downloadexecline-4f7270df65d7c79222ab29b8628f251eee16053b.tar.xz
New envfile format; prepare for 2.6.1.0
Diffstat (limited to 'doc/envfile.html')
-rw-r--r--doc/envfile.html40
1 files changed, 29 insertions, 11 deletions
diff --git a/doc/envfile.html b/doc/envfile.html
index 5c0523c..713b6ae 100644
--- a/doc/envfile.html
+++ b/doc/envfile.html
@@ -55,19 +55,32 @@ it execs into <em>prog</em>.
<p>
<em>file</em> is a text file containing lines of the form <tt>key = value</tt>.
-Whitespace is permitted before and after <em>key</em>, and before or after <em>value</em>,
-but <em>key</em> or <em>value</em> can never contain whitespace. No quoting
-is possible.
+Whitespace is permitted before and after <em>key</em>, and before or after <em>value</em>.
</p>
<p>
Empty lines, or lines containing only whitespace, are ignored.
Lines beginning with <tt>#</tt> (possibly after some whitespace)
are ignored (and typically used for comments).
-Comments are also possible at the end of lines:
-<tt>key = value # comment</tt> is a valid line. Note that there
-<em>must</em> be whitespace between <em>value</em> and <tt>#</tt>
-in this case (else <tt>#</tt> is just read as a part of <em>value</em>).
+Leading and trailing whitespace is stripped from values; but a
+value can be double-quoted, which allows for inclusion of leading
+and trailing whitespace.
+</p>
+
+<p>
+ A non-commented line that ends with a backslash ("<tt>\</tt>") is
+concatenated with the following one, and the newline character is
+ignored. If a backslashed newline happens before the start of a
+value, then the whitespace at the beginning of the new line will be
+part of the value (i.e. leading whitespace on a new line is not
+stripped).
+</p>
+
+<p>
+ C escapes, including hexadecimal and octal sequences, are supported
+in quoted values. Unicode codepoint sequences are not supported. It
+is possible to include a newline in a quoted value by using <tt>\n</tt>;
+but including newlines in environment variables is not recommended.
</p>
<p>
@@ -78,16 +91,21 @@ added to the environment, with an empty value. If you do not want
the environment.
</p>
+<p>
+ The envfile format is largely compatible with systemd's
+<a href="https://www.freedesktop.org/software/systemd/man/systemd.exec.html#EnvironmentFile=">EnvironmentFile</a>
+format, which allows for the reuse of such files outside of systemd.
+</p>
+
<h2> Notes </h2>
<ul>
<li> If <em>file</em> is <tt>-</tt> then <tt>envfile</tt> reads
and parses its standard input instead. To read a file literally named
<tt>-</tt>, you can use <tt>./-</tt> for instance. </li>
- <li> The variables and values that can be defined with <tt>envfile</tt>
-are purposefully restricted in order to keep the parsing extremely simple.
-If you need fancy values, for instance values that contain whitespace or
-a newline, you should use an envdir instead: see
+ <li> The variables that can be defined with <tt>envfile</tt>
+are purposefully restricted. If you need more expressive power for your
+variable names, or for your values, you should use an envdir instead: see
<a href="//skarnet.org/software/s6/s6-envdir.html">s6-envdir</a>. </li>
</ul>