2 Provides interface to shell internal functions for shell commands.
4 This library is for use ONLY by shell commands linked into the shell application.
5 This library will not function if it is used for UEFI Shell 2.0 Applications.
7 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
8 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
9 (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR>
10 This program and the accompanying materials
11 are licensed and made available under the terms and conditions of the BSD License
12 which accompanies this distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php.
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #ifndef _SHELL_COMMAND_LIB_
21 #define _SHELL_COMMAND_LIB_
25 #include <Protocol/Shell.h>
26 #include <Protocol/ShellParameters.h>
27 #include <Protocol/UnicodeCollation.h>
28 #include <Protocol/SimpleFileSystem.h>
30 #include <Library/UefiBootServicesTableLib.h>
33 // The extern global protocol poionters.
35 extern EFI_UNICODE_COLLATION_PROTOCOL
*gUnicodeCollation
;
36 extern CONST CHAR16
* SupportLevel
[];
39 // The map list objects.
43 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
45 CHAR16
*CurrentDirectoryPath
;
48 /// List of Mappings - DeviceName and Drive Letter(ism).
49 extern SHELL_MAP_LIST gShellMapList
;
50 /// Pointer to node of current directory in the mMapList.
51 extern SHELL_MAP_LIST
*gShellCurMapping
;
54 Returns the help MAN fileName for a given shell command.
56 @retval !NULL The unicode string of the MAN filename.
57 @retval NULL An error ocurred.
62 (EFIAPI
*SHELL_GET_MAN_FILENAME
)(
67 Runs a shell command on a given command line.
69 The specific operation of a given shell command is specified in the UEFI Shell
70 Specification 2.0, or in the source of the given command.
72 Upon completion of the command run the shell protocol and environment variables
73 may have been updated due to the operation.
75 @param[in] ImageHandle The ImageHandle to the app, or NULL if
76 the command built into shell.
77 @param[in] SystemTable The pointer to the system table.
79 @retval RETURN_SUCCESS The shell command was sucessful.
80 @retval RETURN_UNSUPPORTED The command is not supported.
84 (EFIAPI
*SHELL_RUN_COMMAND
)(
85 IN EFI_HANDLE ImageHandle
,
86 IN EFI_SYSTEM_TABLE
*SystemTable
90 Registers the handlers of type SHELL_RUN_COMMAND and
91 SHELL_GET_MAN_FILENAME for each shell command.
93 If the ShellSupportLevel is greater than the value of
94 PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
96 Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
97 with the command specified by CommandString. If the command named by
98 CommandString has already been registered, then return
99 RETURN_ALREADY_STARTED.
101 If there are not enough resources available to register the handlers, then
102 RETURN_OUT_OF_RESOURCES is returned.
104 If CommandString is NULL, then ASSERT().
105 If GetHelpInfoHandler is NULL, then ASSERT().
106 If CommandHandler is NULL, then ASSERT().
107 If ProfileName is NULL, then ASSERT().
109 @param[in] CommandString The pointer to the command name. This is the
110 name to look for on the command line in
112 @param[in] CommandHandler The pointer to a function that runs the
114 @param[in] GetManFileName The pointer to a function that provides man
116 @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
118 @param[in] ProfileName The profile name to require for support of this
120 @param[in] CanAffectLE Indicates whether this command's return value
121 can change the LASTERROR environment variable.
122 @param[in] HiiHandle The handle of this command's HII entry.
123 @param[in] ManFormatHelp The HII locator for the help text.
125 @retval RETURN_SUCCESS The handlers were registered.
126 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
127 register the shell command.
128 @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
129 currently allowed support level.
130 @retval RETURN_ALREADY_STARTED The CommandString represents a command that
131 is already registered. Only one handler set for
132 a given command is allowed.
133 @sa SHELL_GET_MAN_FILENAME
134 @sa SHELL_RUN_COMMAND
138 ShellCommandRegisterCommandName (
139 IN CONST CHAR16
*CommandString
,
140 IN SHELL_RUN_COMMAND CommandHandler
,
141 IN SHELL_GET_MAN_FILENAME GetManFileName
,
142 IN UINT32 ShellMinSupportLevel
,
143 IN CONST CHAR16
*ProfileName
,
144 IN CONST BOOLEAN CanAffectLE
,
145 IN CONST EFI_HANDLE HiiHandle
,
146 IN CONST EFI_STRING_ID ManFormatHelp
150 Checks if a command string has been registered for CommandString, and if so, it runs
151 the previously registered handler for that command with the command line.
153 If CommandString is NULL, then ASSERT().
155 If Sections is specified, then each section name listed will be compared in a case sensitive
156 manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
157 it is appended to the returned help text. If the section does not exist, no
158 information is returned. If Sections is NULL, then all help text information
159 available is returned.
161 @param[in] CommandString The pointer to the command name. This is the name
162 found on the command line in the shell.
163 @param[in, out] RetVal The pointer to the return value from the command handler.
165 @param[in, out] CanAffectLE Indicates whether this command's return value
166 needs to be placed into LASTERROR environment variable.
168 @retval RETURN_SUCCESS The handler was run.
169 @retval RETURN_NOT_FOUND The CommandString did not match a registered
171 @sa SHELL_RUN_COMMAND
175 ShellCommandRunCommandHandler (
176 IN CONST CHAR16
*CommandString
,
177 IN OUT SHELL_STATUS
*RetVal
,
178 IN OUT BOOLEAN
*CanAffectLE OPTIONAL
182 Checks if a command string has been registered for CommandString, and if so, it
183 returns the MAN filename specified for that command.
185 If CommandString is NULL, then ASSERT().
187 @param[in] CommandString The pointer to the command name. This is the name
188 found on the command line in the shell.
190 @retval NULL The CommandString was not a registered command.
191 @retval other The name of the MAN file.
192 @sa SHELL_GET_MAN_FILENAME
196 ShellCommandGetManFileNameHandler (
197 IN CONST CHAR16
*CommandString
203 CHAR16
*CommandString
;
207 Get the list of all available shell internal commands. This is a linked list,
208 via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
209 list functions. Do not modify the values.
211 @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise.
213 @return A linked list of all available shell commands.
217 ShellCommandGetCommandList (
218 IN CONST BOOLEAN Sort
223 CHAR16
*CommandString
;
228 Registers aliases to be set as part of the initialization of the shell application.
230 If Command is NULL, then ASSERT().
231 If Alias is NULL, then ASSERT().
233 @param[in] Command The pointer to the Command.
234 @param[in] Alias The pointer to Alias.
236 @retval RETURN_SUCCESS The handlers were registered.
237 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
238 register the shell command.
242 ShellCommandRegisterAlias (
243 IN CONST CHAR16
*Command
,
244 IN CONST CHAR16
*Alias
248 Get the list of all shell alias commands. This is a linked list,
249 via LIST_ENTRY structure. Enumerate through it using the BaseLib linked
250 list functions. Do not modify the values.
252 @return A linked list of all requested shell aliases.
256 ShellCommandGetInitAliasList (
261 Determine if a given alias is on the list of built in aliases.
263 @param[in] Alias The alias to test for.
265 @retval TRUE The alias is a built in alias.
266 @retval FALSE The alias is not a built in alias.
270 ShellCommandIsOnAliasList (
271 IN CONST CHAR16
*Alias
275 Checks if a command is already on the list.
277 @param[in] CommandString The command string to check for on the list.
279 @retval TRUE CommandString represents a registered command.
280 @retval FALSE CommandString does not represent a registered command.
284 ShellCommandIsCommandOnList (
285 IN CONST CHAR16
*CommandString
289 Get the help text for a command.
291 @param[in] CommandString The command name.
293 @retval NULL No help text was found.
294 @return The string of the help text. The caller required to free.
298 ShellCommandGetCommandHelp (
299 IN CONST CHAR16
*CommandString
303 Function to make sure that the above pointers are valid.
312 Function to determine current state of ECHO. Echo determines if lines from scripts
313 and ECHO commands are enabled.
315 @retval TRUE Echo is currently enabled.
316 @retval FALSE Echo is currently disabled.
320 ShellCommandGetEchoState (
325 Function to set current state of ECHO. Echo determines if lines from scripts
326 and ECHO commands are enabled.
328 @param[in] State TRUE to enable Echo, FALSE otherwise.
332 ShellCommandSetEchoState (
339 Indicate that the current shell or script should exit.
341 @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise.
342 @param[in] ErrorCode The 64 bit error code to return.
346 ShellCommandRegisterExit (
347 IN BOOLEAN ScriptOnly
,
348 IN CONST UINT64 ErrorCode
352 Retrieve the Exit code.
354 @return the value passed into RegisterExit.
358 ShellCommandGetExitCode (
363 Retrieve the Exit indicator.
365 @retval TRUE Exit was indicated.
366 @retval FALSE Exit was not indicated.
370 ShellCommandGetExit (
375 Retrieve the Exit script indicator.
377 If ShellCommandGetExit returns FALSE, then the return from this is undefined.
379 @retval TRUE ScriptOnly was indicated.
380 @retval FALSE ScriptOnly was not indicated.
384 ShellCommandGetScriptExit (
389 LIST_ENTRY Link
; ///< List enumerator items.
390 UINTN Line
; ///< What line of the script file this was on.
391 CHAR16
*Cl
; ///< The original command line.
392 VOID
*Data
; ///< The data structure format dependant upon Command. (not always used)
393 BOOLEAN Reset
; ///< Reset the command (it must be treated like a initial run (but it may have data already))
394 } SCRIPT_COMMAND_LIST
;
397 CHAR16
*ScriptName
; ///< The filename of this script.
398 CHAR16
**Argv
; ///< The parmameters to the script file.
399 UINTN Argc
; ///< The count of parameters.
400 LIST_ENTRY CommandList
; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
401 SCRIPT_COMMAND_LIST
*CurrentCommand
; ///< The command currently being operated. If !=NULL must be a member of CommandList.
402 LIST_ENTRY SubstList
; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
406 Function to return a pointer to the currently running script file object.
408 @retval NULL A script file is not currently running.
409 @return A pointer to the current script file object.
413 ShellCommandGetCurrentScriptFile (
418 Function to set a new script as the currently running one.
420 This function will correctly stack and unstack nested scripts.
422 @param[in] Script The pointer to new script information structure. If NULL,
423 it removes and de-allocates the topmost Script structure.
425 @return A pointer to the current running script file after this
426 change. It is NULL if removing the final script.
430 ShellCommandSetNewScript (
431 IN SCRIPT_FILE
*Script OPTIONAL
435 Function to cleanup all memory from a SCRIPT_FILE structure.
437 @param[in] Script The pointer to the structure to cleanup.
441 DeleteScriptFileStruct (
442 IN SCRIPT_FILE
*Script
446 Function to get the current Profile string.
448 This is used to retrieve what profiles were installed.
450 @retval NULL There are no installed profiles.
451 @return A semicolon-delimited list of profiles.
455 ShellCommandGetProfileList (
460 MappingTypeFileSystem
,
463 } SHELL_MAPPING_TYPE
;
466 Function to generate the next default mapping name.
468 If the return value is not NULL then it must be callee freed.
470 @param Type What kind of mapping name to make.
472 @retval NULL a memory allocation failed.
473 @return a new map name string
477 ShellCommandCreateNewMappingName(
478 IN CONST SHELL_MAPPING_TYPE Type
482 Function to initialize the table for creating consistent map names.
484 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
486 @retval EFI_SUCCESS The table was created successfully.
490 ShellCommandConsistMappingInitialize (
491 EFI_DEVICE_PATH_PROTOCOL
***Table
495 Function to uninitialize the table for creating consistent map names.
497 The parameter must have been received from ShellCommandConsistMappingInitialize.
499 @param[out] Table The pointer to pointer to DevicePathProtocol object.
501 @retval EFI_SUCCESS The table was deleted successfully.
505 ShellCommandConsistMappingUnInitialize (
506 EFI_DEVICE_PATH_PROTOCOL
**Table
510 Create a consistent mapped name for the device specified by DevicePath
513 This must be called after ShellCommandConsistMappingInitialize() and
514 before ShellCommandConsistMappingUnInitialize() is called.
516 @param[in] DevicePath The pointer to the dev path for the device.
517 @param[in] Table The Table of mapping information.
519 @retval NULL A consistent mapped name could not be created.
520 @return A pointer to a string allocated from pool with the device name.
524 ShellCommandConsistMappingGenMappingName (
525 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
526 IN EFI_DEVICE_PATH_PROTOCOL
**Table
530 Function to search the list of mappings for the first matching node on the
531 list based on the MapKey.
533 @param[in] MapKey The pointer to the string key to search for in the map.
535 @return the node on the list.
539 ShellCommandFindMapItem (
540 IN CONST CHAR16
*MapKey
544 Function to add a map node to the list of map items and update the "path" environment variable (optionally).
546 If Path is TRUE (during initialization only), the path environment variable will also be updated to include
547 default paths on the new map name...
549 Path should be FALSE when this function is called from the protocol SetMap function.
551 @param[in] Name The human readable mapped name.
552 @param[in] DevicePath The Device Path for this map.
553 @param[in] Flags The Flags attribute for this map item.
554 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
556 @retval EFI_SUCCESS The addition was sucessful.
557 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
558 @retval EFI_INVALID_PARAMETER A parameter was invalid.
562 ShellCommandAddMapItemAndUpdatePath(
563 IN CONST CHAR16
*Name
,
564 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
565 IN CONST UINT64 Flags
,
566 IN CONST BOOLEAN Path
570 Creates the default map names for each device path in the system with
571 a protocol depending on the Type.
573 Also sets up the default path environment variable if Type is FileSystem.
575 @retval EFI_SUCCESS All map names were created sucessfully.
576 @retval EFI_NOT_FOUND No protocols were found in the system.
577 @return Error returned from gBS->LocateHandle().
583 ShellCommandCreateInitialMappingsAndPaths(
588 Add mappings for any devices without one. Do not change any existing maps.
590 @retval EFI_SUCCESS The operation was successful.
594 ShellCommandUpdateMapping (
599 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
601 @param[in] Handle The SHELL_FILE_HANDLE to convert.
603 @return a EFI_FILE_PROTOCOL* representing the same file.
607 ConvertShellHandleToEfiFileProtocol(
608 IN CONST SHELL_FILE_HANDLE Handle
612 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
614 @param[in] Handle The SHELL_FILE_HANDLE to remove.
616 @retval TRUE The item was removed.
617 @retval FALSE The item was not found.
621 ShellFileHandleRemove(
622 IN CONST SHELL_FILE_HANDLE Handle
626 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
628 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
629 @param[in] Path The path to the file for verification.
631 @return a SHELL_FILE_HANDLE representing the same file.
635 ConvertEfiFileProtocolToShellHandle(
636 IN CONST EFI_FILE_PROTOCOL
*Handle
,
637 IN CONST CHAR16
*Path
641 Find the path that was logged with the specified SHELL_FILE_HANDLE.
643 @param[in] Handle The SHELL_FILE_HANDLE to query on.
645 @return A pointer to the path for the file.
649 ShellFileHandleGetPath(
650 IN CONST SHELL_FILE_HANDLE Handle
655 Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
657 This will NOT work on directories.
659 If Handle is NULL, then ASSERT.
661 @param[in] Handle the file handle
663 @retval TRUE the position is at the end of the file
664 @retval FALSE the position is not at the end of the file
669 IN SHELL_FILE_HANDLE Handle
678 Frees any BUFFER_LIST defined type.
680 @param[in] List The pointer to the list head.
689 Function printing hex output to the console.
691 @param[in] Indent Number of spaces to indent.
692 @param[in] Offset Offset to start with.
693 @param[in] DataSize Length of data.
694 @param[in] UserData Pointer to some data.
706 Dump HEX data into buffer.
708 @param[in] Buffer HEX data to be dumped in Buffer.
709 @param[in] Indent How many spaces to indent the output.
710 @param[in] Offset The offset of the printing.
711 @param[in] DataSize The size in bytes of UserData.
712 @param[in] UserData The data to print out.
723 #endif //_SHELL_COMMAND_LIB_