env_get(3)                                                   env_get(3)

  env_t()

  NAME

    env_t - environment manipulation type and functions

  SYNOPSIS

    #include 

    env_t * env_alloc (void)
    env_t * env_winlogin (struct passwd *pw)
    env_t * env_login (struct passwd *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 ) 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)

  USAGE NOTES

    None of these functions are thread safe.

    None of these functions are async-signal safe.