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

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       setenv - add or change environment variable
13

SYNOPSIS

15       #include <stdlib.h>
16
17       int setenv(const char *envname, const char *envval, int overwrite);
18
19

DESCRIPTION

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

RETURN VALUE

44       Upon successful completion, zero shall be returned. Otherwise, -1 shall
45       be returned, errno set to indicate the error, and the environment shall
46       be unchanged.
47

ERRORS

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

EXAMPLES

61       None.
62

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

95       None.
96

SEE ALSO

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

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