Previous: Argz Functions, Up: Argz and Envz Vectors
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.
The
envz_entryfunction 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,0is returned.
The
envz_getfunction finds the entry in envz with the name name (likeenvz_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),0is returned.
The
envz_addfunction 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 is0, then the new entry will the special null type of entry (mentioned above).
The
envz_mergefunction adds each entry in envz2 to envz, as if withenvz_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.