man3/setenv.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\" and Copyright (C) 2004, 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" References consulted:
   8 .\"     Linux libc source code
   9 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  10 .\"     386BSD man pages
  11 .\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu)
  12 .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
  13 .\" Modified 9 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  14 .\"     Changed unsetenv() prototype; added EINVAL error
  15 .\"     Noted nonstandard behavior of setenv() if name contains '='
  16 .\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug
  17 .\"
  18 .TH setenv 3 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 setenv \- change or add an environment variable
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <stdlib.h>
  27 .P
  28 .BI "int setenv(const char *" name ", const char *" value ", int " overwrite );
  29 .BI "int unsetenv(const char *" name );
  30 .fi
  31 .P
  32 .RS -4
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .RE
  36 .P
  37 .BR setenv (),
  38 .BR unsetenv ():
  39 .nf
  40     _POSIX_C_SOURCE >= 200112L
  41         || /* glibc <= 2.19: */ _BSD_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 The
  45 .BR setenv ()
  46 function adds the variable
  47 .I name
  48 to the
  49 environment with the value
  50 .IR value ,
  51 if
  52 .I name
  53 does not
  54 already exist.
  55 If
  56 .I name
  57 does exist in the environment, then
  58 its value is changed to
  59 .I value
  60 if
  61 .I overwrite
  62 is nonzero;
  63 if
  64 .I overwrite
  65 is zero, then the value of
  66 .I name
  67 is not changed (and
  68 .BR setenv ()
  69 returns a success status).
  70 This function makes copies of the strings pointed to by
  71 .I name
  72 and
  73 .I value
  74 (by contrast with
  75 .BR putenv (3)).
  76 .P
  77 The
  78 .BR unsetenv ()
  79 function deletes the variable
  80 .I name
  81 from
  82 the environment.
  83 If
  84 .I name
  85 does not exist in the environment,
  86 then the function succeeds, and the environment is unchanged.
  87 .SH RETURN VALUE
  88 .BR setenv ()
  89 and
  90 .BR unsetenv ()
  91 functions return zero on success,
  92 or \-1 on error, with
  93 .I errno
  94 set to indicate the error.
  95 .SH ERRORS
  96 .TP
  97 .B EINVAL
  98 .I name
  99 is NULL, points to a string of length 0,
 100 or contains an \[aq]=\[aq] character.
 101 .TP
 102 .B ENOMEM
 103 Insufficient memory to add a new variable to the environment.
 104 .SH ATTRIBUTES
 105 For an explanation of the terms used in this section, see
 106 .BR attributes (7).
 107 .TS
 108 allbox;
 109 lbx lb lb
 110 l l l.
 111 Interface       Attribute       Value
 112 T{
 113 .na
 114 .nh
 115 .BR setenv (),
 116 .BR unsetenv ()
 117 T}      Thread safety   MT-Unsafe const:env
 118 .TE
 119 .SH STANDARDS
 120 POSIX.1-2008.
 121 .SH HISTORY
 122 POSIX.1-2001, 4.3BSD.
 123 .P
 124 Prior to glibc 2.2.2,
 125 .BR unsetenv ()
 126 was prototyped
 127 as returning
 128 .IR void ;
 129 more recent glibc versions follow the
 130 POSIX.1-compliant prototype shown in the SYNOPSIS.
 131 .SH CAVEATS
 132 POSIX.1 does not require
 133 .BR setenv ()
 134 or
 135 .BR unsetenv ()
 136 to be reentrant.
 137 .SH BUGS
 138 POSIX.1 specifies that if
 139 .I name
 140 contains an \[aq]=\[aq] character, then
 141 .BR setenv ()
 142 should fail with the error
 143 .BR EINVAL ;
 144 however, versions of glibc before glibc 2.3.4 allowed an \[aq]=\[aq] sign in
 145 .IR name .
 146 .SH SEE ALSO
 147 .BR clearenv (3),
 148 .BR getenv (3),
 149 .BR putenv (3),
 150 .BR environ (7)