Searches the environment array for the current process and
    returns the value associated with a specified environment name.

    Format

      #include  <stdlib.h>

      char *getenv  (const char *name);

1  –  Argument

 name

    One of the following values:

    o  HOME-Your login directory

    o  TERM-The type of terminal being used

    o  PATH-The default device and directory

    o  USER-The name of the user who initiated the process

    o  Logical name or command-language interpreter (CLI) symbolic
       name

    o  An environment variable set with setenv or putenv

    The case of the specified name is important.

2  –  Description

    In certain situations, the getenv function attempts to perform a
    logical name translation on the user-specified argument:

    1. If the argument to getenv does not match any of the
       environment strings present in your environment array, getenv
       attempts to translate your argument as a logical name by
       searching the logical name tables indicated by the LNM$FILE_
       DEV logical, as is done for file processing.

       getenv first does a case-sensitive lookup. If that fails, it
       does a case-insensitive lookup. In most instances, logical
       names are defined in uppercase, but getenv can also find
       logical names that include lowercase letters.

       getenv does not perform iterative logical name translation.

    2. If the logical name is a search list with multiple equivalence
       values, the returned value points to the first equivalence
       value. For example:

       $ DEFINE A B,C

       ptr = getenv("A");

       A returns a pointer to "B".

    3. If no logical name exists, getenv attempts to translate the
       argument string as a CLI symbol. If it succeeds, it returns
       the translated symbol text. If it fails, the return value is
       NULL.

       getenv does not perform iterative CLI translation.

    If your CLI is the DEC/Shell, the function does not attempt a
    logical name translation since Shell environment symbols are
    implemented as DCL symbols.

                                  NOTES

       o  In OpenVMS Version 7.1, a cache of OpenVMS environment
          variables (that is, logical names and DCL symbols)
          was added to the getenv function to avoid the library
          making repeated calls to translate a logical name or
          to obtain the value of a DCL symbol. By default, the
          cache is disabled. If your application does not need to
          track changes in OpenVMS environment variables that can
          occur during its execution, the cache can be enabled
          by enabling the DECC$ENABLE_GETENV_CACHE logical before
          invoking the application.

       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

    x                  Pointer to an array containing the translated
                       symbol. An equivalence name is returned at
                       index zero.
    NULL               Indicates that the translation failed.