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
'=' characters are present in an element, that element is
considered the name of a “null” entry, as distinct from an entry with an
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
As with argz functions, envz functions that may allocate memory (and thus
fail) have a return type of
error_t, and return either
These functions are declared in the standard include file envz.h.
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,
envz_getfunction 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),
envz_addfunction adds an entry to
*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).
envz_mergefunction adds each entry in envz2 to envz, as if with
*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.