Appendix C
Programming Reference

This appendix gives guidance on the programming environment associated with the UEFI Shell. The UEFI Shell provides programmatic interfaces that are not part of the main UEFI specification. The data in this reference should provide some insight into the programmatic interactions that are possible. This appendix is intended to be a useful summary of the UEFI Shell programming environment. However, if more details are required, refer to the UEFI Shell Specification.

Script-based Programming

Even though Appendix B is really intended as the enumeration of all of the shell commands that can be executed by a script, a few aspects of the scripting environment require additional explanation beyond the descriptions of the commands themselves. These topics include:

Parameter passing

Redirection and piping

Return codes

Environment variables

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 – The ability to redirect the output of an application or command to a file or an environment variable. This also includes the ability to use the content of a file or an environment variable as the standard input to an application or command.

Command Piping – The ability to channel the output of an application or command and feed the data to the standard input of another program.

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:

Command [options] > Target – Redirect the output of a command to a target. This will create a new Target and will overwrite any pre-existing item of the same name.

Command [options] >> Target – Append the output of a command to the Target location.

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:

Command [options] < Source – Use the Source as the standard input for the Command.

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:

Command [options] | Command

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

Character Sequence Description
| Pipe output of a command to another program in UCS-2 format.
|a Pipe output of a command to another program in ASCII format.

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

Variable V/NV RO/RW Description
Cwd V/RO The current working directory, including the current working file system.
Lasterror V/RO Last returned error from a UEFI Shell command or batch script
path V/RW The UEFI Shell has a default volatile environment variable path, which contains the default path that UEFI Shell will search if necessary. When the user wants to launch a UEFI application, UEFI Shell will first try to search the current directory if it exists, and then search the path list sequentially. If the application is found in one of the paths, it will stop searching and execute that application. If the application is not found in all the paths, UEFI Shell will report the application is not found.
Profiles NV/RO The list of UEFI Shell command profiles supported by the shell. Each profile name may only contain alphanumericcharacters or the “_” character. Profile names are semicolon (“;”) delimited.
Shellsupport V/RO Reflects the current support level enabled by the currently running shell environment. The contents of thevariable will reflect the text-based numeric version in theform that looks like:
3
This variable is produced by the shell itself and is intended as read-only, any attempt to modify the contentswill be ignored.
uefishellversion V/RO Reflects the revision of the UEFI Shell specification that the shell supports. The contents are formatted as text:2.00
Uefiversion V/RO Reflects the revision of the UEFI specification which the underlying firmware supports. The contents will look likethis:
2.10

Non-Script-based Programming

While the users of shell environments may often focus on the shell commands and scripts, a wide variety of programmatic interfaces are available in the shell environment. In most cases, this kind of infrastructure comes into play when a user wants to create a shell extension (such as a new shell command). One should realize that the UEFI Shell environment is provided by a UEFI application that complies with the UEFI specification. This means that the return codes and underlying system services are at least partially composed of UEFI service calls and conventions. There are, however, two main protocols (programmatic services) that are introduced by the UEFI Shell environment:

Shell Protocol

Shell Parameters Protocol

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

Function Description
BatchIsActive This function tells whether any script files are currently being processed.
CloseFile This function closes a specified file handle. All “dirty” cached file data is flushed to the device, and the file is closed. In all cases the handle is closed.
CreateFile This function creates an empty new file or directory with the specified attributes and returns the new file’s handle.
DeleteFile This function closes and deletes a file. In all cases the file handle is closed.
DeleteFileByName This function deletes the file specified by the file handle.
DisablePageBreak This function disables the page break output mode.
EnablePageBreak This function enables the page break output mode.
Execute This function creates a nested instance of the shell and executes the specified command with the specified environment.
FindFiles This function searches for all files and directories that match the specified file pattern. The file pattern can contain wild-card characters.
FindFilesInDir This function returns all files in a specified directory.
FlushFile This function flushes all modified data associated with a file to a device.
FreeFileList This function cleans up the file list and any related data structures. It has no impact on the files themselves.
GetCurDir This function returns the current directory on a device.
GetDeviceName This function gets the user-readable name of the device specified by the device handle.
GetDevicePathFromFilePath This function gets the device path associated with a mapping.
GetDevicePathFromMap This function converts a file system style name to a device path, by replacing any mapping references to the associated device path.
GetEnv This function returns the current value of the specified environment variable.
GetFileInfo This function allocates a buffer to store the file’s information. It’s the caller’s responsibility to free the buffer.
GetFilePathFromDevicePath This function converts a device path to a file system path by replacing part, or all, of the device path with the file-system mapping.
GetFilePosition This function returns the current file position for the file handle.
GetFileSize This function returns the size of the specified file.
GetHelpText This function returns the help information for the specified command.
GetMapFromDevicePath This function returns the mapping which corresponds to a particular device path.
GetPageBreak User can use this function to determine current page break mode.
IsRootShell This function informs the user whether the active shell is the root shell.
OpenFileByName This function opens the specified file and returns a file handle.
OpenFileList This function opens the files that match the path pattern specified.
OpenRoot This function opens the root directory of a device and returns a file handle to it.
OpenRootByHandle This function returns the root directory of a file system on a particular handle.
ReadFile This function reads the requested number of bytes from the file at the file’s current position and returns them in a buffer.
RemoveDupInFileList This function deletes the duplicate files in the given file list.
SetAlias This function adds or removes the alias for a specific shell command.
SetCurDir This function changes the current directory on a device.
SetEnv This function changes the current value of the specified environment variable.
SetFileInfo This function sets the file information of an opened file handle.
SetFilePosition This function sets the current read/write file position for the handle to the position supplied.
SetMap This function creates, updates, or deletes a mapping between a device and a device path.
WriteFile This function writes the specified number of bytes to the file at the current file position. The current file position is also advanced by the actual number of
bytes written.
ExecutionBreak Event signaled by the UEFI Shell when the user presses Ctrl-C to indicate that the current UEFI Shell command execution should be interrupted.
MajorVersion The major version of the shell environment.
MinorVersion The minor version of the shell environment.

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

Parameter Description
Argv Points to an Argc-element array of points to null-terminated strings containing the command-line parameters. The first entry in the array is always the full file path of the executable. Any quotation marks that were used to preserve whitespace have been removed.
Argc The number of elements in the Argv array.
StdIn The file handle for the standard input for this executable. This may be different from the ConInHandle in the EFI SYSTEM TABLE.
StdOut The file handle for the standard output for this executable. This may be different from the ConOutHandle in the EFI SYSTEM TABLE.
StdErr The file handle for the standard error output for this executable. This may be different from the StdErrHandle in the EFI_SYSTEM_TABLE.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.118.166.106