envz_add, envz_entry, envz_get, envz_merge, envz_remove, envz_strip

Name

envz_add, envz_entry, envz_get, envz_merge, envz_remove, envz_strip -- Operate on environment vectors

Synopsis

#include <envz.h>

error_t envz_add(char ** envz, size_t * envz_len, const char * name, const char * value);

char envz_entry(const char * envz, size_t envz_len, const char * name);

char envz_get(const char * envz, size_t envz_len, const char * name);

error_t envz_merge(char ** envz, size_t * envz_len, const char * envz2, size_t envz2_len, int override);

void envz_remove(char ** envz, size_t * envz_len, const char * name);

void envz_strip(char ** envz, size_t * envz_len);

Description

The envz functions operate on envz vectors, which are typically used to manipulate program environment variables.

An envz vector is identical in makeup to an argz vector (see argz_add, argz_add_sep, argz_append, argz_count, argz_create, argz_create_sep, argz_delete, argz_extract, argz_insert, argz_next, argz_replace, argz_stringify) but has the constraint that each element is a name, value pair separated by an = character. Only the first = character in an element has special meaning, any subsequent instances are part of the value string. If no = character is present in an element, the value is taken to be NULL. If an element has an empty value (an = character is present), the value will return the empty string "" when queried.

Since an envz vector is an argz vector, the argz functions can be used where it makes sense. For example, converting from a program's environment variables (as described in Chapter 8 of the XBD volume of POSIX 1003.1-2008 (ISO/IEC 9945-2009)) to an envz vector is done with argz_create().

The envz_add() function adds a string constructed from name and value in the form "name=value" to the envz vector identified by envz and envz_len, updating envz and envz_len. If value is NULL it adds a string of the form "name". If an entry with the same name already exists, it is replaced..

The envz_entry() function searches for name in the envz vector identified by envz and envz_len, returning the full entry if found, or NULL if not.

The envz_get() function searches for name in the envz vector identified by envz and envz_len, returning the value part of the entry if found, or NULL if not. Note the value may be also NULL.

The envz_merge() function adds each entry from the envz vector identified by envz2 and envz2_len to the envz vector identified by envz and envz_len, updating envz and envz_len. The behavior is as if envz_add() were called for each entry in envz2. If override is true, then values from envz2 will replace those with the same name in envz.

The envz_remove() function removes the entry for name from the envz vector identified by envz and envz_len if it exists, updating envz and envz_len.

The envz_strip() function removes all entries with value NULL.

Return Value

The envz functions that perform memory allocation (envz_add() and envz_merge()) return an error_t type. These functions return 0 on success; if memory allocation fails, they return ENOMEM.

envz_entry() and envz_get() return a pointer to a substring in an envz vector, or NULL.

See Also

argz_add, argz_add_sep, argz_append, argz_count, argz_create, argz_create_sep, argz_delete, argz_extract, argz_insert, argz_next, argz_replace, argz_stringify