ENVZADD(3) Linux Programmer's Manual ENVZADD(3)

NAME
       envzadd,  envzentry,  envzget, envzmerge, envzremove, envzstrip -
       environment string support

SYNOPSIS
       #include 

       errort envzadd(char **envz, sizet *envzlen,
                        const char *name, const char *value);

       char *envzentry(const char *envz, sizet *envzlen, const char *name);

       char *envzget(const char *envz, sizet *envzlen, const char *name);

       errort envzmerge(char **envz, sizet *envzlen,
                          const char *envz2, sizet envz2len, int override);

       void envzremove(char **envz, sizet *envzlen, const char *name);

       void envzstrip(char **envz, sizet *envzlen);

DESCRIPTION
       These functions are glibc-specific.

       An argz vector is a pointer to  a  character  buffer  together  with  a
       length,  see  argzadd(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.

       envzadd()  adds the string "name=value" (in case value is non-NULL) or
       "name" (in case value is NULL) to the  envz  vector  (*envz, *envzlen)
       and  updates  *envz  and  *envzlen.   If  an  entry with the same name
       existed, it is removed.

       envzentry() looks for name in the  envz  vector  (envz, envzlen)  and
       returns the entry if found, or NULL if not.

       envzget()  looks  for  name  in  the  envz vector (envz, envzlen) 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.)

       envzmerge()  adds each entry in envz2 to *envz, as if with envzadd().
       If override is true, then values in envz2 will supersede those with the
       same name in *envz, otherwise not.

       envzremove()  removes  the  entry  for name from (*envz, *envzlen) if
       there was one.

       envzstrip() removes all entries with value NULL.

RETURN VALUE
       All envz functions that do memory allocation  have  a  return  type  of
       errort,  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   │
       ├────────────────────────────┼───────────────┼─────────┤
       │envzadd(), envzentry(),   │ Thread safety │ MT-Safe │
       │envzget(), envzmerge(),   │               │         │
       │envzremove(), envzstrip() │               │         │
       └────────────────────────────┴───────────────┴─────────┘

CONFORMING TO
       These functions are a GNU extension.  Handle with care.

EXAMPLE
       #include 
       #include 
       #include 

       int
       main(int argc, char *argv[], char *envp[])
       {
           int i, elen = 0;
           char *str;

           for (i = 0; envp[i] != NULL; i++)
               elen += strlen(envp[i]) + 1;

           str = envzentry(*envp, elen, "HOME");
           printf("%s\n", str);
           str = envzget(*envp, elen, "HOME");
           printf("%s\n", str);
           exit(EXITSUCCESS);
       }

SEE ALSO
       argzadd(3)

COLOPHON
       This  page  is  part of release 3.53 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.



                                  2007-05-18                       ENVZADD(3)