# envz_add

## NAME



           envz_add, envz_entry, envz_get, envz_merge, envz_remove,
           envz_strip - environment string support
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <envz.h>**
    
           **error_t envz_add(char **restrict** _envz_**, size_t *restrict** _envz_len_**,**
                          **const char *restrict** _name_**, const char *restrict** _value_**);**
    
           **char *envz_entry(const char *restrict** _envz_**, size_t** _envz_len_**,**
                          **const char *restrict** _name_**);**
    
           **char *envz_get(const char *restrict** _envz_**, size_t** _envz_len_**,**
                          **const char *restrict** _name_**);**
    
           **error_t envz_merge(char **restrict** _envz_**, size_t *restrict** _envz_len_**,**
                          **const char *restrict** _envz2_**, size_t** _envz2_len_**,**
                          **int** _override_**);**
    
           **void envz_remove(char **restrict** _envz_**, size_t *restrict** _envz_len_**,**
                          **const char *restrict** _name_**);**
    
           **void envz_strip(char **restrict** _envz_**, size_t *restrict** _envz_len_**);**
    


## DESCRIPTION



           These functions are glibc-specific.
    
           An argz vector is a pointer to a character buffer together with a
           length, see argz_add(3).  An envz vector is a special argz vector,
           namely one where the strings have the form "name=value".
           Everything after the first '=' is considered to be the value.  If
           there is no '=', the value is taken to be NULL.  (While the value
           in case of a trailing '=' is the empty string "".)
    
           These functions are for handling envz vectors.
    
           **envz_add**() adds the string "_name_ =_value_ " (in case _value_ is non-
           NULL) or "_name_ " (in case _value_ is NULL) to the envz vector
           (_*envz_ , _*envz_len_) and updates _*envz_ and _*envz_len_.  If an entry
           with the same _name_ existed, it is removed.
    
           **envz_entry**() looks for _name_ in the envz vector (_envz_ , _envz_len_)
           and returns the entry if found, or NULL if not.
    
           **envz_get**() looks for _name_ in the envz vector (_envz_ , _envz_len_) and
           returns the value if found, or NULL if not.  (Note that the value
           can also be NULL, namely when there is an entry for _name_ without
           '=' sign.)
    
           **envz_merge**() adds each entry in _envz2_ to _*envz_ , as if with
           **envz_add**().  If _override_ is true, then values in _envz2_ will
           supersede those with the same name in _*envz_ , otherwise not.
    
           **envz_remove**() removes the entry for _name_ from (_*envz_ , _*envz_len_)
           if there was one.
    
           **envz_strip**() removes all entries with value NULL.
    


## RETURN VALUE



           All envz functions that do memory allocation have a return type of
           _error_t_ (an integer type), and return 0 for success, and **ENOMEM** if
           an allocation error occurs.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **envz_add**(), **envz_entry**(),            │ Thread safety │ MT-Safe │
           │ **envz_get**(), **envz_merge**(),            │               │         │
           │ **envz_remove**(), **envz_strip**()          │               │         │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## STANDARDS



           GNU.
    


## EXAMPLES



           #include <envz.h>
           #include <stdio.h>
           #include <stdlib.h>
    
           int
           main(int argc, char *argv[], char *envp[])
           {
               char    *str;
               size_t  e_len = 0;
    
               for (size_t i = 0; envp[i] != NULL; i++)
                   e_len += strlen(envp[i]) + 1;
    
               str = envz_entry(*envp, e_len, "HOME");
               printf("%s\n", str);
               str = envz_get(*envp, e_len, "HOME");
               printf("%s\n", str);
               exit(EXIT_SUCCESS);
           }
    


* * *