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
13 setenv — add or change environment variable
14
16 #include <stdlib.h>
17 int setenv(const char *envname, const char *envval, int overwrite);
19
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 The setenv() function shall update the list of pointers to which envi‐
34 ron points.
35 The strings described by envname and envval are copied by this func‐
37 tion.
38 The setenv() function need not be thread-safe.
40
42 Upon successful completion, zero shall be returned. Otherwise, −1 shall
43 be returned, errno set to indicate the error, and the environment shall
44 be unchanged.
45
47 The setenv() function shall fail if:
48 EINVAL The envname argument points to an empty string or points to a
50 string containing an '=' character.
51 ENOMEM Insufficient memory was available to add a variable or its value
53 to the environment.
54 The following sections are informative.
56
58 None.
59
61 See exec() for restrictions on changing the environment in multi-
62 threaded applications.
63
65 Unanticipated results may occur if setenv() changes the external vari‐
66 able environ. In particular, if the optional envp argument to main()
67 is present, it is not changed, and thus may point to an obsolete copy
68 of the environment (as may any other copy of environ). However, other
69 than the aforementioned restriction, the standard developers intended
70 that the traditional method of walking through the environment by way
71 of the environ pointer must be supported.
72 It was decided that setenv() should be required by this version because
74 it addresses a piece of missing functionality, and does not impose a
75 significant burden on the implementor.
76 There was considerable debate as to whether the System V putenv() func‐
78 tion or the BSD setenv() function should be required as a mandatory
79 function. The setenv() function was chosen because it permitted the
80 implementation of the unsetenv() function to delete environmental vari‐
81 ables, without specifying an additional interface. The putenv() func‐
82 tion is available as part of the XSI option.
83 The standard developers considered requiring that setenv() indicate an
85 error when a call to it would result in exceeding {ARG_MAX}. The
86 requirement was rejected since the condition might be temporary, with
87 the application eventually reducing the environment size. The ultimate
88 success or failure depends on the size at the time of a call to exec,
89 which returns an indication of this error condition.
90 See also the RATIONALE section in getenv().
92
94 None.
95
97 exec, getenv(), putenv(), unsetenv()
98 The Base Definitions volume of POSIX.1‐2008, <stdlib.h>, <sys_types.h>,
100 <unistd.h>
101
103 Portions of this text are reprinted and reproduced in electronic form
104 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
105 -- Portable Operating System Interface (POSIX), The Open Group Base
106 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
107 cal and Electronics Engineers, Inc and The Open Group. (This is
108 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
109 event of any discrepancy between this version and the original IEEE and
110 The Open Group Standard, the original IEEE and The Open Group Standard
111 is the referee document. The original Standard can be obtained online
112 at http://www.unix.org/online.html .
113 Any typographical or formatting errors that appear in this page are
115 most likely to have been introduced during the conversion of the source
116 files to man page format. To report such errors, see https://www.ker‐
117 nel.org/doc/man-pages/reporting_bugs.html .
118IEEE/The Open Group 2013 SETENV(3P)