env_t()

NAME

env_t - environment manipulation type and functions

SYNOPSIS

#include <interix/env.h>

env_t * env_alloc (void) env_t * env_winlogin (struct passwd *pw) env_t * env_login (struct passwed *pw) env_t * env_cron (struct passwd *pw) void env_free (env_t *environ) char * env_get (env_t *env, char *name) int env_set (env_t *env, char *name, char *value, int action) int env_unset (env_t *env, char *name) int env_put (env_t *env, char *entry, int action) char ** env_array (env_t *env) int env_putarray (env_t *env, char **array, int action) char * env_expand_win (env_t *env, char *str) void env_strfree (char *str)

DESCRIPTION

These calls and the env_t structure (declared in <interix/env.h>) deal with user environments in the Interix subsystem. The env_t structure is an opaque data structure; all manipulation of its members should be done through these calls.

The following functions are provided:

env_t * env_alloc() Allocate a new, empty env_t object.
env_t * env_winlogin() Create an env_t object initialized with Win32 data.
env_t * env_login() Create a standard env_t object.
env_t * env_cron() Create a standard env_t object initialized for the user's cron environment.
void env_free() Deallocate an env_t object.
char * env_get() Get the value for an environment variable.
int env_set() Set the value for an environment variable.
int env_put() Set the value for an environment variable as a single string.
int env_unset() Unset an environment variable.
char ** env_array() Return pointer to an array of environment entries.
int env_putarray() Set the values in an array of environment entries.
char * env_expand_win() Expand Windows environment variables
void env_strfree() Deallocate memory used for string.

For all the functions that take a struct passwd argument, (env_login(3), env_cron(3), and env_winlogin(3)) it is the responsibility of the caller to ensure this structure contains current and valid information returned from a successful call to getpwuid(2) or getpwnam(2). If this structure contains invalid data, then the data returned from the env_* functions will also be invalid. These functions do not check if the struct passwd contains valid data so there is no error indication can be returned.

The env_alloc(3) call creates an empty env_t object.

The env_winlogin(3) call creates a new env_t object and initializes it with the standard Windows login environment for the user specified in the pw password structure. The Windows login environment is already in the Interix syntax. (The conversion is done by converting all environment variable names to upper case, and by translating the Windows PATH variable to the Interix syntax.)

The env_login(3) call creates a new env_t object and initializes it with the standard Interix user environment for the user specified in the pw password structure. The Interix environment consists of the Windows login environment (as created by env_winlogin(3)) plus HOME (pw->pw_dir), LOGNAME (pw->pw_name), SHELL (/bin/sh), and LD_LIBRARY_PATH (/usr/lib).

The env_cron(3) call creates a new env_t object and initializes it with the standard cron(1) environment, as required by the Single UNIX Standard, for the user specified in the pw password structure. The environment defined includes the Windows login environment (as returned by env_winlogin(3)) plus HOME, LOGNAME, SHELL, PATH, and LD_LIBRARY_PATH.

The env_free(3) call deallocates an existing env_t object.

The env_get(3) call retrieves the value of name within the environment object env. It returns a pointer to the value, or NULL if the variable isn't set.

The env_set(3) call sets the environment variable name to the provided value in the environment referenced by env. The action controls how the variable is set and can have one of the following values:

ENV_OVERRIDE
Set name; if name is already defined, override the current value.
ENV_SETIFUNSET
Set name only if it is currently not defined.
ENV_APPEND
Quickly append a new name-value pair to the end of the environment without checking to see if name is already defined.

If the action is invalid, the call returns -1.

The env_put(3) function behaves in the same way as env_set(3), except that the name and value are represented as a single string, entry, of the form

name=value

The env_array(3) call returns the contents of an env_t structure as a conventional NULL-terminated array of environment entries.

The env_putarray(3) function takes a traditional NULL-terminated array of environment entries, array, and calls env_put(3) once for env_t structure env.

The env_expand_win(3) call takes str and expands all occurrences of the Windows %var% syntax with the value of the variable var found in env. If env is NULL, then the environment used is the Windows system environment. The call returns a new string, or NULL if there's an error. Note that the new string can only be deallocated by calling env_strfree(3).

The env_strfree(3) call deallocates the memory pointed to by str.

RETURN VALUES

The functions env_alloc(3), env_winlogin(3), env_login(3), env_cron(3), env_get(3), env_array(3), and env_expand_win(3) functions return a pointer on success or NULL on failure. The env_set(3), env_unset(3), env_put(3), and env_putarray(3) functions return 0 on success or -1 on failure.

On failure, all of these functions set errno to indicate the cause of the error.

ERRORS

The env_*(3) functions can fail for the following reasons:

[EINVAL]
The entry in an env_put(3) call was poorly formed.
[EIO]
An I/O error while reading the system environment.
[ENOENT]
The user's environment could not be retrieved from the registry.
[ENOMEM]
Insufficient memory to allocate the env_t object.
[ERANGE]
A string in the environment cannot be represented in the current locale.

SEE ALSO

login(1)