blob: a859e32798cb40fb780b2c543327d0cbd439939c [file] [log] [blame]
Patrick Delaunayaa5f43a2022-04-14 19:07:05 +02001.. SPDX-License-Identifier: GPL-2.0-or-later:
2
Heinrich Schuchardt1b0c3162024-01-14 14:53:13 +01003.. index::
4 single: env (command)
5
Patrick Delaunayaa5f43a2022-04-14 19:07:05 +02006env command
7===========
8
9Synopsis
10--------
11
12::
13
14 env ask name [message] [size]
15 env callbacks
16 env default [-f] (-a | var [...])
17 env delete [-f] var [...]
18 env edit name
19 env exists name
20 env export [-t | -b | -c] [-s size] addr [var ...]
21 env flags
22 env grep [-e] [-n | -v | -b] string [...]
23 env import [-d] [-t [-r] | -b | -c] addr [size] [var ...]
24 env info [-d] [-p] [-q]
25 env print [-a | name ...]
26 env print -e [-guid guid] [-n] [name ...]
27 env run var [...]
28 env save
29 env erase
30 env load
31 env select [target]
32 env set [-f] name [value]
33 env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value]
34
35Description
36-----------
37
38The *env* commands is used to handle the U-Boot (:doc:`../environment`) or
39the UEFI variables.
40
41The next commands are kept as alias and for compatibility:
42
43+ *editenv* = *env edit*
44+ *grepenv* = *env grep*
45+ *setenv* = *env set*
46+ *askenv* = *env ask*
47+ *run* = *env run*
48
49Ask
50~~~
51
52The *env ask* command asks for the new value of an environment variable
53(alias :doc:`askenv`).
54
55 name
56 name of the environment variable.
57
58 message
59 message to be displayed while the command waits for the value to be
60 entered from stdin. If no message is specified, a default message
61 "Please enter name:" will be displayed.
62
63 size
64 maximum number of characters that will be stored in the environment
65 variable name. This is in decimal number format (unlike in
66 other commands where size values are hexa-decimal). The default
67 value of size is 1023 (CONFIG_SYS_CBSIZE - 1).
68
69Callbacks
70~~~~~~~~~
71
72The *env callbacks* command prints callbacks and their associated variables.
73
74Default
75~~~~~~~
76
77The *env default* command resets the selected variables in the U-Boot
78environment to their default values.
79
80 var
81 list of variable name.
82 \-a
83 all U-Boot environment.
84 \-f
85 forcibly, overwrite read-only/write-once variables.
86
87Delete
88~~~~~~
89
90The *env delete* command deletes the selected variables from the U-Boot
91environment.
92
93 var
94 name of the variable to delete.
95 \-f
96 forcibly, overwrite read-only/write-once variables.
97
98Edit
99~~~~
100
101The *env edit* command edits an environment variable.
102
103 name
104 name of the variable.
105
106Exists
107~~~~~~
108
109The *env exists* command tests for existence of variable.
110
111 name
112 name of the variable.
113
114Export
115~~~~~~
116
117The *env export* command exports the U-Boot environment in memory; on success,
118the variable $filesize will be set.
119
120 addr
121 memory address where environment gets stored.
122 var
123 list of variable names that get included into the export.
124 Without arguments, the whole environment gets exported.
125 \-b
126 export as binary format (name=value pairs separated by
127 list end marked by double "\0\0").
128 \-t
129 export as text format; if size is given, data will be
130 padded with '\0' bytes; if not, one terminating '\0'
131 will be added.
132 \-c
133 Export as checksum protected environment format as used by
134 'env save' command.
135 \-s size
136 size of output buffer.
137
138Flags
139~~~~~
140
141The *env flags* command prints variables that have non-default flags.
142
143Grep
144~~~~
145
146The *env grep* command searches environment, list environment name=value pairs
147matching the requested 'string'.
148
149 string
150 string to search in U-Boot environment.
151 \-e
152 enable regular expressions.
153 \-n
154 search string in variable names.
155 \-v
156 search string in vairable values.
157 \-b
158 search both names and values (default).
159
160Import
161~~~~~~
162
163The *env import* command imports environment from memory.
164
165 addr
166 memory address to read from.
167 size
168 length of input data; if missing, proper '\0' termination is mandatory
169 if var is set and size should be missing (i.e. '\0' termination),
170 set size to '-'.
171 var
172 List of the names of the only variables that get imported from
173 the environment at address 'addr'. Without arguments, the whole
174 environment gets imported.
175 \-d
176 delete existing environment before importing if no var is passed;
177 if vars are passed, if one var is in the current environment but not
178 in the environment at addr, delete var from current environment;
179 otherwise overwrite / append to existing definitions.
180 \-t
181 assume text format; either "size" must be given or the text data must
182 be '\0' terminated.
183 \-r
184 handle CRLF like LF, that means exported variables with a content which
185 ends with \r won't get imported. Used to import text files created with
186 editors which are using CRLF for line endings.
187 Only effective in addition to -t.
188 \-b
189 assume binary format ('\0' separated, "\0\0" terminated).
190 \-c
191 assume checksum protected environment format.
192
193Info
194~~~~
195
196The *env info* command displays (without argument) or evaluates the U-Boot
197environment information.
198
199 \-d
200 evaluate if the default environment is used.
201 \-p
202 evaluate if environment can be persisted.
203 \-q
204 quiet output, use only for command result, by example with
205 'test' command.
206
207Print
208~~~~~
209
210The *env print* command prints the selected variables in U-Boot environment or
211in UEFI variables.
212
213 name
214 list of variable name.
215 \-a
216 all U-Boot environment, when 'name' is absent.
217 \-e
218 print UEFI variables, all by default when 'name'.
219 \-guid guid
220 print only the UEFI variables matching this GUID (any by default)
221 with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
222 \-n
223 suppress dumping variable's value for UEFI.
224
225Run
226~~~
227
228The *env run* command runs commands in an environment variable.
229
230 var
231 name of the variable.
232
233Save
234~~~~
235
236The *env save* command saves the U-Boot environment in persistent storage.
237
238Erase
239~~~~~
240
241The *env erase* command erases the U-Boot environment.
242
243Load
244~~~~
245
246The *env load* command loads the U-Boot environment from persistent storage.
247
248Select
249~~~~~~
250
251The *env select* command selects an U-Boot environment target, it is useful to
252overid the default location when several U-Boot environment backend are
253availables.
254
255 target
256 name of the U-Boot environment backend to select: EEPROM, EXT4, FAT,
257 Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI.
258
259
260Set
261~~~
262
263The *env set* command sets or delete (when 'value' or '-i' are absent)
264U-Boot variable in environment or UEFI variables (when -e is specified).
265
266 name
267 variable name to modify.
268 value
269 when present, set the environment variable 'name' to 'value'
270 when absent, delete the environment variable 'name'.
271 \-f
272 forcibly, overwrite read-only/write-once U-Boot variables.
273 \-e
274 update UEFI variables.
275 \-nv
276 set non-volatile attribute (UEFI).
277 \-bs
278 set boot-service attribute (UEFI).
279 \-rt
280 set runtime attribute (UEFI).
281 \-at
282 set time-based authentication attribute (UEFI).
283 \-a
284 append-write (UEFI).
285 \-i addr:size
286 use <addr,size> as variable's value (UEFI).
287 \-v
288 verbose message (UEFI).
289
290Example
291-------
292
293Print the U-Boot environment variables::
294
295 => env print -a
296 => env print bootcmd stdout
297
298Update environment variable in memory::
299
300 => env set bootcmd "run distro_bootcmd"
301 => env set stdout "serial,vidconsole"
302
303Delete environment variable in memory::
304
305 => env delete bootcmd
306 => env set bootcmd
307
308Reset environment variable to default value, in memory::
309
310 => env default bootcmd
311 => env default -a
312
313Save current environment in persistent storage::
314
315 => env save
316
317Restore the default environment in persistent storage::
318
319 => env erase
320
321Create a text snapshot/backup of the current settings in RAM
322(${filesize} can be use to save the snapshot in file)::
323
324 => env export -t ${backup_addr}
325
326Re-import this snapshot, deleting all other settings::
327
328 => env import -d -t ${backup_addr}
329
330Save environment if default enviromnent is used and persistent storage is
331selected::
332
333 => if env info -p -d -q; then env save; fi
334
335Configuration
336-------------
337
338The env command is always available but some sub-commands depend on
339configuration options:
340
341ask
342 CONFIG_CMD_ASKENV
343
344callback
345 CONFIG_CMD_ENV_CALLBACK
346
347edit
348 CONFIG_CMD_EDITENV
349
350exists
351 CONFIG_CMD_ENV_EXISTS
352
353flsgs
354 CONFIG_CMD_ENV_FLAGS
355
356erase
357 CONFIG_CMD_ERASEENV
358
359export
360 CONFIG_CMD_EXPORTENV
361
362grep
363 CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option
364
365import
366 CONFIG_CMD_IMPORTENV
367
368info
369 CONFIG_CMD_NVEDIT_INFO
370
371load
372 CONFIG_CMD_NVEDIT_LOAD
373
374run
375 CONFIG_CMD_RUN
376
377save
378 CONFIG_CMD_SAVEENV
379
380select
381 CONFIG_CMD_NVEDIT_SELECT
382
383set, print
384 CONFIG_CMD_NVEDIT_EFI for '-e' option