1SETENV(3P) POSIX Programmer's Manual SETENV(3P)
2
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
12 setenv — add or change environment variable
13
15 #include <stdlib.h>
16 int setenv(const char *envname, const char *envval, int overwrite);
18
20 The setenv() function shall update or add a variable in the environment
21 of the calling process. The envname argument points to a string con‐
22 taining the name of an environment variable to be added or altered. The
23 environment variable shall be set to the value to which envval points.
24 The function shall fail if envname points to a string which contains an
25 '=' character. If the environment variable named by envname already
26 exists and the value of overwrite is non-zero, the function shall
27 return success and the environment shall be updated. If the environment
28 variable named by envname already exists and the value of overwrite is
29 zero, the function shall return success and the environment shall
30 remain unchanged.
31 The setenv() function shall update the list of pointers to which envi‐
33 ron points.
34 The strings described by envname and envval are copied by this func‐
36 tion.
37 The setenv() function need not be thread-safe.
39
41 Upon successful completion, zero shall be returned. Otherwise, -1 shall
42 be returned, errno set to indicate the error, and the environment shall
43 be unchanged.
44
46 The setenv() function shall fail if:
47 EINVAL The envname argument points to an empty string or points to a
49 string containing an '=' character.
50 ENOMEM Insufficient memory was available to add a variable or its value
52 to the environment.
53 The following sections are informative.
55
57 None.
58
60 See exec() for restrictions on changing the environment in multi-
61 threaded applications.
62
64 Unanticipated results may occur if setenv() changes the external vari‐
65 able environ. In particular, if the optional envp argument to main()
66 is present, it is not changed, and thus may point to an obsolete copy
67 of the environment (as may any other copy of environ). However, other
68 than the aforementioned restriction, the standard developers intended
69 that the traditional method of walking through the environment by way
70 of the environ pointer must be supported.
71 It was decided that setenv() should be required by this version because
73 it addresses a piece of missing functionality, and does not impose a
74 significant burden on the implementor.
75 There was considerable debate as to whether the System V putenv() func‐
77 tion or the BSD setenv() function should be required as a mandatory
78 function. The setenv() function was chosen because it permitted the
79 implementation of the unsetenv() function to delete environmental vari‐
80 ables, without specifying an additional interface. The putenv() func‐
81 tion is available as part of the XSI option.
82 The standard developers considered requiring that setenv() indicate an
84 error when a call to it would result in exceeding {ARG_MAX}. The
85 requirement was rejected since the condition might be temporary, with
86 the application eventually reducing the environment size. The ultimate
87 success or failure depends on the size at the time of a call to exec,
88 which returns an indication of this error condition.
89 See also the RATIONALE section in getenv().
91
93 None.
94
96 exec, getenv(), putenv(), unsetenv()
97 The Base Definitions volume of POSIX.1‐2017, <stdlib.h>, <sys_types.h>,
99 <unistd.h>
100
102 Portions of this text are reprinted and reproduced in electronic form
103 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
104 table Operating System Interface (POSIX), The Open Group Base Specifi‐
105 cations Issue 7, 2018 Edition, Copyright (C) 2018 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 Any typographical or formatting errors that appear in this page are
113 most likely to have been introduced during the conversion of the source
114 files to man page format. To report such errors, see https://www.ker‐
115 nel.org/doc/man-pages/reporting_bugs.html .
116IEEE/The Open Group 2017 SETENV(3P)