#include "Shell.h"

Macros
#define	SHELL_MAN_HII_GUID

Functions
CHAR16 *	GetExecuatableFileName (IN CONST CHAR16 *NameString)

CHAR16 *	GetManFileName (IN CONST CHAR16 *ManFileName)

EFI_STATUS	SearchPathForFile (IN CONST CHAR16 FileName, OUT SHELL_FILE_HANDLE Handle)

EFI_STATUS	ManFileFindSections (IN SHELL_FILE_HANDLE Handle, IN CONST CHAR16 Sections, OUT CHAR16 HelpText, OUT UINTN HelpSize, IN BOOLEAN Ascii)

BOOLEAN	IsTitleHeader (IN CONST CHAR16 Command, IN CHAR16 Line, OUT CHAR16 *BriefDesc OPTIONAL, OUT UINTN BriefSize OPTIONAL, OUT BOOLEAN *Found)

EFI_STATUS	ManFileFindTitleSection (IN SHELL_FILE_HANDLE Handle, IN CONST CHAR16 Command, OUT CHAR16 BriefDesc OPTIONAL, OUT UINTN BriefSize OPTIONAL, IN OUT BOOLEAN *Ascii)

EFI_STATUS	ProcessManFile (IN CONST CHAR16 ManFileName, IN CONST CHAR16 Command, IN CONST CHAR16 Sections OPTIONAL, OUT CHAR16 BriefDesc OPTIONAL, OUT CHAR16 *HelpText)

Variables
EFI_HII_HANDLE	mShellManHiiHandle = NULL

EFI_HANDLE	mShellManDriverHandle = NULL

SHELL_MAN_HII_VENDOR_DEVICE_PATH	mShellManHiiDevicePath

Detailed Description

Provides interface to shell MAN file parser.

Definition in file ShellManParser.c.

Macro Definition Documentation

◆ SHELL_MAN_HII_GUID

#define SHELL_MAN_HII_GUID

Value:

{ \
  0xf62ccd0c, 0x2449, 0x453c, { 0x8a, 0xcb, 0x8c, 0xc5, 0x7c, 0xf0, 0x2a, 0x97 } \
}

Definition at line 12 of file ShellManParser.c.

Function Documentation

◆ GetExecuatableFileName()

CHAR16 * GetExecuatableFileName ( IN CONST CHAR16 * NameString )

Verifies that the filename has .EFI on the end.

allocates a new buffer and copies the name (appending .EFI if necessary). Caller to free the buffer.

Parameters

[in] NameString original name string

Returns: the new filename with .efi as the extension.

Definition at line 53 of file ShellManParser.c.

◆ GetManFileName()

CHAR16 * GetManFileName ( IN CONST CHAR16 * ManFileName )

Verifies that the filename has .MAN on the end.

allocates a new buffer and copies the name (appending .MAN if necessary)

ASSERT if ManFileName is NULL

Parameters

[in] ManFileName original filename

Returns: the new filename with .man as the extension.

Definition at line 108 of file ShellManParser.c.

◆ IsTitleHeader()

BOOLEAN IsTitleHeader	(	IN CONST CHAR16 *	Command,
		IN CHAR16 *	Line,
		OUT CHAR16 **BriefDesc	OPTIONAL,
		OUT UINTN *BriefSize	OPTIONAL,
		OUT BOOLEAN *	Found
	)

Parses a line from a MAN file to see if it is the Title Header. If it is, then if the "Brief Description" is desired, allocate a buffer for it and return a copy. Upon a successful return the caller is responsible to free the memory in BriefDesc

Uses a simple state machine that allows "unlimited" whitespace before and after the ".TH", compares Command and the MAN file command name without respect to case, and allows "unlimited" whitespace and '0' and '1' characters before the Short Description. The PCRE regex describing this functionality is: ^\s*.TH\s+(\S)\s[\s01]*(.*)$ where group 1 is the Command Name and group 2 is the Short Description.

Parameters

[in]	Command	name of command whose MAN file we think Line came from
[in]	Line	Pointer to a line from the MAN file
[out]	BriefDesc	pointer to pointer to string where description goes.
[out]	BriefSize	pointer to size of allocated BriefDesc
[out]	Found	TRUE if the Title Header was found and it belongs to Command

Return values

TRUE	Line contained the Title Header
FALSE	Line did not contain the Title Header

Definition at line 337 of file ShellManParser.c.

◆ ManFileFindSections()

EFI_STATUS ManFileFindSections	(	IN SHELL_FILE_HANDLE	Handle,
		IN CONST CHAR16 *	Sections,
		OUT CHAR16 **	HelpText,
		OUT UINTN *	HelpSize,
		IN BOOLEAN	Ascii
	)

Parses through the MAN file specified by SHELL_FILE_HANDLE and returns the detailed help for any sub section specified in the comma separated list of sections provided. If the end of the file or a .TH section is found then return.

Upon a successful return the caller is responsible to free the memory in *HelpText

Parameters

[in]	Handle	FileHandle to read from
[in]	Sections	name of command's sub sections to find
[out]	HelpText	pointer to pointer to string where text goes.
[out]	HelpSize	pointer to size of allocated HelpText (may be updated)
[in]	Ascii	TRUE if the file is ASCII, FALSE otherwise.

Return values

EFI_OUT_OF_RESOURCES	a memory allocation failed.
EFI_SUCCESS	the section was found and its description stored in an allocated buffer.

Definition at line 208 of file ShellManParser.c.

