commit 4dcf9fa0521a1c4243c28fb2f657d8029317e55e
parent bcb8e950789c173c387bea5c8a6906f9e26a8038
Author: Laurent Bercot <ska-skaware@skarnet.org>
Date: Fri, 17 May 2024 22:19:26 +0000
Fix some bits and pieces of the new doc
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat:
2 files changed, 25 insertions(+), 24 deletions(-)
diff --git a/doc/libstddjb/env.html b/doc/libstddjb/env.html
@@ -39,7 +39,7 @@ and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
</p>
-<h3> Modif bytestrings </h3>
+<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>)
@@ -53,13 +53,13 @@ environment variables, or to remove them from the environment.
<h3> Fetching variables </h3>
<p>
-<code>char const *env_get (char const *s)</code></br>
+<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 />
+<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
@@ -69,7 +69,7 @@ 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 />
+<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>
@@ -79,31 +79,31 @@ process's environment.
<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.
+<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>
+<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>
+<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>argc</em> contiguous NUL-terminated strings contained in the byte-string
+<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 />
+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>
+<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
@@ -111,16 +111,17 @@ 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>
+<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>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>
+<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>
@@ -128,7 +129,7 @@ terminated.
<h3> Envdir functions </h3>
<p>
-<code>int envdir_internal (char const *path, stralloc *modifs, unsigned int options, char nullis)</code></br>
+<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
@@ -140,21 +141,21 @@ the program it executes.
</p>
<p>
-<code>int envdir_chomp (char const *path, stralloc *modifs)</code><br />
+<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 />
+<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>
+<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>
diff --git a/doc/libstddjb/envalloc.html b/doc/libstddjb/envalloc.html
@@ -5,7 +5,7 @@
<meta http-equiv="Content-Language" content="en" />
<title>skalibs: the envalloc header</title>
<meta name="Description" content="skalibs: the envalloc header" />
- <meta name="Keywords" content="skalibs header envalloc environ environment char** stralloc dynamic heap" />
+ <meta name="Keywords" content="skalibs header envalloc environ environment array stralloc dynamic heap" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
@@ -36,7 +36,7 @@ header that lets one use <a href="stralloc.html">genallocs</a> of
<h2> Functions </h2>
<p>
-<code>int envalloc_uniq (genalloc *v, char delim)</code><br />
+<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
@@ -44,7 +44,7 @@ success, -1 (and sets errno) on failure.
</p>
<p>
-<code>int envalloc_0 (genalloc *v)</code><br />
+<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>
