1PUTENV(P)                  POSIX Programmer's Manual                 PUTENV(P)
2
3
4

NAME

6       putenv - change or add a value to an environment
7

SYNOPSIS

9       #include <stdlib.h>
10
11       int putenv(char *string);
12
13

DESCRIPTION

15       The  putenv() function shall use the string argument to set environment
16       variable values. The string argument should point to a  string  of  the
17       form  "  name=  value ".  The putenv() function shall make the value of
18       the environment variable name equal to value by  altering  an  existing
19       variable  or  creating a new one. In either case, the string pointed to
20       by string shall become part of the environment, so altering the  string
21       shall  change  the  environment.  The space used by string is no longer
22       used once a new string which defines name is passed to putenv().
23
24       The putenv() function need not be reentrant. A  function  that  is  not
25       required to be reentrant is not required to be thread-safe.
26

RETURN VALUE

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

ERRORS

32       The putenv() function may fail if:
33
34       ENOMEM Insufficient memory was available.
35
36
37       The following sections are informative.
38

EXAMPLES

40   Changing the Value of an Environment Variable
41       The following example changes the value of the HOME  environment  vari‐
42       able to the value /usr/home.
43
44
45              #include <stdlib.h>
46              ...
47              static char *var = "HOME=/usr/home";
48              int ret;
49
50
51              ret = putenv(var);
52

APPLICATION USAGE

54       The  putenv()  function manipulates the environment pointed to by envi‐
55       ron, and can be used in conjunction with getenv().
56
57       See exec() , for restrictions on changing  the  environment  in  multi-
58       threaded applications.
59
60       This routine may use malloc() to enlarge the environment.
61
62       A potential error is to call putenv() with an automatic variable as the
63       argument, then return from the calling function while string  is  still
64       part of the environment.
65
66       The setenv() function is preferred over this function.
67

RATIONALE

69       The standard developers noted that putenv() is the only function avail‐
70       able to add to the environment without permitting memory leaks.
71

FUTURE DIRECTIONS

73       None.
74

SEE ALSO

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

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