mirror of https://github.com/mkerrisk/man-pages
121 lines
4.6 KiB
Plaintext
121 lines
4.6 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "SETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" setenv
|
|
.SH NAME
|
|
setenv \- add or change environment variable
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdlib.h>
|
|
.br
|
|
.sp
|
|
int setenv(const char *\fP\fIenvname\fP\fB, const char *\fP\fIenvval\fP\fB,
|
|
int\fP \fIoverwrite\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIsetenv\fP() function shall update or add a variable in the
|
|
environment of the calling process. The \fIenvname\fP
|
|
argument points to a string containing the name of an environment
|
|
variable to be added or altered. The environment variable shall
|
|
be set to the value to which \fIenvval\fP points. The function shall
|
|
fail if \fIenvname\fP points to a string which contains an
|
|
\fB'='\fP character. If the environment variable named by \fIenvname\fP
|
|
already exists and the value of \fIoverwrite\fP is
|
|
non-zero, the function shall return success and the environment shall
|
|
be updated. If the environment variable named by
|
|
\fIenvname\fP already exists and the value of \fIoverwrite\fP is zero,
|
|
the function shall return success and the environment
|
|
shall remain unchanged.
|
|
.LP
|
|
If the application modifies \fIenviron\fP or the pointers to which
|
|
it points, the behavior of \fIsetenv\fP() is undefined. The
|
|
\fIsetenv\fP() function shall update the list of pointers to which
|
|
\fIenviron\fP points.
|
|
.LP
|
|
The strings described by \fIenvname\fP and \fIenvval\fP are copied
|
|
by this function.
|
|
.LP
|
|
The \fIsetenv\fP() function need not be reentrant. A function that
|
|
is not required to be reentrant is not required to be
|
|
thread-safe.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, zero shall be returned. Otherwise, -1
|
|
shall be returned, \fIerrno\fP set to indicate the error, and
|
|
the environment shall be unchanged.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIsetenv\fP() function shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIname\fP argument is a null pointer, points to an empty string,
|
|
or points to a string containing an \fB'='\fP
|
|
character.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient memory was available to add a variable or its value to
|
|
the environment.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
See \fIexec\fP() , for restrictions on changing the environment in
|
|
multi-threaded applications.
|
|
.SH RATIONALE
|
|
.LP
|
|
Unanticipated results may occur if \fIsetenv\fP() changes the external
|
|
variable \fIenviron\fP. In particular, if the optional
|
|
\fIenvp\fP argument to \fImain\fP() is present, it is not changed,
|
|
and thus may point to an obsolete copy of the environment (as
|
|
may any other copy of \fIenviron\fP). However, other than the aforementioned
|
|
restriction, the developers of
|
|
IEEE\ Std\ 1003.1-2001 intended that the traditional method of walking
|
|
through the environment by way of the \fIenviron\fP
|
|
pointer must be supported.
|
|
.LP
|
|
It was decided that \fIsetenv\fP() should be required by this revision
|
|
because it addresses a piece of missing functionality,
|
|
and does not impose a significant burden on the implementor.
|
|
.LP
|
|
There was considerable debate as to whether the System V \fIputenv\fP()
|
|
function or the
|
|
BSD \fIsetenv\fP() function should be required as a mandatory function.
|
|
The \fIsetenv\fP() function was chosen because it
|
|
permitted the implementation of the \fIunsetenv\fP() function to delete
|
|
environmental
|
|
variables, without specifying an additional interface. The \fIputenv\fP()
|
|
function is
|
|
available as an XSI extension.
|
|
.LP
|
|
The standard developers considered requiring that \fIsetenv\fP() indicate
|
|
an error when a call to it would result in exceeding
|
|
{ARG_MAX}. The requirement was rejected since the condition might
|
|
be temporary, with the application eventually reducing the
|
|
environment size. The ultimate success or failure depends on the size
|
|
at the time of a call to \fIexec\fP, which returns an indication of
|
|
this error condition.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIexec\fP() , \fIgetenv\fP() , \fIunsetenv\fP() , the Base Definitions
|
|
volume of IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP, \fI<sys/types.h>\fP,
|
|
\fI<unistd.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|