EFI Shell User s Guide Draft for Review

Transcription

1 EFI Shell User s Guide Draft for Review Version 1.0_to7thRvw July 7, 2005 i

2 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 , Intel Corporation. All Rights Reserved. ii

3 Revision History Revision Revision History Date 1.0_toRvw 1.0_to2ndRvw 1.0_to7thRvw 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 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. Incorporated review comments received from Fang & Liu. (External). Synchronized database. 8/25/04 7/6/ to7thRvw July, 2005 iii

4 EFI Shell User's Guide iv

5 Contents 1 Introduction Overview Help System of This Document Terms Conventions Used in This Document Command Descriptions Pseudo-Code Conventions Typographic Conventions Features Shell Features Introduction Shell Appearance Supported Features Supported Features EFI Shell Commands Batch Scripts Nesting the Shell PATH Variable Support KEY History Support Execution Interrupts Consistent Mapping of File Systems Output Redirection Output Streaming Control Scroll Back Buffer Support Verbose Help Support EFI Compatibility of the EFI Shell Running Modes and Backward-Compatibility Support Invoking the EFI Shell Invoking the EFI Shell Start-up Batch File Startup.nsh EFI Shell Prompt Syntax Introduction Special Characters Variable and Alias Substitution Environment Variables and Variable Substitution Alias Substitution Valid Characters for Variable Names Variables Available Only in Batch Scripts Special Shell Variables Variable Substitution Flowchart Wildcard Expansion to7thRvw July, 2005 v

6 EFI Shell User's Guide 3.5 Switches and Arguments in Commands Quotation Marks Output Redirection File Naming Conventions Batch Scripts Introduction Batch Script Command Descriptions Summary of Batch Script Commands for...endfor goto if...else...endif pause shift Variable, Argument, and Alias Substitution Variable, Argument, and Alias Substitution in Batch Scripts Alias Substitution Rule in Batch Scripts General Variable Substitution Rule in Batch Scripts General Command Line Variable Substitution Rule in Batch Scripts Supported Number of Arguments in Batch Scripts Syntax for Variables in Batch Scripts Example of Variable, Argument, and Alias Substitution in Batch Scripts Comments Error Handling Running Modes in Batch Scripts Nesting Batch Scripts Output Redirection in Batch Scripts Echoing in Batch Scripts Known Limitations with the Shell Scripting Language Commands Introduction External Commands Supported EFI Protocols in the Shell MS-DOS* 6.22 and Unix* Equivalents Internal Command Descriptions Summary of EFI Shell Internal Commands Command Usage Notes alias attrib cd cls connect copy cp date del dh vi

7 dir disconnect drivers drvcfg drvdiag echo exit help load ls map mkdir mv reconnect reset rm set time touch type unload ver vol Shell How To's Introduction 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 Shell 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 to7thRvw July, 2005 vii

8 EFI Shell User's Guide 6.24 How to Edit Memory How to Connect a Driver to a Device 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 viii

9 1.1 Overview 1 Introduction 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 Book Introduction Features Syntax Batch Scripts Commands Shell How To's Description 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. 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. Introduces the required syntax for commands and batch scripts in the EFI Shell. Lists all batch script commands that are available in the EFI Shell. Lists all the internal core commands that are available in the EFI Shell. Gives instructions on how to perform various tasks in the EFI Shell. 1.2 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): 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

10 EFI Shell User's Guide Introduction DXE EFI 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. 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 Command Descriptions The commands that are described in this document generally have the following format: Command Name: The formal name of the command. Summary: EFI Versions: Usage: Description: Examples: A brief description of the command. Indicates the versions of EFI with which the command can be used. A brief usage of the command. A detailed description about how to use that command. Examples to show how to use that command. 10

11 Features 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 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,

12 EFI Shell User's Guide Introduction text text text 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 The EFI Documentation help system is available from the EFI web site 12

13 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

14 EFI Shell User's Guide Features Figure 2-1 EFI Shell Look and Feel 2.3 Supported Features 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

15 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 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 Internal Description 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. For more information, see... 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) 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,

16 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 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 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

17 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 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 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 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 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,

18 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 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 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 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

19 Features 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 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 Line help Verbose help Description Describes the Shell command usage in one sentence. 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 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,

20 EFI Shell User's Guide Features 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 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 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

21 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 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,

22 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 Newline Description Ends a command line. space # Starts a comment. > Used for output redirection. Ends an argument, if it is not in quotation marks. This character is sometimes referred to as the splitting character. % 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

23 Syntax 3.3 Variable and Alias Substitution 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 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 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 Variables Available Only in Batch Scripts This topic describes the following variables, which are available only in batch scripts: 1.0to7thRvw July,

24 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 Required Syntax Description Index %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. Positional %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 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 path Description Contains the default directories that may exist on all the discovered file systems. These 24

25 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 efishellmode StartupDelay 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. 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 xxx is the valid value for efishellmode: 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. 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,

26 EFI Shell User's Guide Syntax Figure 3-1 Variable and Argument Substitution Flowchart 26

27 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,

28 EFI Shell User's Guide Syntax Shell> load nc IsaBus.efi Shell> map -r Shell> connect c Shell> 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

29 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,

30 EFI Shell User's Guide Syntax 3.8 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

31 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 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 for...endfor goto if...else...endif pause shift Description Executes commands for each item in a set of items. Makes the execution of the batch file jump to another location. Executes commands in specified conditions. Prints a message and suspends for keyboard input. Shifts the arguments from %0 to %9 one by one. 31

32 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 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

33 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,

34 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 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