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
11

NAME

13       setenv — add or change environment variable
14

SYNOPSIS

16       #include <stdlib.h>
17
18       int setenv(const char *envname, const char *envval, int overwrite);
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       The setenv() function shall update the list of pointers to which  envi‐
34       ron points.
35
36       The  strings  described  by envname and envval are copied by this func‐
37       tion.
38
39       The setenv() function need not be thread-safe.
40

RETURN VALUE

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

ERRORS

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

EXAMPLES

58       None.
59

APPLICATION USAGE

61       See exec() for restrictions  on  changing  the  environment  in  multi-
62       threaded applications.
63

RATIONALE

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
73       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
77       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
84       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
91       See also the RATIONALE section in getenv().
92

FUTURE DIRECTIONS

94       None.
95

SEE ALSO

97       exec, getenv(), putenv(), unsetenv()
98
99       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
114       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 .
118
119
120
121IEEE/The Open Group                  2013                           SETENV(3P)
Impressum