Envz Functions - The GNU C Library

Previous: Argz Functions, Up: Argz and Envz Vectors

#### 5.12.2 Envz Functions

Envz vectors are just argz vectors with additional constraints on the form of each element; as such, argz functions can also be used on them, where it makes sense.

Each element in an envz vector is a name-value pair, separated by a `'='` character; if multiple `'='` characters are present in an element, those after the first are considered part of the value, and treated like all other non-`'\0'` characters.

If no `'='` characters are present in an element, that element is considered the name of a “null” entry, as distinct from an entry with an empty value: `envz_get` will return `0` if given the name of null entry, whereas an entry with an empty value would result in a value of `""`; `envz_entry` will still find such entries, however. Null entries can be removed with `envz_strip` function.

As with argz functions, envz functions that may allocate memory (and thus fail) have a return type of `error_t`, and return either `0` or `ENOMEM`.

These functions are declared in the standard include file `envz.h`.

— Function: char * envz_entry (const char *envz, size_t envz_len, const char *name)

> The `envz_entry` function finds the entry in envz with the name name, and returns a pointer to the whole entry—that is, the argz element which begins with name followed by a `'='` character. If there is no entry with that name, `0` is returned.

— Function: char * envz_get (const char *envz, size_t envz_len, const char *name)

> The `envz_get` function finds the entry in envz with the name name (like `envz_entry`), and returns a pointer to the value portion of that entry (following the `'='`). If there is no entry with that name (or only a null entry), `0` is returned.

— Function: error_t envz_add (char **envz, size_t *envz_len, const char *name, const char *value)

> The `envz_add` function adds an entry to `*`envz (updating `*`envz and `*`envz_len) with the name name, and value value. If an entry with the same name already exists in envz, it is removed first. If value is `0`, then the new entry will the special null type of entry (mentioned above).

— Function: error_t envz_merge (char **envz, size_t *envz_len, const char *envz2, size_t envz2_len, int override)

> The `envz_merge` function adds each entry in envz2 to envz, as if with `envz_add`, updating `*`envz and `*`envz_len. If override is true, then values in envz2 will supersede those with the same name in envz, otherwise not.

> Null entries are treated just like other entries in this respect, so a null entry in envz can prevent an entry of the same name in envz2 from being added to envz, if override is false.

— Function: void envz_strip (char **envz, size_t *envz_len)

> The `envz_strip` function removes any null entries from envz, updating `*`envz and `*`envz_len.