1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>execline: the envfile program</title>
<meta name="Description" content="execline: the envfile program" />
<meta name="Keywords" content="execline command envfile environment file shell envdir s6-envdir env" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">execline</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>envfile</tt> program </h1>
<p>
<tt>envfile</tt> reads a file containing variable assignments,
adds the variables to the environment, then executes a program.
</p>
<h2> Interface </h2>
<pre>
envfile [ -i | -I ] <em>file</em> <em>prog...</em>
</pre>
<p>
<tt>envfile</tt> reads <em>file</em> and adds the key-value pairs
defined in <em>file</em> to the environment. Then it
execs into <em>prog...</em>, i.e. the rest of its command line,
with the modified environment.
</p>
<h2> Exit codes </h2>
<ul>
<li> 1: syntax error in <em>file</em> </li>
<li> 100: wrong usage </li>
<li> 111: system call failed </li>
<li> 126: execve() on <em>prog</em> failed (unknown reason) </li>
<li> 127: execve() on <em>prog</em> failed (<em>prog</em> could not be found) </li>
</ul>
<p>
0 is not listed because on success, <tt>envfile</tt> does not exit:
it execs into <em>prog</em>.
</p>
<h2> Options </h2>
<ul>
<li> <tt>-i</tt> : strict. If <em>file</em> does not exist, exit 111 with an
error message. This is the default. </li>
<li> <tt>-I</tt> : loose. If <em>file</em> does not exist, exec into
<em>prog</em> without modifying the environment. </li>
</ul>
<h2> File syntax </h2>
<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>.
</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).
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>
If <em>value</em> is empty, <em>key</em> is <strong>still</strong>
added to the environment, with an empty value. If you do not want
<em>key</em> to be added to the environment at all, comment out the line.
<tt>envfile</tt> does not offer a way to <em>remove</em> variables from
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 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>
</body>
</html>
|
