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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
<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>skalibs: the env header</title>
<meta name="Description" content="skalibs: the env header" />
<meta name="Keywords" content="skalibs header env environ environment char**" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libstddjb</a><br />
<a href="../libskarnet.html">libskarnet</a><br />
<a href="../index.html">skalibs</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>skalibs/env.h</tt> header </h1>
<p>
The following functions are declared in the <tt>skalibs/env.h</tt> header,
and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
</p>
<h2> General information </h2>
<p>
<tt>env.h</tt> contains functions that help shape the environment of programs
before spawning or executing them, without affecting the environment of the
main program.
</p>
<p>
Unless otherwise noted, all functions in this header return 1 on success or
0 (and set errno) on failure.
</p>
<h3> Bytestrings for environment modifications </h3>
<p>
A few functions in <tt>env.h</tt> (and many in <a href="exec.html">exec.h</a>)
have arguments named <tt>modifs</tt> and <tt>modiflen</tt>. A <em>modif</em>
is a byte-string that encodes a series of instructions to set/override
environment variables, or to remove them from the environment.
</p>
<h2> Functions </h2>
<h3> Fetching variables </h3>
<p>
<code>char const *env_get (char const *s)</code><br>
Deprecated alias of
<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/getenv.html">getenv()</a>.
</p>
<p>
<code>char const *ucspi_get (char const *s)</code><br>
Prepends the current <a href="//cr.yp.to/proto/ucspi.txt">UCSPI</a> protocol
to <em>s</em> and returns that environment variable. For instance,
<tt>uscpi_get("REMOTEEUID")</tt> would return the contents of the environment
variable <tt>IPCREMOTEEUID</tt> under <tt>s6-ipcserver</tt>. Returns NULL
EINVAL if it detects the program is not being run under UCSPI, or NULL ENOENT
if the variable that was specifically requested is not found.
</p>
<p>
<code>char const *env_get2 (char const *const *envp, char const *s)</code><br>
Similar to getenv(), but searches in <em>envp</em> instead of the current
process's environment.
</p>
<h3> Serialization </h3>
<p>Despite the name, these functions also work for <tt>argv</tt>s.</p>
<p>
<code>size_t env_len (char const *const* envp)</code><br>
Returns the number of elements in the array of strings <em>envp</em> up to, but
not including, the first null pointer.
</p>
<p>
<code>int env_string (stralloc *sa, char const *const *envp, size_t envlen)</code><br>
Serializes the array of NUL-terminated strings <em>envp</em> with <em>envlen</em>
elements into a series of contiguous NUL-terminated strings in the stralloc
*<em>sa</em>.
</p>
<p>
<code>int env_make (char const **v, size_t n, char const *s, size_t len)</code></br>
Deserializes the result of <tt>env_string</tt>: pointers to the first
<em>n</em> contiguous NUL-terminated strings contained in the byte-string
<em>s</em> of length <em>len</em> are written to <em>v</em>. Returns 1 on
success, or 0 EINVAL if <em>s</em> does not end in a NUL. <br>
Note that this function does not write NULL to the final value of <em>v</em>.
</p>
<h3> Environment modification </h3>
<p>
<code>int env_addmodif (stralloc *sa, char const *s, char const *t)</code><br>
Adds an instruction to the modif contained in *<em>sa</em>. If <em>t</em> is
null, add an instruction to remove the variable <em>s</em> from the
environment. If <em>t</em> is not null, add an instruction to always set the
variable <em>s</em> to <em>t</em>.
</p>
<p>
<code>size_t env_merge (char const **v, size_t vmax, char const *const *envp, size_t envlen, char const *modifs, size_t modiflen)</code><br>
Takes the environment with <em>envlen</em> variables contained in <em>envp</em>,
applies the modifications encoded in the modif <em>modifs</em> of length
<em>modiflen</em>, and stores the result in <em>v</em> with a terminating NULL.
It only tries to store up to <em>vmax-1</em> variables, which makes <em>vmax</em>
entries after the terminating NULL. Returns the number of elements now in
<em>v</em>, or 0 if the resulting <em>v</em> would be larger than <em>vmax</em>.
</p>
<p>
<code>size_t env_merg (char const **v, size_t vmax, char const *const *envp, char const *modifs, size_t modiflen)</code><br>
Similar to the above function, but <em>envp</em> is assumed to be NULL
terminated.
</p>
<h3> Envdir functions </h3>
<p>
<code>int envdir_internal (char const *path, stralloc *modifs, unsigned int options, char nullis)</code><br>
Essentially <a href="/software/s6/s6-envdir.html">s6-envdir</a> as library.
<em>options</em> is a bitwise OR of <tt>SKALIBS_ENVDIR_VERBATIM</tt>,
<tt>SKALIBS_ENVDIR_NOCHOMP</tt> and <tt>SKALIBS_ENVDIR_NOCLAMP</tt>, which
correspond to s6-envdir's <tt>-f</tt>, <tt>-n</tt> and <tt>-L</tt> options,
respectively.<br />
It adds instructions to <em>modifs</em> that replicate the effect
<tt>s6-envdir [-f] [-n] [-L] -c <em>nullis</em> <em>path</em></tt> would have on
the program it executes.
</p>
<p>
<code>int envdir_chomp (char const *path, stralloc *modifs)</code><br>
A macro that calls
<tt>envdir_internal(path, modifs, SKALIBS_ENVDIR_NOCHOMP, '\n')</tt>.
</p>
<p>
<code>int envdir (char const *path, stralloc *modifs)</code><br />
<code>int envdir_verbatim (char const *path, stralloc *modifs)</code><br>
<code>int envdir_verbatim_chomp (char const *path, stralloc *modifs)</code><br>
Macros that call <tt>envdir_internal(path, modifs, options, '\n')</tt>, with
<em>options</em> set to self-explanatory values.
</p>
<p>
<code>int env_dump (char const *dir, mode_t mode, char const *const *envp)</code><br>
Turns the contents of the NULL terminated environment in <em>envp</em> into an
envdir located at <em>dir</em>. Files are created with mode <em>mode</em>.
</p>
</body>
</html>
|
