Debian Codegraph @

upstream/debian-unstable/man7/environ.7

raw
1 .\" Copyright 1997, Andries E. Brouwer <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH environ 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 environ \- user environment
9 .SH SYNOPSIS
10 .nf
11 .BI "extern char **" environ ;
12 .fi
13 .SH DESCRIPTION
14 The variable
15 .I environ
16 points to an array of pointers to strings called the "environment".
17 The last pointer in this array has the value NULL.
18 This array of strings is made available to the process by the
19 .BR execve (2)
20 call when a new program is started.
21 When a child process is created via
22 .BR fork (2),
23 it inherits a
24 .I copy
25 of its parent's environment.
26 .P
27 By convention, the strings in
28 .I environ
29 have the form
30 .RI \[dq] name\f[B]=\f[]value \[dq].
31 The name is case-sensitive and may not contain
32 the character
33 .RB \[dq] = \[dq].
34 The value can be anything that can be represented as a string.
35 The name and the value may not contain an embedded null byte (\[aq]\[rs]0\[aq]),
36 since this is assumed to terminate the string.
37 .P
38 Environment variables may be placed in the shell's environment by the
39 .I export
40 command in
41 .BR sh (1),
42 or by the
43 .I setenv
44 command if you use
45 .BR csh (1).
46 .P
47 The initial environment of the shell is populated in various ways,
48 such as definitions from
49 .I /etc/environment
50 that are processed by
51 .BR pam_env (8)
52 for all users at login time
53 (on systems that employ
54 .BR pam (8)).
55 In addition,
56 various shell initialization scripts,
57 such as the system-wide
58 .I /etc/profile
59 script and per-user initialization scripts
60 may include commands
61 that add variables to the shell's environment;
62 see the manual page of your preferred shell for details.
63 .P
64 Bourne-style shells support the syntax
65 .P
66 .in +4n
67 .EX
68 NAME=value command
69 .EE
70 .in
71 .P
72 to create an environment variable definition
73 only in the scope of the process that executes
74 .IR command .
75 Multiple variable definitions,
76 separated by white space,
77 may precede
78 .IR command .
79 .P
80 Arguments may also be placed in the environment
81 at the point of an
82 .BR exec (3).
83 A C program can manipulate its environment using the functions
84 .BR getenv (3),
85 .BR putenv (3),
86 .BR setenv (3),
87 and
88 .BR unsetenv (3).
89 .P
90 What follows is a list of environment variables
91 typically seen on a system.
92 This list is incomplete and includes only common variables seen
93 by average users in their day-to-day routine.
94 Environment variables specific to a particular program or library function
95 are documented in the ENVIRONMENT section of the appropriate manual page.
96 .TP
97 .B USER
98 The name of the logged-in user
99 (used by some BSD-derived programs).
100 Set at login time;
101 see section NOTES below.
102 .TP
103 .B LOGNAME
104 The name of the logged-in user
105 (used by some System-V derived programs).
106 Set at login time;
107 see section NOTES below.
108 .TP
109 .B HOME
110 A user's login directory.
111 Set at login time;
112 see section NOTES below.
113 .TP
114 .B LANG
115 The name of a locale to use for locale categories
116 when not overridden by
117 .B LC_ALL
118 or more specific environment variables such as
119 .BR LC_COLLATE ,
120 .BR LC_CTYPE ,
121 .BR LC_MESSAGES ,
122 .BR LC_MONETARY ,
123 .BR LC_NUMERIC ,
124 and
125 .B LC_TIME
126 (see
127 .BR locale (7)
128 for further details of the
129 .B LC_*
130 environment variables).
131 .TP
132 .B PATH
133 The sequence of directory prefixes that
134 .BR sh (1)
135 and many other programs employ
136 when searching for an executable file
137 that is specified as a simple filename
138 (i.a., a pathname that contains no slashes).
139 The prefixes are separated by colons
140 .RB ( : ).
141 The list of prefixes is searched from beginning to end,
142 by checking the pathname formed by catenating
143 a prefix, a slash, and the filename,
144 until a file with execute permission is found.
145 .IP
146 As a legacy feature,
147 a zero-length prefix
148 (specified as two adjacent colons, or an initial or terminating colon)
149 is interpreted to mean the current working directory.
150 However,
151 use of this feature is deprecated,
152 and POSIX notes that a conforming application shall use
153 an explicit pathname
154 (e.g.,
155 .IR . )
156 to specify the current working directory.
157 .IP
158 Analogously to
159 .BR PATH ,
160 one has
161 .BR CDPATH ,
162 used by some shells to find the target
163 of a change directory command,
164 .B MANPATH
165 used by
166 .BR man (1)
167 to find manual pages, and so on.
168 .TP
169 .B PWD
170 Absolute path to the current working directory;
171 required to be partially canonical (no
172 .I .\&
173 or
174 .I ..\&
175 components).
176 .TP
177 .B SHELL
178 The absolute pathname of the user's login shell.
179 Set at login time, see section NOTES below.
180 .TP
181 .B TERM
182 The terminal type for which output is to be prepared.
183 .TP
184 .B PAGER
185 The user's preferred utility to display text files.
186 Any string acceptable as a command-string operand to the
187 .I sh\ \-c
188 command shall be valid.
189 If
190 .B PAGER
191 is null or is not set,
192 then applications that launch a pager will default to a program such as
193 .BR less (1)
194 or
195 .BR more (1).
196 .TP
197 .BR EDITOR / VISUAL
198 The user's preferred utility to edit text files.
199 Any string acceptable as a command_string operand to the
200 .I sh\ \-c
201 command shall be valid.
202 .\" .TP
203 .\" .B BROWSER
204 .\" The user's preferred utility to browse URLs. Sequence of colon-separated
205 .\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ .
206 .P
207 Note that the behavior of many programs and library routines is
208 influenced by the presence or value of certain environment variables.
209 Examples include the following:
210 .IP \[bu] 3
211 The variables
212 .BR LANG ,
213 .BR LANGUAGE ,
214 .BR NLSPATH ,
215 .BR LOCPATH ,
216 .BR LC_ALL ,
217 .BR LC_MESSAGES ,
218 and so on influence locale handling;
219 see
220 .BR catopen (3),
221 .BR gettext (3),
222 and
223 .BR locale (7).
224 .IP \[bu]
225 .B TMPDIR
226 influences the path prefix of names created by
227 .BR tempnam (3)
228 and other routines, and the temporary directory used by
229 .BR sort (1)
230 and other programs.
231 .IP \[bu]
232 .BR LD_LIBRARY_PATH ,
233 .BR LD_PRELOAD ,
234 and other
235 .B LD_*
236 variables influence the behavior of the dynamic loader/linker.
237 See also
238 .BR ld.so (8).
239 .IP \[bu]
240 .B POSIXLY_CORRECT
241 makes certain programs and library routines
242 follow the prescriptions of POSIX.
243 .IP \[bu]
244 The behavior of
245 .BR malloc (3)
246 is influenced by
247 .B MALLOC_*
248 variables.
249 .IP \[bu]
250 The variable
251 .B HOSTALIASES
252 gives the name of a file containing aliases
253 to be used with
254 .BR gethostbyname (3).
255 .IP \[bu]
256 .B TZ
257 and
258 .B TZDIR
259 give timezone information used by
260 .BR tzset (3)
261 and through that by functions like
262 .BR ctime (3),
263 .BR localtime (3),
264 .BR mktime (3),
265 .BR strftime (3).
266 See also
267 .BR tzselect (8).
268 .IP \[bu]
269 .B TERMCAP
270 gives information on how to address a given terminal
271 (or gives the name of a file containing such information).
272 .IP \[bu]
273 .B COLUMNS
274 and
275 .B LINES
276 tell applications about the window size,
277 possibly overriding the actual size.
278 .IP \[bu]
279 .B PRINTER
280 or
281 .B LPDEST
282 may specify the desired printer to use.
283 See
284 .BR lpr (1).
285 .SH NOTES
286 Historically and by standard,
287 .I environ
288 must be declared in the user program.
289 However,
290 as a (nonstandard) programmer convenience,
291 .I environ
292 is declared in the header file
293 .I <unistd.h>
294 if the
295 .B _GNU_SOURCE
296 feature test macro is defined (see
297 .BR feature_test_macros (7)).
298 .P
299 The
300 .BR prctl (2)
301 .B PR_SET_MM_ENV_START
302 and
303 .B PR_SET_MM_ENV_END
304 operations can be used to control the location of the process's environment.
305 .P
306 The
307 .BR HOME ,
308 .BR LOGNAME ,
309 .BR SHELL ,
310 and
311 .B USER
312 variables are set when the user is changed
313 via a session management interface,
314 typically by a program such as
315 .BR login (1)
316 from a user database
317 (such as
318 .BR passwd (5)).
319 (Switching to the root user using
320 .BR su (1)
321 may result in a mixed environment where
322 .B LOGNAME
323 and
324 .B USER
325 are retained from old user;
326 see the
327 .BR su (1)
328 manual page.)
329 .SH BUGS
330 Clearly there is a security risk here.
331 Many a system command has been
332 tricked into mischief by a user who specified unusual values for
333 .B IFS
334 or
335 .BR LD_LIBRARY_PATH .
336 .P
337 There is also the risk of name space pollution.
338 Programs like
339 .I make
340 and
341 .I autoconf
342 allow overriding of default utility names from the environment
343 with similarly named variables in all caps.
344 Thus one uses
345 .B CC
346 to select the desired C compiler
347 (and similarly
348 .BR MAKE ,
349 .BR AR ,
350 .BR AS ,
351 .BR FC ,
352 .BR LD ,
353 .BR LEX ,
354 .BR RM ,
355 .BR YACC ,
356 etc.).
357 However,
358 in some traditional uses,
359 such an environment variable
360 gives options for the program instead of a pathname.
361 Thus,
362 one has
363 .B MORE
364 and
365 .BR LESS .
366 Such usage is considered mistaken,
367 and to be avoided in new programs.
368 .SH SEE ALSO
369 .BR bash (1),
370 .BR csh (1),
371 .BR env (1),
372 .BR login (1),
373 .BR printenv (1),
374 .BR sh (1),
375 .BR su (1),
376 .BR tcsh (1),
377 .BR execve (2),
378 .BR clearenv (3),
379 .BR exec (3),
380 .BR getenv (3),
381 .BR putenv (3),
382 .BR setenv (3),
383 .BR unsetenv (3),
384 .BR locale (7),
385 .BR ld.so (8),
386 .BR pam_env (8)