diff options
| -rw-r--r-- | doc/libstddjb/env.html | 137 | ||||
| -rw-r--r-- | doc/libstddjb/envalloc.html | 32 |
2 files changed, 167 insertions, 2 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> diff --git a/doc/libstddjb/envalloc.html b/doc/libstddjb/envalloc.html index cda94ad..fcc2534 100644 --- a/doc/libstddjb/envalloc.html +++ b/doc/libstddjb/envalloc.html @@ -21,7 +21,37 @@ <h1> The <tt>skalibs/envalloc.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>envalloc.h</tt> is a supplement of <a href="env.html"><tt>env.h</tt></a> +header that lets one use <a href="stralloc.html">genallocs</a> of +<tt>char const *</tt> instead of fixed-size <tt>char const *[]</tt>. +</p> + +<h2> Functions </h2> + +<p> +<code>int envalloc_uniq (genalloc *v, char delim)</code><br /> +Removes strings in the <em>v</em> that share the same prefix up to the first +<em>delim</em> character. For instance, if delim is <tt>=</tt>, duplicate +environment variables are removed. Returns the number of removed entries on +success, -1 (and sets errno) on failure. +</p> + +<p> +<code>int envalloc_0 (genalloc *v)</code><br /> +Appends a null pointer to <em>v</em>. Returns 1 on sucess, 0 (and sets errno) +on failure. +</p> + +<p> +<tt>envalloc_make</tt> and <tt>envalloc_merge</tt> work exactly like their +<tt>env.h</tt> counterparts. </p> </body> |