1.\"	$NetBSD: env.1,v 1.17 2025/02/09 14:25:26 kre Exp $
2.\"
3.\" Copyright (c) 1980, 1990 The Regents of the University of California.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" the Institute of Electrical and Electronics Engineers, Inc.
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	from: @(#)printenv.1	6.7 (Berkeley) 7/28/91
33.\"	$NetBSD: env.1,v 1.17 2025/02/09 14:25:26 kre Exp $
34.\"
35.Dd February 9, 2025
36.Dt ENV 1
37.Os
38.Sh NAME
39.Nm env
40.Nd set and print environment
41.Sh SYNOPSIS
42.Nm
43.Op Fl 0i
44.Op Fl C Ar dir
45.Op Fl u Ar name
46.Op Fl Fl
47.Op Ar name=value ...
48.Op Fl Fl
49.Oo
50.Ar utility
51.Op Ar argument ...
52.Oc
53.Sh DESCRIPTION
54.Nm
55executes
56.Ar utility ,
57with the given
58.Ar argument Ns s ,
59after modifying the environment as
60specified on the command line.
61Each
62.Ar name=value
63option specifies
64an environment variable,
65.Ar name  ,
66with a value of
67.Ar value
68which may be empty,
69that is to replace an existing environment variable
70with the same
71.Ar name ,
72or otherwise is to be added to the environment.
73.Pp
74The
75.Sq Fl i
76option causes
77.Nm
78to completely ignore the environment
79it inherits.
80.Pp
81The
82.Sq Fl C Ar dir
83option causes the working directory to be changed to
84.Ar dir ,
85and the environment variable
86.Ev PWD
87to be removed from the environment.
88.Pp
89The
90.Sq Fl u Ar name
91option causes removal of the
92.Ar name
93environment variable if it is in the environment.
94This is similar to the
95.Ic unset
96command in
97.Xr sh 1 .
98The value for
99.Ar name
100must not include the
101.Ql =
102character.
103.Pp
104To allow for either a
105.Ar name
106to be added to the environment, or the
107.Ar utility Ns 's
108name (if no environment additions are present),
109to begin with a minus sign
110.Pq Sq \&\-
111the first
112.Dq Fl Fl
113argument is required.
114To allow for
115.Ar utility Ns 's
116name to contain an equals character
117.Pq Sq \&=
118(anywhere in its word)
119the second
120.Dq Fl Fl
121is required.
122If there are no
123.Ar name=value
124arguments given, then to allow for
125.Ar utility
126to contain an equals character, both
127.Dq Fl Fl
128arguments are required.
129The first ends the options, the second ends
130the (in this case empty) environment variable additions.
131.Pp
132If no
133.Ar utility
134is specified,
135.Nm
136prints out the names and values of the variables in the environment.
137Each
138.Ar name=value
139pair is separated by a new line unless
140.Fl 0
141is specified, in which case name/value pairs are separated by a nul
142character
143.Pq Sq \&\e0 .
144The
145.Fl 0
146option is ignored if a
147.Ar utility
148is given.
149.Sh EXIT STATUS
150If a
151.Ar utility
152is specified, can be located, and successfully
153invoked, the exit status of
154.Nm
155is the exit status of the
156.Ar utility .
157See its documentation for the possible values and interpretations.
158.Pp
159Otherwise
160.Nm
161exits with one of the following values:
162.Bl -tag -width Ds
163.It 0
164No
165.Ar utility
166was specified, and
167.Nm
168has successfully written the contents of the
169.Pq possibly modified
170environment to standard output.
171.It 125
172.Nm
173was given an invalid option,
174a requested operation failed,
175or some other error occurred.
176.It 126
177.Ar utility
178was found, but could not be invoked.
179.It 127
180.Ar utility
181could not be found.
182.El
183.Pp
184Whenever
185.Nm
186exits with a non-zero status, without having invoked a
187.Ar utility ,
188it writes a message to the standard error stream
189identifying itself, and the reason for the non-zero exit.
190This can help distinguish cases where
191.Nm
192exits because of a problem, from when
193.Ar utility
194does so.
195The case of a zero exit status is simpler;
196if a
197.Ar utility
198was given on the command line, the zero status
199is from that utility, otherwise it is from
200.Nm .
201.Sh COMPATIBILITY
202The historic
203.Fl
204option has been deprecated but is still supported in this implementation.
205.Pp
206The
207.Fl C , u
208and
209.Fl 0
210options are non-standard extensions.
211.Sh SEE ALSO
212.Xr chdir 2 ,
213.Xr execvp 3 ,
214.Xr environ 7
215.Sh STANDARDS
216The
217.Nm
218utility conforms to
219.St -p1003.2-92 .
220.Sh HISTORY
221The
222.Nm
223command appeared in
224.Bx 4.4 .
225.Pp
226The
227.Fl u
228and
229.Fl 0
230options first appeared in
231.Nx 10 ,
232after earlier appearing in other systems.
233.Pp
234The
235.Fl C
236option first appeared in
237.Nx 10.1 .
238