summaryrefslogtreecommitdiffstats
path: root/man3/putenv.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/putenv.3142
1 files changed, 142 insertions, 0 deletions
diff --git a/man3/putenv.3 b/man3/putenv.3
new file mode 100644
index 0000000..da15b2e
--- /dev/null
+++ b/man3/putenv.3
@@ -0,0 +1,142 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\" Linux libc source code
+.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\" 386BSD man pages
+.\" Single UNIX Specification, Version 2
+.\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe
+.\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu)
+.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
+.\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl)
+.\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl)
+.\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl)
+.TH putenv 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+putenv \- change or add an environment variable
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.PP
+.BI "int putenv(char *" string );
+.\" Not: const char *
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR putenv ():
+.nf
+ _XOPEN_SOURCE
+ || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+ || /* glibc <= 2.19: */ _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR putenv ()
+function adds or changes the value of environment
+variables.
+The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP.
+If \fIname\fP does not already exist in the environment, then
+\fIstring\fP is added to the environment.
+If \fIname\fP does exist,
+then the value of \fIname\fP in the environment is changed to
+\fIvalue\fP.
+The string pointed to by \fIstring\fP becomes part of the environment,
+so altering the string changes the environment.
+.SH RETURN VALUE
+The
+.BR putenv ()
+function returns zero on success.
+On failure, it returns a nonzero value, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B ENOMEM
+Insufficient space to allocate new environment.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR putenv ()
+T} Thread safety MT-Unsafe const:env
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr2, 4.3BSD-Reno.
+.PP
+The
+.BR putenv ()
+function is not required to be reentrant, and the
+one in glibc 2.0 is not, but the glibc 2.1 version is.
+.\" .LP
+.\" Description for libc4, libc5, glibc:
+.\" If the argument \fIstring\fP is of the form \fIname\fP,
+.\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP
+.\" is removed from the environment.
+.\" If
+.\" .BR putenv ()
+.\" has to allocate a new array \fIenviron\fP,
+.\" and the previous array was also allocated by
+.\" .BR putenv (),
+.\" then it will be freed.
+.\" In no case will the old storage associated
+.\" to the environment variable itself be freed.
+.PP
+Since glibc 2.1.2, the glibc implementation conforms to SUSv2:
+the pointer \fIstring\fP given to
+.BR putenv ()
+is used.
+In particular, this string becomes part of the environment;
+changing it later will change the environment.
+(Thus, it is an error to call
+.BR putenv ()
+with an automatic variable
+as the argument, then return from the calling function while \fIstring\fP
+is still part of the environment.)
+However, from glibc 2.0 to glibc 2.1.1, it differs:
+a copy of the string is used.
+On the one hand this causes a memory leak, and on the other hand
+it violates SUSv2.
+.PP
+The 4.3BSD-Reno version, like glibc 2.0, uses a copy;
+this is fixed in all modern BSDs.
+.PP
+SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3.
+.PP
+The GNU C library implementation provides a nonstandard extension.
+If
+.I string
+does not include an equal sign:
+.PP
+.in +4n
+.EX
+putenv("NAME");
+.EE
+.in
+.PP
+then the named variable is removed from the caller's environment.
+.SH SEE ALSO
+.BR clearenv (3),
+.BR getenv (3),
+.BR setenv (3),
+.BR unsetenv (3),
+.BR environ (7)