share/man/man7/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: head/share/man/man7/environ.7 363907 2020-08-05 11:41:41Z gbe $
  30 .\"
  31 .Dd November 1, 2020
  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 to each process by
  43 .Xr execve 2
  44 when a process begins.
  45 By convention these strings have the form
  46 .Va name Ns No = Ns Ar value ,
  47 and are referred to as
  48 .Dq environment variables .
  49 A process can query, update, and delete these strings using the
  50 .Xr getenv 3 ,
  51 .Xr setenv 3 ,
  52 and
  53 .Xr unsetenv 3
  54 functions, respectively.
  55 The shells also provide commands to manipulate the environment;
  56 they are described in the respective shell manual pages.
  57 .Pp
  58 What follows is a list of environment variables typically
  59 seen on a
  60 .Ux
  61 system.
  62 It includes only those variables that a user can expect to see during their
  63 day-to-day use of the system, and is far from complete.
  64 Environment variables specific to a particular program or library function
  65 are documented in the
  66 .Sx ENVIRONMENT
  67 section of the appropriate manual page.
  68 .Sh ENVIRONMENT
  69 .Bl -tag -width LD_LIBRARY_PATH
  70 .It Ev BLOCKSIZE
  71 The size of the block units used by several disk-related commands,
  72 most notably
  73 .Xr df 1 ,
  74 .Xr du 1
  75 and
  76 .Xr ls 1 .
  77 .Ev BLOCKSIZE
  78 may be specified in units of a byte by specifying a number,
  79 in units of a kilobyte by specifying a number followed by
  80 .Ql K
  81 or
  82 .Ql k ,
  83 in units of a megabyte by specifying a number followed by
  84 .Ql M
  85 or
  86 .Ql m ,
  87 and in units of a gigabyte by specifying a number followed
  88 by
  89 .Ql G
  90 or
  91 .Ql g .
  92 Sizes less than 512 bytes or greater than a gigabyte are ignored.
  93 This variable is processed by the
  94 .Xr getbsize 3
  95 function.
  96 .It Ev COLUMNS
  97 The user's preferred width in column positions for the terminal.
  98 Utilities such as
  99 .Xr ls 1
 100 and
 101 .Xr who 1
 102 use this to format output into columns.
 103 If unset or empty, utilities will use an
 104 .Xr ioctl 2
 105 call to ask the terminal driver for the width.
 106 .It Ev EDITOR
 107 Default editor name.
 108 .It Ev EXINIT
 109 A startup list of commands read by
 110 .Xr ex 1
 111 and
 112 .Xr vi 1 .
 113 .It Ev HOME
 114 A user's login directory, set by
 115 .Xr login 1
 116 from the password file
 117 .Xr passwd 5 .
 118 .It Ev LANG
 119 This variable configures all programs which use
 120 .Xr setlocale 3
 121 to use the specified locale unless the
 122 .Ev LC_*
 123 variables are set.
 124 .It Ev LC_ALL
 125 Overrides the values of
 126 .Ev LC_COLLATE ,
 127 .Ev LC_CTYPE ,
 128 .Ev LC_MESSAGES ,
 129 .Ev LC_MONETARY ,
 130 .Ev LC_NUMERIC ,
 131 .Ev LC_TIME
 132 and
 133 .Ev LANG .
 134 .It Ev LC_COLLATE
 135 Locale to be used for ordering of strings.
 136 .It Ev LC_CTYPE
 137 Locale to be used for character classification
 138 (letter, space, digit, etc.) and for interpreting byte sequences as
 139 multibyte characters.
 140 .It Ev LC_MESSAGES
 141 Locale to be used for diagnostic messages.
 142 .It Ev LC_MONETARY
 143 Locale to be used for interpreting monetary input
 144 and formatting output.
 145 .It Ev LC_NUMERIC
 146 Locale to be used for interpreting numeric input and
 147 formatting output.
 148 .It Ev LC_TIME
 149 Locale to be used for interpreting dates input and
 150 for formatting output.
 151 .It Ev MAIL
 152 The location of the user's
 153 mailbox instead of the default in /var/mail,
 154 used by
 155 .Xr mail 1 ,
 156 .Xr sh 1 ,
 157 and many other mail clients.
 158 .It Ev MANPATH
 159 The sequence of directories, separated by colons, searched by
 160 .Xr man 1
 161 when looking for manual pages.
 162 .It Ev NLSPATH
 163 List of directories to be searched for the message catalog referred to by
 164 .Ev LC_MESSAGES .
 165 See
 166 .Xr catopen 3 .
 167 .It Ev PAGER
 168 Default paginator program.
 169 The program specified by this variable is used by
 170 .Xr mail 1 ,
 171 .Xr man 1 ,
 172 .Xr ftp 1 ,
 173 etc, to display information which is longer than the current display.
 174 .It Ev PATH
 175 The sequence of directories, separated by colons, searched by
 176 .Xr csh 1 ,
 177 .Xr sh 1 ,
 178 .Xr system 3 ,
 179 .Xr execvp 3 ,
 180 etc, when looking for an executable file.
 181 .Ev PATH
 182 is set to ``/usr/bin:/bin'' initially by
 183 .Xr login 1 .
 184 .It Ev POSIXLY_CORRECT
 185 When set to any value, this environment variable modifies the behaviour
 186 of certain commands to (mostly) execute in a strictly POSIX-compliant manner.
 187 .It Ev PRINTER
 188 The name of the default printer to be used by
 189 .Xr lpr 1 ,
 190 .Xr lpq 1 ,
 191 and
 192 .Xr lprm 1 .
 193 .It Ev PWD
 194 The current directory pathname.
 195 .It Ev SHELL
 196 The full pathname of the user's login shell.
 197 .It Ev TERM
 198 The kind of terminal for which output is to be prepared.
 199 This information is used by commands, such as
 200 .Xr nroff 1
 201 which may exploit special terminal capabilities.
 202 See
 203 .Pa /usr/share/misc/termcap
 204 .Pq Xr termcap 5
 205 for a list of terminal types.
 206 .It Ev TERMCAP
 207 The string describing the terminal in
 208 .Ev TERM ,
 209 or, if
 210 it begins with a '/', the name of the termcap file.
 211 See
 212 .Ev TERMPATH
 213 below, and
 214 .Xr termcap 5 .
 215 .It Ev TERMPATH
 216 A sequence of pathnames of termcap files, separated by colons or spaces,
 217 which are searched for terminal descriptions in the order listed.
 218 Having
 219 no
 220 .Ev TERMPATH
 221 is equivalent to a
 222 .Ev TERMPATH
 223 of
 224 .Pa $HOME/.termcap:/etc/termcap .
 225 .Ev TERMPATH
 226 is ignored if
 227 .Ev TERMCAP
 228 contains a full pathname.
 229 .It Ev TMPDIR
 230 The directory in which to store temporary files.
 231 Most applications use either
 232 .Pa /tmp
 233 or
 234 .Pa /var/tmp .
 235 Setting this variable will make them use another directory.
 236 .It Ev TZ
 237 The timezone to use when displaying dates.
 238 The normal format is a pathname relative to
 239 .Pa /usr/share/zoneinfo .
 240 For example, the command
 241 .Pp
 242 .Dl env TZ=America/Los_Angeles date
 243 .Pp
 244 displays the current time in California.
 245 See
 246 .Xr tzset 3
 247 for more information.
 248 .It Ev USER
 249 The login name of the user.
 250 It is recommended that portable applications use
 251 .Ev LOGNAME
 252 instead.
 253 .El
 254 .Pp
 255 Further names may be placed in the environment by the
 256 .Xr export 1
 257 command and
 258 .Ar name=value
 259 arguments in
 260 .Xr sh 1 ,
 261 or by the
 262 .Xr setenv 1
 263 command if you use
 264 .Xr csh 1 .
 265 It is unwise to change certain
 266 .Xr sh 1
 267 variables that are frequently exported by
 268 .Pa .profile
 269 files, such as
 270 .Ev MAIL ,
 271 .Ev PS1 ,
 272 .Ev PS2 ,
 273 and
 274 .Ev IFS ,
 275 unless you know what you are doing.
 276 .Pp
 277 The current environment variables can be printed with
 278 .Xr env 1 ,
 279 .Xr set 1
 280 or
 281 .Xr printenv 1
 282 in
 283 .Xr sh 1
 284 and
 285 .Xr env 1 ,
 286 .Xr printenv 1
 287 or the
 288 .Cm printenv
 289 built-in command in
 290 .Xr csh 1 .
 291 .Sh SEE ALSO
 292 .Xr cd 1 ,
 293 .Xr csh 1 ,
 294 .Xr env 1 ,
 295 .Xr ex 1 ,
 296 .Xr login 1 ,
 297 .Xr printenv 1 ,
 298 .Xr sh 1 ,
 299 .Xr execve 2 ,
 300 .Xr execle 3 ,
 301 .Xr getbsize 3 ,
 302 .Xr getenv 3 ,
 303 .Xr setenv 3 ,
 304 .Xr setlocale 3 ,
 305 .Xr system 3 ,
 306 .Xr termcap 3 ,
 307 .Xr termcap 5 ,
 308 .Xr nls 7
 309 .Sh HISTORY
 310 The
 311 .Nm
 312 manual page appeared in
 313 .At v7 .