Download EFI Shell User`s Guide Draft for Review

EFI Shell User’s Guide
Draft for Review
Version 1.0_to7thRvw
July 7, 2005
i
EFI Shell User's Guide
Information in this document is provided in connection with Intel products. No license, express or implied, by estoppel or
otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel's Terms and Conditions
of Sale for such products, Intel assumes no liability whatsoever, and INTEL DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES
RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT,
COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life
saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time,
without notice.
This document contains information on products in the design phase. The information here is subject to change without
notice. Do not finalize a design with this information.
Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined."
Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising
from future changes to them.
This document as well as the software described in it is furnished under license and may only be used or copied in
accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to
change without notice, and should not be construed as a commitment by Intel Corporation to update or revise the
information or document. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may
appear in this document or any software that may be provided in association with this document.
This document provides website addresses for certain third party websites. The referenced sites are not under the control of
Intel and Intel is not responsible for the content of any referenced site or any link contained in a referenced site. Intel does
not endorse companies or products for sites which it references. If you decide to access any of the third party sites
referenced in this document, you do this entirely at your own risk.
*Other names and brands may be claimed as the property of others.
Intel, the Intel logo, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in
the United States and other countries.
Copyright © 2000–2005, Intel Corporation. All Rights Reserved.
ii
Revision History
Revision
Revision History
Date
1.0_toRvw
Finished editing pass and first help version. Sent to engr owner for
review. This version is missing the Shell How To's chapter (will be
added soon).
7/15/04
Added Shell How To's chapter and sent for review.
8/2/04
1.0_to2ndRvw
Incorporated the review comments that I received from Winters. Did
not receive replies for all of my review questions, so some are still
included in this version.
8/25/04
1.0_to7thRvw
Incorporated review comments received from Fang & Liu.
(External). Synchronized database.
7/6/2005
1.0to7thRvw
July, 2005
iii
EFI Shell User's Guide
iv
Contents
1 Introduction ...................................................................................................... 9
1.1
1.2
1.3
1.4
Overview ........................................................................................................................ 9
Help System of This Document...................................................................................... 9
Terms ............................................................................................................................. 9
Conventions Used in This Document........................................................................... 10
1.4.1
Command Descriptions ................................................................................. 10
1.4.2
Pseudo-Code Conventions............................................................................ 11
1.4.3
Typographic Conventions.............................................................................. 11
2 Features .......................................................................................................... 13
2.1
2.2
2.3
2.4
Shell Features Introduction .......................................................................................... 13
Shell Appearance......................................................................................................... 13
Supported Features ..................................................................................................... 14
2.3.1
Supported Features....................................................................................... 14
2.3.2
EFI Shell Commands..................................................................................... 15
2.3.3
Batch Scripts ................................................................................................. 15
2.3.4
Nesting the Shell ........................................................................................... 16
2.3.5
PATH Variable Support ................................................................................. 16
2.3.6
KEY History Support...................................................................................... 17
2.3.7
Execution Interrupts....................................................................................... 17
2.3.8
Consistent Mapping of File Systems ............................................................. 18
2.3.9
Output Redirection......................................................................................... 18
2.3.10 Output Streaming Control.............................................................................. 18
2.3.11 Scroll Back Buffer Support ............................................................................ 19
2.3.12 Verbose Help Support ................................................................................... 19
2.3.13 EFI Compatibility of the EFI Shell.................................................................. 19
2.3.14 Running Modes and Backward-Compatibility Support .................................. 20
Invoking the EFI Shell .................................................................................................. 20
2.4.1
Invoking the EFI Shell.................................................................................... 20
2.4.2
Start-up Batch File Startup.nsh ..................................................................... 20
2.4.3
EFI Shell Prompt ........................................................................................... 21
3 Syntax.............................................................................................................. 22
3.1
3.2
3.3
3.4
Introduction .................................................................................................................. 22
Special Characters....................................................................................................... 22
Variable and Alias Substitution .................................................................................... 23
3.3.1
Environment Variables and Variable Substitution ......................................... 23
3.3.2
Alias Substitution ........................................................................................... 23
3.3.3
Valid Characters for Variable Names ............................................................ 23
3.3.4
Variables Available Only in Batch Scripts...................................................... 23
3.3.5
Special Shell Variables.................................................................................. 24
3.3.6
Variable Substitution Flowchart ..................................................................... 25
Wildcard Expansion ..................................................................................................... 27
1.0to7thRvw
July, 2005
v
EFI Shell User's Guide
3.5
3.6
3.7
3.8
Switches and Arguments in Commands ...................................................................... 27
Quotation Marks........................................................................................................... 28
Output Redirection ....................................................................................................... 29
File Naming Conventions ............................................................................................. 30
4 Batch Scripts .................................................................................................. 31
4.1
4.2
Introduction .................................................................................................................. 31
Batch Script Command Descriptions ........................................................................... 31
4.2.1
Summary of Batch Script Commands ........................................................... 31
4.2.2
for...endfor ..................................................................................................... 32
4.2.3
goto................................................................................................................ 34
4.2.4
if...else...endif ................................................................................................ 35
4.2.5
pause............................................................................................................. 36
4.2.6
shift ................................................................................................................ 39
4.3 Variable, Argument, and Alias Substitution.................................................................. 40
4.3.1
Variable, Argument, and Alias Substitution in Batch Scripts ......................... 40
4.3.2
Alias Substitution Rule in Batch Scripts......................................................... 41
4.3.3
General Variable Substitution Rule in Batch Scripts ..................................... 41
4.3.4
General Command Line Variable Substitution Rule in Batch Scripts ............ 41
4.3.5
Supported Number of Arguments in Batch Scripts........................................ 42
4.3.6
Syntax for Variables in Batch Scripts ............................................................ 42
4.3.7
Example of Variable, Argument, and Alias Substitution in Batch Scripts ...... 42
4.4 Comments.................................................................................................................... 43
4.5 Error Handling .............................................................................................................. 43
4.6 Running Modes in Batch Scripts .................................................................................. 44
4.7 Nesting Batch Scripts................................................................................................... 44
4.8 Output Redirection in Batch Scripts ............................................................................. 44
4.9 Echoing in Batch Scripts .............................................................................................. 45
4.10 Known Limitations with the Shell Scripting Language.................................................. 45
5 Commands...................................................................................................... 46
5.1
5.2
5.3
5.4
5.5
vi
Introduction .................................................................................................................. 46
External Commands..................................................................................................... 46
Supported EFI Protocols in the Shell ........................................................................... 46
MS-DOS* 6.22 and Unix* Equivalents ......................................................................... 48
Internal Command Descriptions................................................................................... 49
5.5.1
Summary of EFI Shell Internal Commands ................................................... 49
5.5.2
Command Usage Notes ................................................................................ 50
5.5.3
alias ............................................................................................................... 51
5.5.4
attrib............................................................................................................... 53
5.5.5
cd................................................................................................................... 56
5.5.6
cls .................................................................................................................. 58
5.5.7
connect .......................................................................................................... 59
5.5.8
copy ............................................................................................................... 62
5.5.9
cp................................................................................................................... 66
5.5.10 date................................................................................................................ 69
5.5.11 del.................................................................................................................. 70
5.5.12 dh................................................................................................................... 73
5.5.13
5.5.14
5.5.15
5.5.16
5.5.17
5.5.18
5.5.19
5.5.20
5.5.21
5.5.22
5.5.23
5.5.24
5.5.25
5.5.26
5.5.27
5.5.28
5.5.29
5.5.30
5.5.31
5.5.32
5.5.33
5.5.34
5.5.35
dir................................................................................................................... 77
disconnect ..................................................................................................... 79
drivers............................................................................................................ 82
drvcfg............................................................................................................. 84
drvdiag........................................................................................................... 88
echo............................................................................................................... 91
exit ................................................................................................................. 94
help................................................................................................................ 94
load................................................................................................................ 97
ls .................................................................................................................... 98
map.............................................................................................................. 101
mkdir............................................................................................................ 108
mv................................................................................................................ 110
reconnect..................................................................................................... 112
reset............................................................................................................. 115
rm ................................................................................................................ 116
set................................................................................................................ 118
time.............................................................................................................. 121
touch............................................................................................................ 122
type.............................................................................................................. 124
unload.......................................................................................................... 127
ver................................................................................................................ 129
vol ................................................................................................................ 131
6 Shell How To's .............................................................................................. 133
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9
6.10
6.11
6.12
6.13
6.14
6.15
6.16
6.17
6.18
6.19
6.20
6.21
6.22
6.23
Introduction ................................................................................................................ 133
How to Switch an External Command to an Internal Command ................................ 133
How to Switch an Internal Command to an External Command ................................ 134
How to Understand Consistent Mapping.................................................................... 135
How to Switch the Running Modes of the EFI Shell................................................... 135
How to Correctly Write Scripts in the New EFI Shell.................................................. 136
How to Start a Specific startup.nsh File When Launching EFI Shell.......................... 136
How to Understand the Use of Quotation Marks........................................................ 137
How to Understand the Use of the Escaping Character '^' ........................................ 138
How to Alias ............................................................................................................... 139
How to Map a File System to a User-Specific Mapping Name .................................. 139
How to Set/Modify/Delete Environment Variables ..................................................... 139
How to Launch and Exit the EFI Shell........................................................................ 140
How to Determine the Version of the EFI Shell.......................................................... 140
How to Get Help Information...................................................................................... 141
How to Terminate the Execution of Commands......................................................... 141
How to Pause the Screen Output............................................................................... 141
How to View the Screen History................................................................................. 142
How to Redirect the Output of Commands to Files.................................................... 142
How to View the Contents of a Text File .................................................................... 142
How to Edit a Text File ............................................................................................... 142
How to Edit a Binary File............................................................................................ 142
How to Edit Disk Blocks ............................................................................................. 143
1.0to7thRvw
July, 2005
vii
EFI Shell User's Guide
6.24 How to Edit Memory................................................................................................... 143
6.25 How to Connect a Driver to a Device ......................................................................... 143
Figures
Figure 2-1 EFI Shell Look and Feel ......................................................................................14
Figure 3-1 Variable and Argument Substitution Flowchart....................................................26
Table
Table 1-1 Organization of This Document .............................................................................9
Table 2-1 Types of Commands Available in the EFI Shell...................................................15
Table 2-2 EFI Shell Command Help Information Level........................................................19
Table 3-1 Special Characters in the EFI Shell .....................................................................22
Table 3-2 Index and Positional Variables ............................................................................24
Table 3-3 Special Shell Variables ........................................................................................24
Table 3-4 Wildcard Character Expansion ............................................................................27
Table 3-5 Output Redirection Syntax...................................................................................29
Table 4-1 EFI Shell Batch Script Commands ......................................................................31
Table 4-2 Additional Information on Running Modes...........................................................44
Table 5-1 EFI Shell Protocol Information Table ...................................................................46
Table 5-2 MS-DOS 6.22 and Unix Equivalents for Shell Internal Commands .....................48
Table 5-3 EFI Shell Internal Commands ..............................................................................49
Table 5-4 Conventions for Directory Names ........................................................................56
Table 5-5 Default Values for the Type Parameter ...............................................................85
Table 6-1 Examples of Custom Aliases .............................................................................139
viii
1
Introduction
1.1
Overview
This document, the EFI Shell User's Guide, is the end-user's manual for the EFI Shell. The EFI
Shell is a special EFI application that allows batch scripting, EFI Shell commands, and other EFI
Shell applications to be launched.
This document is organized as listed in the table below.
Table 1-1 Organization of This Document
1.2
Book
Description
Introduction
Provides definitions of terms that are used in this document and
information on references that are mentioned. It also describes the
typographic conventions that are used in this specification.
Features
Describes the features of the EFI Shell. It introduces Shell
commands, batch scripts, PATH variable support, KEY history
support, verbose help support, and other Shell features.
Syntax
Introduces the required syntax for commands and batch scripts in
the EFI Shell.
Batch Scripts
Lists all batch script commands that are available in the EFI Shell.
Commands
Lists all the internal core commands that are available in the EFI
Shell.
Shell How To's
Gives instructions on how to perform various tasks in the EFI Shell.
Help System of This Document
This document is also available in an online help format from the EFI web site. To view the help
system, go to the following URL and go to Tool Documentation > EFI Shell > Standalone
Product in the table of contents (TOC):
http://developer.intel.com/technology/efi/help/efidocs.htm
1.3
Terms
The terms listed below are used throughout this document. See the master Glossary topic in the EFI
Documentation help system and the glossary in the EFI 1.10 Specification for additional definitions
of terms and abbreviations that are used in this document or that might be useful in understanding
the descriptions presented in this document.
9
EFI Shell User's Guide
Introduction
DXE
Driver Execution Environment. Phase of operation in the Intel® Platform Innovation
Framework for EFI that supports running modular code in the form of EFI drivers. Common
to all platforms. Typically in C language. See the Intel® Platform Innovation Framework for
EFI Architecture Specification for more information on this phase.
EFI
The specification containing interface definitions for firmware. These interfaces include those
that are used by the operating system for booting as well as those for the internal construction
of firmware.
Framework
Intel® Platform Innovation Framework for EFI. An implementation of EFI that has been
designed to perform the full range of operations that are required to initialize the platform
from power-on through transfer of control to the operating system. See Related Information
from Intel Corporation in the EFI Documentation help system for more information.
Shell
The EFI Shell is a simple, interactive environment that allows EFI device drivers to be
loaded, EFI applications to be launched, and operating systems to be booted.
1.4
Conventions Used in This Document
1.4.1
Command Descriptions
The commands that are described in this document generally have the following format:
Command Name:
The formal name of the command.
Summary:
A brief description of the command.
EFI Versions:
Indicates the versions of EFI with which the command can
be used.
Usage:
A brief usage of the command.
Description:
A detailed description about how to use that command.
Examples:
Examples to show how to use that command.
10
Features
1.4.2
Pseudo-Code Conventions
Pseudo code is presented to describe algorithms in a more concise form. None of the algorithms in
this document are intended to be compiled directly. The code is presented at a level corresponding
to the surrounding text.
In describing variables, a list is an unordered collection of homogeneous objects. A queue is an
ordered list of homogeneous objects. Unless otherwise noted, the ordering is assumed to be First In
First Out (FIFO).
Pseudo code is presented in a C-like format, using C conventions where appropriate. The coding
style, particularly the indentation style, is used for readability and does not necessarily comply with
an implementation of the Extensible Firmware Interface Specification.
1.4.3
Typographic Conventions
This document uses the typographic and illustrative conventions described below:
Plain text
The normal text typeface is used for the vast majority of the descriptive
text in a specification.
Plain text (blue)
In the online help version of this specification, any plain text that is
underlined and in blue indicates an active link to the cross-reference.
Click on the word to follow the hyperlink. Note that these links are not
active in the PDF of the specification.
Bold
In text, a Bold typeface identifies a processor register name. In other
instances, a Bold typeface can be used as a running head within a
paragraph.
Italic
In text, an Italic typeface can be used as emphasis to introduce a new
term or to indicate a manual or specification name.
BOLD Monospace
Computer code, example code segments, and all prototype code
segments use a BOLD Monospace typeface with a dark red color.
These code listings normally appear in one or more separate paragraphs,
though words or segments can also be embedded in a normal text
paragraph.
Bold Monospace
In the online help version of this specification, words in a
Bold Monospace typeface that is underlined and in blue indicate an
active hyperlink to the code definition for that function or type definition.
Click on the word to follow the hyperlink. Note that these links are not
active in the PDF of the specification. Also, these inactive links in the
PDF may instead have a Bold Monospace appearance that is
underlined but in dark red. Again, these links are not active in the PDF of
the specification.
Italic Monospace
In code or in text, words in Italic Monospace indicate placeholder
names for variable information that must be supplied (i.e., arguments).
Plain Monospace
In code, words in a Plain Monospace typeface that is a dark red
color but is not bold or italicized indicate pseudo code or example code.
These code segments typically occur in one or more separate paragraphs.
1.0to7thRvw
July, 2005
11
EFI Shell User's Guide
text text text
Introduction
In the PDF of this specification, text that is highlighted in yellow
indicates that a change was made to that text since the previous revision
of the PDF. The highlighting indicates only that a change was made
since the previous version; it does not specify what changed. If text was
deleted and thus cannot be highlighted, a note in red and highlighted in
yellow (that looks like (Note: text text text.)) appears where the deletion
occurred.
See the glossary sections in the EFI 1.10 Specification and in the EFI Documentation help system
for definitions of terms and abbreviations that are used in this document or that might be useful in
understanding the descriptions presented in this document.
See the references sections in the EFI 1.10 Specification and in the in the EFI Documentation help
system for a complete list of the additional documents and specifications that are required or
suggested for interpreting the information presented in this document:
The EFI 1.10 Specification is available from the EFI web site
http://developer.intel.com/technology/efi/. The EFI Documentation help
system is available from the EFI web site
http://developer.intel.com/technology/efi/help/efidocs.htm
12
2
Features
2.1
Shell Features Introduction
This section provides information on the various features of the EFI Shell. The EFI Shell is a
simple, interactive environment that allows users to do the following:
• Load EFI device drivers.
• Launch EFI applications.
• Boot operating systems.
• Use a set of basic commands to manage files, system environment variables, and other elements
of EFI.
The EFI Shell provides an environment that can be modified to easily adapt to many different
hardware configurations.
The EFI Shell supports the following:
• A command line interface
• A set of Shell internal commands and external commands
• Batch scripting
2.2
Shell Appearance
The figure below shows what the device mapping table looks like in the EFI Shell GUI.
13
EFI Shell User's Guide
Features
Figure 2-1 EFI Shell Look and Feel
2.3
Supported Features
2.3.1
Supported Features
The EFI Shell supports the following features, which are discussed in more detail in subsequent
topics:
• EFI Shell Commands
• Batch Scripts
• Nesting the Shell
• PATH Variable
• KEY History
• Execution Interrupts
14
Features
• Consistent Mapping of File Systems
• Output Redirection
• Output Streaming Control
• Scroll Back Buffer
• Verbose Help
• Aliases
• EFI Compatibility of the EFI Shell
• Running Modes and Backward Compatibility
2.3.2
EFI Shell Commands
Three types of commands are available in the EFI Shell:
• Internal commands
• External commands
• Script-only commands
The following table describes these commands.
Table 2-1 Types of Commands Available in the EFI Shell
Type of
Command
For more information,
see...
Description
Internal
Commands that are integrated into the EFI Shell core image.
These commands provide general-purpose management such
as file/directory management and date/time management under
the EFI Shell. The Shell also provides some EFI-specific
management commands, such as for connecting and
disconnecting devices and loading and unloading EFI drivers.
Commands chapter
External
A set of Shell applications.
External Commands in
the Commands chapter
Script-only
Commands that can be executed only when using batch script
files.
Batch Scripts chapter
All commands are invoked by typing the name of the command at the Shell command prompt (also
called just the Shell prompt).
2.3.3
Batch Scripts
The EFI Shell can execute commands from a file, which is called a batch script file (or batch script
program). These files allow users to simplify routine or repetitive tasks. A batch script program is a
Unicode or ASCII text file that contains one or more commands and has an .nsh file name
extension. EFI Shell batch script files are invoked by typing the file name at the command prompt,
with or without the file name extension. Commands in the file are then executed sequentially.
1.0to7thRvw
July, 2005
15
EFI Shell User's Guide
Features
All Shell commands can be executed in batch scripts. In addition, this version of the Shell provides
a set of script-only commands to do the following:
• Perform basic flow control.
• Allow branching and looping in a script
• Allow users to control input and output and call other batch programs (known as script nesting).
Script only means that those commands can be executed only in Shell batch script files and cannot
be executed at the Shell prompt.
See the Batch Script chapter for detailed descriptions of batch scripts and the script-only
commands.
2.3.4
Nesting the Shell
The EFI Shell supports nesting the Shell itself. The EFI Shell can run the Shell from within itself.
The nesting level is determined by how much memory the system has.
The exit command exits the EFI Shell environment. In a nested Shell, this command will quit
only the current Shell. In scripts, the exit command terminates the current Shell, not the current
script. If the current Shell is a child Shell, it will return to the parent Shell. The newly launched
Shell will have a brand new execution environment except for variables and aliases.
Internal Commands in a Nested Shell
Different instances of the EFI Shell can have different sets of internal commands. For example, you
can boot the system to an EFI Shell with the minimum set of internal commands, and then you can
load an EFI Shell with the expected built-in internal commands at the Shell command prompt.
Users can dynamically change their internal command sets in this way and do not need to recompile
their EFI Shell.
2.3.5
PATH Variable Support
The EFI Shell has a default volatile environment variable path, which contains the default path
that the EFI Shell will search if necessary. When a user tries to launch an EFI application, the Shell
first searches for the application in the current directory and does the following:
• If it finds the application in the current directory, it stops searching and executes that application.
• If it does not find the application in the current directory, it will search the path list that is stored
in the path variable sequentially. If it finds the application in one of the paths, it stops searching
and executes that application.
• If the path variable is empty or it does not exist, it treats the current directory as the working
directory.
• If it does not find the application in any of the paths, it reports that the application was not found.
In general, paths that are stored in the path variable look like the following:
16
Features
path:
.;fs0:\efi\tools;fs0:\efi\boot;fs0:\;fs1:\efi\tools;fs1:\efi\boot
;fs1:\
The EFI Shell supports both absolute paths and relative paths when executing commands. Users
can set path to any specified value, but this variable will be refreshed immediately after the
map -r command is executed. This variable is volatile, so the contents will be lost after a reset or
power off.
Typically, users can append the paths to this variable in the following way:
set -v path %path%;fs0:\test
2.3.6
KEY History Support
The EFI Shell saves the history of commands that executed from a Shell prompt. Press the up or
down arrow key to recall the previous commands. Note that the Shell will not save commands that
are executed in batch scripts in the KEY history.
2.3.7
2.3.7.1
Execution Interrupts
Execution Interrupt Support
The EFI Shell supports interrupting the execution of the Shell commands and scripts. There are two
kinds of execution interrupts, which are described in more detail in the next topics:
•
Script execution interrupts
•
Internal command execution interrupts
2.3.7.2
Script Execution Interrupt
Press the ESC key to interrupt the execution of a batch script. The interrupt can happen only
between commands that are included in the batch script. The batch script supports the nesting of the
script. Once a script is interrupted, all its predecessor scripts are also interrupted.
2.3.7.3
Internal Command Execution Interrupt
Press the ESC key to interrupt the execution of time-consuming EFI Shell internal commands (for
example, ls -r). These EFI Shell commands implement the interrupt mechanism by themselves.
1.0to7thRvw
July, 2005
17
EFI Shell User's Guide
Features
Currently, the EFI Shell core does not support interrupting the execution of commands or
applications all by itself. It requires that the commands or applications be able to detect
interruptions.
2.3.8
Consistent Mapping of File Systems
This version of the EFI Shell adopts a new rule called consistent mapping for file system mappings.
Under this rule, names of file system mappings will not change in either of the following scenarios:
• After a reboot
• After the map -r command if the hardware configuration does not change
If two or more computers have the same hardware configuration, the results of the consistent
mapping on these computers should be exactly the same. Hardware configuration changes are
defined as a change to the controllers or physical interfaces to which the devices are
connected.
If you used an older version of the Shell that used the fsX notation style for mapping file systems,
then the new consistent mapping convention might look a little different. For example, a GUIDed
file system may have a consistent mapping name as
f0agonennapphibbndlnmeaakamjeafdnb.They are provided to deliver the capability of
consistent mapping.
The old fsX-style mapping names will be kept in this version of EFI Shell to facilitate the use of
mapping names on the command line, but they do not have the consistent mapping characteristics.
If you need to use mapping names that are consistently mapped, please do not use the old fsX-style
mapping names.
The consistent mapping rule applies only to file system mappings. It does not apply to block I/O
mappings.
2.3.9
Output Redirection
The output of EFI Shell commands can be redirected to Unicode or ASCII text files. See the
following for more information:
• Output Redirection in the Syntax chapter
• Output Redirection in Batch Scripts in the Batch Scripts chapter
2.3.10 Output Streaming Control
The EFI Shell supports pausing and resuming the streaming of characters to the output device.
Press the Tab key to pause and resume the output results that are produced by the current running
commands or applications. This feature is especially useful for commands and applications that
may produce a large number of output results.
18
Features
2.3.11 Scroll Back Buffer Support
The EFI Shell supports scrolling the output buffer back and forward so that consoles can have a
screen history. Press the Page Up and Page Down keys to scroll back and forward in the screen
history, and press any other key to quit scrolling. However, you cannot scroll through the screen
history while a command, application, or script is being executed.
The text output history is limited to a maximum of three screens.
2.3.12 Verbose Help Support
The EFI Shell supports verbose help for each command. Type either help cmd or cmd -? to get
detailed help information for that command. See the help command description in the Commands
chapter for more details.
There are two levels of help information, which are listed in the following table.
Table 2-2 EFI Shell Command Help Information Level
Level
Description
Line help
Describes the Shell command usage in one sentence.
Verbose help
Describes the Shell command usage in detail, including explanations of each switch
and examples.
The help information is built into the EFI Shell image. If you need help support for a customized
internal command, the command has to process the -? flag. The command should print its verbose
help information when it sees this flag. See the EFI Shell Developer’s Guide for details.
2.3.13 EFI Compatibility of the EFI Shell
The EFI Shell is designed to run on all EFI implementations that conform to version 1.02 or higher
of the EFI Specification. As a result, it should be able to run on the following implementations
without any modifications:
• EFI 1.02
• EFI 1.10
• Intel® Platform Innovation Framework for EFI (hereafter referred to as "the Framework")
However, some Shell commands and applications are not supported in all implementations and may
not work on all implementations. The Summary of Shell Internal Commands topic and the
description of each individual command (see the Commands chapter) indicate the versions of EFI
with which the command can be used.
1.0to7thRvw
July, 2005
19
EFI Shell User's Guide
Features
2.3.14 Running Modes and Backward-Compatibility Support
This version of the EFI Shell has two running modes:
• Backward-compatible mode
• Enhanced Shell mode
In backward-compatible mode, users can run old Shell scripts, old Shell commands with old syntax,
and part of the old Shell application without modification or recompiling. In enhanced Shell mode,
the Shell runs with more new features and is not completely compatible with old versions of the
EFI Shell.
This latest version of the EFI Shell uses a reserved volatile environment variable efishellmode
to control and indicate the mode in which the Shell is running. See Special Shell Variables in the
Syntax chapter for more information on this variable.
By default, the EFI Shell will run in enhanced Shell mode. See Running Modes in Batch Scripts in
the Batch Scripts chapter for more information on setting running modes in batch scripts.
2.4
Invoking the EFI Shell
2.4.1
Invoking the EFI Shell
The EFI Shell is provided in two forms:
• As the built-in EFI Shell
• As an .efi image file of the EFI Shell
In the first form, the EFI Shell is built with the firmware and it can be a boot option. In the second
form, the EFI Shell is provided as a file, which users can load and run using either of the following
methods:
• Through the menus in the EFI boot manager (in EFI 1.10) or the Boot Maintenance Manager (in
the Framework)
• By executing the file at the EFI Shell command prompt
2.4.2
Start-up Batch File Startup.nsh
When the EFI Shell is invoked, it searches for a start-up file named startup.nsh and displays
the following message:
Press ESC in 5 seconds to skip startup.nsh, any other key to continue.
20
Features
Startup.nsh is a batch script file that contains Shell commands that will be executed when the
Shell starts. Press the ESC key within five seconds to prevent startup.nsh from executing.
Press any other key to immediately execute startup.nsh. See Shell Appearance for a screen
shot of this prompt.
Startup.nsh is not a required file and does not have to exist.
If the Shell was launched from a file system, it first looks for the startup.nsh file in the same
directory from which the Shell image was just launched. If it cannot find the startup.nsh file in
that directory or if it was not launched from a file system, it will search the execution path that is
defined by the environment variable path. Once the start-up file commands in startup.nsh
have been executed, the Shell looks for commands from a console input device.
When the shell starts it waits for 5 seconds, then executes startup.nsh. Use the shell
environment variable “StartupDelay” to set the waiting time.
2.4.3
EFI Shell Prompt
The Shell prompt—which can also be called the Shell command prompt—is the basic entry for
users to do the following:
• Execute Shell commands.
• Load drivers.
• Execute EFI applications.
It displays one of the following prompt symbols on the screen and waits for user input:
fs0:\> or Shell>
All commands and applications are invoked by typing the name of the command at the Shell
prompt. In addition, the active drive may be changed at the command prompt by typing the mapped
name followed by a colon (:).
1.0to7thRvw
July, 2005
21
3
Syntax
3.1
Introduction
This section provides information on the syntax to use with the EFI Shell. In this context, syntax
means the general rules for what you can and cannot type at the command prompt and include in
batch scripts. It covers the following information:
• Special Characters
• Variable and Alias Substitution
• Wildcard Expansion
• Switches and Arguments in Commands
• Quotation Marks
• Output Redirection
• File Naming Conventions
3.2
Special Characters
The EFI Shell implements a programming language that provides control over the execution of
individual commands. Command names and keywords in certain commands are all case insensitive.
When the Shell scans its input, it always treats certain characters (#, >, %, *, ?, ^, ", space, ,, [,
], and newline)specially. Care should be exercised when using these characters. The following
table describes the uses of these characters.
Table 3-1 Special Characters in the EFI Shell
Character
Description
Newline
Ends a command line.
space
Ends an argument, if it is not in quotation marks. This character is sometimes
referred to as the splitting character.
#
Starts a comment.
>
Used for output redirection.
%
Used to delimit a variable or an argument.
"
Used to delimit a quotation.
^
Prevents the next character from being interpreted as having special meaning.
This character is referred to as the escaping character.
* ? [ ]
Wildcards to specify multiple similar file names.
22
Syntax
3.3
Variable and Alias Substitution
3.3.1
Environment Variables and Variable Substitution
Environment variables are variables that can hold user-specified contents and can be read on a
command line or in scripts. There are two kinds of environment variables:
• Volatile environment variables
• Nonvolatile environment variables
Volatile environment variables will be lost when the system is reset or turned off. Nonvolatile
environment variables will not change until they are modified or deleted.
Environment variables can be set and viewed using the set command. To access the value of an
environment variable, delimit the name of the variable with a % character before and after the
variable name—for example, %myvariable%. The variable names are case insensitive.
Variable substitution is not a recursive process. If %a% is set to %b% and %b% is set to 123, the
substitution result of %a% is %b%, not 123.
In addition to the other topics in this subsection, see Variable, Argument, and Alias Substitution in
the Batch Scripts chapter for more information.
3.3.2
Alias Substitution
If the first argument of a command is a defined alias, the Shell replaces the alias with its defined
value. The alias substitution occurs after the variable substitution. For example, if
%myvariable% is set to dir and dir is aliased to ls, entering %myvariable% in the
command line will cause the ls command to be executed.
Like variable substitution, alias substitution is not recursive.
See Aliases in the Features chapter for more information on aliases.
3.3.3
Valid Characters for Variable Names
Any appearance of invalid characters in a variable name will cause the Shell to stop substituting,
and it will discard the current % on the command line. Only the following characters can be used in
variable names:
• _ (underscore)
• The digits 0 through 9
• Lowercase letters a through z
• Uppercase letters A through Z
3.3.4
Variables Available Only in Batch Scripts
This topic describes the following variables, which are available only in batch scripts:
1.0to7thRvw
July, 2005
23
EFI Shell User's Guide
•
•
Syntax
Index and positional variables
Lasterror variable
See the Batch Scripts chapter for more information on batch scripts.
Index and Positional Variables
In scripts, you can access two other kinds of variables, which are described in the table below:
• Index variables
• Positional variables
Table 3-2 Index and Positional Variables
Variable
Denoted
By
Index
Positional
Required Syntax
Description
%x
Any alphabet
character from
a to z or A to Z
Used in for loops. This variable is valid only within the
for statement in which it is defined.
%n
Digit between 0
and 9
Refers to the arguments that are specified on the
command line with the script. Up to ten positional
arguments are supported for batch scripts. Positional
arguments are substituted before each line in the script
file is executed.
By convention, %0 is the name of the script file that is
currently being executed.
See Variable Substitution Flowchart for the substitution rule in scripts.
To delimit an index variable or positional variable, use a % before the variable name. For example,
%a will delimit the content of index variable a as well as the positional variable.
Lasterror Variable
The Shell also defines a special variable named lasterror that is valid only in scripts. See
Special Shell Variables for more information.
3.3.5
Special Shell Variables
The Shell maintains the following three special variables, which are described in the table below:
• path
• lasterror
• efishellmode
• StartupDelay
Table 3-3 Special Shell Variables
Variable
Description
path
Contains the default directories that may exist on all the discovered file systems. These
24
Syntax
default directories are the root directory, \efi\tools , and \efi\boot. If the
Shell cannot find the script or application under the current directory, it will search the
directories that are referred by this variable when users execute a script or an
application. For more information on this variable, see PATH Variable Support in the
Features chapter.
lasterror
Contains the return code of the most recently executed Shell command. This variable
is valid only in scripts and cannot be set by users. Its name space is separate from that
of an environment variable. Script-only commands, such as if, for, else, and
goto, which are used to control the logic of the script, do not change the value of
lasterror.
efishellmode
A reserved volatile environment variable that is used to determine or specify the current
running mode (backward-compatible mode/enhanced Shell mode, or a newer mode in
a future version of the EFI Shell).
Users can specify a value for this variable using the following command, where
is the valid value for efishellmode:
xxx
set -v efishellmode xxx
Users can read the value of efishellmode the same as when they are reading a
normal environment variable, %efishellmode%. For more information on this
variable, see Running Modes and Backward Compatibility in the Features chapter.
StartupDelay
3.3.6
Set the Startup.nsh delay time.
Variable Substitution Flowchart
The following figure shows the sequence for variable and argument substitution. %x means an
index variable and %n means a positional variable.
1.0to7thRvw
July, 2005
25
EFI Shell User's Guide
Figure 3-1 Variable and Argument Substitution Flowchart
26
Syntax
Syntax
3.4
Wildcard Expansion
The *, ?, [, and ] characters can be used as wildcard characters in file name arguments to certain
Shell commands. Besides the file or directory operation commands, the script-only for and if
commands also expand arguments containing wildcard characters to existing file names that match
the pattern. A ^ before the wildcard cannot prevent the wildcard from being expanded.
[ and ] can be either wildcard characters or literal file name characters. The EFI Shell will first try
to interpret them as wildcard characters to match files. If any files are matched, the Shell makes no
further interpretation. Otherwise, the [ and ] characters will be considered as literal characters in
file names.
The table below describes the wildcard expansion for the *, ?, [, and ] characters.
Table 3-4 Wildcard Character Expansion
Character Sequence
Description
*
Matches zero or more characters in a file name.
?
Matches exactly one character in a file name.
[ and ]
Matches one character in a file name with one of the characters in [ and
].
3.5
Switches and Arguments in Commands
Most Shell commands take arguments after the command name that allow you to additionally
specify what the command is supposed to do. Some arguments are optional or required,
depending on the command. The syntax for the command, as listed in the command description
in this document (or in the verbose help for the command), indicates the required
format for any arguments.
The Shell and this document also use some specialized terms switch, flag, and option
to indicate a subset of arguments. These terms are used interchangeably and indicate
an argument that begins with a + or – character. The Shell will interpret this argument
specially.
The following are some examples of arguments and switches that can be used in specific
Shell commands. The text after the command name are arguments or switches.
1.0to7thRvw
July, 2005
27
EFI Shell User's Guide
Shell>
Shell>
Shell>
Shell>
Syntax
load –nc IsaBus.efi
map -r
connect –c
set -d diagnosticpath
All of the internal and external Shell commands support the flag -b. This flag tells the command to
display one screen at a time. This flag is very useful when listing the help information of a
command. Because it is a default flag that is available in all commands, it is not listed in the
commands’ syntax or help information.
3.6
Quotation Marks
The EFI Shell uses quotation marks for argument grouping. A quoted string is treated as a single
argument to a command or as a part of a single argument to a command. Any white space
(including spaces, tabs, and commas) that is included in the quoted string is simply part of that
single argument.
Double quotation marks ("") are used to denote strings and should appear in pairs. However, if
unpaired quotation marks appear in a command line, they will be discarded before passing to the
command entry point. Empty strings are treated as valid command line arguments. It is up to each
command whether to ignore these empty strings.
Quotation marks can define the smallest unit upon which variable substitution will be performed.
This smallest unit is called a part. A part is a subset of a single argument. For example, there are
three parts in the following argument, which are abc, %1, and def, respectively:
abc"%1"def
The introduction of a part helps to avoid ambiguity in the variable substitution process. Variable
substitution will be performed within a single part and cannot be performed across the boundary of
any two adjacent parts. As a result, a"%1"b is completely different from a%"1"b for variable
substitution.
In a command line, the EFI Shell will treat an argument that begins with a + or – character as a flag
option, and it will be specially interpreted. As a result, to prevent an argument from being
interpreted as a flag, a string starting with a + or - character must be enclosed by a pair of quotation
marks. For example, in the following command line, the argument -b will not be interpreted as a
flag:
alias more "-b"
As an alternate approach, you can use the escaping character ^ to prevent an argument that starts
with a + or – character from being interpreted as a flag option. For example, if you type echo ^d" at the command prompt, -d is interpreted as a string and not as a flag, and the string -d will be
displayed instead of an error message that the flag -d is unknown.
28
Syntax
3.7
Output Redirection
The output of EFI Shell commands can be redirected to files. The following is the syntax for this
redirection:
Command > unicode_output_file_pathname
Command >a ascii_output_file_pathname
Command 1> unicode_output_file_pathname
Command 1>a ascii_output_file_pathname
Command 2> unicode_output_file_pathname
Command 2>a ascii_output_file_pathname
Command >> unicode_output_file_pathname
Command >>a ascii_output_file_pathname
Command 1>> unicode_output_file_pathname
Command 1>>a ascii_output_file_pathname
The table below describes the special character combinations that are used in the syntax above.
Table 3-5 Output Redirection Syntax
Character
Sequence Description
>
Redirects standard output to a Unicode file.
>a
Redirects standard output to an ASCII file.
1>
Redirects standard output to a Unicode file.
1>a
Redirects standard output to an ASCII file.
2>
Redirects standard error to a Unicode file.
2>a
Redirects standard error to an ASCII file.
>>
Redirects standard output that is appended to a Unicode file.
>>a
Redirects standard output that is appended to an ASCII file.
1>>
Redirects standard output that is appended to a Unicode file.
1>>a
Redirects standard output that is appended to an ASCII file.
The EFI Shell will redirect standard output to a single file and standard errors to a single file.
Redirecting both standard output and standard errors to different files is allowed. The following
actions are not currently supported:
• Redirecting standard output and standard errors to the same file
• Redirecting standard output to more than one file on the same command
• Redirecting standard errors to multiple files
NUL is used as a special output file name. When NUL is used, the output will not be written into a
file. Instead, it is discarded silently.
1.0to7thRvw
July, 2005
29
EFI Shell User's Guide
3.8
Syntax
File Naming Conventions
This version of the EFI Shell supports only the FAT file system. All file and directory naming
conventions are compatible with the FAT file system specification. The following FAT versions are
supported:
• For system partitions: FAT32
• For removable media: FAT12 and FAT16
Both short and long names are supported. The maximum valid length for a file or directory name is
255 characters. According to conventions, the following characters cannot be used in a file or
directory name:
•*
•?
•<
•>
•/
•\
•"
•:
•|
30
4
Batch Scripts
4.1
Introduction
This chapter describes batch scripts and the batch-script-only commands in more detail.
Specifically, it provides detailed descriptions of all batch script commands (also known as scriptonly commands) and discusses the following:
• Performing variable, argument, and alias substitution in batch script files
• Using comments in batch script files
• Handling errors in batch scripts
• Handling running modes in batch scripts
• Nesting the execution of batch script files
• Redirecting the output of batch script files
• Echoing commands in batch scripts to the console
• Known limitations with the scripting language in batch scripts
See the Batch Scripts topic in the Features chapter for introductory information on batch scripts.
All EFI Shell command syntax that was described in the Syntax chapter applies to EFI Shell batch
scripts. Note that the Shell does not save commands that are executed from a batch script for the
KEY history (up-arrow command recall).
4.2
Batch Script Command Descriptions
4.2.1
Summary of Batch Script Commands
The table below lists the script-only commands. The following topics describe the EFI Shell batch
script commands in detail.
Table 4-1 EFI Shell Batch Script Commands
Command
Description
for...endfor
Executes commands for each item in a set of items.
goto
Makes the execution of the batch file jump to another location.
if...else...endif
Executes commands in specified conditions.
pause
Prints a message and suspends for keyboard input.
shift
Shifts the arguments from %0 to %9 one by one.
31
EFI Shell User's Guide
Batch Scripts
NOTE
The indentation, spacing, or line breaks that are used in the script command descriptions in this
section are optimized for viewing the documentation. They might not always match what is in the
EFI Shell product itself.
4.2.2
for...endfor
NOTE
This command is available only in batch script files.
Summary
Executes one or more commands for each item in a set of items.
Usage
for %indexvar in set
command [arguments]
[command [arguments]]
...
endfor
for %indexvar run (start end [step])
command [arguments]
[command [arguments]]
...
endfor
Description
The for command executes one or more commands for each item in a set of items. The set may
be text strings, file names, or a mixture of both, separated by spaces (if not in quotation marks). If
the length of an element in the set is between 0 and 256 and if the string contains wildcards, the
string will be treated as a file name containing wildcards and be expanded before command is
executed. If no such files are found after expansion, the literal string itself is kept.
Indexvar is any alphabet character from a to z or A to Z, and they are case sensitive. It should
not be a digit (0–9) because %digit will be interpreted as a positional argument in the command
line that launches the script. The name space for index variables is separate from that for
environment variables, so if indexvar has the same name as an existing environment variable,
the environment variable will remain unchanged by the for loop. Each command is executed once
for each item in the set, with any occurrence of %indexvar in the command being replaced with
the current item.
In the second format of the for...endfor statement, indexvar will be assigned a value from
start to end with an interval of step. The start and end values can be any integer whose
32
Batch Scripts
length is less than 7 digits excluding the sign, and it can also apply to step with one exception of
zero.
Step is optional. If step is not specified, it will automatically be determined by the following
rule: if start <= end, then step = 1; otherwise step = -1.
Start, end, and step are divided by a space.
Examples
Example 1
#
# Sample for loop - listing all .txt files
#
echo -off
for %a in *.txt
echo %a exists
endfor
If there are two files named file1.txt and file2.txt in the current directory, the following
will be the output of the sample script:
Sample1> echo -off
file1.txt exists
file2.txt exists
Theoretically it is legal for two nested for commands to use the same alphabet letter as their index
variable, for instance, a.
#
# Sample for loop from 1 to 3 with step 1
#
echo -off
for %a run (1 3)
echo %a
endfor
#
# Sample for loop from 3 down to 1 with step -1
#
echo -off
for %a run (3 1 -1)
echo %a
endfor
Example 2
1.0to7thRvw
July, 2005
33
EFI Shell User's Guide
Batch Scripts
#
# Sample for loop - 2 nested for using same index variable
#
echo -off
for %a in value1 value2
for %a in value3 value4
echo %a
endfor
endfor
When processing the first for loop and before seeing the endfor, the index variable %a has the
value value1. As a result, in the second for loop, the %a has already been defined and will be
replaced with the current value of %a. After substitution, the string becomes for value1 in
value3 value4, which is not a legal for command. Thus, the script will execute without error
only when the value of %a is also a single alphabet letter. If two independent for commands use
the same index variable, the first for has already freed the variable when the second for is
encountered, so there will be no problem in this case.
4.2.3
goto
NOTE
This command is available only in batch script files.
Summary
Makes the execution of the batch file jump to another location.
Usage
goto label
Description
The goto command directs the batch file to execute the line in the batch file after the given label.
This command is not supported from the interactive Shell.
A label is a line beginning with a colon (:). It can appear either before or after the goto command.
The Shell searches forward in the batch file for label, from the current file position. If it reaches
the end of the file, the search resumes at the top of the file and continues until it finds label or it
reaches the starting point. If label is not found, the batch process terminates and the Shell
displays an error message. If a label is encountered but the goto command was not executed, the
label lines are ignored.
You cannot use the goto command to jump into another for loop, but it is legal to jump into an
if statement.
34
Batch Scripts
Examples
# This is a batch script
goto Done
...
:Done
cleanup.nsh
4.2.4
if...else...endif
NOTE
This command is available only in batch script files.
Summary
Executes one or more commands depending on whether a specified condition is true or false.
Usage
The if command has two forms:
(1)if [not] exist filename then
command [arguments]
[command [arguments]]
...
[else
command [arguments]
[command [arguments]]
...
]
endif
(2)if [/i] [not] string1 == string2 then
command [arguments]
[command [arguments]]
...
[else
command [arguments]
[command [arguments]]
...
]
endif
Description
The if command executes one or more commands before the else or endif commands, if the
specified condition is true; otherwise, commands between else (if there is an else) and endif
are executed.
1.0to7thRvw
July, 2005
35
EFI Shell User's Guide
Batch Scripts
In the first usage above of if, the exist condition is true when the file that is specified by
filename exists. The filename argument may include device and path information. This first
form of if also supports wildcard expansion. If more than one file matches the wildcard pattern,
the condition evaluates to TRUE.
In the second usage, the string1 == string2 condition is true if the two strings are identical.
Here the comparison can be case sensitive or insensitive, depending on the optional switch /i. If
/i is specified, it will compare strings in the case-insensitive manner; if /i is not specified, it
compares strings in the case-sensitive manner.
The else command is optional in an if/else statement.
Examples
#
# Example script for "if" command
#
if exist fs0:\myscript.nsh then
myscript myarg1 myarg2
endif
if %myvar% == runboth then
myscript1
myscript2
else
echo ^%myvar^% != runboth
endif
In this example, if the script file myscript.nsh exists in fs0:\, then this script will be
launched with the following two arguments:
• myarg1
• myarg2
The environment variable %myvar% is then checked to see if its value is runboth. If it is, the
scripts myscript1 and myscript2 will be executed one after the other; otherwise, the
following message is printed:
%myvar% != runboth
4.2.5
pause
NOTE
This command is available only in batch script files.
Summary
Prints a message to the display and then suspends batch file execution and waits for keyboard input.
36
Batch Scripts
Usage
pause [-q]
Description
The pause command prints a message to the display and then suspends the execution of the batch
file and waits for keyboard input. Pressing any key except for q or Q resumes execution of the
script. If q or Q is pressed, batch processing terminates; otherwise, execution continues with the
next line after the pause command.
The -q switch is optional and hides the message.
1.0to7thRvw
July, 2005
37
EFI Shell User's Guide
Batch Scripts
Examples
* The following script is a sample of 'pause' command:
fs0:\> type pause.nsh
File: fs0:\pause.nsh, Size 204
#
# Example script for 'pause' command
#
echo pause.nsh begin..
date
time
pause
echo pause.nsh done.
* To execute the script with echo on:
fs0:\> pause.nsh
+pause.nsh> echo pause.nsh begin..
pause.nsh begin..
+pause.nsh> date
06/19/2001
+pause.nsh> time
00:51:45
+pause.nsh> pause
Enter 'q' to quit, any other key to continue:
+pause.nsh> echo pause.nsh done.
pause.nsh done.
* To execute the script with echo off:
fs0:\> echo -off
fs0:\> pause.nsh
pause.nsh begin..
06/19/2001
00:52:50
Enter 'q' to quit, any other key to continue: q
fs0:\>
Shell>
38
Batch Scripts
* The following script is a sample of 'pause -q' command:
fs0:\> type pause.nsh
File: fs0:\pause.nsh, Size 207
#
# Example script for 'pause' command
#
echo pause.nsh begin..
date
time
pause -q
echo pause.nsh done.
* To execute the script with echo on:
fs0:\> pause.nsh
+pause.nsh> echo pause.nsh begin..
pause.nsh begin..
+pause.nsh> date
06/19/2001
+pause.nsh> time
00:51:45
+pause.nsh> pause -q
+pause.nsh> echo pause.nsh done.
pause.nsh done.
* To execute the script with echo off:
fs0:\> echo -off
fs0:\> pause.nsh
pause.nsh begin..
06/19/2001
00:52:50
pause.nsh done.
fs0:\>
Shell>
4.2.6
shift
NOTE
This command is available only in batch script files.
Summary
Shifts the arguments from %0 to %9 one by one.
1.0to7thRvw
July, 2005
39
EFI Shell User's Guide
Batch Scripts
Usage
shift
Description
The shift command increases the number of positional parameters to more than the standard ten
for use.
Examples
* Following script is a sample of 'shift' command:
fs0:\> type shift.nsh
File: fs0:\shift.nsh, Size 79
#
# Example script for 'shift' command
#
echo %1 %2 %3
shift
echo %1 %2
* To execute the script with echo on:
fs0:\> shift.nsh welcome EFI world
+shift.nsh> echo welcome EFI world
Welcome EFI world
+shift.nsh> shift
+shift.nsh> echo EFI world
EFI world
* To execute the script with echo off:
fs0:\> echo -off
fs0:\> shift.nsh welcome EFI world
welcome EFI world
EFI world
4.3
Variable, Argument, and Alias Substitution
4.3.1
Variable, Argument, and Alias Substitution in Batch Scripts
This section describes variable, argument, and alias substitution in batch scripts and covers the
following:
• Alias Substitution Rule
• General Variable Substitution Rule
• General Command Line Variable Substitution Rule
• Supported Number of Arguments
• Syntax for Variables
40
Batch Scripts
• Examples
The rules that are described in this section are true only in enhanced Shell mode.
4.3.2
Alias Substitution Rule in Batch Scripts
NOTE
This rule is true only in enhanced Shell mode.
In batch scripts, only the first argument on the command line can be an alias. No other arguments
will be interpreted as an alias. Substitution of aliases is not recursive.
4.3.3
General Variable Substitution Rule in Batch Scripts
NOTE
This rule is true only in enhanced Shell mode.
Besides environment variables, there are positional variables and index variables that can be used
only in batch scripts. As a result, variable substitution in scripts is more complicated. See the
Variable Substitution Flowchart in the Syntax chapter for the searching sequence for variable
substitution.
4.3.4
General Command Line Variable Substitution Rule in Batch Scripts
NOTE
This rule is true only in enhanced Shell mode.
Command line variable substitution in batch scripts is simple, because it does not have to consider
index variables and positional variables. Command line variable substitution deals only with
environment variables. For environment variables, the syntax is %var%, where var is a valid
variable name and should be included between two % characters.
If the command line interpreter finds an environment variable whose name is var, it will substitute
the %var% string with the content that is defined by the variable. If the command line interpreter
cannot find any environment variable whose name is var, then it will substitute the %var% string
with an empty string.
Variable substitution is not recursive, which means that the content that is extracted from a variable
will not be further interpreted as a variable.
1.0to7thRvw
July, 2005
41
EFI Shell User's Guide
4.3.5
Batch Scripts
Supported Number of Arguments in Batch Scripts
NOTE
This rule is true only in enhanced Shell mode.
This release of the EFI Shell supports a maximum of 256 arguments for batch scripts. However,
only a maximum of nine positional variables from %0 to %9 are provided in scripts. This version of
the Shell adds a new script-only command shift, which provides access to all the arguments by
rotating the positional variables from %0 to %9.
4.3.6
Syntax for Variables in Batch Scripts
NOTE
This rule is true only in enhanced Shell mode.
The syntax listed in Valid Characters for Variable Names (in the Syntax chapter) also applies for
variables in batch scripts.
For index variables, their names are case sensitive and can only be one of the letters.
For positional variables, their names can only be one of the digits from 0 to 9.
4.3.7
Example of Variable, Argument, and Alias Substitution in Batch
Scripts
The following uses the script file ArgVar.nsh as an example:
# Variable & Argument substitution
echo -off
for %a in IndexVarA
echo Output: %1%a%b
endfor
echo -on
Suppose there is an environment variable %1% defined as EnvVar1 and another variable %a%
defined as EnvVarA:
fs0:>ArgVar PosArg1
Argvar> echo -off
Output: EnvVar1ab
When the script is executed with an argument, %1 is defined as EnvArg1. When the first % is met,
environment variable %1 is attempted, which causes the %1 be replaced with EnvArg1. Then a is
42
Batch Scripts
met and it is kept as it is. Lastly, the %b is attempted. Because %b does not exist, the % will be
discarded and b will be left.
Now launch the script without the command line argument:
fs0:>set –d 1
Argvar> echo -off
Output: EnvVarAb
This time %1% does not exist and %1 becomes undefined. The next check will then be %a%, and
%a% will be substituted with EnvVarA. The resulting string then looks like EnvVarAb.
Now delete another environment variable %a% and try the script:
fs0:>set -d a
fs0:>ArgVar
Argvar> echo -off
Output: IndexVarAb
In the previous example, %1 is replaced with an empty string. Then the second % is met. Because
%a% also is not defined, the index variable %a is attempted, which will find a match. Thus %a is
replaced with IndexVarA. Then, the remaining %b takes the form %x but matches nothing, so the
% is discarded.
The argument and variable substitution is a single circular process, so if the value of a positional
argument contains an environment variable %var% and regardless of whether %var% is defined
when the script is launched, the argument will be replaced with the literal string %var%.
After the arguments and variables are substituted, the Shell examines the first argument to see if it
is an alias name. If so, the alias name is replaced with its value.
4.4
Comments
Comments can be embedded in batch scripts. The # character on a line is used to denote that the
Shell is to ignore all characters on the same line and to the right of the #. Comments are not echoed
to the console regardless of whether the echo state is on or off.
4.5
Error Handling
By default, if an error is encountered during the execution of a command in a batch script, the script
will continue to execute. However, if an error is encountered that affects the logic of the script
when executing the script-only commands (such as for...endfor, if...else...endif,
and goto), the script will exit. If the error-causing script is called by another script, the caller script
will continue to execute.
1.0to7thRvw
July, 2005
43
EFI Shell User's Guide
Batch Scripts
The lasterror Shell variable is provided to allow batch scripts to test the results of the most
recently executed command using the if command. This variable is not an environment variable; it
is a special variable that the Shell maintains for the lifetime of the current instance of the Shell. It is
a read-only variable and cannot be modified by the command set. Script-only commands, which
are used to control the logic of the script, do not affect the value of the lasterror variable.
4.6
Running Modes in Batch Scripts
The running mode will always be set to backward-compatible mode at the beginning of execution
of a batch script file, no matter what mode the Shell was in before the script is executed. As a
result, it is the user's responsibility to have the script set the running mode to the proper mode for
its purpose.
See the topics that are listed in the table below for more information on running modes.
Table 4-2 Additional Information on Running Modes
Topic
Chapter
Description
Running Modes and
Backward Compatibility
Features
Provides general information on running modes in the Shell.
Nesting Batch Scripts
Batch Scripts
Discusses running modes in nested batch scripts.
4.7
Nesting Batch Scripts
Execution of batch script files can be nested; that is, script files may be executed from within other
script files. Recursion is allowed.
A batch script can contain one or more batch scripts. The maximum nesting level is 9. The
embedded batch script will be executed as a command. After the whole embedded batch script is
executed completely, the next command will be executed.
The EFI Shell will automatically save and restore the running mode before and after the execution
of nested scripts so that the changes of running modes in nested scripts will not affect the running
mode of a parent script.
4.8
Output Redirection in Batch Scripts
Output redirection is fully supported in scripts. Output redirection on a command in a script file
causes the output for that command to be redirected. Output redirection on the invocation of a batch
44
Batch Scripts
script causes the output for all commands that are executed from that batch script to be redirected to
the file, with the output of each command appended to the end of the file.
If a command in a script redirects its output to file1 but the output is redirected to file2 on
invocation of a whole script, the output of that command will be redirected to file1. However,
the echo of the command itself (if the echo state is on) will appear in file2, as well as the output
of all other commands.
4.9
Echoing in Batch Scripts
By default, both the input and output for all commands that are executed from a batch script are
echoed to the console. Use the echo -off command to suppress displaying commands that are
read from a batch file. In addition, you can insert an additional @ character before a command in a
batch file to prevent the current command from being echoed.
When a script is launched from the interactive Shell, by default its echo state inherits the echo state
of the interactive Shell. Changing the echo state in the script does not affect the echo state of the
interactive Shell. When a script calls another script, the called script inherits the caller script's
current echo state. However, if the called script changes the echo state, after returning, the caller's
echo script also changes.
4.10 Known Limitations with the Shell Scripting Language
The following are some known limitations with the EFI Shell scripting language capabilities:
• Do not try to read from and write to the same file within a single command. For example, do not
use the following:
fs0:>type test.nsh > test.nsh;
• Do not use the goto command to jump into another loop.
• Do not use the same index variable in nested for statements, which can easily lead to errors.
• Do not reference the index value outside of the for statement that defines it.
• Do not use continue and break (which are unsupported) to begin the next iteration or quit a
loop. Use the goto command to control the execution flow if necessary. Note that there is a
Shell command called break, but it is for debug purposes only and is not documented in this
user's guide.
• Do not use the exit command to quit the current script. This command will quit the entire EFI
Shell.
1.0to7thRvw
July, 2005
45
5
Commands
5.1
Introduction
The EFI Shell environment provides a rich set of commands that extend and enhance the EFI Shell
capability. These commands can be used directly from a command prompt.
In addition, users can combine and organize these commands into a batch file. Batch files (also
called batch programs) allow users to simplify routine or repetitive tasks (see the Batch Scripts
chapter for more information).
This chapter does the following:
• Briefly discusses external Shell commands
• Lists the abbreviations that are used in the EFI Shell to indicate EFI protocol names
• Lists the MS-DOS* 6.22 and Unix* equivalent names for EFI Shell internal commands
• Provides descriptions of all the Shell internal commands
5.2
External Commands
External commands are a set of Shell applications. There is no difference between internal and
external Shell commands, and they can be switched to each other very easily. See the Shell How
To's chapter for instructions on switching internal commands to external commands, and vice versa.
However, some internal commands are internal only and cannot be switched to external commands,
because they are too close to the EFI Shell core and it is not reasonable to make them external.
These commands are noted with a double asterisk (**) in Shell Internal Command Descriptions
Overview and in the detailed description of each command.
External commands have to reside in a file system. As a result, to run them, users need to have at
least one mapped file system and put those external commands under this file system.
5.3
Supported EFI Protocols in the Shell
The table below shows all the supported protocol information in the EFI Shell. Some Shell
commands need this information to operate. For example, the dh command needs the protocol
symbol for its -p flag to list all the handles on which the specific protocol was installed.
Table 5-1 EFI Shell Protocol Information Table
Protocol Symbol
EFI Protocol
BlkIo
Block I/O Protocol
46
Commands
BusSpecificDriverOverride
Bus Specific Driver Override Protocol
ComponentName
Component Name Protocol
Configuration
Driver Configuration Protocol
ConIn
Console-in Device
ConOut
Console-out Device
DebugPort
Debugport Protocol
DebugSupport
Debug Support Protocol
Decompress
Decompress Protocol
DevIo
Device I/O Protocol
Diagnostics
Driver Diagnostics Protocol
DiskIo
Disk I/O Protocol
Dpath
Device Path Protocol
DriverBinding
Driver Binding Protocol
ErrOutSplit
Error-out Splitter Protocol
Fs
Simple File System Protocol
Image
Loaded Image Protocol
IsaAcpi
ISA ACPI Protocol
IsaIo
ISA I/O Protocol
LegacyBoot
Legacy Boot Protocol
Load
Load File Protocol
Net
Simple Network Protocol
Nii
Network Interface Identifier Protocol
PciIo
PCI I/O Protocol
PciRootBridgeIo
PCI Root Bridge I/O Protocol
Pxebc
PXE Base Code Protocol
ScsiIo
SCSI I/O Protocol
ScsiPassThru
SCSI Pass Thru Protocol
SerialIo
Serial I/O Protocol
SimplePointer
Simple Pointer Protocol
StdErr
Standard Error Device
Tcp
TCP Protocol
Txtin
Simple Text-in Protocol
TxtInSplit
Text-in Splitter Protocol
Txtout
Simple Text Output Protocol
TxtOutSplit
Text-out Splitter Protocol
UgaDraw
UGA Draw Protocol
UgaIo
UGA I/O Protocol
UnicodeCollation
Unicode Collation Protocol
1.0to7thRvw
July, 2005
47
EFI Shell User's Guide
Commands
UsbIo
USB I/O Protocol
VgaClass
VGA Class Driver Protocol
5.4
MS-DOS* 6.22 and Unix* Equivalents
The following table lists the equivalent command names for internal EFI Shell commands and MSDOS* 6.22 and Unix* commands.
Table 5-2 MS-DOS 6.22 and Unix Equivalents for Shell Internal Commands
EFI Shell Command
MS-DOS 6.22 Equivalent
alias
Unix Equivalent
alias
attrib
attrib
chmod
cd
cd
cd
cls
cls
clear
copy
copy
cp
cp
copy
cp
date
date
date
del
del
rm
dir
dir
echo
echo
echo
exit
exit
exit
connect
dh
dir
disconnect
drivers
drvcfg
drvdiag
help
help
load
ls
dir
ls
mkdir
mkdir
mkdir
mv
move
mv
reset
reset
reboot
rm
del
rm
map
reconnect
48
Commands
set
set
set
time
time
time
touch
touch
type
type
type
unload
ver
ver
vol
vol
5.5
Internal Command Descriptions
5.5.1
Summary of EFI Shell Internal Commands
The EFI Shell core integrates some internal commands. The table below lists all the internal EFI
Shell commands that are supported. The following topics describe each command in more detail.
Because there are some fundamental differences between different EFI implementations, some of
the commands cannot run across all implementations. The table indicates the versions of EFI that
are supported for each respective command. If you run a command that is not supported on a
system, the command should quit gracefully with a message.
In the table below, a double asterisk (**) indicates that the command is an internal-only command;
it cannot be switched to an external command or application. See the External Commands topic in
this chapter for more information.
All of the Shell commands listed below support the -b flag. This flag tells the command to display
one screen at a time. Because it is a default flag that is available in all commands, it is not listed in
the commands’ syntax or help information.
Table 5-3 EFI Shell Internal Commands
Command
Supported EFI
Version
Description
alias**
EFI 1.02 and above
Displays, creates, or deletes aliases in the EFI Shell.
attrib
EFI 1.02 and above
Displays or changes the attributes of files/directories.
cd**
EFI 1.02 and above
Displays or changes the current directory.
cls
EFI 1.02 and above
Clears the standard output with a background color.
connect**
EFI 1.10 and above
Binds an EFI driver to a device and starts the driver.
copy
EFI 1.02 and above
Copies one or more files/directories to another location.
cp
EFI 1.02 and above
Copies one or more files/directories to another location.
date
EFI 1.02 and above
Displays the current date or sets the date in the system.
del
EFI 1.02 and above
Deletes one or more files or directories.
dh**
EFI 1.10 and above
Displays the handles in the EFI environment.
1.0to7thRvw
July, 2005
49
EFI Shell User's Guide
Commands
dir
EFI 1.02 and above
Displays a list of files and subdirectories.
disconnect**
EFI 1.10 and above
Disconnects one or more drivers from a device.
drivers
EFI 1.10 and above
Displays a list of drivers that follow the EFI Driver Model.
drvcfg
EFI 1.10 and above
Invokes the Driver Configuration Protocol.
drvdiag
EFI 1.10 and above
Invokes the Driver Diagnostics Protocol.
echo**
EFI 1.02 and above
Displays messages or turns command echoing on or off.
exit**
EFI 1.02 and above
Exits the EFI Shell.
help, ?**
EFI 1.02 and above
Displays the list of commands or verbose help of a command.
load
EFI 1.10 and above
Loads EFI drivers.
ls
EFI 1.02 and above
Displays a list of files and subdirectories.
map**
EFI 1.02 and above
Displays or defines mappings.
mkdir
EFI 1.02 and above
Creates one or more directories.
mv
EFI 1.02 and above
Moves one or more files/directories to a destination.
reconnect**
EFI 1.10 and above
Disconnects a driver from a device and then connects it again.
reset
EFI 1.02 and above
Resets the system.
rm
EFI 1.02 and above
Deletes one or more files or directories.
set**
EFI 1.02 and above
Displays/creates/changes/deletes environment variables.
time
EFI 1.02 and above
Displays the current time or sets the time of the system.
touch
EFI 1.02 and above
Updates the time with the current time.
type
EFI 1.02 and above
Displays the contents of a file.
unload
EFI 1.10 and above
Unloads a protocol image.
ver
EFI 1.02 and above
Displays the version information.
vol
EFI 1.02 and above
Displays volume information of the file system.
**
This command is an internal-only command; it cannot be switched to an external command or application.
NOTE
The indentation, spacing, or line breaks that are used in the command descriptions in this section
are optimized for viewing the documentation. They might not always match what is in the EFI Shell
product itself.
All of the syntax in these command descriptions is only for enhanced Shell mode.
5.5.2
Command Usage Notes
Note the following when using the Shell internal commands:
1. If the Handle parameter is required in the internal Shell command argument—for example, in
the dh or disconnect command—it actually indicates the handle index, not the real handle.
For convenience, the EFI Shell views the handle index as the equivalent of the real handle to
operate an image handle, device handle, and so on. As a result, users should also use the handle
50
Commands
index instead of the real handle value in Shell commands. The handle index can change after
some hardware changes or the execution of some commands, such as disconnect, connect,
reconnect. To get the current handle index for the specified device, driver, or image, use the
dh command.
In some file-operation-related Shell commands, such as load and attrib, an argument is listed
as File... or Directory... in the syntax. The suffix "..." here indicates that the
arguments can be one or more files/directories. The command will process these arguments in the
order in which they appear on the command line. Any previous execution failures will not prevent
the following commands from executing. For example, attrib +h file1 file2 file3
is a legal command and has the same execution results as the following command sequence:
attrib +h file1
attrib +h file2
attrib +h file3
If any execution among them fails, the next command will continue executing until all the
arguments in the list have been executed.
2.
3.
4.
5.
5.5.3
alias
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Displays, creates, or deletes aliases in the EFI Shell environment.
EFI Versions
EFI 1.02 and above.
Usage
ALIAS [-d|-v] [sname] [value]
-d
-v
sname
value
-
Deletes an alias
Volatile variable
Alias name
Original name
Description
This command displays, creates, or deletes aliases in the EFI Shell environment. An alias provides
a new name for an existing EFI Shell command or an EFI application. Once the alias is created, it
can be used to run the command or launch the EFI application. There are some aliases that are
predefined in the EFI Shell environment. These aliases provide the MS-DOS* and Unix*
1.0to7thRvw
July, 2005
51
EFI Shell User's Guide
Commands
equivalent names for the file manipulation commands. The examples below show the default
aliases that are available in the EFI Shell.
See the following for more information on alias substitution:
• Alias Substitution in the Syntax chapter
• Alias Substitution Rule in the Batch Scripts chapter
Examples
Shell> help alias
Displays, creates, modifies, or deletes aliases in the EFI Shell
environment.
ALIAS [-d|-v] [sname] [value]
-d
-v
sname
value
-
Deletes an alias
Volatile variable
Alias name
Original name
Note:
1. 'sname' should not be an internal Shell command.
2. 'value' can be an internal Shell command, a script, or an EFI
application. However, any other values are also acceptable.
3. Alias values are stored in EFI NVRAM and will be retained
between
boots unless the flag '-v' is specified.
4. Alias should not succeed to add a non-volatile alias when a
same
volatile alias exists, or vice versa.
52
Commands
Examples:
* To display all aliases in the current EFI environment:
Shell> alias
md
: mkdir
rd
: rm
* To create an
Shell> alias
Shell> alias
md
:
rd
:
myguid :
alias to the EFI environment:
myguid guid
* To delete an
Shell> alias
Shell> alias
md
:
rd
:
alias in the EFI environment:
-d myguid
mkdir
rm
guid
mkdir
rm
* To add a volatile alias in the current EFI environment, which
has a
star * at the line head. This volatile alias will disappear
at
next boot.
Shell> alias -v fs0 floppy
Shell> alias
md
: mkdir
rd
: rm
* fs0 : floppy
Shell>
5.5.4
attrib
Summary
Displays and sets the attributes of files or directories.
EFI Versions
EFI 1.02 and above.
1.0to7thRvw
July, 2005
53
EFI Shell User's Guide
Commands
Usage
ATTRIB [+a|-a] [+s|-s] [+h|-h] [+r|-r] [file...] [directory...]
+a|-a
+s|-s
+h|-h
+r|-r
file
directory
-
Sets or clears 'archive' attribute
Sets or clears 'system' attribute
Sets or clears 'hidden' attribute
Sets or clears 'read only' attribute
File name (wildcards are permitted)
Directory name (wildcards are permitted)
Description
This command displays and sets the attributes of files or directories. The following four attribute
types are supported in the EFI file system:
• Archive [A]
• System [S]
• Hidden [H]
• Read only [R]
If a file (in general meaning) is a directory, then it is also shown to have the attribute [D].
If any file in the file list that is specified in the command line does not exist, attrib will continue
processing the remaining files while reporting the error.
54
Commands
Examples
Shell> help attrib
Displays or changes the attributes of files or directories.
ATTRIB [+a|-a]
+a|-a
+s|-s
+h|-h
+r|-r
file
directory
[+s|-s] [+h|-h] [+r|-r] [file...] [directory...]
- Sets or clears 'archive' attribute
- Sets or clears 'system' attribute
- Sets or clears 'hidden' attribute
- Sets or clears 'read only' attribute
- File name (wildcards are permitted)
- Directory name (wildcards are permitted)
Notes:
1. If no attribute option is specified in the parameters, the
command
simply displays the attributes of specified files or
directories.
2. If no file or directory is specified in the command line
arguments,
then the command applies to all the files and directories
within the
current directory.
Examples:
* To display the attributes of a directory:
fs0:\> attrib fs0:\
attrib:D
fs0:\
* To add the system attribute to all files of extension '.efi':
fs0:\> attrib +s *.efi
* To display attributes of all files/directories in the current
directory:
fs0:\> attrib *
attrib: AS
fs0:\serial.efi
attrib:DA
fs0:\test1
attrib: A HR fs0:\bios.inf
attrib: A
fs0:\VerboseHelp.txt
attrib: AS
fs0:\IsaBus.efi
* To remove attributes of files, using the -a, -s, -h, -r
option:
fs0:\> attrib -r *.inf
attrib: A H fs0:\bios.inf
1.0to7thRvw
July, 2005
55
EFI Shell User's Guide
Commands
Shell>
5.5.5
cd
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Changes the current working directory that is used by the EFI Shell environment.
EFI Versions
EFI 1.02 and above.
Usage
CD [path]
path - The relative or absolute file path
Description
This command changes the current working directory that is used by the EFI Shell environment.
The table below describes the conventions that are used to refer to the directory, its parent, and its
driver mapping in the EFI Shell environment.
Table 5-4 Conventions for Directory Names
Convention
Description
.
Refers to the current directory.
..
Refers to the directory's parent.
\
Refers to the root of the current driver mapping.
The following example shows how to move between the directories on a floppy drive containing an
EFI directory and a TOOLS subdirectory below the EFI directory.
56
Commands
Examples
Shell> help cd
Displays or changes the current directory.
CD [path]
path - The relative or absolute file path
Note:
1. Type CD without parameters to display the current fs and
directory.
2. The 'path' parameter can contain some special usage. When '.'
or
'..' is used as a directory, '.' means the current directory,
and
'..' means its parent directory. '\' can also be used at the
beginning of the path to represent the root of the current
driver
mapping.
3. CD shall be used in the same volume.
4. CD can change the current directory in the file system other
than
current file system.
5. There must be at least one blank space between CD and path.
Examples:
* To change the current fs to the mapped fs0:
Shell> fs0:
* To change the current directory to subdirectory 'efi':
fs0:\> cd efi
* To change the current directory to the parent directory
(fs0:\):
fs0:\efi\> cd ..
* To change the current directory to 'fs0:\efi\tools':
fs0:\> cd efi\tools
* To change the current directory to the root of the current fs
(fs0):
fs0:\efi\tools\> cd \
fs0:\>
* To move between volumes and maintain the current path .
fs0:\> cd \efi\tools
fs0:\efi\tools\> fs1:
fs1:\> cd tmp
fs1:\tmp> cp fs0:*.* .
1.0to7thRvw
July, 2005
57
EFI Shell User's Guide
Commands
Shell>
5.5.6
cls
Summary
Clears the standard output device with an optional background color attribute.
EFI Versions
EFI 1.02 and above.
Usage
CLS [color]
color
- New
0
1
2
3
4
5
6
7
background color
- Black
- Blue
- Green
- Cyan
- Red
- Magenta
- Yellow
- Light gray
Description
This command clears the standard output device with an optional background color attribute. If
color is not defined, then the background color does not change.
58
Commands
Examples
Shell> help cls
Clears the standard output with an optional background color.
CLS [color]
color
- New
0
1
2
3
4
5
6
7
background color
- Black
- Blue
- Green
- Cyan
- Red
- Magenta
- Yellow
- Light gray
Note:
1. If no parameters are specified, this command clears the
standard output device. The background color is not changed.
Examples:
* To clear the output but not change the background color:
fs0:\> cls
* To clear the output and change the background color to Cyan:
fs0:\> cls 3
* To clear the output and change the background with default
color (black):
fs0:\> cls 0
Shell>
5.5.7
connect
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Binds a driver to a specific device and starts the driver.
EFI Versions
EFI 1.10 and above.
1.0to7thRvw
July, 2005
59
EFI Shell User's Guide
Commands
Usage
CONNECT [[DeviceHandle] [DriverHandle] | [-c] | [-r]]
-r
-c
- Connect recursively
- Connect console devices described in the
EFI
DeviceHandle
number
DriverHandle
number
Environment Variables
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
Description
This command binds a driver to a specific device and starts the driver. If the -r flag is used, then
the connection is done recursively until no further connections between devices and drivers are
made. If the -c flag is used, then the connect command will bind the proper drivers to the
console devices that are described in the EFI environment variables. The example below shows the
typical output from the verbose help for this command.
60
Commands
Examples
Shell> help connect
Binds an EFI driver to a device and starts the driver.
CONNECT [[DeviceHandle] [DriverHandle] | [-c] | [-r]]
-r
-c
- Connect recursively
- Connect console devices described in the
EFI
DeviceHandle
number
DriverHandle
number
Environment Variables
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
Note:
1. When option '-c' is specified, only console devices described
in the
EFI Environment Variables and related devices will be
connected.
2. If recursive option '-r' is specified, it causes EFI to scan
all
handles and checks to see if any loaded or embedded driver can
match
the specified device. If so, the driver will be bound to the
device.
Additionally, if more device handles are created during the
binding, these
handles will also be checked to see if a matching driver can
bind to
these devices as well. The process is repeated until no more
drivers
are able to connect to any devices. However, if without the
option,
the newly created device handles will not be further bound to
any
drivers.
3. If no 'DriverHandle' parameter is specified, all matched
drivers will
be bound to the specified device.
4. If no 'DeviceHandle' parameter is specified, all device
handles in the
current system will be the default.
5. If only a single handle is specified and the handle has an
EFI_DRIVER_BINDING_PROTOCOL on it, then the handle is assumed
to
be a driver handle. Otherwise, it is assumed to be a device
handle.
1.0to7thRvw
July, 2005
61
EFI Shell User's Guide
Commands
6. If nothing is specified, then all proper drivers will be tried
to bind
to all the devices without recursion. Each connection status
will
be dumped.
7. Output redirection is not supported for ‘connect –r’ usage.
Examples:
* To connect all drivers to all devices recursively:
Shell> connect –r
* To display all connections:
Shell> connect
ConnectController(1) : Status = Success
ConnectController(2) : Status = Success
ConnectController(3) : Status = Success
...
ConnectController(3D) : Status = Success
* To connect driver 0x17 to all the devices it can manage:
Shell> connect 17
* To connect all possible drivers to device 0x19:
Shell> connect 19
* To connect driver 0x17 to device 0x19:
Shell> connect 19 17
* To connect console devices described in the EFI Environment
Variables:
Shell> connect -c
Shell>
5.5.8
copy
Summary
Copies one or more source files or directories to a destination.
EFI Versions
EFI 1.02 and above
62
Commands
Usage
COPY [-r] [-q] src [src...] [dst]
-r
-q
prompt)
src
permitted)
dst
- Recursive copy
- Quiet copying (replace existing files without
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Description
This command copies one or more source files or directories to a destination. If the source is a
directory, the -r flag must be specified. If -r is specified, then the source directory will be
recursively copied to the destination (which means that all subdirectories will be copied). If a
destination is not specified, then the current working directory is assumed to be the destination.
If any target file (not directory) already exists, there will be a prompt asking the user to confirm
replacing the file. The following four choices are available:
• Yes: Replace the file.
• No: Do not replace the file.
• All: Replace the existing files in all subsequent cases.
• Cancel: Do not replace any existing files in all subsequent cases.
If there are multiple source files/directories, the destination must be a directory.
1.0to7thRvw
July, 2005
63
EFI Shell User's Guide
Commands
Examples
Shell> help copy
Copies one or more files/directories to another location.
COPY [-r] [-q] src [src...] [dst]
-r
-q
prompt)
src
permitted)
dst
- Recursive copy
- Quiet copying (replace existing files without
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Note:
1. '-r' must be specified if src is a directory. If '-r' is
specified,
then the source directory will be recursively copied to the
destination. Src itself will be copied.
2. If 'dst' parameter is not specified, then the current
directory is assumed to
be the destination.
3. 'COPY -r src1 src2 dst' is to copy all files and
subdirectories in
'src1' and 'src2' to the destination 'dst'. 'Src1' and 'src2'
themselves are also
copied. 'dst' parameter will be interpreted as a directory.
4. Copying a directory/file to itself is not allowed.
5. If an error occurs, COPY will exit immediately and the
remaining files or
directories will not be copied.
6. When 'copy' is executed with a script file, it always performs
quiet
copying regardless of whether the '-q' option is specified.
7. If you are copying multiple files, the destination must be an
existing
directory.
Examples:
* To display the contents of current directory first of all:
fs0:\> ls
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/13/01
06/13/01
64
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
10:00a
10:00a
512
512
512
28,739
32,838
efi
test1
test2
IsaBus.efi
IsaSerial.efi
Commands
06/18/01
06/18/01
08:04p
29
08:05p <DIR>
512
3 File(s)
61,606 bytes
4 Dir(s)
temp.txt
test
* To copy a file in the same directory but change the file
name:
fs0:\> copy temp.txt readme.txt
copying fs0:\temp.txt -> fs0:\readme.txt
- [ok]
* To copy multiple files to another directory:
fs0:\> copy temp.txt isaBus.efi \test
copying fs0:\temp.txt -> fs0:\test\temp.txt
- [ok]
copying fs0:\isaBus.efi -> fs0:\test\IsaBus.efi
- [ok]
* To copy multiple directories recursively to another
directory:
fs0:\> copy -r test1 test2 boot \test
copying fs0:\test1 -> fs0:\test\test1
copying fs0:\test1\test1.txt -> fs0:\test\test1\test1.txt
- [ok]
copying fs0:\test2 -> fs0:\test\test2
copying fs0:\test2\test2.txt -> fs0:\test\test2\test2.txt
- [ok]
copying fs0:\boot -> fs0:\test\boot
copying fs0:\boot\shell.efi -> fs0:\test\boot\shell.efi
- [ok]
* To see the results of the above operations:
fs0:\> ls \test
Directory of: fs0:\test
06/18/01
06/18/01
01/28/01
01/28/01
01/28/01
01/28/01
01/28/01
01:01p <DIR>
512
01:01p <DIR>
0
08:21p <DIR>
512
08:21p <DIR>
512
08:21p <DIR>
512
08:23p
29
08:23p
28,739
2 File(s)
28,828 bytes
5 Dir(s)
.
..
test1
test2
boot
temp.txt
IsaBus.efi
Shell>
1.0to7thRvw
July, 2005
65
EFI Shell User's Guide
5.5.9
Commands
cp
Summary
Copies one or more source files or directories to a destination.
EFI Versions
EFI 1.02 and above.
Usage
CP [-r] [-q] src [src...] [dst]
-r
-q
prompt)
src
permitted)
dst
- Recursive copy
- Quiet copying (replace existing files without
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Description
This command copies one or more source files or directories to a destination. If the source is a
directory, the -r flag must be specified. If -r is specified, then the source directory will be
recursively copied to the destination (which means that all subdirectories will be copied). If a
destination is not specified, then the current working directory is assumed to be the destination.
If any target file (not directory) already exists, there will be a prompt asking the user to confirm
replacing the file. The following four choices are available:
• Yes: Replace the file.
• No: Do not replace the file.
• All: Replace the existing files in all subsequent cases.
• Cancel: Do not replace any existing files in all subsequent cases.
If there are multiple source files/directories, the destination must be a directory.
66
Commands
Examples
Shell> help cp
Copies one or more files/directories to another location.
CP [-r] [-q] src [src...] [dst]
-r
-q
prompt)
src
permitted)
dst
- Recursive copy
- Quiet copying (replace existing files without
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Note:
1. ‘-r’ must be specified if src is a directory. If '-r' is
specified,
then the source directory will be recursively copied to the
destination.
Src itself will be copied.
2. If 'dst' parameter is not specified, then the current
directory is assumed to
be the destination.
3. 'Cp -r src1 src2 dst' is to copy all files and subdirectories
in
'src1' and 'src2' to the 'dst.' 'Src1' and 'src2' themselves
are also
copied. 'dst' parameter will be interpreted as a directory.
4. Copying a directory/file to itself is not allowed.
5. If an error occurs, cp will exit immediately and the remaining
files or
directories will not be copied.
6. When 'cp' is executed with a script file, it always performs
quiet
copy regardless of whether the '-q' option is specified.
7. If are copying multiple files, the destination must be an
existing directory.
Examples:
* To display the contents of current directory first of all:
fs0:\> ls
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/13/01
06/13/01
1.0to7thRvw
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
10:00a
10:00a
July, 2005
512
512
512
28,739
32,838
efi
test1
test2
IsaBus.efi
IsaSerial.efi
67
EFI Shell User's Guide
06/18/01
06/18/01
08:04p
29
08:05p <DIR>
512
3 File(s)
61,606 bytes
4 Dir(s)
Commands
temp.txt
test
* To copy a file in the same directory but change the file
name:
fs0:\> cp temp.txt readme.txt
copying fs0:\temp.txt -> fs0:\readme.txt
- [ok]
* To copy multiple files to another directory:
fs0:\> cp temp.txt isaBus.efi \test
copying fs0:\temp.txt -> fs0:\test\temp.txt
- [ok]
copying fs0:\isaBus.efi -> fs0:\test\IsaBus.efi
- [ok]
* To copy multiple directories recursively to another
directory:
fs0:\> cp -r test1 test2 boot \test
copying fs0:\test1 -> fs0:\test\test1
copying fs0:\test1\test1.txt -> fs0:\test\test1\test1.txt
- [ok]
copying fs0:\test2 -> fs0:\test\test2
copying fs0:\test2\test2.txt -> fs0:\test\test2\test2.txt
- [ok]
copying fs0:\boot -> fs0:\test\boot
copying fs0:\boot\shell.efi -> fs0:\test\boot\shell.efi
- [ok]
* To see the results of the above operations:
fs0:\> ls \test
Directory of: fs0:\test
06/18/01
06/18/01
01/28/01
01/28/01
01/28/01
01/28/01
01/28/01
Shell>
68
01:01p <DIR>
512
01:01p <DIR>
0
08:21p <DIR>
512
08:21p <DIR>
512
08:21p <DIR>
512
08:23p
29
08:23p
28,739
2 File(s)
28,828 bytes
5 Dir(s)
.
..
test1
test2
boot
temp.txt
IsaBus.efi
Commands
5.5.10 date
Summary
Displays and sets the current date for the system.
EFI Versions
EFI 1.02 and above.
Usage
DATE [mm/dd/[yy]yy]
mm
dd
yyyy
- Month of date to be set, Month range: 1 – 12
- Day of date to be set, Day range: 1 – 31
- Year of date to be set, Year range: 1998 – 2099
Description
This command displays and/or sets the current date for the system. If no parameters are used, it
shows the current date. If a valid month, day, and year are provided, then the system's date will be
updated. Detailed rules are listed below:
1. Except for numeric characters and /, all other characters in the argument are invalid. The Shell
will report an error if the number is in the wrong month/date/year range.
2. Space before or after the numeric character is not allowed. Inserting a space into the number is
invalid.
3. Repeated zeros are allowed before the number. For example:
Shell > date 0000008/000004/000097
Shell > date
08/04/2097
Shell >
4. The year range is greater than or equal to 1998. Two numeric characters indicate the year.
Numbers below 98 are regarded as 20xx, and numbers equal to or above 98 are regarded as 19xx.
00 means 2000. For example:
Shell > date 8/4/97
Shell > date
08/04/2097
Shell >
Shell > date 8/4/98
Shell > date
08/04/1998
Shell >
5. The range of valid years is from 1998–2099.
1.0to7thRvw
July, 2005
69
EFI Shell User's Guide
Commands
Examples
Shell> help date
Displays the current date or sets the date in the system.
DATE [mm/dd/[yy]yy]
mm
dd
yyyy
- Month of date to be set, Month range: 1 - 12
- Day of date to be set, Day range: 1 - 31
- Year of date to be set, Year range: 1998 - 2099
Note:
1. yy: 98=1998, 99=1999, 00=2000, 01=2001, ..., 97=2097.
2. yyyy: 1998 - 2099, other values are invalid.
3. EFI may behave unpredictably if illegal date values are used.
Examples:
* To display the current date in the system:
fs0:\> date
06/18/2001
* To set the date with long year format:
fs0:\> date 01/01/2050
fs0:\> date
01/01/2050
* To set the date with short year format:
fs0:\> date 06/18/01
fs0:\> date
06/18/2001
Shell>
5.5.11 del
Summary
Deletes one or more files or directories.
EFI Versions
EFI 1.02 and above.
70
Commands
Usage
DEL [-q] file/directory [file/directory ...]
-q
confirmation
file
directory
- Quiet mode; does not prompt user for a
- File name (wildcards are permitted)
- Directory name (wildcards are permitted)
Description
This command deletes one or more files or directories. If the target is a directory, it will delete the
directory, including all its subdirectories. It is not allowed to redirect a file whose parent directory
(or the file itself) is being deleted.
1.0to7thRvw
July, 2005
71
EFI Shell User's Guide
Commands
Examples
Shell> help del
Deletes one or more files or directories.
DEL [-q] file/directory [file/directory ...]
-q
confirmation
file
directory
- Quite mode: does not prompt user for a
- File name (wildcards are permitted)
- Directory name (wildcards are permitted)
Note:
1. Removing a read-only file/directory will result in a failure.
Removing a
directory containing read-only file(s) will result failure.
2. If an error occurs, DEL will exit immediately and later
files/directories
will not be removed.
3. You cannot remove a directory when the current directory is
itself or its
subdirectory.
4. If file contains wildcards, it will not ask the user for
confirmation.
5. You cannot remove the root directory.
6. You cannot remove thecurrent directory or its ancestor.
7. Redirecting output to a file that exists under the directory
that will
be removed is not allowed.
Examples:
* To remove multiple directories at a time:
fs0:\> ls test
Directory of: fs0:\test
06/18/01
06/18/01
06/19/01
06/19/01
01:01p <DIR>
01:01p <DIR>
12:59a <DIR>
12:59a <DIR>
0 File(s)
4 Dir(s)
512
0
512
512
0 bytes
.
..
temp1
temp2
* Error occurs and DEL will exit:
fs0:\> del test\temp11 temp2
rm/del: Cannot find 'fs0:\test\temp11' - Not Found
* To remove multiple directories with wildcards:
fs0:\> del test\temp*
rm/del: Remove subtree 'fs0:\test\temp1' [y/n]? y
72
Commands
removing fs0:\test\temp1\temp1.txt
- [ok]
removing fs0:\test\temp1\boot\nshell.efi
- [ok]
removing fs0:\test\temp1\boot
- [ok]
removing fs0:\test\temp1
- [ok]
rm/del: Remove subtree 'fs0:\test\temp2' [y/n]? y
removing fs0:\test\temp2\temp2.txt
- [ok]
removing fs0:\test\temp2
- [ok]
* Removing a directory that contains a read-only file will
fail:
fs0:\> attrib +r test\temp1\readme.txt
A R fs0:\test\temp1\readme.txt
fs0:\> del test\temp1
rm/del: Cannot open 'readme.txt' under 'fs0:\test\temp1' in
writable
mode
- [error] - Access Denied
Exit status code: Access Denied
Shell>
5.5.12 dh
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Displays the device handles in the EFI environment.
EFI Versions
EFI 1.10 and above.
1.0to7thRvw
July, 2005
73
EFI Shell User's Guide
Commands
Usage
DH [-l <lang>] [handle | -p <prot_id>] [-d] [-v]
handle
taken as
-p
prot_id
-d
-l
-v
- Dumps information of a specified handle, always
hexadecimal number
- Dumps all handles of a protocol specified by
- Dumps EFI Driver Model related information
- Dumps information using the ISO 639-2 language
specified by lang.
- Dumps verbose information on specified handle
Description
This command displays the device handles in the EFI environment. If this command is used with a
specific handle number, the details of all the protocols that are associated with that device handle
are displayed. Otherwise, the -p option can be used to list the device handles that contain a specific
protocol. See Supported EFI Protocols in the Shell for the abbreviations that are used with this
command for EFI protocols. The following examples show how the command can be used.
74
Commands
Examples
Shell> help dh
Displays the handles in the EFI environment.
DH [-l <lang>] [handle | -p <prot_id>] [-d] [-v]
handle
always taken
-p
prot_id
-d
-l
-v
- Dumps information of a specified handle,
as hexadecimal number
- Dumps all handles of a protocol specified by
- Dumps EFI Driver Model related information
- Dumps information using the ISO 639-2 language
specified by lang.
- Dumps verbose information on specified handle
Note:
1. When neither 'handle' nor 'prot_id' is specified, a list of
all the
handles in the EFI environment is displayed.
2. Option '-d' can be used to display EFI Driver Model related
information, including its parent handles, child handles, all
drivers
on it, etc.
3. Option '-v' can be used to display verbose information on the
specified handle, including all the protocols on it and their
details.
4. If option '-p' is specified, all handles containing the
specified
protocol will be displayed. Otherwise, the 'handle' parameter
has to
be specified for display. In this case, option '-d' will be
enabled
automatically if option '-v' is not specified.
Examples:
* To display all handles and display one screen at a time:
Shell> dh -b
Handle dump
1: Image(DXE Foundation)
2: FwVol FwFileSys FwVolBlk DevPath(MemMap(11:1B500001D4FFC8))
3: Image(Ebc)
4: DevPath(MemMap(11:1CA0000-1CB0000))
5: Image(WinNtThunk)
6: WinNtThunk DevPath(..76F3-11D4-BCEA-0080C73C8881))
7: Image(WinNtBusDriver) DriverBinding
...
1.0to7thRvw
July, 2005
75
EFI Shell User's Guide
Commands
* To display the detailed information on handle 0x30:
Shell> dh 30
Handle 30 (01AF5308)
IsaIo
ROM Size......: 00000000
ROM Location..: 00000000
ISA Resource List :
IO : 000003F8-000003FF Attr : 00000000
INT : 00000004-00000000 Attr : 00000000
dpath
PNP Device Path for PnP
HID A0341D0, UID 0x0
Hardware Device Path for PCI
PNP Device Path for PnP
HID 50141D0, UID 0
AsStr: 'Acpi(PNP0A03,0)/Pci(1F|0)/Acpi(PNP0501,0)'
* To display all handles with 'diskio' protocol:
Shell> dh -p diskio
Handle dump by protocol 'Diskio'
15: DiskIo BlkIo DevPath(..i(3|1)/Ata(Secondary,Master))
16: DiskIo BlkIo DevPath(..,1)/PCI(0|0)/Scsi(Pun0,Lun0))
44: DiskIo BlkIo Fs DevPath(..ABD0-01C0-507B-9E5F8078F531))
ESP
45: DiskIo BlkIo Fs DevPath(..i(Pun0,Lun0)/HD(Part4,SigG0))
ESP
17: DiskIo BlkIo DevPath(..PCI(3|1)/Ata(Primary,Master))
* To display all handles with 'Image' protocol and break when
the screen is
full:
Shell> dh -p Image -b
Handle dump by protocol 'image'
1: Image(DXE Foundation)
5: Image(WinNtThunk)
7: Image(WinNtBusDriver) DriverBinding
8: Image(Metronome)
A: Image(IsaBus) DriverBinding
B: Image(WinNtConsole) DriverBinding
...
Shell>
76
Commands
5.5.13 dir
Summary
Lists directory contents or file information.
EFI Versions
EFI 1.02 and above.
Usage
DIR [-r] [-a[attrib]] [file]
-r
attrib
file
- Displays recursively (including subdirectories)
- 'a', 's', 'h', 'r', 'd' or combination of them
a
- Archive
s
- System
h
- Hidden
r
- Read-only
d
- Directory
- Name of file/directory (wildcards are permitted)
Description
This command lists directory contents or file information. If no file name or directory name is
specified, then the current directory is assumed. The contents of a directory are listed if all of the
following are true:
• If option -r is not specified
• If no wildcard characters are specified in the file parameter
• If file represents an existing directory
In all other cases, the command functions as follows:
• All files/directories that match the specified name are displayed.
• The -r flag determines whether a recursive search is performed.
• The option flag -a[attrib] tells the command to display only those files with the attributes
that are specified by [attrib]. If more than one attribute is specified, only the files that have
all those attributes will be listed. If -a is followed by nothing, then all files/directories are
displayed, regardless of their attributes. If -a itself is not specified, then all files except system
and hidden files are displayed.
1.0to7thRvw
July, 2005
77
EFI Shell User's Guide
Commands
Examples
Shell> help dir
Displays a list of files and subdirectories in a directory.
DIR [-r] [-a[attrib]] [file]
-r
attrib
file
- Displays recursively (including subdirectories)
- 'a', 's', 'h', 'r', 'd' or combination of them
a
- Archive
s
- System
h
- Hidden
r
- Read-only
d
- Directory
- Name of file/directory (wildcards are permitted)
Examples:
* To hide files by adding the hidden or system attribute to
them:
fs0:\> attrib +s +h *.efi
ASH fs0:\IsaBus.efi
ASH fs0:\IsaSerial.efi
* To display all, except the files/directories with 'h' or 's'
attribute:
fs0:\> dir
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
01/28/01
09:32p
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
08:04p
08:05p <DIR>
08:24p
r
3 File(s)
4 Dir(s)
153
512
512
512
29
512
29
211 bytes
for.nsh
efi
test1
test2
temp.txt
test
readme.txt
* To display files with all attributes in the current
directory:
fs0:\> dir -a
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
78
09:32p
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
10:59p
10:59p
153
512
512
512
28,739
32,838
for.nsh
efi
test1
test2
IsaBus.efi
IsaSerial.efi
Commands
06/18/01
06/18/01
01/28/01
08:04p
29
08:05p <DIR>
512
08:24p
r
29
5 File(s)
61,788 bytes
4 Dir(s)
temp.txt
test
readme.txt
* To display files with read-only attributes in the current
directory:
fs0:\> dir -ar
Directory of: fs0:\
06/18/01
11:14p
1 File(s)
0 Dir(s)
r
29
readme.txt
29 bytes
* To display the files with attribute of 's':
fs0:\> dir -as isabus.efi
Directory of: fs0:\
06/18/01
10:59p
1 File(s)
0 Dir(s)
28,739
28,739 bytes
IsaBus.efi
* To display all in fs0:\efi directory recursively:
fs0:\> dir -r -a efi
* To search for files with the specified type in the current
directory recursively:
fs0:\> dir -r -a *.efi -b
Shell>
5.5.14 disconnect
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Disconnects one or more drivers from the specified devices.
EFI Versions
EFI 1.10 and above.
1.0to7thRvw
July, 2005
79
EFI Shell User's Guide
Commands
Usage
DISCONNECT DeviceHandle [DriverHandle [ChildHandle]]
DISCONNECT -r
DeviceHandle
number
DriverHandle
number
ChildHandle
-r
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
- Child handle of a device, always taken as
hexadecimal number
- Disconnect drivers from all devices
Description
This command disconnects one or more drivers from the specified devices. If the -r option is used,
all drivers are disconnected from all devices in the system. The following example is the typical
output from the help for this command.
80
Commands
Examples
Shell> help disconnect
Disconnects one or more drivers from a device.
DISCONNECT DeviceHandle [DriverHandle [ChildHandle]]
DISCONNECT -r
DeviceHandle
number
DriverHandle
number
ChildHandle
-r
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
- Child handle of a device, always taken as
hexadecimal number
- Disconnect drivers from all devices
Notes:
1. If option '-r' is used, all drivers will be disconnected from
all
devices in the system. In this case, no other parameters are
allowed
to be used together.
2. If no 'ChildHandle' parameter is specified, the default is to
disconnect all child handles of the 'DeviceHandle.
3. If no 'DriverHandle' parameter is specified, the default is to
disconnect all driver handles on the 'DeviceHandle.'
4. This command does not support output redirection.
Examples:
* To disconnect all drivers from all devices:
Shell> disconnect -r
* To disconnect all drivers from device 0x28:
fs0:\> disconnect 28
* To disconnect driver 0x17 from device 0x28:
fs0:\> disconnect 28 17
* To disconnect driver 0x17 from controlling the child 0x32 of
device 0x28
fs0:\> disconnect 28 17 32
Shell>
1.0to7thRvw
July, 2005
81
EFI Shell User's Guide
Commands
5.5.15 drivers
Summary
Displays a list of information for drivers that follow the EFI Driver Model in the EFI environment.
EFI Versions
EFI 1.10 and above.
Usage
DRIVERS [-l XXX]
-l
language
- Displays drivers using the ISO 639-2
specified by XXX
Description
This command displays a list of information for drivers that follow the EFI Driver Model in EFI
environment. The list has the following columns:
• DRV: The handle number of the EFI driver.
• VERSION: The version number of the EFI driver.
• TYPE: The driver type. A B in this column indicates a bus driver, and D indicates a device driver.
• CFG: Indicates that the driver supports the Driver Configuration Protocol.
• DIAG: Indicates that the driver supports the Driver Diagnostics Protocol.
• #D: The number of devices that this driver is managing.
• #C: The number of child devices that this driver has produced.
• DRIVER NAME: The name of the driver from the Component Name Protocol.
• IMAGE NAME: The file path from which the driver was loaded.
82
Commands
Examples
Shell> help drivers
Displays the list of drivers that follow the EFI Driver Model
DRIVERS [-l XXX]
-l
language
- Displays drivers using the ISO 639-2
specified by XXX
Display Format:
DRV - The handle number of the EFI driver
TYPE - The driver type
[B] Bus driver
[D] Device driver
CFG - The driver supports the Driver Configuration Protocol
DIAG - The driver supports the Driver Diagnostics Protocol
#D - The number of devices that this driver is managing
#C - The number of child devices that this driver has produced
DRIVER NAME - The name of the driver from the Component Name
Protocol
IMAGE NAME - The file path from which the driver was loaded
Examples:
* To display the list:
Shell> drivers
T
D
D
Y C I
R
P F A
V VERSION E G G #D #C DRIVER NAME
IMAGE
NAME
=== ======== = = = == == ===================================
===================
39 00000010 D - - 1 - Platform Console Management Driver
ConPlatform
3A 00000010 D - - 1 - Platform Console Management Driver
ConPlatform
3B 00000010 B - - 1 1 Console Splitter Driver
ConSplitter
3C 00000010 ? - - - - Console Splitter Driver
ConSplitter
3D 00000010 B - - 1 1 Console Splitter Driver
ConSplitter
3E 00000010 ? - - - - Console Splitter Driver
ConSplitter
42 00000010 D - - 1 - UGA Console Driver
GraphicsConsole
1.0to7thRvw
July, 2005
83
EFI Shell User's Guide
43 00000010 ? - - Terminal
44 00000010 D - - 1
DiskIo
45 00000010 D - - 1
48 00000010 ? - - -
Commands
- Serial Terminal Driver
- Generic Disk I/O Driver
- FAT File System Driver
- ISA Bus Driver
IsaBus
49 00000010 ? - - - - ISA Serial Driver
IsaSerial
4C 00000010 B - - 1 1 PCI Bus Driver
PciBus
55 00000010 D X X 1 - Windows Block I/O Driver
WinNtBlockIo
56 00000010 ? - - - - Windows Text Console Driver
WinNtConsole
57 00000010 ? - - - - Windows Serial I/O Driver
WinNtSerialIo
58 00000010 D - - 1 - Windows Simple File System Driver
WinNtSimpleFileSystem
59 00000010 B - - 1 3 Windows Bus Driver
WinNtBusDriver
5F 00000010 D - - 1 - Windows Universal Graphics Adapter
WinNtUga
Shell>
5.5.16 drvcfg
Summary
Invokes the Driver Configuration Protocol.
EFI Versions
EFI 1.10 and above.
84
Fat
Commands
Usage
DRVCFG [-l XXX] [-c] [-f <Type>|-v|-s] [DriverHandle
[DeviceHandle [ChildHandle]]]
-c
- Configure all child devices
-l
- Configure using the ISO 639-2 language
specified by XXX
-f
- Force defaults
-v
- Validate options
-s
- Set options
Type
- The type of default configuration options to
force on
the controller.
0 - Safe Defaults.
1 - Manufacturing Defaults.
2 - Custom Defaults.
3 - Performance Defaults.
DriverHandle - The handle of the driver to configure
DeviceHandle - The handle of a device that DriverHandle is
managing
ChildHandle - The handle of a device that is a child of
DeviceHandle
Description
This command invokes the Driver Configuration Protocol. The table below describes the values for
the Type parameter. Other values depend on the driver’s implementation.
Table 5-5 Default Values for the Type Parameter
Value
Type of Default
Description
0x0000
Safe Defaults
Places a controller in a safe configuration that has the greatest
probability of functioning correctly in a platform.
0x0001
Manufacturing Defaults
Optional type that places the controller in a configuration that is
suitable for a manufacturing and test environment.
0x0002
Custom Defaults
Optional type that places the controller in a custom
configuration.
0x0003
Performance Defaults
Optional type that places the controller in a configuration that
maximizes the controller’s performance in a platform.
1.0to7thRvw
July, 2005
85
EFI Shell User's Guide
Commands
Examples
Shell> help drvcfg
Invokes the Driver Configuration Protocol
DRVCFG [-l XXX] [-c] [-f <Type>|-v|-s] [DriverHandle
[DeviceHandle [ChildHandle]]]
-c
- Configure all child devices
-l
- Configure using the ISO 639-2 language
specified by XXX
-f
- Force defaults
-v
- Validate options
-s
- Set options
Type
- The type of default configuration options to
force on
the controller.
0 - Safe Defaults.
1 - Manufacturing Defaults.
2 - Custom Defaults.
3 - Performance Defaults.
DriverHandle - The handle of the driver to configure
DeviceHandle - The handle of a device that DriverHandle is
managing
ChildHandle - The handle of a device that is a child of
DeviceHandle
Notes:
1. Default Type.
0 - Safe Defaults. It places a controller in a safe
configuration
that has the greatest probability of functioning
correctly in a
platform.
1 - Manufacturing Defaults. Optional type that places the
controller
in a configuration suitable for a manufacturing and test
environment.
2 - Custom Defaults. Optional type that places the
controller in a
custom configuration.
3 - Performance Defaults. Optional type that places the
controller in
a configuration that maximizes the controller's
performance in a
platform.
Other values depend on the driver's implementation.
Examples:
86
Commands
* To display the list of devices that are available for
configuration:
Shell> drvcfg
* To display the list of devices and child devices that are
available
for configuration:
Shell> drvcfg –c
* To force defaults on all devices:
Shell> drvcfg –f 0
* To force defaults on all devices that are managed by driver
0x17:
Shell> drvcfg –f 0 17
* To force defaults on device 0x28 that is managed by driver
0x17:
Shell> drvcfg –f 0 17 28
* To force defaults on all child devices of device 0x28 that is
managed
by driver 0x17:
Shell> drvcfg –f 0 17 28 –c
* To force defaults on child device 0x30 of device 0x28 that is
managed
by driver 0x17:
Shell> drvcfg –f 0 17 28 30
* To validate options on all devices:
Shell> drvcfg –v
* To validate options on all devices that are managed by driver
0x17:
Shell> drvcfg –v 17
* To validate options on device 0x28 that is managed by driver
0x17:
Shell> drvcfg –v 17 28
* To validate options on all child devices of device 0x28 that
is
managed by driver 0x17:
Shell> drvcfg –v 17 28 –c
* To validate options on child device 0x30 of device 0x28 that
is
managed by driver 0x17:
1.0to7thRvw
July, 2005
87
EFI Shell User's Guide
Commands
Shell> drvcfg –v 17 28 30
* To set options on device 0x28 that is managed by driver 0x17:
Shell> drvcfg –s 17 28
* To set options on child device 0x30 of device 0x28 that is
managed by
driver 0x17:
Shell> drvcfg –s 17 28 30
* To set options on device 0x28 that is managed by driver 0x17
in
English:
Shell> drvcfg –s 17 28 –l eng
* To set options on device 0x28 that is managed by driver 0x17
in
Spanish:
Shell> drvcfg –s 17 28 –l spa
Shell>
5.5.17 drvdiag
Summary
Invokes the Driver Diagnostics Protocol.
EFI Versions
EFI 1.10 and above.
88
Commands
Usage
DRVDIAG [-c] [-l XXX] [-s|-e|-m] [DriverHandle [DeviceHandle
[ChildHandle]]]
-c
-l
specified by XXX
-s
-e
-m
DriverHandle
DeviceHandle
managing
ChildHandle
DeviceHandle
- Diagnose all child devices
- Diagnose using the ISO 639-2 language
-
Run
Run
Run
The
The
diagnostics in standard mode
diagnostics in extended mode
diagnostics in manufacturing mode
handle of the driver to diagnose
handle of a device that DriverHandle is
- The handle of a device that is a child of
Description
This command invokes the Driver Diagnostics Protocol.
1.0to7thRvw
July, 2005
89
EFI Shell User's Guide
Commands
Examples
Shell> help drvdiag
Invokes the Driver Diagnostics Protocol
DRVDIAG [-c] [-l XXX] [-s|-e|-m] [DriverHandle [DeviceHandle
[ChildHandle]]]
-c
-l
specified by XXX
-s
-e
-m
DriverHandle
DeviceHandle
managing
ChildHandle
DeviceHandle
- Diagnose all child devices
- Diagnose using the ISO 639-2 language
-
Run
Run
Run
The
The
diagnostics in standard mode
diagnostics in extended mode
diagnostics in manufacturing mode
handle of the driver to diagnose
handle of a device that DriverHandle is
- The handle of a device that is a child of
Examples:
* To display the list of devices that are available for
diagnostics:
Shell> drvdiag
* To display the list of devices and child devices that are
available
for diagnostics:
Shell> drvdiag –c
* To run diagnostics in standard mode on all devices:
Shell> drvdiag –s
* To run diagnostics in standard mode on all devices in
English:
Shell> drvdiag –s –l eng
* To run diagnostics in standard mode on all devices in
Spanish:
Shell> drvdiag –s –l spa
* To run diagnostics in standard mode on all devices and child
devices:
Shell> drvdiag –s –c
* To run diagnostics in extended mode on all devices:
Shell> drvdiag –e
* To run diagnostics in manufacturing mode on all devices:
90
Commands
Shell> drvdiag –m
* To run diagnostics in standard mode on all devices managed by
driver 0x17:
Shell> drvdiag –s 17
* To run diagnostics in standard mode on device 0x28 managed by
driver 0x17:
Shell> drvdiag –s 17 28
* To run diagnostics in standard mode on all child devices of
device 0x28
managed by driver 0x17:
Shell> drvdiag –s 17 28 –c
* To run diagnostics in standard mode on child device 0x30 of
device 0x28
managed by driver 0x17:
Shell> drvdiag –s 17 28 30
Shell>
5.5.18 echo
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Controls whether or not batch commands are displayed as they are read from the batch file and
prints the given message to the display.
EFI Versions
EFI 1.02 and above.
1.0to7thRvw
July, 2005
91
EFI Shell User's Guide
Commands
Usage
ECHO [-on|-off]
ECHO [message]
-on
files
-off
lines
message
- Displays when reading command lines from batch
- Does not display when reading batch command
- Displays a message string
Description
The first form of this command controls whether or not batch commands are displayed as they are
read from the batch file. If no argument is given, the current "on" or "off" status is displayed. The
second form prints the given message to the display.
92
Commands
Examples
Shell> help echo
Displays a message, or turns command echoing on or off in batch
files.
ECHO [-on|-off]
ECHO [message]
-on
files
-off
lines
message
- Displays when reading command lines from batch
- Does not display when reading batch command
- Displays a message string
Note:
1. Echo -off means to not display the command line when reading
from batch
files. This command is not like the MS-DOS echo.
2. Echo without a parameter shows current echo setting.
Examples:
* To display a message string of 'Hello World':
fs0:\> echo Hello World
Hello World
* To turn command echoing on:
fs0:\> echo -on
* To execute HelloWorld.nsh, and display when reading lines
from the batch file:
fs0:\> HelloWorld.nsh
+HelloWorld.nsh> echo Hello World
Hello World
* To turn command echoing off:
fs0:\> echo -off
* To display the current echo setting:
fs0:\> echo
Echo is off
Shell>
1.0to7thRvw
July, 2005
93
EFI Shell User's Guide
Commands
5.5.19 exit
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Exits the EFI Shell environment and returns control to the parent that launched the EFI Shell.
EFI Versions
EFI 1.02 and above.
Usage
EXIT
Description
This command exits the EFI Shell environment and returns control to the parent that launched the
EFI Shell.
Examples
Shell> help exit
Exits the EFI Shell environment and returns control to its
parent.
EXIT
Examples:
Shell> exit
5.5.20 help
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Displays the list of commands that are built into the EFI Shell.
EFI Versions
EFI 1.02 and above.
94
Commands
Usage
HELP [cmd | pattern]
cmd
- Shell command
pattern – Wildmatch pattern
Description
The help command displays the list of commands that are built into the EFI Shell. It also supports
displaying the verbose help information for a specified command.
You can also use cmd -? to display the verbose help of a command, where cmd is the name of the
EFI Shell command or application. This syntax does the same thing as help cmd and can be used
for both internal and external Shell commands. The form of help cmd, however, can be used
only for internal Shell commands.
The following example shows the output from this command.
1.0to7thRvw
July, 2005
95
EFI Shell User's Guide
Commands
Examples
Shell> help help
Displays the list of commands or verbose help of a command in the
EFI Shell.
HELP [cmd | pattern]
cmd
- Shell command
pattern – Wildmatch pattern
Note:
1. 'cmd -?' also displays the verbose help of cmd, the same as
'help cmd'.
2. If cmd has no verbose help, its line help will be displayed
instead.
3. HELP will only show commands that were documented in the
Shell.
Examples:
* To display the list of commands in the EFI Shell and break
after one screen:
Shell> help –b
?
- Displays commands list or verbose help of a
command
alias
- Displays, creates, or deletes aliases in the
EFI shell
attrib
- Displays or changes the attributes of files
or
directories
cd
- Displays or changes the current directory
cls
- Clears the standard output with an optional
background
color
connect
- Binds an EFI driver to a device and starts
the driver
copy
- Copies one or more files/directories to
another
location
...
* To display help information of a Shell command - ls:
Shell> help ls
Shell> ? ls
Shell> ls -?
96
Commands
* To display the list of commands that start with character
‘p’:
Shell> help p*
pause – Prints a message and suspends for keyboard input
5.5.21 load
Summary
Loads an EFI driver into memory.
EFI Versions
EFI 1.10 and above.
Usage
LOAD [-nc] file [file...]
-nc
file
(wildcards
- Load the driver, but do not connect the driver.
- File that contains the image of the EFI driver
are permitted)
Description
This command loads an EFI driver into memory. It can load multiple files at one time, and the file
name supports the asterisk wildcard. If the -nc flag is not specified, this command will try to
connect the driver to a proper device; meanwhile it may cause loaded drivers be connected to their
corresponding devices. This action is not a bug but the implementation policy.
1.0to7thRvw
July, 2005
97
EFI Shell User's Guide
Commands
Examples
Shell> help load
Loads EFI drivers and then they can provide available services.
LOAD [-nc] file [file...]
-nc
file
(wildcards
- Load the driver, but do not connect the driver.
- File that contains the image of the EFI driver
are permitted)
Note:
1. LOAD can deal with multiple files and supports wildcards.
2. Use 'UNLOAD' command to unload a driver if it supports
unloading.
3. If option –nc is not specified, then the loaded drivers will
be
automatically connected. If –nc is specified, then none of the
loaded
drivers will be connected. Loading without –nc could cause the
previously loaded drivers to be connected. This is not a bug,
and it
complies with EFI specification.
Examples:
fs0:\> load Isabus.efi
load: Image 'fs0:\Isabus.efi' loaded at 18FE000 - Success
fs0:\> load Isabus.efi IsaSerial.efi
load: Image 'fs0:\Isabus.efi' loaded at 18E5000 - Success
load: Image 'fs0:\IsaSerial.efi' loaded at 18DC000 - Success
fs0:\> load Isa*.efi
load: Image 'fs0:\IsaBus.efi' loaded at 18D4000 - Success
load: Image 'fs0:\IsaSerial.efi' loaded at 18CB000 – Success
fs0:\> load –nc IsaBus.efi
load: Image ‘fs0:\Isabus.efi’ loaded at 18FE000 - Success
Shell>
5.5.22 ls
Summary
Lists a directory's contents or file information.
98
Commands
EFI Versions
EFI 1.02 and above.
Usage
LS [-r] [-a[attrib]] [file]
-r
attrib
file
- Displays recursively (including subdirectories)
- 'a', 's', 'h', 'r', 'd' or combination of them
a
- Archive
s
- System
h
- Hidden
r
- Read-only
d
- Directory
- Name of file/directory (wildcards are permitted)
Description
This command lists directory contents or file information. If no file name or directory name is
specified, then the current directory is assumed. The contents of a directory are listed if all of the
following are true:
• If option -r is not specified
• If no wildcard characters are specified in the file parameter
• If file represents an existing directory
In all other cases, the command functions as follows:
• All files/directories that match the specified name are displayed.
• The -r flag determines whether a recursive search is performed.
• The option flag -a[attrib] tells the command to display only those files with the attributes
that are specified by [attrib]. If more than one attribute is specified, only the files that have
all those attributes will be listed. If -a is followed by nothing, then all files/directories are
displayed, regardless of their attributes. If -a itself is not specified, then all files except system
and hidden files are displayed.
1.0to7thRvw
July, 2005
99
EFI Shell User's Guide
Commands
Examples
Shell> help ls
Displays a list of files and subdirectories in a directory.
LS [-r] [-a[attrib]] [file]
-r
attrib
file
- Displays recursively (including subdirectories)
- 'a', 's', 'h', 'r', 'd' or combination of them
a
- Archive
s
- System
h
- Hidden
r
- Read-only
d
- Directory
- Name of file/directory (wildcards are permitted)
Examples:
* To hide files by adding the hidden or system attribute to
them:
fs0:\> attrib +s +h *.efi
ASH fs0:\IsaBus.efi
ASH fs0:\IsaSerial.efi
* To display all, except the files/directories with 'h' or 's'
attribute:
fs0:\> ls
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
01/28/01
09:32p
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
08:04p
08:05p <DIR>
08:24p
r
3 File(s)
4 Dir(s)
153
512
512
512
29
512
29
211 bytes
for.nsh
efi
test1
test2
temp.txt
test
readme.txt
* To display files with all attributes in the current
directory:
fs0:\> ls -a
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
100
09:32p
01:02p <DIR>
01:02p <DIR>
01:02p <DIR>
10:59p
10:59p
153
512
512
512
28,739
32,838
for.nsh
efi
test1
test2
IsaBus.efi
IsaSerial.efi
Commands
06/18/01
06/18/01
01/28/01
08:04p
29
08:05p <DIR>
512
08:24p
r
29
5 File(s)
61,788 bytes
4 Dir(s)
temp.txt
test
readme.txt
* To display files with read-only attributes in the current
directory:
fs0:\> ls -ar
Directory of: fs0:\
06/18/01
11:14p
1 File(s)
0 Dir(s)
r
29
readme.txt
29 bytes
* To display the files with attribute of 's':
fs0:\> ls -as isabus.efi
Directory of: fs0:\
06/18/01
10:59p
1 File(s)
0 Dir(s)
28,739
28,739 bytes
IsaBus.efi
* To display all in fs0:\efi directory recursively:
fs0:\> ls -r -a efi
* To search for files with the specified type in the current
directory recursively:
fs0:\> ls -r -a *.efi -b
Shell>
5.5.23 map
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Defines a mapping between a user-defined name and a device handle.
EFI Versions
EFI 1.02 and above.
1.0to7thRvw
July, 2005
101
EFI Shell User's Guide
Commands
Usage
MAP [-d <sname>]
MAP [[-r][-v][-c][-f][-t <type[,type…]>][sname]]
MAP [sname handle | mapname]
-d
-r
-v
sname
handle
-
Deletes a mapping
Resets to default mappings
Lists verbose information of mappings
Defines a name for the mapping by users
The number of handle, which is same as dumped from
'dh'
-c
-f
mapping).
-t
type.
command
- Shows the consistent mapping name.
- Shows the normal mapping name (not consistent
- Shows the device mapping name according the device
type
- The device type. The current supported
types are:
fp (Floppy)
hd (Hard Disk)
cd (CD Rom)
Types can be combined by putting a comma between
two
types. Spaces are not allowed between types.
mapname – The device’s mapped name. Use this parameter to
assign a new
mapping name to a device. There is a postfix ':'
after the
mapname.
Description
This command is used to define a mapping between a user-defined name and a device handle. The
most common use of this command is to assign drive letters to device handles that support a file
system protocol. Once these mappings are created, the drive letters can be used with all the file
manipulation commands.
The EFI Shell environment creates default mappings for all the device handles that support a
recognized file system.
This command can be used to create additional mappings, or it can be used to delete an existing
mapping with the -d option. If the map command is used without any parameters, all the current
mappings will be listed. If the -v option is used, the mappings will be shown with additional
information about each mapped handle. The -r option is used to regenerate all the default
mappings in a system; this option is useful if the system configuration has changed since the last
boot.
102
Commands
Each device in the system has a consistent mapping name. If the hardware configuration has not
changed, the device’s consistent mapping names do not change. If two or more machines have the
same hardware configurations, the device’s consistent mapping will be the same. Use the -c option
to list all the consistent mapping names in the system.
The mapping name consists of digits and characters. Other characters are illegal.
This command support wildcards. You can use the wildcards to delete or show the mapping name.
However, when you assign the mapping name, wildcards are forbidden.
1.0to7thRvw
July, 2005
103
EFI Shell User's Guide
Commands
Examples
Shell> help map
Displays or defines mappings between user-defined names and
device handles.
MAP [-d <sname>]
MAP [[-r][-v][-c][-f][-t <type[,type…]>][sname]]
MAP [sname handle | mapname]
-d
-r
-v
sname
handle
-
Deletes a mapping
Resets to default mappings
Lists verbose information of mappings
Defines a name for the mapping by users
The number of handle, which is same as dumped from
'dh'
-c
-f
mapping).
-t
type.
command
- Shows the consistent mapping name.
- Shows the normal mapping name (not consistent
- Shows the device mapping name according the device
type
- The device type. The current supported
types are:
fp (Floppy)
hd (Hard Disk)
cd (CD Rom)
Types can be combined by putting a comma between
two
types. Spaces are not allowed between types.
mapname – The device’s mapped name. Use this parameter to
assign a new
mapping name to a device. There is a postfix ':'
after the
mapname.
Note:
1. Consistent mapping is persistent across
and a
system reboot.
2. Only characters and numbers are allowed
3. Redirection is not allowed when running
know the file
system before mapping is done.
4. Output redirection is not supported for
104
the 'map -r' command
inside of sname.
map because we do not
'map –r' usage.
Commands
Examples:
* To reset the mapping table to the default mappings:
shell> map -r
Device mapping table
f4
:UnknownDevice - Alias fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
fs0
:UnknownDevice - Alias f4 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
blk0 :UnknownDevice - Alias f4 fs0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
1.0to7thRvw
July, 2005
105
EFI Shell User's Guide
Commands
* To display all mappings in the device mapping table:
Shell> map
Device mapping table
f4
:UnknownDevice - Alias fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
fs0
:UnknownDevice - Alias f4 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
blk0 :UnknownDevice - Alias f4 fs0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
* To display mapping table verbosely:
Shell> map -v
Device mapping table
f4
Consist Name f4
Other Name
fs0 blk0
Handle
5F: Fs DiskIo BlkIo WinNtDriverIo
Media Type
UnknownDevice
Removeable
NO
Current Dir \
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA0080C73C8881)
fs0
Consist Name f4
Other Name
blk0
Handle
5F: Fs DiskIo BlkIo WinNtDriverIo
Media Type
UnknownDevice
Removeable
NO
Current Dir \
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA0080C73C8881)
blk0
Consist Name f4
Other Name
fs0
Handle
5F: Fs DiskIo BlkIo WinNtDriverIo
Media Type
UnknownDevice
Removeable
NO
Current Dir \
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
106
Commands
/VenHw(0C95A92F-A006-11D4-BCFA0080C73C8881)
* To assign fs0 another name:
Shell> map floppy fs0:
floppy:UnknownDevice - Alias f4 fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA-0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA0080C73C8881)
* To display the information of the mapped name:
Shell> map floppy
floppy:UnknownDevice - Alias f4 fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA-0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA0080C73C8881)
* To operate with the mapped name:
Shell> floppy:
floppy:\> ls
* To delete a mapped name:
Shell> map -d floppy
Shell> map
Device mapping table
f4
:UnknownDevice - Alias fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
fs0
:UnknownDevice - Alias f4 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
blk0 :UnknownDevice - Alias f4 fs0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
* To display all the mapped names that start with 'f':
Shell> map f*
Device mapping table:
f4
:UnknownDevice - Alias fs0 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
fs0
:UnknownDevice - Alias f4 blk0
Device Path VenHw(58C518B1-76F3-11D4-BCEA0080C73C8881)
/VenHw(0C95A92F-A006-11D4-BCFA-0080C73C8881)
1.0to7thRvw
July, 2005
107
EFI Shell User's Guide
Commands
5.5.24 mkdir
Summary
Creates one or more new directories.
EFI Versions
EFI 1.02 and above.
Usage
MKDIR dir [dir...]
dir
- Name of a directory to be created (wildcards are
not
allowed).
Description
This command creates one or more new directories.
Examples
108
Commands
Shell> help mkdir
Creates one or more directories.
MKDIR dir [dir...]
dir
allowed)
- Name of a directory to be created(wildcards are not
Note:
1. The parent directory must already exist.
2. If the directory already exists, it will fail to make such a
directory.
3. The directories in the command line should not rely on the
creation of
other directories in the command line. For example, 'mkdir new
new\test'
is not allowed.
4. Redirecting output to a file that exists under the directory
specified
on the command line is not allowed.
Examples:
* To create a new directory:
fs0:\> mkdir rafter
fs0:\> ls
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
08:05p <DIR>
11:14p
r
11:50p <DIR>
1 File(s)
2 Dir(s)
512
29
512
211 bytes
test
readme.txt
rafter
* To create multiple directories:
fs0:\> mkdir temp1 temp2
fs0:\> ls
Directory of: fs0:\
06/18/01
06/18/01
06/18/01
06/18/01
06/18/01
08:05p <DIR>
11:14p
r
11:50p <DIR>
11:52p <DIR>
11:52p <DIR>
1 File(s)
4 Dir(s)
512
29
512
512
512
211 bytes
test
readme.txt
rafter
temp1
temp2
Shell>
1.0to7thRvw
July, 2005
109
EFI Shell User's Guide
Commands
5.5.25 mv
Summary
Moves one or more files to a destination within a file system.
EFI Versions
EFI 1.02 and above.
Usage
MV src [src...] [dst]
src
permitted)
dst
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Description
This command moves one or more files to a destination within a file system. Moving between file
system volumes is not supported. If the destination is an existing directory, then the sources are
moved into that directory. Otherwise, the sources are moved to the destination, as if the directory
has been renamed. If a destination is not specified, the current directory is assumed to be the
destination.
110
Commands
Examples
Shell> help mv
Moves one or more files/directories to destination within fs.
MV src [src...] [dst]
src
permitted)
dst
- Source file/directory name (wildcards are
- Destination file/directory name (wildcards are not
permitted)
Note:
1. If 'dst' is not specified, then the current directory is
assumed to be the
'dst'.
2. If there is more than one argument in the command line, the
last one
will be taken as 'dst' unconditionally. If there is more than
one
source file/directory to move, the 'dst' should be an existing
directory.
3. Attempting to move a read-only file/directory will result a
failure.
4. Moving a directory containing read-only file(s) is allowed.
5. You cannot move a directory into itself or its subdirectories.
6. You cannot move a directory if current directory is itself or
its
subdirectory.
7. Redirecting output to a file that exists under the directory
that will
be moved is not allowed.
8. If an error occurs, the remaining files or directories will
still be
moved.
Examples:
* To rename a file:
fs0:\> mv IsaBus.efi Bus.efi
moving fs0:\IsaBus.efi -> \Bus.efi
- [ok]
* To move a directory to the current directory:
fs0:\> mkdir test1\temp
fs0:\> mv test1\temp
moving fs0:\test1\temp -> \.\temp
- [ok]
* To rename a directory:
1.0to7thRvw
July, 2005
111
EFI Shell User's Guide
Commands
fs0:\> mv efi efi1.1
moving fs0:\efi -> \efi1.1
- [ok]
* To move multiple directories at a time:
fs0:\> mv test1 test2 test
moving fs0:\test1 -> \test\test1
- [ok]
moving fs0:\test2 -> \test\test2
- [ok]
* Moving a read-only directory will result a failure:
fs0:\test> attrib +r temp1
DA R fs0:\test\temp1
fs0:\test> mv temp1 temp2
moving fs0:\test\temp1 -> \test\temp2
- error - Invalid Parameter
Shell>
5.5.26 reconnect
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Reconnects drivers to the specific device.
EFI Versions
EFI 1.10 and above.
112
Commands
Usage
RECONNECT DeviceHandle [DriverHandle [ChildHandle]]
RECONNECT -r
DeviceHandle
number
DriverHandle
number
ChildHandle
hexadecimal
-r
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
- Child handle of device, always taken as
number
- Reconnect drivers to all devices
Description
This command reconnects drivers to the specific device. It will first disconnect the specified driver
from the specified device and then connect the driver to the device recursively.
If the -r option is used, then all drivers will be reconnected to all devices. See the connect and
disconnect commands for more details. The example below is the typical output from the help
for this command.
1.0to7thRvw
July, 2005
113
EFI Shell User's Guide
Commands
Examples
Shell> Help Reconnect
Reconnects one or more drivers from a device.
RECONNECT DeviceHandle [DriverHandle [ChildHandle]]
RECONNECT -r
DeviceHandle
number
DriverHandle
number
ChildHandle
hexadecimal
-r
- Device handle, always taken as hexadecimal
- Driver handle, always taken as hexadecimal
- Child handle of device, always taken as
number
- Reconnect drivers to all devices
Note:
1. This command disconnects the drivers from the controller, just
like
'DISCONNECT', but it then immediately reconnects them
recursively.
2. If option '-r' is specified, any drivers that are binding to
any devices will be
disconnected first and then connected recursively.
3. If no 'ChildHandle' parameter is specified, all child handles
of the
specified device will be the default.
4. If no 'DriverHandle' parameter is specified, all drivers on
the
specified device will be the default.
5. This command is a great way to test if drivers are following
the
EFI 1.10 Driver Model.
6. This command does not support output redirection.
Examples:
* To reconnect all drivers to all devices:
Shell> reconnect -r
* To reconnect all drivers to device 0x28:
fs0:\> reconnect 28
* To reconnect driver 0x17 to device 0x28:
fs0:\> reconnect 28 17
* To reconnect driver 0x17 to child 0x32 of device 0x28:
fs0:\> reconnect 28 17 32
114
Commands
Shell>
5.5.27 reset
Summary
Resets the system.
EFI Versions
EFI 1.02 and above.
Usage
RESET [-w [string]]
RESET [-s [string]]
-w
-s
string
- Performs a warm reset
- Performs a shutdown
- String to be passed to reset service
Description
This command resets the system. The default is to perform a cold reset unless the -w parameter is
specified. If the reset string is specified, then it is passed into the Reset() function, so the
system can know the reason for the system reset.
1.0to7thRvw
July, 2005
115
EFI Shell User's Guide
Commands
Examples
Shell> help reset
Resets the system.
RESET [-w [string]]
RESET [-s [string]]
-w
-s
string
- Performs a warm reset
- Performs a shutdown
- String to be passed to reset service
Note:
1. Not all systems implement '-w' flag. This may mean different
things
depending on which BIOS EFI is implemented.
2. Reset will be guaranteed to reset the chipset as well as the
processor
when cold reset is called.
3. This command does not support output redirection.
Shell>
5.5.28 rm
Summary
Deletes one or more files or directories.
EFI Versions
EFI 1.02 and above.
Usage
RM [-q] file/directory [file/directory ...]
-q
confirmation
file
directory
- Quiet mode; does not prompt user for a
- File name (wildcards are permitted)
- Directory name (wildcards are permitted)
Description
This command deletes one or more files or directories. If the target is a directory, it will delete the
directory, including all its subdirectories. It is not allowed to redirect a file whose parent directory
(or the file itself) is being deleted.
116
Commands
Examples
Shell> help rm
Deletes one or more files or directories.
RM [-q] file/directory [file/directory ...]
-q
confirmation
file
directory
- Quite mode; does not prompt user for a
- File name (wildcards are permitted)
- Directory name (wildcards are permitted)
Note:
1. Removing a read-only file/directory will result in a failure.
Removing a
directory containing read-only file(s) will result in a
failure.
2. If an error occurs, RM will exit immediately and later
files/directories
will not be removed.
3. You cannot remove a directory when the current directory is
itself or its
subdirectory.
4. If file contains wildcards, it will not ask user for
confirmation.
5. You cannot remove the root directory.
6. You cannot remove the current directory or its ancestor.
7. Redirecting output to a file that exists under the directory
that will
be removed is not allowed.
Examples:
* To remove multiple directories at a time:
fs0:\> ls test
Directory of: fs0:\test
06/18/01
06/18/01
06/19/01
06/19/01
01:01p <DIR>
01:01p <DIR>
12:59a <DIR>
12:59a <DIR>
0 File(s)
4 Dir(s)
512
0
512
512
0 bytes
.
..
temp1
temp2
* Error occurs and RM will exit:
fs0:\> rm test\temp11 temp2
rm/del: Cannot find 'fs0:\test\temp11' - Not Found
* To remove multiple directories with wildcards:
fs0:\> rm test\temp*
1.0to7thRvw
July, 2005
117
EFI Shell User's Guide
Commands
rm/del: Remove subtree 'fs0:\test\temp1' [y/n]? y
removing fs0:\test\temp1\temp1.txt
- [ok]
removing fs0:\test\temp1\boot\nshell.efi
- [ok]
removing fs0:\test\temp1\boot
- [ok]
removing fs0:\test\temp1
- [ok]
rm/del: Remove subtree 'fs0:\test\temp2' [y/n]? y
removing fs0:\test\temp2\temp2.txt
- [ok]
removing fs0:\test\temp2
- [ok]
* Removing a directory that contains a read-only file will
fail:
fs0:\> attrib +r test\temp1\readme.txt
A R fs0:\test\temp1\readme.txt
fs0:\> rm test\temp1
rm/del: Cannot open 'readme.txt' under 'fs0:\test\temp1' in
writable
mode
- [error] - Access Denied
Exit status code: Access Denied
Shell>
5.5.29 set
NOTE
This command is an internal-only command. It cannot be switched to an external command.
Summary
Used to maintain the environment variables that are available from the EFI environment.
EFI Versions
EFI 1.02 and above.
118
Commands
Usage
SET [-v] [sname [value]]
SET [-d <sname>]
-d
-v
sname
value
-
Deletes the environment variable
Volatile variable
Environment variable name
Environment variable value
Description
This command is used to maintain the environment variables that are available from the EFI
environment. This command can do the following:
• Display the environment variables.
• Create new environment variables.
• Change the value of existing environment variables.
• Delete environment variables.
The set command will set the environment variable that is specified by sname to value. This
command can be used to create a new environment variable or to modify an existing environment
variable. If the set command is used without any parameters, then all the environment variables
are displayed. If the set command is used with the -d option, then the environment variable that
is specified by sname will be deleted. The following examples show how this command can be
used to create, modify, and delete the environment variable DiagnosticPath.
1.0to7thRvw
July, 2005
119
EFI Shell User's Guide
Commands
Examples
Shell> help set
Displays, creates, changes, or deletes EFI environment variables.
SET [-v] [sname [value]]
SET [-d <sname>]
-d
-v
sname
value
-
Deletes the environment variable
Volatile variable
Environment variable name
Environment variable value
Notes:
1. Size of NVRAM for set command will depend on the system
implementation.
2. May send NVRAM variables to /efi/boot/bootstr.nvr on the file
system if
no NVRAM is implemented in the core EFI routines.
3. SET values are stored in EFI NVRAM and will be retained
between boots
unless the option -v is specified.
4. A * in front of sname means that this variable is a volatile
variable.
To make any changes to it, please use the command with the –
voption.
Examples:
* To add an environment variable:
Shell> set DiagnosticPath fs0:\efi\diag;fs1:\efi\diag
* To display environment variables:
Shell> set
* path
: .
diagnosticPath : fs0:\efi1.1\diag;fs1:\efi1.1\diag
* To delete an environment variable:
Shell> set -d diagnosticpath
Shell> set
* path
: .
* To change an environment variable:
fs0:\> set src efi
fs0:\> set
* path : .;fs0:\efi\tools;fs0:\efi\boot;fs0:\
src : efi
fs0:\> set src efi1.1
fs0:\> set
* path : .;fs0:\efi\tools;fs0:\efi\boot;fs0:\
120
Commands
src
: efi1.1
* To append an environment variable:
Shell> set
* path
: .
Shell> set path %path%;fs0:\efi\tools;fs0:\efi\boot;fs0:\
Shell> set
* path
: .;fs0:\efi\tools;fs0:\efi\boot;fs0:\
* To set a volatile variable that will disappear at the next
boot:
Shell> set -v EFI_SOURCE c:\project\EFI1.1
Shell> set
* path
: .;fs0:\efi\tools;fs0:\efi\boot;fs0:\
* EFI_SOURCE : c:\project\EFI1.1
Shell>
5.5.30 time
Summary
Displays or sets the current time for the system.
EFI Versions
EFI 1.02 and above.
Usage
TIME [hh:mm[:ss]]
hh
mm
ss
- Hour of time, Hour range: 0 - 23
- Minute of time, Minute range: 0 - 59
- Second of time, Second range: 0 - 59
Description
This command displays or sets the current time for the system. If no parameters are used, it shows
the current time. If valid hours, minutes, and seconds are provided, then the system's time will be
updated. Note the following rules:
1. Except for numeric characters and the : character, all other characters in the argument are
invalid. The Shell will report an error if the number is in the wrong hour/minute/second range.
2. Spaces before or after the numeric character are not allowed. Spaces inserted into the number are
not allowed either.
3. Repeated zeros are allowed before the number. For example:
1.0to7thRvw
July, 2005
121
EFI Shell User's Guide
Commands
Shell > time 00000017:000004:0000
Shell > time
17:04:00 (GMT+08:00)
Shell >
4. The seconds parameter is optional. If there is no seconds number, it will set to zero by default.
Shell > time 17:23
Shell > time
17:23:00(GMT+08:00)
Shell > time 17:23:
Shell > time
17:23:00(GMT+08:00)
Examples
Shell> help time
Displays the current time or sets the time of the system.
TIME [hh:mm[:ss]]
hh
mm
ss
- Hour of time, hour range: 0 - 23
- Minute of time, minute range: 0 - 59
- Second of time, second range: 0 - 59
Note:
1. Hour and minute are required to set the time.
2. If second is not specified, 0 will be used as default.
Examples:
* To display current time:
fs0:\> time
16:51:03 (GMT+08:00)
* To set the system time:
fs0:\> time 9:51:30
fs0:\> time
09:51:31 (GMT+08:00)
Shell>
5.5.31 touch
Summary
Updates the time and date on a file to the current time and date.
122
Commands
EFI Versions
EFI 1.02 and above.
Usage
TOUCH [-r] file [file …]
-r
file
can be
- Recursive to subdirectories
- The name or pattern of the file or directory. There
multiple files on the command line.
Description
This command updates the time and date on the file that is specified by the file parameter to the
current time and date.
Examples
Shell> help touch
Updates time and date with current time.
TOUCH [-r] file [file …]
-r
file
- Recursive to subdirectories
- The name or pattern of file or directory. There can
be
multiple files on the command line.
Notes:
1. If multiple files are specified on the command line, it will
continue
processing even fail to touch some of them.
2. Touch can not change the time and date of read-only files and
directories.
1.0to7thRvw
July, 2005
123
EFI Shell User's Guide
Commands
Examples:
* To touch a file (the time and date of file will be changed
after
TOUCH):
fs0:\> ls for.nsh
Directory of: fs0:\
06/18/01 09:32p
153 for.nsh
1 File(s)
153 bytes
0 Dir(s)
fs0:\> touch for.nsh
touch: fs0:\for.nsh [ok]
fs0:\> ls for.nsh
Directory of: fs0:\
06/19/01 09:54a
1 File(s)
0 Dir(s)
153
153 bytes
for.nsh
* To touch a directory recursively:
fs0:\> touch -r efi1.1
touch: fs0:\efi1.1 [ok]
touch: fs0:\efi1.1\boot [ok]
touch: fs0:\efi1.1\boot\nshell.efi [ok]
5.5.32 type
Summary
Sends the contents of a file to the standard output device.
EFI Versions
EFI 1.02 and above.
Usage
TYPE [-a|-u] file [file...]
-a
-u
file
- Displays the file as ASCII characters
- Displays the file as Unicode characters
- Name of file to display
Description
This command sends the contents of a file to the standard output device. If no options are used, then
the file type is automatically detected and sent to the standard output device. If the -a option is
124
Commands
specified, the file is sent to the standard output device as a stream of ASCII characters. If the -u
option is specified, the file is sent to the standard output device as a stream of Unicode characters.
The example below shows how to send the ASCII file README.TXT on the floppy drive to the
standard output device and the Unicode file READMEU.TXT on the floppy drive to the standard
output device.
Type redirection to the same file is not supported currently. Wildcards are permitted in the file
name. If the type command is used in conjunction with an ASCII file with the -u flag, this flag
will be ignored and the contents of the file will be sent to the standard output device as ASCII
characters. If the type command is used in conjunction with a Unicode file with the -a flag, the
file will be sent as ASCII characters but with an additional space between each character.
1.0to7thRvw
July, 2005
125
EFI Shell User's Guide
Commands
Examples
Shell> help type
Displays the contents of a file on the standard output device.
TYPE [-a|-u] file [file...]
-a
-u
file
- Displays the file as ASCII characters
- Displays the file as Unicode characters
- Name of file to display
Examples:
* To display the file as Unicode characters:
fs0:\> type -u pause.nsh
File: fs0:\pause.nsh, Size 204
#
# Example script for 'pause' command
#
echo pause.nsh begin..
date
time
pause
echo pause.nsh done.
* To display the file as ASCII characters:
fs0:\> type -a pause.nsh
File: fs0:\pause.nsh, Size 204
#
#
E x a m p l e
s c r i p t
f o r
' p a u s e '
c o m m a n d
#
e c h o
p a u s e . n s h
b e g i n . .
d a t e
t i m e
p a u s e
e c h o
p a u s e . n s h
d o n e .
* To type multiple files at a time:
fs0:\> type test.*
File: fs0:\test.txt, Size 23
How to Install?
File: fs0:\test.nsh, Size 48
time
stall 3000000
time
Shell>
126
Commands
5.5.33 unload
Summary
Unloads a driver image that was already loaded.
EFI Versions
EFI 1.10 and above.
Usage
UNLOAD [-n] [-v] Handle
-n
-v
Handle
- Without prompt
- Dump Verbose information
- Handle of driver to unload, always taken as
hexadecimal number
Description
This command unloads a driver image that was already loaded.
1.0to7thRvw
July, 2005
127
EFI Shell User's Guide
Commands
Examples
Shell> help unload
Unloads a driver image.
UNLOAD [-n] [-v] Handle
-n
-v
Handle
- Without prompt
- Dump Verbose information
- Handle of driver to unload, always taken as
hexadecimal number
Note:
1. Option '-n' can be used to skip all the prompts during the
unloading so
that it can be used in a batch file.
2. If option '-v' is specified, the verbose information on the
image will
be displayed before the image is unloaded.
3. Only those images that can support the unloading operation can
be unloaded
successfully.
4. The 'LOAD' is the opposite.
Examples:
* To find the handle index driver image to unload:
Shell> dh -b
Handle dump
1: Image(DXE Foundation)
2: FwVol FwFileSys FwVolBlk DevPath(MemMap(11:1760000189FFC8))
...
27: Image(Reset)
28: Image(WinNtBlockIo) DriverBinding
29: Image(Timer)
...
* To unload the driver image of 'Reset':
Shell> unload 27
27: Image(Reset)
Unload driver image (y/n)? n
Exit status code: Aborted
128
Commands
5.5.34 ver
Summary
Displays the version information for this EFI firmware.
EFI Versions
EFI 1.02 and above.
Usage
VER [-s]
-s
- Displays only the EFI Shell version
Description
This command displays the version information for this EFI Firmware or the version information
for the EFI Shell itself. The information is retrieved through the EFI System Table or the Shell
image.
1.0to7thRvw
July, 2005
129
EFI Shell User's Guide
Commands
Examples
Shell> help ver
Displays the version information for this EFI Firmware.
VER [-s]
-s
- Displays the EFI Shell version
Examples:
* To display the version information of a platform:
fs0:\> ver
EFI Specification Revision : 1.10
EFI Vendor
: INTEL
EFI Revision
: 14.5
* To display the version information of another platform:
Note that the version information may vary from different
platforms
due to some platform-specific information.
fs0:\> ver
EFI Specification Revision : 1.02
EFI Vendor
: INTEL
EFI Revision
: 12.38
SAL Specification Revision
SAL_A Revision
= 1. 1
SAL_B Revision
= 1. 1
PAL_A Revision
PAL_B Revision
3. 0
66.23
66.23
Other modules mentioned in FIT (Firmware Interface Table)
FIT_Entry Type
0, Revision
2.60
FIT_Entry Type 15, Revision
66.23
FIT_Entry Type 16, Revision
0.90
FIT_Entry Type 32, Revision
0.30
FIT_Entry Type 30, Revision
1. 0
FIT_Entry Type 17, Revision
0.90
FIT_Entry Type 18, Revision
6. 0
FIT_Entry Type 20, Revision
0.80
SalProc Entry 000000003FE3F720 and GP 000000003FF22480
PalProc Entry 000000003FF48010 IO Port Base 00000FFFFC000000
Cache Enabled
* To display the version information of the EFI Shell
Shell> ver -s
EFI Shell Revision 1.0
130
Commands
EFI Shell Signature: D2C18636-40E5-4EB5-A31B-36695FD42C87
Shell>
5.5.35 vol
Summary
Displays the volume information for the file system that is specified by fs.
EFI Versions
EFI 1.02 and above.
Usage
VOL [fs] [-n <Volume Label>]
VOL [fs] [-d]
fs
Volume Label
-d
- The name of the file system
- New volume label
- Empty volume label
Description
This command displays the volume information for the file system that is specified by fs. If fs is
not specified, the current file system will be taken as the correct fs. If Volume Label is
specified, then the volume label for fs will be set to Volume Label. The maximum length for
Volume Label is 11 characters.
1.0to7thRvw
July, 2005
131
EFI Shell User's Guide
Commands
Examples
Shell> help vol
Displays volume information for the file system specified by fs.
VOL [fs] [-n <Volume Label>]
VOL [fs] [-d]
fs
Volume Label
-d
- The name of the file system
- New volume label
- Empty volume label
Notes:
1. The following characters cannot be used in Volume Label:
% ^ * + = [ ] | : ; “ < > ? / ..
2. No space is allowed in Volume Label.
3. If fs is not specified, the current file system will be taken
as fs.
Examples:
* To display the volume of the current fs:
fs0:\> vol
Volume has no label (rw)
1,457,664 bytes total disk space
1,149,440 bytes available on disk
512 bytes in each allocation unit
* To change the label of fs0:
shell> vol fs0 –n help_test
Volume HELP_TEST (rw)
1,457,664 bytes total disk space
1,149,440 bytes available on disk
512 bytes in each allocation unit
* To get rid of the label of fs0:
fs0:\> vol fs0 -d
Volume has no label (rw)
1,457,664 bytes total disk space
220,160 bytes available on disk
512 bytes in each allocation unit
Shell>
132
6
Shell How To's
6.1
Introduction
This section provides instructions on how to perform various tasks in the EFI Shell. These tasks
include the following:
• How to Switch an External Command to an Internal Command
• How to Switch an Internal Command to an External Command
• How to Understand Consistent Mapping
• How to Switch the Running Modes of the EFI Shell
• How to Correctly Write Scripts in the New EFI Shell
• How to Start a Specific startup.nsh File When Launching EFI
• How to Understand the Use of Quotation Marks
• How to Understand the Use of the Escaping Character '^'
• How to Alias
• How to Map a File System to a User-Specific Mapping Name
• How to Set/Modify/Delete Environment Variables
• How to Launch and Exit the EFI Shell
• How to Determine the Version of the EFI Shell
• How to Get Help Information
• How to Terminate the Execution of Commands
• How to Pause the Screen Output
• How to View the Screen History
• How to Redirect the Output of Commands to Files
• How to View the Contents of a Text File
• How to Edit a Text File
• How to Edit a Binary File
• How to Edit Disk Blocks
• How to Edit Memory
• How to Connect a Driver to a Device
6.2
How to Switch an External Command to an Internal Command
The following steps explain how to switch an external command to an internal command:
1. You should put all the files of your external command (or application) under a subdirectory of the
EFI Shell source root directory in the release package. For example, if the EDK root directory is
C:\EDK, you should put your source code directory under
C:\EDK\Other\Maintained\Application\Shell (e.g.,
C:\EDK\Other\Maintained\Application\Shell\Hello)
133
EFI Shell User's Guide
Shell How-To’s
2. Add lines into the sources.common section of shell.inf, which is located under the EFI
Shell source root directory, to include all the source files of your external command. If your
external command uses any .uni files, they should be included here and must be put ahead of
any .c files of your command. For example:
Hello\HelloString.uni
Hello\Hello.c
If your external command (or application) uses any .h files, please add lines into the
includes.common section to indicate where the .h files can be found (e.g., the file
Hello.h is under C:\EDK\Other\Maintained\Application\Shell\Hello).
$(EDK_SOURCE)\Other\Maintained\Application\Shell\Hello
The macro EDK_SOURCE represents the EDK root directory. It should be followed by the
relative path from the root where the .h files can be found.
3. In the file shell\shellenv\cmddisp.c, declare the entry point function and line help
function of your external command ahead of the SEnvInternalCommands table. Add an
entry for your external command into the SEnvInternalCommands table using the following
values in the order listed:
• Entry point function
• Internal command name
• Line help function
You must add the entry inside the #ifdef EFI_MONOSHELL...#endif block.
4.
6.3
Build the EFI Shell. Your external command should then have been added as an internal
command.
How to Switch an Internal Command to an External Command
The following steps explain how to switch an internal command to an external command (or
application):
1. You will need to write an .inf file for your external command (or application). See the EFI
Shell Developer’s Guide for instructions on how to write an .inf file for external commands (or
applications).
2. Remove the lines for the previous internal command from the shell.inf file, which is located
under the EFI Shell source root directory.
3. Remove the declarations of the entry point function and line help function from
shell\shellenv\cmddisp.c.
4. Remove the entry for the previous internal command from the SEnvInternalCommands
table.
134
Shell How-To’s
NOTE
Changing an "internal-only" command to an external command is not permitted. See the
Commands chapter for the list of internal-only commands.
6.4
How to Understand Consistent Mapping
Consistent mapping was introduced in this version of the EFI Shell to provide the ability to map file
systems to consistent mapping names that will change only if the system’s hardware configuration
changes. Because what constitutes a hardware configuration change can be defined in several ways,
this document uses the following rules to determine if the hardware configuration has changed:
• The number of buses or controllers in a system has changed.
• The physical connections of buses or controllers in a system have changed.
• The physical connection of a device to the system has changed.
In general, use the following as the definition of a hardware configuration change: A hardware
configuration change is any change in the number of or physical connections of a device that
has the capability to produce child devices.
Hardware configuration changes have global scope effects. Any hardware configuration change
could possibly nullify the existing consistent mapping names.
If the hardware configuration remains consistent, all the consistent mapping names will remain
consistent. This constancy reflects two characteristics of consistent mapping:
• Outside of hardware configuration changes, all the consistent mapping names will be kept the
same.
• Systems that have exactly the same hardware configuration should have exactly the same
consistent mapping names.
The second characteristic is very useful for users to write scripts that will be executed across
multiple systems that have exactly the same hardware configuration. It guarantees consistent access
to file systems in the scripts.
Consistent mapping names are different and typically a little longer than traditional fsx-style file
system names. A GUIDed file system may have a consistent mapping name that may have more
than 64 characters. For users who work with the command prompt, traditional fsx-style mapping
names are still the norm. Keep in mind that if you are using the fsx-style map names on the
command prompt, they do not have consistent mapping characteristics.
6.5
How to Switch the Running Modes of the EFI Shell
To be backward compatible to older versions of the EFI Shell (for example, the EFI Shell that was
included in the EFI 1.10.14.62 Sample Implementation), the new EFI Shell provides two running
modes:
• Backward-compatible mode
• Enhanced Shell mode
1.0to7thRvw
July, 2005
135
EFI Shell User's Guide
Shell How-To’s
See Running Modes and Backward-Compatibility Support in the Features chapter for more
information on these running modes. Enhanced Shell mode is the default running mode in this
release of the EFI Shell.
To change the current running mode, execute the following command at the Shell prompt:
set -v efishellmode xxx
In the above command, efishellmode is the reserved volatile variable that the EFI Shell uses to
control the current running mode (see Special Shell Variables in the Syntax chapter for more
information on this variable). xxx is the value for the running mode. 1.1.1 is for backwardcompatible mode and 1.1.2 is for enhanced Shell mode. Any other values are invalid in the
current version.
6.6
How to Correctly Write Scripts in the New EFI Shell
Two running modes are introduced in this version of the EFI Shell (see Running Modes and
Backward Compatibility in the Features chapter for more information):
• Backward-compatible mode
• Enhanced Shell mode
When a batch script is started, the default running mode is set to backward-compatible mode. This
mode is different from the default running mode when you are at the command prompt. As a result,
you must place a statement at the beginning of the script to set the running mode to the desired
setting. This statement must be the first command in a script.
Note that scripts can be called inside scripts (a feature that is referred to as nested batch scripts; see
Nesting Batch Scripts in the Batch Scripts chapter for more information). Nested scripts should set
and maintain the running mode for themselves. However, child scripts cannot change the running
mode in the parent script.
To determine the current running mode, scripts can read the reserved variable efishellmode,
the same as if they are reading a normal environment variable. See Special Shell Variables in the
Syntax chapter for more information on this variable.
6.7
How to Start a Specific startup.nsh File When Launching EFI
Shell
The following steps explain how to start a specific start-up batch script file startup.nsh when
you are launching the EFI Shell:
1. Ensure that the EFI Shell will be launched from a file system. Currently, the EFI Shell does not
support starting a specific startup.nsh file if the EFI Shell is launched from firmware.
2. Put the specific startup.nsh file that you want to run in the same directory with the EFI Shell
image that will be launched. Note that the file name must be startup.nsh (case insensitive).
3. Load and execute the EFI Shell image. The specified startup.nsh file will then be executed
unless the user cancels its execution.
136
Shell How-To’s
6.8
How to Understand the Use of Quotation Marks
The quotation mark character is one of the special functional characters in the EFI Shell. A single
quotation mark character that is not paired with another closing quotation mark will be discarded
after the command line is processed and will not cause any consequences. The quotation mark pair
has the following three main functions:
• Makes the input on the command line literal
• Helps to group arguments on the command line
• Specifies the boundaries for variable substitution
Making the Input Literal
Making the input literal means that none of the characters in the input will be treated as a special
functional character. In the EFI Shell, any strings that start with a - or +character will be
interpreted as flags to a command. If you want to prevent them from being interpreted as flags, you
can use quotation marks to make them literal. For example, if you want to display the string 'dump,' you can use the following at the command prompt:
echo "-dump"
Here the quotation marks will prevent the string '-dump' from being interpreted as a flag to the
command echo.
NOTE
You can also use the escaping character ^ to make the input literal. See How to Understand the
Use of the Escaping Character '^' for more information.
Grouping Arguments on the Command Line
Because the EFI Shell interprets blank spaces as the splitting character to separate arguments on
the command line, you need to use quotation marks to help pass arguments that contain blank
spaces to commands. For example, if you want to list a directory named 'good news,' type the
following at the command prompt:
dir "good news"
If you type the following at the command prompt instead, the EFI Shell will think that you want to
list two directories, 'good' and 'news':
dir good news
Specifying the Boundaries for Variable Substitution
In this version of the EFI Shell, users can specify the boundary inside which variable substitution
will be performed. In a single argument, quotation marks can define the boundaries that divide the
argument into multiple parts; variable substitution will then be performed in each part.
For example, say we have an environment variable 1a whose content is xyz and a script a.nsh,
as follows:
1.0to7thRvw
July, 2005
137
EFI Shell User's Guide
Shell How-To’s
for %a in 1 2 3
echo %1a%a
endfor
If we execute the command a.nsh abc (the string abc will be taken as the first positional
argument %1 to this script), the output will be the following:
xyza
xyza
xyza
The substitution of environment variables has higher priority than that of positional arguments. So
if we want the result to be the following:
abca1
abca2
abca3
The script should be written like the following:
for %a in 1 2 3
echo "%1"a%a
endfor
6.9
How to Understand the Use of the Escaping Character '^'
The character ^ is defined as the escaping character in the EFI Shell. It can unconditionally make
any character that immediately follows it a literal character and thus prevents that following
character from being interpreted as having special meaning. However, if a ^ character is
immediately followed by another ^ character, the second ^ character becomes a literal character
and cannot escape the immediately following character; in other words, the character that
immediately follows the second ^ character is not made literal and will still be interpreted as having
special meaning.
In the EFI Shell, flags (or switches) on a command line all start with - or + character, so the side
effect is that all arguments that start with - or + will be interpreted as flags by default. For example,
typing echo -Title at the command prompt will give you the following error message
echo: Unknown flag - '-Title'
The escaping character ^ can be very useful in this case. Putting an escaping character before the or +, as shown in the following example, will stop the EFI Shell from interpreting the following
string as a flag:
echo ^-Title
You can also use a pair of quotation marks to do the same thing. However, a pair of quotation
marks cannot make the escaping character literal, and they also cannot make quotation marks
literal. If you want to pass quotation marks to a command as part of the argument, you must use the
escaping character ^ to transfer the meaning of the quotation marks.
Escaping characters will be discarded after a command line has been processed, assuming the
escaping character was not escaped by another escaping character.
138
Shell How-To’s
6.10 How to Alias
Users can set aliases to commands. Use the alias command to view, set up, and delete aliases.
See the following topics or chapters for more information on the following:
• The Aliases topic in the Features chapter for general information on aliases
• The Commands chapter for the detailed help information for the alias command
The following table gives examples of custom (i.e., not predefined) aliases. It shows what to type at
the command prompt to set the alias and then describes the result of that command.
Table 6-1 Examples of Custom Aliases
Command to Type at Shell Prompt
Result
alias ll "ls -b"
alias -v rmdir "rm -q"
Sets ll as the alias to the command ls
-b.
Sets rmdir as the alias to the command rm -q.
6.11 How to Map a File System to a User-Specific Mapping Name
Use the map command to map a file system to a user-specific mapping name. For example, you can
map a file system that is represented by hd0a1 to a user-specific name hdisk1 by typing the
following at the command prompt:
map hdisk1 hd0a1:
Note that the last colon is required because the map command also supports mapping a userspecific mapping name to a file system handle. The colon eliminates the ambiguity of two usages.
If you want to specify a name for a certain file system by handle, you can do so by typing the
following at the command prompt:
map name handle
See the Commands chapter for the detailed help information for the map command.
6.12 How to Set/Modify/Delete Environment Variables
Use the set command to set, modify, and delete environment variables. Environment variables are
variables that can be accessed at the command prompt or in batch scripts. The EFI Shell currently
only supports a string data type for all the environment variables. See Valid Characters for Variable
Names in the Syntax chapter for the characters that can be used to make variable names.
There is no limitation on the contents of variables. To delimit an environment variable, put the
variable name inside a pair of percentage signs and the entire expression will be replaced by the
content of the environment variable. See the Syntax and Batch Scripts chapters for the detailed
variable substitution rules.
To set a environment variable test whose content is hello, type the following at the command
prompt:
1.0to7thRvw
July, 2005
139
EFI Shell User's Guide
Shell How-To’s
set test hello
The EFI Shell also supports volatile environment variables. For example, to set a volatile
environment variable GUI, type the following at the command prompt:
set -v GUI "graphic world"
See the Commands chapter for the detailed help information for the set command.
6.13 How to Launch and Exit the EFI Shell
Launching (or Invoking) the EFI Shell
The EFI Shell can be launched in the following three ways:
• Launched as a default boot option
• Loaded and launched from the boot option maintenance menu as an application
• Loaded and launched from the EFI Shell command prompt as an application
The EFI Shell can be built as part of the firmware and will be added as a default boot option at boot
time.
Exiting the EFI Shell
The exit command is provided to let users exit the EFI Shell. Because the EFI Shell supports
nesting the Shell, the exit command will exit the current instance of the EFI Shell and return to its
parent. If there is no parent EFI Shell, it should go back to the EFI boot manager or the boot option
maintenance menu.
In batch scripts, the exit command will terminate the entire EFI Shell, not only the scripts.
6.14 How to Determine the Version of the EFI Shell
Use the ver command to display the version information of the firmware and the EFI Shell. To
display the version of the firmware, type the following at the command prompt:
ver
To display the version of the EFI Shell, type the following at the command prompt:
ver -s
See the Commands chapter for the detailed help information for the ver command.
140
Shell How-To’s
6.15 How to Get Help Information
For Internal Commands
Use the help command to display the line help and the verbose help information of internal Shell
commands. Line help is a one-sentence description of the Shell command usage, and verbose help
is a detailed description of the usage of a Shell command, including explanations of each switch
and examples.
To display the verbose help information of an internal command, type either of the following at the
command prompt, where cmd is the name of the internal command:
help cmd
cmd -?
NOTE
The help cmd form can only be used with internal Shell commands.
To display all the line help information of all the internal Shell commands, type the following at the
command prompt:
help
The help command supports wildcards in internal command names. For example, help d* will
display the line help information of all the internal commands whose names start with the character
d.
See the Commands chapter for the detailed information for the help command.
For External Commands
To display the verbose help information of an external Shell command, type the following at the
command prompt, where cmd is the name of the external command. This form does the same thing
as help cmd.
cmd -?
6.16 How to Terminate the Execution of Commands
Press the ESC key to terminate the execution of internal commands and batch scripts.
6.17 How to Pause the Screen Output
Press the Tab key to pause and resume the streaming of output characters to the console.
1.0to7thRvw
July, 2005
141
EFI Shell User's Guide
Shell How-To’s
6.18 How to View the Screen History
The EFI Shell will store the output of commands that have been executed. Press the Page Up and
Page Down buttons to browse through the screen history, which is also called the scroll back buffer.
You can view a maximum of three screens of output history.
6.19 How to Redirect the Output of Commands to Files
The EFI Shell supports redirecting the standard output and the standard error output of commands
to files. See Output Redirection in the Syntax chapter for the redirection flags that you can use to
perform output redirection.
When performing a redirection, put the command and all of its arguments on the left side of the
redirection flags. You can redirect one standard output and one error output on the command line at
a time, but the redirection files should be different. You cannot put multiple standard output flags
and multiple error output flags on the command line either.
6.20 How to View the Contents of a Text File
Use the type command to view the contents of a text file. This command is similar to the MSDOS* command type and the Unix* command cat.
See the Commands chapter for the detailed help information for the type command.
6.21 How to Edit a Text File
An edit application is provided along with the EFI Shell to allow users to edit text files. This
application provides a simple editor environment to create and edit text files. To launch the edit
application, type the following at the command prompt:
edit
6.22 How to Edit a Binary File
An application hexedit is provided along with the EFI Shell to allow users to edit binary files.
To launch the hexedit application, type the following at the command prompt:
hexedit
Type the following at the command prompt for detailed help information for the hexedit
command:
142
Shell How-To’s
hexedit -?
6.23 How to Edit Disk Blocks
There are two applications that can be used to view and edit disk blocks:
• dblk
• hexedit
Type the following at the command prompt for the detailed help information for these two
applications:
dblk -?
hexedit -?
6.24 How to Edit Memory
Use the external mm command to edit bytes in specific memory locations. Type the following at the
command prompt to get the detailed help information for the mm command:
mm -?
6.25 How to Connect a Driver to a Device
Use the connect command to connect a single driver to a specific device or to connect all the
drivers to all the devices. See the Commands chapter for detailed help information for the
connect command.
1.0to7thRvw
July, 2005
143