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

DESCRIPTION

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
32       The setenv() function shall update the list of pointers to which  envi‐
33       ron points.
34
35       The  strings  described  by envname and envval are copied by this func‐
36       tion.
37
38       The setenv() function need not be thread-safe.
39

RETURN VALUE

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

ERRORS

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

EXAMPLES

57       None.
58

APPLICATION USAGE

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

RATIONALE

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
72       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
76       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
83       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
90       See also the RATIONALE section in getenv().
91

FUTURE DIRECTIONS

93       None.
94

SEE ALSO

96       exec, getenv(), putenv(), unsetenv()
97
98       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
112       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 .
116
117
118
119IEEE/The Open Group                  2017                           SETENV(3P)
Impressum