Sets an environmental variable.

    Format

      #include  <stdlib.h>

      int putenv  (const char *string);

1  –  Argument

 string

    A pointer to a name=value string.

2  –  Description

    The putenv function sets the value of an environment variable
    by altering an existing variable or by creating a new one. The
    string argument points to a string of the form name=value, where
    name is the environment variable and value is the new value for
    it.

    The string pointed to by string becomes part of the environment,
    so altering the string changes the environment. When a new
    string-defining name is passed to putenv, the space used by
    string is no longer used.

                                  NOTES

       o  The putenv function manipulates the environment pointed
          to by the environ external variable, and can be used with
          getenv. However, the third argument to the main function
          (the environment pointer), is not changed.

          The putenv function uses the malloc function to enlarge
          the environment.

          A potential error is to call putenv with an automatic
          variable as the argument, then exit the calling function
          while string is still part of the environment.

       o  Do not use the setenv, getenv, and putenv functions
          to manipulate symbols and logicals. Instead, use the
          OpenVMS library calls lib$set_logical, lib$get_logical,
          lib$set_symbol, and lib$get_symbol. The *env functions
          deliberately provide UNIX behavior, and are not a
          substitute for these OpenVMS runtime library calls.

          OpenVMS DCL symbols, not logical names, are the closest
          analog to environment variables on UNIX systems. While
          getenv is a mechanism to retrieve either a logical name
          or a symbol, it maintains an internal cache of values for
          use with setenv and subsequent getenv calls. The setenv
          function does not write or create DCL symbols or OpenVMS
          logical names.

          This is consistent with UNIX behavior. On UNIX systems,
          setenv does not change or create any symbols that will be
          visible in the shell after the program exits.

3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error. errno is set to ENOMEM-
                       Not enough memory available to expand the
                       environment list.

4  –  Restriction

    The putenv function cannot take a 64-bit address.