2 Main file for Help shell level 3 function.
4 Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved. <BR>
5 Copyright (c) 2014, ARM Limited. All rights reserved. <BR>
6 (C) Copyright 2015 Hewlett-Packard Development Company, L.P.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #include "UefiShellLevel3CommandsLib.h"
20 #include <Library/ShellLib.h>
21 #include <Library/HandleParsingLib.h>
23 #include <Protocol/EfiShellDynamicCommand.h>
26 function to insert string items into a list in the correct alphabetical place
28 the resultant list is a double NULL terminated list of NULL terminated strings.
30 upon successful return the memory must be caller freed (unless passed back in
31 via a loop where it will get reallocated).
33 @param[in,out] DestList double pointer to the list. may be NULL.
34 @param[in,out] DestSize pointer to the size of list. may be 0, if DestList is NULL.
35 @param[in] Item the item to insert.
37 @retval EFI_SUCCESS the operation was successful.
41 LexicalInsertIntoList(
42 IN OUT CHAR16
**DestList
,
43 IN OUT UINTN
*DestSize
,
48 INTN LexicalMatchValue
;
50 UINTN SizeOfAddedNameInBytes
;
53 // If there are none, then just return with success
55 if (Item
== NULL
|| *Item
== CHAR_NULL
|| StrLen(Item
)==0) {
61 SizeOfAddedNameInBytes
= StrSize(Item
);
62 NewList
= ReallocatePool(*DestSize
, (*DestSize
) + SizeOfAddedNameInBytes
, NewList
);
63 (*DestSize
) = (*DestSize
) + SizeOfAddedNameInBytes
;
66 // Find the correct spot in the list
68 for (LexicalSpot
= NewList
69 ; LexicalSpot
!= NULL
&& LexicalSpot
< NewList
+ (*DestSize
)
70 ; LexicalSpot
+= StrLen(LexicalSpot
) + 1
73 // Get Lexical Comparison Value between PrevCommand and Command list entry
75 LexicalMatchValue
= gUnicodeCollation
->StriColl (
77 (CHAR16
*)LexicalSpot
,
81 // The new item goes before this one.
83 if (LexicalMatchValue
> 0 || StrLen(LexicalSpot
) == 0) {
84 if (StrLen(LexicalSpot
) != 0) {
86 // Move this and all other items out of the way
89 LexicalSpot
+ (SizeOfAddedNameInBytes
/sizeof(CHAR16
)),
91 (*DestSize
) - SizeOfAddedNameInBytes
- ((LexicalSpot
- NewList
) * sizeof(CHAR16
))
96 // Stick this one in place
98 StrCpyS(LexicalSpot
, SizeOfAddedNameInBytes
/sizeof(CHAR16
), Item
);
104 return (EFI_SUCCESS
);
108 function to add each command name from the linked list to the string list.
110 the resultant list is a double NULL terminated list of NULL terminated strings.
112 @param[in,out] DestList double pointer to the list. may be NULL.
113 @param[in,out] DestSize pointer to the size of list. may be 0, if DestList is NULL.
114 @param[in] SourceList the double linked list of commands.
116 @retval EFI_SUCCESS the operation was successful.
120 CopyListOfCommandNames(
121 IN OUT CHAR16
**DestList
,
122 IN OUT UINTN
*DestSize
,
123 IN CONST COMMAND_LIST
*SourceList
126 CONST COMMAND_LIST
*Node
;
128 for ( Node
= (COMMAND_LIST
*)GetFirstNode(&SourceList
->Link
)
129 ; SourceList
!= NULL
&& !IsListEmpty(&SourceList
->Link
) && !IsNull(&SourceList
->Link
, &Node
->Link
)
130 ; Node
= (COMMAND_LIST
*)GetNextNode(&SourceList
->Link
, &Node
->Link
)
132 LexicalInsertIntoList(DestList
, DestSize
, Node
->CommandString
);
134 return (EFI_SUCCESS
);
138 function to add each dynamic command name to the string list.
140 the resultant list is a double NULL terminated list of NULL terminated strings.
142 @param[in,out] DestList double pointer to the list. may be NULL.
143 @param[in,out] DestSize pointer to the size of list. may be 0, if DestList is NULL.
145 @retval EFI_SUCCESS the operation was successful.
146 @return an error from HandleProtocol
151 CopyListOfCommandNamesWithDynamic(
152 IN OUT CHAR16
** DestList
,
153 IN OUT UINTN
*DestSize
156 EFI_HANDLE
*CommandHandleList
;
157 CONST EFI_HANDLE
*NextCommand
;
158 EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL
*DynamicCommand
;
161 CommandHandleList
= GetHandleListByProtocol(&gEfiShellDynamicCommandProtocolGuid
);
164 // If there are none, then just return with success
166 if (CommandHandleList
== NULL
) {
167 return (EFI_SUCCESS
);
170 Status
= EFI_SUCCESS
;
173 // Append those to the list.
175 for (NextCommand
= CommandHandleList
; *NextCommand
!= NULL
&& !EFI_ERROR(Status
) ; NextCommand
++) {
176 Status
= gBS
->HandleProtocol(
178 &gEfiShellDynamicCommandProtocolGuid
,
179 (VOID
**)&DynamicCommand
182 if (EFI_ERROR(Status
)) {
186 Status
= LexicalInsertIntoList(DestList
, DestSize
, DynamicCommand
->CommandName
);
189 SHELL_FREE_NON_NULL(CommandHandleList
);
195 Attempt to print help from a dynamically added command.
197 @param[in] CommandToGetHelpOn The unicode name of the command that help is
199 @param[in] SectionToGetHelpOn Pointer to the section specifier(s).
200 @param[in] PrintCommandText Print the command followed by the help content
203 @retval EFI_SUCCESS The help was displayed
204 @retval EFI_NOT_FOUND The command name could not be found
205 @retval EFI_DEVICE_ERROR The help data format was incorrect.
209 PrintDynamicCommandHelp(
210 IN CONST CHAR16
*CommandToGetHelpOn
,
211 IN CONST CHAR16
*SectionToGetHelpOn
,
212 IN BOOLEAN PrintCommandText
217 EFI_HANDLE
*CommandHandleList
;
218 EFI_HANDLE
*NextCommand
;
219 EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL
*DynamicCommand
;
221 Status
= EFI_NOT_FOUND
;
223 CommandHandleList
= NULL
;
225 CommandHandleList
= GetHandleListByProtocol(&gEfiShellDynamicCommandProtocolGuid
);
227 if (CommandHandleList
== NULL
) {
229 // not found or out of resources
234 for (NextCommand
= CommandHandleList
; *NextCommand
!= NULL
; NextCommand
++) {
235 Status
= gBS
->HandleProtocol(
237 &gEfiShellDynamicCommandProtocolGuid
,
238 (VOID
**)&DynamicCommand
241 if (EFI_ERROR(Status
)) {
246 // Check execution break flag when printing multiple command help information.
248 if (ShellGetExecutionBreakFlag ()) {
252 if ((gUnicodeCollation
->MetaiMatch (gUnicodeCollation
, (CHAR16
*)DynamicCommand
->CommandName
, (CHAR16
*)CommandToGetHelpOn
)) ||
253 (gEfiShellProtocol
->GetAlias (CommandToGetHelpOn
, NULL
) != NULL
&& (gUnicodeCollation
->MetaiMatch (gUnicodeCollation
, (CHAR16
*)DynamicCommand
->CommandName
, (CHAR16
*)(gEfiShellProtocol
->GetAlias(CommandToGetHelpOn
, NULL
)))))) {
254 // Print as Shell Help if in ManPage format.
255 Status
= ShellPrintHelp (DynamicCommand
->CommandName
, SectionToGetHelpOn
,
257 if (Status
== EFI_DEVICE_ERROR
) {
258 ShellPrintHiiEx (-1, -1, NULL
, STRING_TOKEN (STR_HELP_INV
),
259 gShellLevel3HiiHandle
, DynamicCommand
->CommandName
);
260 } else if (EFI_ERROR(Status
)) {
261 ShellPrintHiiEx (-1, -1, NULL
, STRING_TOKEN (STR_HELP_NF
),
262 gShellLevel3HiiHandle
, DynamicCommand
->CommandName
);
269 SHELL_FREE_NON_NULL(CommandHandleList
);
271 return (Found
? EFI_SUCCESS
: Status
);
275 STATIC CONST SHELL_PARAM_ITEM ParamList
[] = {
276 {L
"-usage", TypeFlag
},
277 {L
"-section", TypeMaxValue
},
278 {L
"-verbose", TypeFlag
},
284 Function for 'help' command.
286 @param[in] ImageHandle Handle to the Image (NULL if Internal).
287 @param[in] SystemTable Pointer to the System Table (NULL if Internal).
291 ShellCommandRunHelp (
292 IN EFI_HANDLE ImageHandle
,
293 IN EFI_SYSTEM_TABLE
*SystemTable
298 CHAR16
*ProblemParam
;
299 SHELL_STATUS ShellStatus
;
300 CHAR16
*SortedCommandList
;
301 CONST CHAR16
*CurrentCommand
;
302 CHAR16
*CommandToGetHelpOn
;
303 CHAR16
*SectionToGetHelpOn
;
306 BOOLEAN PrintCommandText
;
307 UINTN SortedCommandListSize
;
309 PrintCommandText
= TRUE
;
311 ShellStatus
= SHELL_SUCCESS
;
312 CommandToGetHelpOn
= NULL
;
313 SectionToGetHelpOn
= NULL
;
314 SortedCommandList
= NULL
;
318 // initialize the shell lib (we must be in non-auto-init...)
320 Status
= ShellInitialize();
321 ASSERT_EFI_ERROR(Status
);
323 Status
= CommandInit();
324 ASSERT_EFI_ERROR(Status
);
327 // parse the command line
329 Status
= ShellCommandLineParse (ParamList
, &Package
, &ProblemParam
, TRUE
);
330 if (EFI_ERROR(Status
)) {
331 if (Status
== EFI_VOLUME_CORRUPTED
&& ProblemParam
!= NULL
) {
332 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_GEN_PROBLEM
), gShellLevel3HiiHandle
, L
"help", ProblemParam
);
333 FreePool(ProblemParam
);
334 ShellStatus
= SHELL_INVALID_PARAMETER
;
340 // Check for conflicting parameters.
342 if (ShellCommandLineGetFlag(Package
, L
"-usage")
343 &&ShellCommandLineGetFlag(Package
, L
"-section")
344 &&(ShellCommandLineGetFlag(Package
, L
"-verbose") || ShellCommandLineGetFlag(Package
, L
"-v"))
346 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_GEN_PARAM_CON
), gShellLevel3HiiHandle
, L
"help");
347 ShellStatus
= SHELL_INVALID_PARAMETER
;
348 } else if (ShellCommandLineGetRawValue(Package
, 2) != NULL
) {
349 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_GEN_TOO_MANY
), gShellLevel3HiiHandle
, L
"help");
350 ShellStatus
= SHELL_INVALID_PARAMETER
;
353 // Get the command name we are getting help on
355 ASSERT(CommandToGetHelpOn
== NULL
);
356 StrnCatGrow(&CommandToGetHelpOn
, NULL
, ShellCommandLineGetRawValue(Package
, 1), 0);
357 if (CommandToGetHelpOn
== NULL
&& ShellCommandLineGetFlag(Package
, L
"-?")) {
359 // If we dont have a command and we got a simple -?
360 // we are looking for help on help command.
362 StrnCatGrow(&CommandToGetHelpOn
, NULL
, L
"help", 0);
365 if (CommandToGetHelpOn
== NULL
) {
366 StrnCatGrow(&CommandToGetHelpOn
, NULL
, L
"*", 0);
367 ASSERT(SectionToGetHelpOn
== NULL
);
368 StrnCatGrow(&SectionToGetHelpOn
, NULL
, L
"NAME", 0);
370 PrintCommandText
= FALSE
;
371 ASSERT(SectionToGetHelpOn
== NULL
);
373 // Get the section name for the given command name
375 if (ShellCommandLineGetFlag(Package
, L
"-section")) {
376 StrnCatGrow(&SectionToGetHelpOn
, NULL
, ShellCommandLineGetValue(Package
, L
"-section"), 0);
377 } else if (ShellCommandLineGetFlag(Package
, L
"-usage")) {
378 StrnCatGrow(&SectionToGetHelpOn
, NULL
, L
"NAME,SYNOPSIS", 0);
379 } else if (ShellCommandLineGetFlag(Package
, L
"-verbose") || ShellCommandLineGetFlag(Package
, L
"-v")) {
382 // The output of help <command> will display NAME, SYNOPSIS, OPTIONS, DESCRIPTION, and EXAMPLES sections.
384 StrnCatGrow (&SectionToGetHelpOn
, NULL
, L
"NAME,SYNOPSIS,OPTIONS,DESCRIPTION,EXAMPLES", 0);
388 if (gUnicodeCollation
->StriColl(gUnicodeCollation
, CommandToGetHelpOn
, L
"special") == 0) {
390 // we need info on the special characters
392 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_SC_HEADER
), gShellLevel3HiiHandle
);
393 HiiString
= HiiGetString(gShellLevel3HiiHandle
, STRING_TOKEN(STR_HELP_SC_DATA
), NULL
);
394 ShellPrintEx(-1, -1, L
"%s", HiiString
);
398 SortedCommandList
= NULL
;
399 SortedCommandListSize
= 0;
400 CopyListOfCommandNames(&SortedCommandList
, &SortedCommandListSize
, ShellCommandGetCommandList(TRUE
));
401 CopyListOfCommandNamesWithDynamic(&SortedCommandList
, &SortedCommandListSize
);
403 for (CurrentCommand
= SortedCommandList
404 ; CurrentCommand
!= NULL
&& *CurrentCommand
!= CHAR_NULL
&& CurrentCommand
< SortedCommandList
+ SortedCommandListSize
/sizeof(CHAR16
)
405 ; CurrentCommand
+= StrLen(CurrentCommand
) + 1
408 // Checking execution break flag when print multiple command help information.
410 if (ShellGetExecutionBreakFlag ()) {
414 if ((gUnicodeCollation
->MetaiMatch(gUnicodeCollation
, (CHAR16
*)CurrentCommand
, CommandToGetHelpOn
)) ||
415 (gEfiShellProtocol
->GetAlias(CommandToGetHelpOn
, NULL
) != NULL
&& (gUnicodeCollation
->MetaiMatch(gUnicodeCollation
, (CHAR16
*)CurrentCommand
, (CHAR16
*)(gEfiShellProtocol
->GetAlias(CommandToGetHelpOn
, NULL
)))))) {
417 // We have a command to look for help on.
419 Status
= ShellPrintHelp(CurrentCommand
, SectionToGetHelpOn
, PrintCommandText
);
420 if (EFI_ERROR(Status
)) {
422 // now try to match against the dynamic command list and print help
424 Status
= PrintDynamicCommandHelp (CurrentCommand
, SectionToGetHelpOn
, PrintCommandText
);
426 if (Status
== EFI_DEVICE_ERROR
) {
427 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_INV
), gShellLevel3HiiHandle
, CurrentCommand
);
428 } else if (EFI_ERROR(Status
)) {
429 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_NF
), gShellLevel3HiiHandle
, CurrentCommand
);
437 // Search the .man file for Shell applications (Shell external commands).
440 Status
= ShellPrintHelp(CommandToGetHelpOn
, SectionToGetHelpOn
, FALSE
);
441 if (Status
== EFI_DEVICE_ERROR
) {
442 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_INV
), gShellLevel3HiiHandle
, CommandToGetHelpOn
);
443 } else if (EFI_ERROR(Status
)) {
444 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_NF
), gShellLevel3HiiHandle
, CommandToGetHelpOn
);
452 ShellStatus
= SHELL_NOT_FOUND
;
456 // free the command line package
458 ShellCommandLineFreeVarList (Package
);
462 if (CommandToGetHelpOn
!= NULL
&& StrCmp(CommandToGetHelpOn
, L
"*") == 0){
464 // If '*' then the command entered was 'Help' without qualifiers, This footer
465 // provides additional info on help switches
467 ShellPrintHiiEx(-1, -1, NULL
, STRING_TOKEN (STR_HELP_FOOTER
), gShellLevel3HiiHandle
);
469 if (CommandToGetHelpOn
!= NULL
) {
470 FreePool(CommandToGetHelpOn
);
472 if (SectionToGetHelpOn
!= NULL
) {
473 FreePool(SectionToGetHelpOn
);
475 SHELL_FREE_NON_NULL(SortedCommandList
);
477 return (ShellStatus
);