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)

Man(1) output converted with man2html