NAME

env_create, env_destroy, env_make, env_addvar, env_addstr, env_remvar, env_lookup, env_getvars -- environment manipulation functions

SYNOPSIS

#include "m_env.h"

env_h env_create( env )
env_h env ;

void env_destroy( env )
env_h env ;

env_h env_make( env_strings )
char **env_strings ;

int env_addvar( env, from_env, var )
env_h env ;
env_h from_env ;
char *var ;

int env_addstr( env, str )
env_h env ;
char *str ;

int env_remvar( env, var )
env_h env ;
char *var ;

char **env_getvars( env )
env_h env ;

DESCRIPTION

This library handles environments. An environment is a set of strings of the form name=value . In the following, we will use the term string as a synonym of NUL-terminated array of char.

env_create() creates a new environment. The new environment will be empty unless the argument env is not ENV_NULL. In that case, the new environment will be a duplicate of env (i.e. they will contain the same strings).

env_destroy() destroys the specified environment.

env_make() creates a new environment which includes the env_strings. env_strings should be a NULL-terminated array of strings.

env_addvar() adds the specified variable var to env. The variable value is obtained from the environment from_env. If the variable exists already in env the old value is replaced with the new value.

env_addstr() adds a string of the form name=value to env.

env_remvar() removes the specified variable var from the environment env.

env_lookup() searches env for variable var. It returns a string of the form name=value where name is the name of the variable (i.e. it is equal to var).

env_getvars returns a NULL-terminated array of strings of the form name=value .

RETURN VALUES

In case of error, all calls will place an error code in the global variable env_errno. Possible error codes:

ENV_ENOMEM

out of memory

ENV_EBADVAR

variable is not in environment

ENV_EBADSTRING

string is not well-formed (i.e. is not of the form name=value).

env_create() returns a handle or ENV_NULL if it fails.

env_make() returns a handle or ENV_NULL if it fails.

env_addvar() returns ENV_OK on success or ENV_ERR on failure.

env_addstr() returns ENV_OK on success or ENV_ERR on failure.

env_remvar() returns ENV_OK on success or ENV_ERR if the variable is not part of the environment.

env_loopkup() returns a string on success or NULL on failure.

SEE ALSO

environ(5)