man3/putenv.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\"     Single UNIX Specification, Version 2
  10 .\" Modified Thu Apr  8 15:00:12 1993, David Metcalfe
  11 .\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu)
  12 .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
  13 .\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl)
  14 .\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl)
  15 .\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl)
  16 .TH PUTENV 3  2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  17 .SH NAME
  18 putenv \- change or add an environment variable
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <stdlib.h>
  25 .PP
  26 .BI "int putenv(char *" string );
  27 .\" Not: const char *
  28 .fi
  29 .PP
  30 .RS -4
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .RE
  34 .PP
  35 .BR putenv ():
  36 .nf
  37     _XOPEN_SOURCE
  38         || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  39         || /* Glibc <= 2.19: */ _SVID_SOURCE
  40 .fi
  41 .SH DESCRIPTION
  42 The
  43 .BR putenv ()
  44 function adds or changes the value of environment
  45 variables.
  46 The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP.
  47 If \fIname\fP does not already exist in the environment, then
  48 \fIstring\fP is added to the environment.
  49 If \fIname\fP does exist,
  50 then the value of \fIname\fP in the environment is changed to
  51 \fIvalue\fP.
  52 The string pointed to by \fIstring\fP becomes part of the environment,
  53 so altering the string changes the environment.
  54 .SH RETURN VALUE
  55 The
  56 .BR putenv ()
  57 function returns zero on success.
  58 On failure, it returns a nonzero value, and
  59 .I errno
  60 is set to indicate the error.
  61 .SH ERRORS
  62 .TP
  63 .B ENOMEM
  64 Insufficient space to allocate new environment.
  65 .SH ATTRIBUTES
  66 For an explanation of the terms used in this section, see
  67 .BR attributes (7).
  68 .ad l
  69 .nh
  70 .TS
  71 allbox;
  72 lbx lb lb
  73 l l l.
  74 Interface       Attribute       Value
  75 T{
  76 .BR putenv ()
  77 T}      Thread safety   MT-Unsafe const:env
  78 .TE
  79 .hy
  80 .ad
  81 .sp 1
  82 .SH STANDARDS
  83 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
  84 .SH NOTES
  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 .\" .LP
  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 .PP
 103 Since version 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, glibc versions 2.0 to 2.1.1 differ: a copy of the string is used.
 115 On the one hand this causes a memory leak, and on the other hand
 116 it violates SUSv2.
 117 .PP
 118 The 4.4BSD version, like glibc 2.0, uses a copy.
 119 .PP
 120 SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3.
 121 .PP
 122 The GNU C library implementation provides a nonstandard extension.
 123 If
 124 .I string
 125 does not include an equal sign:
 126 .PP
 127 .in +4n
 128 .EX
 129 putenv("NAME");
 130 .EE
 131 .in
 132 .PP
 133 then the named variable is removed from the caller's environment.
 134 .SH SEE ALSO
 135 .BR clearenv (3),
 136 .BR getenv (3),
 137 .BR setenv (3),
 138 .BR unsetenv (3),
 139 .BR environ (7)