lib/libc/stdlib/getenv.3

   1 .\"     $NetBSD: getenv.3,v 1.25 2010/10/26 22:34:33 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1988, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     from: @(#)getenv.3      8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd October 25, 2010
  37 .Dt GETENV 3
  38 .Os
  39 .Sh NAME
  40 .Nm getenv ,
  41 .Nm getenv_r ,
  42 .Nm putenv ,
  43 .Nm setenv ,
  44 .Nm unsetenv
  45 .Nd environment variable functions
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In stdlib.h
  50 .Ft char *
  51 .Fn getenv "const char *name"
  52 .Ft int
  53 .Fn getenv_r "const char *name" "char *buf" "size_t len"
  54 .Ft int
  55 .Fn setenv "const char *name" "const char *value" "int overwrite"
  56 .Ft int
  57 .Fn putenv "char *string"
  58 .Ft int
  59 .Fn unsetenv "const char *name"
  60 .Sh DESCRIPTION
  61 These functions set, unset and fetch environment variables from the
  62 host
  63 .Em environment list .
  64 For compatibility with differing environment conventions,
  65 the
  66 .Fn getenv
  67 or
  68 .Fn getenv_r
  69 given argument
  70 .Ar name
  71 may be appended with an equal sign
  72 .Dq Li \&= .
  73 .Pp
  74 The
  75 .Fn getenv
  76 function obtains the current value of the environment variable
  77 .Ar name .
  78 If the variable
  79 .Ar name
  80 is not in the current environment, a
  81 .Dv NULL
  82 pointer is returned.
  83 .Pp
  84 The
  85 .Fn getenv_r
  86 function obtains the current value of the environment variable
  87 .Fa name
  88 and copies it to
  89 .Fa buf .
  90 If
  91 .Fa name
  92 is not in the current environment, or the string length of the value of
  93 .Fa name
  94 is longer than
  95 .Fa len
  96 characters, then \-1 is returned and
  97 .Va errno
  98 is set to indicate the error.
  99 .Pp
 100 The
 101 .Fn setenv
 102 function inserts or resets the environment variable
 103 .Ar name
 104 in the current environment list.
 105 If the variable
 106 .Ar name
 107 does not exist in the list,
 108 it is inserted with the given
 109 .Ar value .
 110 If the variable does exist, the argument
 111 .Ar overwrite
 112 is tested; if
 113 .Ar overwrite is
 114 zero, the
 115 variable is not reset, otherwise it is reset
 116 to the given
 117 .Ar value .
 118 .Pp
 119 The
 120 .Fn putenv
 121 function takes an argument of the form
 122 .Dq name=value
 123 and it will set the environment variable
 124 .Dq name
 125 equal to
 126 .Dq value
 127 by altering an existing entry, or creating a new one if an existing
 128 one does not exist.
 129 The actual string argument passed to
 130 .Fn putenv
 131 will become part of the environment.
 132 If one changes the string, the environment will also change.
 133 .Pp
 134 The
 135 .Fn unsetenv
 136 function
 137 deletes all instances of the variable name pointed to by
 138 .Fa name
 139 from the list.
 140 .Sh RETURN VALUES
 141 The functions
 142 .Fn getenv_r ,
 143 .Fn setenv ,
 144 .Fn putenv ,
 145 and
 146 .Fn unsetenv
 147 return zero if successful; otherwise the global variable
 148 .Va errno
 149 is set to indicate the error and a
 150 \-1 is returned.
 151 .Pp
 152 If
 153 .Fn getenv
 154 is successful, the string returned should be considered read-only.
 155 .Sh ERRORS
 156 .Bl -tag -width Er
 157 .It Bq Er EINVAL
 158 The
 159 .Fa name
 160 argument to
 161 .Fn setenv
 162 or
 163 .Fn unsetenv
 164 is a null pointer, points to an empty string, or points to a string
 165 containing an
 166 .Dq Li \&=
 167 character.
 168 The
 169 .Fa value
 170 argument to
 171 .Fn setenv
 172 is a null pointer.
 173 The
 174 .Fa string
 175 argument to
 176 .Fn putenv
 177 is a null pointer, or points to a string that either starts with a
 178 .Dq Li \&=
 179 character or does not contain one at all.
 180 .It Bq Er ENOMEM
 181 The function
 182 .Fn setenv
 183 or
 184 .Fn putenv
 185 failed because they were unable to allocate memory for the environment.
 186 .El
 187 .Pp
 188 The function
 189 .Fn getenv_r
 190 can return the following errors:
 191 .Bl -tag -width Er
 192 .It Bq Er ENOENT
 193 The variable
 194 .Fa name
 195 was not found in the environment.
 196 .It Bq Er ERANGE
 197 The value of the named variable is too long to fit in the supplied buffer.
 198 .El
 199 .Sh SEE ALSO
 200 .Xr csh 1 ,
 201 .Xr sh 1 ,
 202 .Xr execve 2 ,
 203 .Xr environ 7
 204 .Sh STANDARDS
 205 The
 206 .Fn getenv
 207 function conforms to
 208 .St -ansiC .
 209 The
 210 .Fn putenv
 211 function conforms to
 212 .St -xpg4 .
 213 The
 214 .Fn unsetenv
 215 function conforms to
 216 .St -p1003.1-2001 .
 217 .Sh HISTORY
 218 The functions
 219 .Fn setenv
 220 and
 221 .Fn unsetenv
 222 appeared in
 223 .At v7 .
 224 The
 225 .Fn putenv
 226 function appeared in
 227 .Bx 4.3 Reno .