man/FreeBSD/environ.7

   1 .\" Copyright (c) 1983, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)environ.7   8.3 (Berkeley) 4/19/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 12, 2003
  32 .Dt ENVIRON 7
  33 .Os
  34 .Sh NAME
  35 .Nm environ
  36 .Nd user environment
  37 .Sh SYNOPSIS
  38 .Ar extern char **environ ;
  39 .Sh DESCRIPTION
  40 An array of strings called the
  41 .Ar environment
  42 is made available by
  43 .Xr execve 2
  44 when a process begins.
  45 By convention these strings have the form
  46 .Dq Ar name=value .
  47 The following names are used by various commands:
  48 .Bl -tag -width LC_MONETARY
  49 .It Ev BLOCKSIZE
  50 The size of the block units used by several commands, most notably
  51 .Xr df 1 ,
  52 .Xr du 1
  53 and
  54 .Xr ls 1 .
  55 This variable is processed by the
  56 .Xr getbsize 3
  57 function.
  58 .It Ev COLUMNS
  59 The user's preferred width in column positions for the terminal.
  60 Utilities such as
  61 .Xr ls 1
  62 and
  63 .Xr who 1
  64 use this to format output into columns.
  65 If unset or empty, utilities will use an
  66 .Xr ioctl 2
  67 call to ask the terminal driver for the width.
  68 .It Ev EDITOR
  69 Default editor name.
  70 .It Ev EXINIT
  71 A startup list of commands read by
  72 .Xr ex 1
  73 and
  74 .Xr vi 1 .
  75 .It Ev HOME
  76 A user's login directory, set by
  77 .Xr login 1
  78 from the password file
  79 .Xr passwd 5 .
  80 .It Ev LANG
  81 This variable configures all programs which use
  82 .Xr setlocale 3
  83 to use the specified locale unless the
  84 .Ev LC_*
  85 variables are set.
  86 .It Ev LC_ALL
  87 Overrides the values of
  88 .Ev LC_COLLATE ,
  89 .Ev LC_CTYPE ,
  90 .Ev LC_MESSAGES ,
  91 .Ev LC_MONETARY ,
  92 .Ev LC_NUMERIC ,
  93 .Ev LC_TIME
  94 and
  95 .Ev LANG .
  96 .It Ev LC_COLLATE
  97 Locale to be used for ordering of strings.
  98 .It Ev LC_CTYPE
  99 Locale to be used for character classification
 100 (letter, space, digit, etc.) and for interpreting byte sequences as
 101 multibyte characters.
 102 .It Ev LC_MESSAGES
 103 Locale to be used for diagnostic messages.
 104 .It Ev LC_MONETARY
 105 Locale to be used for interpreting monetary input
 106 and formatting output.
 107 .It Ev LC_NUMERIC
 108 Locale to be used for interpreting numeric input and
 109 formatting output.
 110 .It Ev LC_TIME
 111 Locale to be used for interpreting dates input and
 112 for formatting output.
 113 .It Ev MAIL
 114 The location of the user's
 115 mailbox instead of the default in /var/mail,
 116 used by
 117 .Xr mail 1 ,
 118 .Xr sh 1 ,
 119 and many other mail clients.
 120 .It Ev NLSPATH
 121 List of directories to be searched for the message catalog referred to by
 122 .Ev LC_MESSAGES .
 123 See
 124 .Xr catopen 3 .
 125 .It Ev PAGER
 126 Default paginator program.
 127 The program specified by this variable is used by
 128 .Xr mail 1 ,
 129 .Xr man 1 ,
 130 .Xr ftp 1 ,
 131 etc, to display information which is longer than the current display.
 132 .It Ev PATH
 133 The sequence of directories, separated by colons, searched by
 134 .Xr csh 1 ,
 135 .Xr sh 1 ,
 136 .Xr system 3 ,
 137 .Xr execvp 3 ,
 138 etc, when looking for an executable file.
 139 .Ev PATH
 140 is set to ``/usr/bin:/bin'' initially by
 141 .Xr login 1 .
 142 .It Ev PRINTER
 143 The name of the default printer to be used by
 144 .Xr lpr 1 ,
 145 .Xr lpq 1 ,
 146 and
 147 .Xr lprm 1 .
 148 .It Ev PWD
 149 The current directory pathname.
 150 .It Ev SHELL
 151 The full pathname of the user's login shell.
 152 .It Ev TERM
 153 The kind of terminal for which output is to be prepared.
 154 This information is used by commands, such as
 155 .Xr nroff 1
 156 or
 157 .Xr plot 1
 158 which may exploit special terminal capabilities.
 159 See
 160 .Pa /usr/share/misc/termcap
 161 .Pq Xr termcap 5
 162 for a list of terminal types.
 163 .It Ev TERMCAP
 164 The string describing the terminal in
 165 .Ev TERM ,
 166 or, if
 167 it begins with a '/', the name of the termcap file.
 168 See
 169 .Ev TERMPATH
 170 below, and
 171 .Xr termcap 5 .
 172 .It Ev TERMPATH
 173 A sequence of pathnames of termcap files, separated by colons or spaces,
 174 which are searched for terminal descriptions in the order listed.
 175 Having
 176 no
 177 .Ev TERMPATH
 178 is equivalent to a
 179 .Ev TERMPATH
 180 of
 181 .Dq Pa $HOME/.termcap:/etc/termcap .
 182 .Ev TERMPATH
 183 is ignored if
 184 .Ev TERMCAP
 185 contains a full pathname.
 186 .It Ev TMPDIR
 187 The directory in which to store temporary files.
 188 Most applications use either
 189 .Dq /tmp
 190 or
 191 .Dq /var/tmp .
 192 Setting this variable will make them use another directory.
 193 .It Ev TZ
 194 The timezone to use when displaying dates.
 195 The normal format is a pathname relative to
 196 .Dq Pa /usr/share/zoneinfo .
 197 For example, the command
 198 .Dq env TZ=America/Los_Angeles date
 199 displays the current time in California.
 200 See
 201 .Xr tzset 3
 202 for more information.
 203 .It Ev USER
 204 The login name of the user.
 205 .El
 206 .Pp
 207 Further names may be placed in the environment by the
 208 .Ic export
 209 command and
 210 .Ar name=value
 211 arguments in
 212 .Xr sh 1 ,
 213 or by the
 214 .Ic setenv
 215 command if you use
 216 .Xr csh 1 .
 217 It is unwise to change certain
 218 .Xr sh 1
 219 variables that are frequently exported by
 220 .Pa .profile
 221 files, such as
 222 .Ev MAIL ,
 223 .Ev PS1 ,
 224 .Ev PS2 ,
 225 and
 226 .Ev IFS ,
 227 unless you know what you are doing.
 228 .Pp
 229 The current environment variables can be printed with
 230 .Xr env 1 ,
 231 .Xr set 1
 232 or
 233 .Xr printenv 1
 234 in
 235 .Xr sh 1
 236 and
 237 .Xr env 1 ,
 238 .Xr printenv 1
 239 or the
 240 .Cm printenv
 241 built-in command in
 242 .Xr csh 1 .
 243 .Sh PROGRAMMING
 244 Programs can query and modify the environment, using the environment routines
 245 .Xr getenv 3 ,
 246 .Xr putenv 3 ,
 247 .Xr setenv 3
 248 and
 249 .Xr unsetenv 3 .
 250 Direct access can be made through the global variable
 251 .Va environ ,
 252 though it is recommended that changes to the enviroment still be made through
 253 the environment routines.
 254 .Pp
 255 Shared libraries and bundles don't have direct access to
 256 .Va environ ,
 257 which is only available to the loader
 258 .Xr ld 1
 259 when a complete program is being linked.
 260 The environment routines can still be used, but if direct access to
 261 .Va environ
 262 is needed, the
 263 .Fn _NSGetEnviron
 264 routine, defined in
 265 .In crt_externs.h ,
 266 can be used to retrieve the address of
 267 .Va environ
 268 at runtime.
 269 .Sh SEE ALSO
 270 .Xr cd 1 ,
 271 .Xr csh 1 ,
 272 .Xr env 1 ,
 273 .Xr ex 1 ,
 274 .Xr login 1 ,
 275 .Xr printenv 1 ,
 276 .Xr sh 1 ,
 277 .Xr execve 2 ,
 278 .Xr execle 3 ,
 279 .Xr getenv 3 ,
 280 .Xr putenv 3 ,
 281 .Xr setenv 3 ,
 282 .Xr unsetenv 3 ,
 283 .Xr setlocale 3 ,
 284 .Xr system 3 ,
 285 .Xr termcap 3 ,
 286 .Xr termcap 5
 287 .Sh HISTORY
 288 The
 289 .Nm
 290 manual page appeared in
 291 .Bx 4.2 .