◆ ManFileFindTitleSection()

EFI_STATUS ManFileFindTitleSection	(	IN SHELL_FILE_HANDLE	Handle,
		IN CONST CHAR16 *	Command,
		OUT CHAR16 **BriefDesc	OPTIONAL,
		OUT UINTN *BriefSize	OPTIONAL,
		IN OUT BOOLEAN *	Ascii
	)

Parses through the MAN file specified by SHELL_FILE_HANDLE and returns the "Brief Description" for the .TH section as specified by Command. If the command section is not found return EFI_NOT_FOUND.

Upon a successful return the caller is responsible to free the memory in *BriefDesc

Parameters

[in]	Handle	FileHandle to read from
[in]	Command	name of command's section to find as entered on the command line (may be a relative or absolute path or be in any case: upper, lower, or mixed in numerous ways!).
[out]	BriefDesc	pointer to pointer to string where description goes.
[out]	BriefSize	pointer to size of allocated BriefDesc
[in,out]	Ascii	TRUE if the file is ASCII, FALSE otherwise, will be set if the file handle is at the 0 position.

Return values

EFI_OUT_OF_RESOURCES	a memory allocation failed.
EFI_SUCCESS	the section was found and its description stored in an allocated buffer if requested.

Definition at line 461 of file ShellManParser.c.

◆ ProcessManFile()

EFI_STATUS ProcessManFile	(	IN CONST CHAR16 *	ManFileName,
		IN CONST CHAR16 *	Command,
		IN CONST CHAR16 *Sections	OPTIONAL,
		OUT CHAR16 **BriefDesc	OPTIONAL,
		OUT CHAR16 **	HelpText
	)

This function returns the help information for the specified command. The help text will be parsed from a UEFI Shell manual page. (see UEFI Shell 2.0 Appendix B)

If Sections is specified, then each section name listed will be compared in a casesensitive manner, to the section names described in Appendix B. If the section exists, it will be appended to the returned help text. If the section does not exist, no information will be returned. If Sections is NULL, then all help text information available will be returned.

if BriefDesc is NULL, then the breif description will not be saved separately, but placed first in the main HelpText.

Parameters

[in]	ManFileName	Points to the NULL-terminated UEFI Shell MAN file name.
[in]	Command	Points to the NULL-terminated UEFI Shell command name.
[in]	Sections	Points to the NULL-terminated comma-delimited section names to return. If NULL, then all sections will be returned.
[out]	BriefDesc	On return, points to a callee-allocated buffer containing brief description text.
[out]	HelpText	On return, points to a callee-allocated buffer containing all specified help text.

Return values

EFI_SUCCESS	The help text was returned.
EFI_OUT_OF_RESOURCES	The necessary buffer could not be allocated to hold the returned help text.
EFI_INVALID_PARAMETER	HelpText is NULL.
EFI_INVALID_PARAMETER	ManFileName is invalid.
EFI_INVALID_PARAMETER	Command is invalid.
EFI_NOT_FOUND	There is no help text available for Command.

Definition at line 556 of file ShellManParser.c.

◆ SearchPathForFile()

EFI_STATUS SearchPathForFile	(	IN CONST CHAR16 *	FileName,
		OUT SHELL_FILE_HANDLE *	Handle
	)

Search the path environment variable for possible locations and test for which one contains a man file with the name specified. If a valid file is found stop searching and return the (opened) SHELL_FILE_HANDLE for that file.

Parameters

[in]	FileName	Name of the file to find and open.
[out]	Handle	Pointer to the handle of the found file. The value of this is undefined for return values except EFI_SUCCESS.

Return values

EFI_SUCCESS	The file was found. Handle is a valid SHELL_FILE_HANDLE
EFI_INVALID_PARAMETER	A parameter had an invalid value.
EFI_NOT_FOUND	The file was not found.

Definition at line 159 of file ShellManParser.c.

Variable Documentation

◆ mShellManDriverHandle

EFI_HANDLE mShellManDriverHandle = NULL

Definition at line 18 of file ShellManParser.c.

◆ mShellManHiiDevicePath

SHELL_MAN_HII_VENDOR_DEVICE_PATH mShellManHiiDevicePath

Initial value:

= {
  {
    {
      HARDWARE_DEVICE_PATH,
      HW_VENDOR_DP,
      {
        (UINT8)(sizeof (VENDOR_DEVICE_PATH)),
        (UINT8)((sizeof (VENDOR_DEVICE_PATH)) >> 8)
      }
    },
    SHELL_MAN_HII_GUID
  },
  {
    END_DEVICE_PATH_TYPE,
    END_ENTIRE_DEVICE_PATH_SUBTYPE,
    {
      (UINT8)(END_DEVICE_PATH_LENGTH),
      (UINT8)((END_DEVICE_PATH_LENGTH) >> 8)
    }
  }
}

Definition at line 20 of file ShellManParser.c.

◆ mShellManHiiHandle

EFI_HII_HANDLE mShellManHiiHandle = NULL

Definition at line 17 of file ShellManParser.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SHELL_MAN_HII_GUID

Function Documentation

◆ GetExecuatableFileName()

◆ GetManFileName()

◆ IsTitleHeader()

◆ ManFileFindSections()

◆ ManFileFindTitleSection()

◆ ProcessManFile()

◆ SearchPathForFile()

Variable Documentation

◆ mShellManDriverHandle

◆ mShellManHiiDevicePath

◆ mShellManHiiHandle