Man Linux: Main Page and Category List

NAME

       putenv - change or add a value to an environment

SYNOPSIS

       #include <stdlib.h>

       int putenv(char *string);

DESCRIPTION

       The  putenv() function shall use the string argument to set environment
       variable values. The string argument should point to a  string  of  the
       form  "  name=  value ".  The putenv() function shall make the value of
       the environment variable name equal to value by  altering  an  existing
       variable  or  creating a new one. In either case, the string pointed to
       by string shall become part of the environment, so altering the  string
       shall  change  the  environment.  The space used by string is no longer
       used once a new string which defines name is passed to putenv().

       The putenv() function need not be reentrant. A  function  that  is  not
       required to be reentrant is not required to be thread-safe.

RETURN VALUE

       Upon  successful  completion,  putenv()  shall  return 0; otherwise, it
       shall return a non-zero value and set errno to indicate the error.

ERRORS

       The putenv() function may fail if:

       ENOMEM Insufficient memory was available.

       The following sections are informative.

EXAMPLES

   Changing the Value of an Environment Variable
       The following  example  changes  the  value  of  the  HOME  environment
       variable to the value /usr/home.

              #include <stdlib.h>
              ...
              static char *var = "HOME=/usr/home";
              int ret;

              ret = putenv(var);

APPLICATION USAGE

       The  putenv()  function  manipulates  the  environment  pointed  to  by
       environ, and can be used in conjunction with getenv().

       See exec() , for restrictions on changing  the  environment  in  multi-
       threaded applications.

       This routine may use malloc() to enlarge the environment.

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

       The setenv() function is preferred over this function.

RATIONALE

       The  standard  developers  noted  that  putenv()  is  the only function
       available to add to the environment without permitting memory leaks.

FUTURE DIRECTIONS

       None.

SEE ALSO

       exec() , getenv() , malloc() , setenv() , the Base  Definitions  volume
       of IEEE Std 1003.1-2001, <stdlib.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .