From bcb8e950789c173c387bea5c8a6906f9e26a8038 Mon Sep 17 00:00:00 2001 From: Carlos Eduardo Date: Fri, 17 May 2024 17:16:06 -0300 Subject: 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. --- doc/libstddjb/env.html | 137 +++++++++++++++++++++++++++++++++++++++++++- 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 @@

The skalibs/env.h header

- TODO: write this documentation page. (Sorry!) + The following functions are declared in the skalibs/env.h header, +and implemented in the libskarnet.a or libskarnet.so library. +

+ +

General information

+ +

+ env.h contains functions that help shape the environment of programs + before spawning or executing them, without affecting the environment of the + main program. +

+ +

+ Unless otherwise noted, all functions in this header return 1 on success or + 0 (and set errno) on failure. +

+ + +

Modif bytestrings

+ +

+A few functions in env.h (and many in exec.h) +have arguments named modifs and modiflen. A modif +is a byte-string that encodes a series of instructions to set/override +environment variables, or to remove them from the environment. +

+ +

Functions

+ +

Fetching variables

+ +

+char const *env_get (char const *s)
+Deprecated alias of +getenv(). +

+ +

+char const *ucspi_get (char const *s)
+Prepends the current UCSPI protocol +to s and returns that environment variable. For instance, +uscpi_get("REMOTEEUID") would return the contents of the environment +variable IPCREMOTEEUID under s6-ipcserver. 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. +

+ +

+char const *env_get2 (char const *const *envp, char const *s)
+Similar to getenv(), but searches in envp instead of the current +process's environment. +

+ +

Serialization

+ +

Despite the name, these functions also work for argvs.

+ +

+size_t env_len (char const *const* envp)
+Returns the number of elements in the array of strings envp up (but +not including) the first null pointer. +

+ +

+int env_string (stralloc *sa, char const *const *envp, size_t envlen)
+Serializes the array of NUL-terminated strings envp with envlen +elements into a series of contiguous NUL-terminated strings in the stralloc +*sa. +

+ +

+int env_make (char const **v, size_t argc, char const *s, size_t len)
+Deserializes the result of env_string: pointers to the first +argc contiguous NUL-terminated strings contained in the byte-string +s of length len are written to v. Returns 1 on +success, or 0 EINVAL if s does not end in a NUL.
+Note that this function does not write NULL to the final value of v. +

+ +

Environment modification

+ +

+int env_addmodif (stralloc *sa, char const *s, char const *t)
+Adds an instruction to the modif contained in *sa. If t is +null, add an instruction to remove the variable s from the +environment. If t is not null, add an instruction to always set the +variable s to t. +

+ +

+size_t env_merge (char const **v, size_t vmax, char const *const *envp, size_t envlen, char const *modifs, size_t modiflen)
+Takes the environment with envlen variables contained in envp, +applies the modifications encoded in the modif modifs of length +modiflen, and stores the result in v. It only tries to store +up to vmax variables. Returns the number of elements now in +v, or 0 if the resulting v would be larger than vmax. +

+ +

+size_t env_merg (char const **v, size_t vmax, char const *const *envp, char const *modifs, size_t modiflen)
+Similar to the above function, but envp is assumed to be NULL +terminated. +

+ +

Envdir functions

+ +

+int envdir_internal (char const *path, stralloc *modifs, unsigned int options, char nullis)
+Essentially s6-envdir as library. +options is a bitwise OR of SKALIBS_ENVDIR_VERBATIM, +SKALIBS_ENVDIR_NOCHOMP and SKALIBS_ENVDIR_NOCLAMP, which +correspond to s6-envdir's -f, -n and -L options, +respectively.
+It adds instructions to modifs that replicate the effect +s6-envdir [-f] [-n] [-L] -c nullis path would have on +the program it executes. +

+ +

+int envdir_chomp (char const *path, stralloc *modifs)
+A macro that calls +envdir_internal(path, modifs, SKALIBS_ENVDIR_NOCHOMP, '\n'). +

+ +

+int envdir (char const *path, stralloc *modifs)
+int envdir_verbatim (char const *path, stralloc *modifs)
+int envdir_verbatim_chomp (char const *path, stralloc *modifs)
+Macros that call envdir_internal(path, modifs, options, '\n'), with +options set to self-explanatory values. +

+ +

+int env_dump (char const *dir, mode_t mode, char const *const *envp)
+Turns the contents of the NULL terminated environment in envp into an +envdir located at dir. Files are created with mode mode.

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 @@

The skalibs/envalloc.h header

- TODO: write this documentation page. (Sorry!) + The following functions are declared in the skalibs/env.h header, +and implemented in the libskarnet.a or libskarnet.so library. +

+ +

General information

+ +

+envalloc.h is a supplement of env.h +header that lets one use genallocs of +char const * instead of fixed-size char const *[]. +

+ +

Functions

+ +

+int envalloc_uniq (genalloc *v, char delim)
+Removes strings in the v that share the same prefix up to the first +delim character. For instance, if delim is =, duplicate +environment variables are removed. Returns the number of removed entries on +success, -1 (and sets errno) on failure. +

+ +

+int envalloc_0 (genalloc *v)
+Appends a null pointer to v. Returns 1 on sucess, 0 (and sets errno) +on failure. +

+ +

+envalloc_make and envalloc_merge work exactly like their +env.h counterparts.

-- cgit v1.2.3