Parameter Passing

Positional parameters are the first ten arguments (%0–%9) passed from the command line into a UEFI Shell script. The first parameter after the UEFI Shell script name becomes %1, the second %2, the third %3, and so on. The argument %0 is the full path name of the script itself.

When executing the UEFI Shell script, the %n is replaced by the corresponding argument on the command line that invoked the script. If a positional parameter is referenced in the UEFI Shell script but that parameter was not present, then an empty string is substituted.

When passing parameters to commands, the associated commands might at times accept parameters with wildcards in them. The most common use of such wildcards is in reference to file names. The asterisk (*) and question mark (?) are often used for filename expansion. The asterisk would be used in a case where one is searching for 0 or more characters in a filename. For example, the reference to a filename of “*.*” would be one searching for any valid file names with any valid extension. This typically means “give me everything.” The question mark is intended to be used when looking to match exactly one character in a given filename. An example of this would be “?I?.TXT” where items that might match this sequence would be JIM.TXT and KIM.TXT.

Redirection and Piping

Depending on the background of the reader, mixing the terms redirection and piping may not seem natural. For purposes of this section, let us explicitly define the terms:

Redirection

When using output redirection, there are several options available for both the source of the data as well as the output of the data. The command syntax for output redirection is:

It should be noted that the aforementioned Target location can be either a traditional file on some non-volatile media or it can be a volatile environment variable. The latter is introduced to support the operation of scripting logic even in a read-only type of environment. Table C.1 summarizes the redirection character sequences.

Table C.1: Output Redirection Support

When using input redirection, the content of a file or environment variable is read and used as the standard input to an application or shell command. The command syntax for input redirection is:

Table C.2 summarizes the input redirection character sequences.

Table C.2: Input Redirection Support

Command Piping

By using the pipe (|) character, a data channel is formed that takes the standard Unicode output of a file and feeds the data as standard input to another program. The format for this support is as follows:

This capability is found in most modern shells and since many common utilities presume the use of pipe operations, this enables maximal environment compatibility for those who port their favorite utilities to this environment. Table C.3 summarizes command piping support.

Table C.3: Command Piping Support

Return Codes

During the execution of most shell commands, a return status is given when that command completes execution. In the UEFI Shell specification, there is a SHELL_STATUS set of return codes used by shell commands.

The lasterror shell variable allows scripts to test the results of the most recently executed command using the if command. This variable is maintained by the shell, is read-only, and cannot be modified by command set. An example of a script testing to see if a command succeeded would be:

Environment Variables

Environment variables are variables that can hold user-specified contents and can be employed on the command line or in scripts. Each environment variable has a casesensitive name (a C-style identifier) and a string value. Environment variables can be either volatile (they will lose their value on reset or power-off) or non-volatile (they will maintain their value across reset or power-off).

Environment variables can be used on the command line by using %variablename% where variable-name is the environment variable’s name. Variable substitution is not recursive. Environment variables can also be retrieved by a UEFI Shell command by using the GetEnv() function.

Environment variables can be displayed or changed using the set shell command. They can also be changed by a UEFI Shell command using the SetEnv() function. Table C.4 lists the environment variables that have special meaning to the UEFI Shell. Each variable is defined to be Volatile (V) or Non-volatile (NV) as well as having Read-Only (RO) or Read-Write (RW) attributes associated with it:

Table C.4: Table C.4 Shell Environment Variables with Special Meaning

Shell Protocol

Table C.5 summarizes the functions of the EFI_SHELL_PROTOCOL whose purpose is to provide shell services to UEFI applications. This protocol is the workhorse of the UEFI Shell environment and is used to provide abstractions to services that facilitate the interaction with the underlying UEFI services as well as shell features.

Table C.5: Shell Protocol Functions

Shell Parameters Protocol

Table C.6 summarizes the functions of the EFI_SHELL_PARAMETERS_PROTOCOL whose purpose is to handle the shell application’s arguments. This protocol handles state information associated with the command line as well as the current input, output, and error consoles.

Table C.6: Shell Parameters Protocol Functions