Linux Standard Base Core Specification, Generic Part | ||
---|---|---|
<<< Previous | Next >>> |
#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);
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
.
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
.
<<< Previous | Home | Next >>> |
endutent | Up | epoll_create |