man3/setenv.3

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