GETENV(3)                      Library Functions                     GETENV(3)

NAME

       getenv, putenv, setenv, unsetenv, environInit, environPop, environPush,
       - environment variable functions

SYNOPSIS

       #include <stdlib.h>

       char *getenv (const char *name);
       int putenv (const char *string);
       int setenv (const char *name, const char *value int overwrite);
       void unsetenv (const char *name);

       int environInit (void);
       int environPush (void);
       void environPop (void);

DESCRIPTION

       These functions set, unset and fetch  environment  variables  from  the
       host  environment  list.   For compatibility with differing environment
       conventions, the given arguments name and value  may  be  appended  and
       prepended, respectively, with an equal sign.

       The  getenv function obtains the current value of the environment vari‐
       able, name.  If the variable name is not in the current environment,  a
       null pointer is returned.

       The  setenv function inserts or resets the environment variable name in
       the current environment list.  If the variable name does not  exist  in
       the  list,  it  is inserted with the given value.  If the variable does
       exist, the argument overwrite is tested;  if  overwrite  is  zero,  the
       variable is not reset, otherwise it is reset to the given value.

       The putenv function performs the equivalent of:

            setenv(name, value, 1);

       and expects string to be of the form name=value.

       The  unsetenv  function  deletes  all  instances  of  the variable name
       pointed to by name from the list.

       The environInit, environPush, and environPop functions are non-standard
       (GNO-specific).

       The  environInit  function  is used to initialize the environ variable,
       since this functionality is provided by neither shell.  It is necessary
       to  use  environInit  before any explicit references to environ, but if
       environ is not to be referenced, it is  not  necessary  to  call  envi����
       ronInit at all.

       environPush  and environPop are used to push and pop, respectively, the
       environment stack.  See environ (8) for more information.

RETURN VALUES

       The functions environInit, environPush, putenv, and setenv return  zero
       if  successful;  otherwise the global variable errno is set to indicate
       the error and a -1 is returned.

ERRORS

       ENOMEM The functions environInit, environPush, putenv, or setenv failed
              because they were unable to allocate memory for the environment.

CAVEATS

       If  environ  has been modified without using the library routines, then
       the internal shell variables and the shell environment  represented  by
       environ will not be consistent.  Also, since environ entries are dynam‐
       ically allocated and freed, modifying those entries without  using  the
       library  routines may result in memory trashing and unpredicable behav‐
       ior.

AUTHORS

       These routines were written for GNO primarily  by  Devin  Reade.   They
       also contain code fragments from Dave Tribby and James Brookes.

       These  routines also contains code is derived from software contributed
       to Berkeley by the American National Standards Committee X3, on  Infor‐
       mation Processing Systems.

SEE ALSO

       gsh(1), sh(1), execve(2), environ(7),

HISTORY

       The functions setenv and unsetenv appeared in Version 7 AT&T UNIX.  The
       putenv function appeared in 4.3BSD (Reno).

       The first appearance of these routines for GNO was as part of the  (now
       superceeded)  lenviron  library.   They were formally incorporated into
       GNO as of v2.0.6.  These routines are no longer guaranteed to  be  com‐
       patible with the ORCA/Shell.

       The  functions environInit, environPush, and environPop were previously
       initenv, pushenv, and popenv, respectively.



GNO                             29 January 1997                      GETENV(3)