document env.h

Singling out envdir_chomp might sound a bit snarky, but it's somewhat
contradictory, so I believe it's better to document it separately.

1 files changed, 136 insertions, 1 deletions

diff --git a/doc/libstddjb/env.html b/doc/libstddjb/env.html
index d8d7e72..05917c4 100644
--- a/doc/libstddjb/env.html
+++ b/doc/libstddjb/env.html
@@ -21,7 +21,142 @@
 <h1> The <tt>skalibs/env.h</tt> header </h1>
 
 <p>
- TODO: write this documentation page. (Sorry!)
+ 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> Modif bytestrings </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 (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 argc, char const *s, size_t len)</code></br>
+Deserializes the result of <tt>env_string</tt>: pointers to the first
+<em>argc</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>. It only tries to store
+up to <em>vmax</em> variables. 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>