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

NAME

6       setenv - add or change environment variable
7

SYNOPSIS

9       #include <stdlib.h>
10
11       int setenv(const char *envname, const char *envval, int overwrite);
12
13

DESCRIPTION

15       The setenv() function shall update or add a variable in the environment
16       of the calling process. The envname argument points to  a  string  con‐
17       taining the name of an environment variable to be added or altered. The
18       environment variable shall be set to the value to which envval  points.
19       The function shall fail if envname points to a string which contains an
20       '=' character. If the environment variable  named  by  envname  already
21       exists  and  the  value  of  overwrite  is non-zero, the function shall
22       return success and the environment shall be updated. If the environment
23       variable  named by envname already exists and the value of overwrite is
24       zero, the function shall  return  success  and  the  environment  shall
25       remain unchanged.
26
27       If the application modifies environ or the pointers to which it points,
28       the behavior of setenv() is  undefined.  The  setenv()  function  shall
29       update the list of pointers to which environ points.
30
31       The  strings  described  by envname and envval are copied by this func‐
32       tion.
33
34       The setenv() function need not be reentrant. A  function  that  is  not
35       required to be reentrant is not required to be thread-safe.
36

RETURN VALUE

38       Upon successful completion, zero shall be returned. Otherwise, -1 shall
39       be returned, errno set to indicate the error, and the environment shall
40       be unchanged.
41

ERRORS

43       The setenv() function shall fail if:
44
45       EINVAL The  name argument is a null pointer, points to an empty string,
46              or points to a string containing an '=' character.
47
48       ENOMEM Insufficient memory was available to add a variable or its value
49              to the environment.
50
51
52       The following sections are informative.
53

EXAMPLES

55       None.
56

APPLICATION USAGE

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

RATIONALE

62       Unanticipated results may occur if setenv() changes the external  vari‐
63       able environ. In particular, if the optional envp argument to main() is
64       present, it is not changed, and thus may point to an obsolete  copy  of
65       the environment (as may any other copy of environ). However, other than
66       the aforementioned restriction, the developers of  IEEE Std 1003.1-2001
67       intended that the traditional method of walking through the environment
68       by way of the environ pointer must be supported.
69
70       It was decided that  setenv()  should  be  required  by  this  revision
71       because  it  addresses  a  piece of missing functionality, and does not
72       impose a significant burden on the implementor.
73
74       There was considerable debate as to whether the System V putenv() func‐
75       tion  or  the  BSD  setenv() function should be required as a mandatory
76       function.  The setenv() function was chosen because  it  permitted  the
77       implementation of the unsetenv() function to delete environmental vari‐
78       ables, without specifying an additional interface. The  putenv()  func‐
79       tion is available as an XSI extension.
80
81       The  standard developers considered requiring that setenv() indicate an
82       error when a call to  it  would  result  in  exceeding  {ARG_MAX}.  The
83       requirement  was  rejected since the condition might be temporary, with
84       the application eventually reducing the environment size. The  ultimate
85       success  or  failure depends on the size at the time of a call to exec,
86       which returns an indication of this error condition.
87

FUTURE DIRECTIONS

89       None.
90

SEE ALSO

92       exec() , getenv()  ,  unsetenv()  ,  the  Base  Definitions  volume  of
93       IEEE Std 1003.1-2001, <stdlib.h>, <sys/types.h>, <unistd.h>
94

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