skalibs: the env header
Keywords: skalibs header env environ environment char**

libstddjb
libskarnet
skalibs
Software
skarnet.org

# The `skalibs/env.h` header

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.

### Bytestrings for environment modifications

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 `argv`s.

`size_t env_len (char const *const* envp)`
Returns the number of elements in the array of strings envp up to, 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 n, char const *s, size_t len)` Deserializes the result of `env_string`: pointers to the first n 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 with a terminating NULL. It only tries to store up to vmax-1 variables, which makes vmax entries after the terminating NULL. 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.