ppuutteennvv() -- General Function (libc)

Add a string to the environment
#iinncclluuddee <ssttddlliibb.hh>
iinntt ppuutteennvv (_e_n_v_s_t_r_i_n_g)
cchhaarr *_e_n_v_s_t_r_i_n_g;

The function ppuutteennvv() puts  _e_n_v_s_t_r_i_n_g into the user's environment.  You can
use this  function to set  a new environmental  variable, or to  change the
definition of an existing variable.

_e_n_v_s_t_r_i_n_g must point to a string of the form _V_A_R_I_A_B_L_E=_v_a_l_u_e, where _V_A_R_I_A_B_L_E
is the environmental variable being set, and _v_a_l_u_e is the value to which it
is being set.

ppuutteennvv()  returns zero  if  all goes  well.   If something  goes wrong,  it
returns a value other than zero.

_S_e_e _A_l_s_o
eennvviirroonn, eennvviirroonnmmeennttaall vvaarriiaabblleess, ggeetteennvv(), lliibbcc, ssttddlliibb.hh

_N_o_t_e_s
The  global variable  eennvviirroonn,  which points  to  a process's  environment,
points  to an  array of  pointers  to strings  rather than  to an  array of
strings.  When  ppuutteennvv() inserts _e_n_v_s_t_r_i_n_g  into the environment,  it calls
mmaalllloocc() to  enlarge the array of string pointers  to which eennvviirroonn points,
then inserts  a pointer  to _e_n_v_s_t_r_i_n_g  into that array.   It does  not copy
_e_n_v_s_t_r_i_n_g anywhere.

If a process uses ppuutteennvv() to insert a string pointer into the environment,
it can also  call ggeetteennvv() to read back that  string; however, the array of
strings passed to the process via  eennvvpp (the third argument to the function
mmaaiinn()) is not  affected by a call to ppuutteennvv().  For details on eennvviirroonn and
eennvvpp, see their entries in the Lexicon.

It is an error to call  ppuutteennvv() with a pointer to an automatic variable as
the argument,  and then exit the calling function  while _e_n_v_s_t_r_i_n_g is still
part of  the environment.  For  safety's sake, _e_n_v_s_t_r_i_n_g should  point to a
string that is static or global.   See the Lexicon entry for ssttaattiicc, or see
the ANSI Standard section 3.5.1.
