Node:Envz Functions, 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
.
char * envz_entry (const char *envz, size_t envz_len, const char *name) | Function |
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.
|
char * envz_get (const char *envz, size_t envz_len, const char *name) | Function |
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.
|
error_t envz_add (char **envz, size_t *envz_len, const char *name, const char *value) | Function |
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).
|
error_t envz_merge (char **envz, size_t *envz_len, const char *envz2, size_t envz2_len, int override) | Function |
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. |
void envz_strip (char **envz, size_t *envz_len) | Function |
The envz_strip function removes any null entries from envz,
updating *envz and *envz_len .
|