man3/putenv.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\"     Single UNIX Specification, Version 2
  11 .\" Modified Thu Apr  8 15:00:12 1993, David Metcalfe
  12 .\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu)
  13 .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
  14 .\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl)
  15 .\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl)
  16 .\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl)
  17 .TH putenv 3 (date) "Linux man-pages (unreleased)"
  18 .SH NAME
  19 putenv \- change or add an environment variable
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <stdlib.h>
  26 .P
  27 .BI "int putenv(char *" string );
  28 .\" Not: const char *
  29 .fi
  30 .P
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .P
  36 .BR putenv ():
  37 .nf
  38     _XOPEN_SOURCE
  39         || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  40         || /* glibc <= 2.19: */ _SVID_SOURCE
  41 .fi
  42 .SH DESCRIPTION
  43 The
  44 .BR putenv ()
  45 function adds or changes the value of environment
  46 variables.
  47 The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP.
  48 If \fIname\fP does not already exist in the environment, then
  49 \fIstring\fP is added to the environment.
  50 If \fIname\fP does exist,
  51 then the value of \fIname\fP in the environment is changed to
  52 \fIvalue\fP.
  53 The string pointed to by \fIstring\fP becomes part of the environment,
  54 so altering the string changes the environment.
  55 .SH RETURN VALUE
  56 The
  57 .BR putenv ()
  58 function returns zero on success.
  59 On failure, it returns a nonzero value, and
  60 .I errno
  61 is set to indicate the error.
  62 .SH ERRORS
  63 .TP
  64 .B ENOMEM
  65 Insufficient space to allocate new environment.
  66 .SH ATTRIBUTES
  67 For an explanation of the terms used in this section, see
  68 .BR attributes (7).
  69 .TS
  70 allbox;
  71 lbx lb lb
  72 l l l.
  73 Interface       Attribute       Value
  74 T{
  75 .na
  76 .nh
  77 .BR putenv ()
  78 T}      Thread safety   MT-Unsafe const:env
  79 .TE
  80 .SH STANDARDS
  81 POSIX.1-2008.
  82 .SH HISTORY
  83 POSIX.1-2001, SVr2, 4.3BSD-Reno.
  84 .P
  85 The
  86 .BR putenv ()
  87 function is not required to be reentrant, and the
  88 one in glibc 2.0 is not, but the glibc 2.1 version is.
  89 .\" .P
  90 .\" Description for libc4, libc5, glibc:
  91 .\" If the argument \fIstring\fP is of the form \fIname\fP,
  92 .\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP
  93 .\" is removed from the environment.
  94 .\" If
  95 .\" .BR putenv ()
  96 .\" has to allocate a new array \fIenviron\fP,
  97 .\" and the previous array was also allocated by
  98 .\" .BR putenv (),
  99 .\" then it will be freed.
 100 .\" In no case will the old storage associated
 101 .\" to the environment variable itself be freed.
 102 .P
 103 Since glibc 2.1.2, the glibc implementation conforms to SUSv2:
 104 the pointer \fIstring\fP given to
 105 .BR putenv ()
 106 is used.
 107 In particular, this string becomes part of the environment;
 108 changing it later will change the environment.
 109 (Thus, it is an error to call
 110 .BR putenv ()
 111 with an automatic variable
 112 as the argument, then return from the calling function while \fIstring\fP
 113 is still part of the environment.)
 114 However, from glibc 2.0 to glibc 2.1.1, it differs:
 115 a copy of the string is used.
 116 On the one hand this causes a memory leak, and on the other hand
 117 it violates SUSv2.
 118 .P
 119 The 4.3BSD-Reno version, like glibc 2.0, uses a copy;
 120 this is fixed in all modern BSDs.
 121 .P
 122 SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3.
 123 .P
 124 The GNU C library implementation provides a nonstandard extension.
 125 If
 126 .I string
 127 does not include an equal sign:
 128 .P
 129 .in +4n
 130 .EX
 131 putenv("NAME");
 132 .EE
 133 .in
 134 .P
 135 then the named variable is removed from the caller's environment.
 136 .SH SEE ALSO
 137 .BR clearenv (3),
 138 .BR getenv (3),
 139 .BR setenv (3),
 140 .BR unsetenv (3),
 141 .BR environ (7)