diff options
Diffstat (limited to 'man/man3/putenv.3')
| -rw-r--r-- | man/man3/putenv.3 | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/man/man3/putenv.3 b/man/man3/putenv.3 new file mode 100644 index 000000000..d0892b420 --- /dev/null +++ b/man/man3/putenv.3 @@ -0,0 +1,141 @@ +'\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +putenv \- change or add an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int putenv(char *" string ); +.\" Not: const char * +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.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 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr2, 4.3BSD-Reno. +.P +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. +.\" .P +.\" 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. +.P +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. +.P +The 4.3BSD-Reno version, like glibc 2.0, uses a copy; +this is fixed in all modern BSDs. +.P +SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3. +.P +The GNU C library implementation provides a nonstandard extension. +If +.I string +does not include an equal sign: +.P +.in +4n +.EX +putenv("NAME"); +.EE +.in +.P +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) |