#include <Uefi.h>
#include <Guid/FileInfo.h>
#include <Protocol/SimpleFileSystem.h>
#include <Protocol/LoadedImage.h>
#include <Protocol/EfiShellInterface.h>
#include <Protocol/EfiShellEnvironment2.h>
#include <Protocol/Shell.h>
#include <Protocol/ShellParameters.h>

Data Structures
struct	SHELL_PARAM_ITEM

Macros
#define	SHELL_FREE_NON_NULL(Pointer)

#define	ShellCommandLineParse(CheckList, CheckPackage, ProblemParam, AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
	Make it easy to upgrade from older versions of the shell library.

Enumerations
enum	SHELL_PARAM_TYPE { TypeFlag = 0 , TypeValue , TypePosition , TypeStart , TypeDoubleValue , TypeMaxValue , TypeTimeValue , TypeMax }

enum	SHELL_PROMPT_REQUEST_TYPE { ShellPromptResponseTypeYesNo , ShellPromptResponseTypeYesNoCancel , ShellPromptResponseTypeFreeform , ShellPromptResponseTypeQuitContinue , ShellPromptResponseTypeYesNoAllCancel , ShellPromptResponseTypeEnterContinue , ShellPromptResponseTypeAnyKeyContinue , ShellPromptResponseTypeMax }

enum	SHELL_PROMPT_RESPONSE { ShellPromptResponseYes , ShellPromptResponseNo , ShellPromptResponseCancel , ShellPromptResponseQuit , ShellPromptResponseContinue , ShellPromptResponseAll , ShellPromptResponseMax }

Functions
CHAR16 *EFIAPI	FullyQualifyPath (IN CONST CHAR16 *Path)

EFI_FILE_INFO *EFIAPI	ShellGetFileInfo (IN SHELL_FILE_HANDLE FileHandle)

EFI_STATUS EFIAPI	ShellSetFileInfo (IN SHELL_FILE_HANDLE FileHandle, IN EFI_FILE_INFO *FileInfo)

EFI_STATUS EFIAPI	ShellOpenFileByDevicePath (IN OUT EFI_DEVICE_PATH_PROTOCOL *FilePath, OUT SHELL_FILE_HANDLE FileHandle, IN UINT64 OpenMode, IN UINT64 Attributes)

EFI_STATUS EFIAPI	ShellOpenFileByName (IN CONST CHAR16 FileName, OUT SHELL_FILE_HANDLE FileHandle, IN UINT64 OpenMode, IN UINT64 Attributes)

EFI_STATUS EFIAPI	ShellCreateDirectory (IN CONST CHAR16 DirectoryName, OUT SHELL_FILE_HANDLE FileHandle)

EFI_STATUS EFIAPI	ShellReadFile (IN SHELL_FILE_HANDLE FileHandle, IN OUT UINTN ReadSize, OUT VOID Buffer)

EFI_STATUS EFIAPI	ShellWriteFile (IN SHELL_FILE_HANDLE FileHandle, IN OUT UINTN BufferSize, IN VOID Buffer)

EFI_STATUS EFIAPI	ShellCloseFile (IN SHELL_FILE_HANDLE *FileHandle)

EFI_STATUS EFIAPI	ShellDeleteFile (IN SHELL_FILE_HANDLE *FileHandle)

EFI_STATUS EFIAPI	ShellSetFilePosition (IN SHELL_FILE_HANDLE FileHandle, IN UINT64 Position)

EFI_STATUS EFIAPI	ShellGetFilePosition (IN SHELL_FILE_HANDLE FileHandle, OUT UINT64 *Position)

EFI_STATUS EFIAPI	ShellFlushFile (IN SHELL_FILE_HANDLE FileHandle)

EFI_STATUS EFIAPI	ShellFindFirstFile (IN SHELL_FILE_HANDLE DirHandle, OUT EFI_FILE_INFO **Buffer)

EFI_STATUS EFIAPI	ShellFindNextFile (IN SHELL_FILE_HANDLE DirHandle, IN OUT EFI_FILE_INFO Buffer, IN OUT BOOLEAN NoFile)

EFI_STATUS EFIAPI	ShellGetFileSize (IN SHELL_FILE_HANDLE FileHandle, OUT UINT64 *Size)

BOOLEAN EFIAPI	ShellGetExecutionBreakFlag (VOID)

CONST CHAR16 *EFIAPI	ShellGetEnvironmentVariable (IN CONST CHAR16 *EnvKey)

EFI_STATUS EFIAPI	ShellSetEnvironmentVariable (IN CONST CHAR16 EnvKey, IN CONST CHAR16 EnvVal, IN BOOLEAN Volatile)

EFI_STATUS EFIAPI	ShellExecute (IN EFI_HANDLE ParentHandle, IN CHAR16 CommandLine, IN BOOLEAN Output, IN CHAR16 *EnvironmentVariables, OUT EFI_STATUS Status)

CONST CHAR16 *EFIAPI	ShellGetCurrentDir (IN CHAR16 *CONST DeviceName OPTIONAL)

VOID EFIAPI	ShellSetPageBreakMode (IN BOOLEAN CurrentState)

EFI_STATUS EFIAPI	ShellOpenFileMetaArg (IN CHAR16 Arg, IN UINT64 OpenMode, IN OUT EFI_SHELL_FILE_INFO *ListHead)

EFI_STATUS EFIAPI	ShellCloseFileMetaArg (IN OUT EFI_SHELL_FILE_INFO **ListHead)

CHAR16 *EFIAPI	ShellFindFilePath (IN CONST CHAR16 *FileName)

CHAR16 *EFIAPI	ShellFindFilePathEx (IN CONST CHAR16 FileName, IN CONST CHAR16 FileExtension)

EFI_STATUS EFIAPI	ShellCommandLineParseEx (IN CONST SHELL_PARAM_ITEM CheckList, OUT LIST_ENTRY CheckPackage, OUT CHAR16 *ProblemParam OPTIONAL, IN BOOLEAN AutoPageBreak, IN BOOLEAN AlwaysAllowNumbers)

VOID EFIAPI	ShellCommandLineFreeVarList (IN LIST_ENTRY *CheckPackage)

BOOLEAN EFIAPI	ShellCommandLineGetFlag (IN CONST LIST_ENTRY CONST CheckPackage, IN CONST CHAR16 CONST KeyString)

CONST CHAR16 *EFIAPI	ShellCommandLineGetValue (IN CONST LIST_ENTRY CheckPackage, IN CHAR16 KeyString)

CONST CHAR16 *EFIAPI	ShellCommandLineGetRawValue (IN CONST LIST_ENTRY *CONST CheckPackage, IN UINTN Position)

UINTN EFIAPI	ShellCommandLineGetCount (IN CONST LIST_ENTRY *CheckPackage)

EFI_STATUS EFIAPI	ShellCommandLineCheckDuplicate (IN CONST LIST_ENTRY CheckPackage, OUT CHAR16 *Param)

EFI_STATUS EFIAPI	ShellInitialize (VOID)

EFI_STATUS EFIAPI	ShellPrintEx (IN INT32 Col OPTIONAL, IN INT32 Row OPTIONAL, IN CONST CHAR16 *Format,...)

EFI_STATUS EFIAPI	ShellPrintHiiEx (IN INT32 Col OPTIONAL, IN INT32 Row OPTIONAL, IN CONST CHAR8 *Language OPTIONAL, IN CONST EFI_STRING_ID HiiFormatStringId, IN CONST EFI_HII_HANDLE HiiFormatHandle,...)

EFI_STATUS EFIAPI	ShellIsDirectory (IN CONST CHAR16 *DirName)

EFI_STATUS EFIAPI	ShellIsFile (IN CONST CHAR16 *Name)

EFI_STATUS EFIAPI	ShellIsFileInPath (IN CONST CHAR16 *Name)

UINTN EFIAPI	ShellStrToUintn (IN CONST CHAR16 *String)

UINTN EFIAPI	ShellHexStrToUintn (IN CONST CHAR16 *String)

CHAR16 *EFIAPI	StrnCatGrow (IN OUT CHAR16 *Destination, IN OUT UINTN CurrentSize, IN CONST CHAR16 *Source, IN UINTN Count)

EFI_STATUS EFIAPI	ShellCopySearchAndReplace (IN CHAR16 CONST SourceString, IN OUT CHAR16 NewString, IN UINTN NewSize, IN CONST CHAR16 FindTarget, IN CONST CHAR16 ReplaceWith, IN CONST BOOLEAN SkipPreCarrot, IN CONST BOOLEAN ParameterReplacing)

BOOLEAN EFIAPI	ShellIsHexaDecimalDigitCharacter (IN CHAR16 Char)

BOOLEAN EFIAPI	ShellIsDecimalDigitCharacter (IN CHAR16 Char)

EFI_STATUS EFIAPI	ShellPromptForResponse (IN SHELL_PROMPT_REQUEST_TYPE Type, IN CHAR16 Prompt OPTIONAL, IN OUT VOID *Response OPTIONAL)

EFI_STATUS EFIAPI	ShellPromptForResponseHii (IN SHELL_PROMPT_REQUEST_TYPE Type, IN CONST EFI_STRING_ID HiiFormatStringId, IN CONST EFI_HII_HANDLE HiiFormatHandle, IN OUT VOID **Response)

BOOLEAN EFIAPI	ShellIsHexOrDecimalNumber (IN CONST CHAR16 *String, IN CONST BOOLEAN ForceHex, IN CONST BOOLEAN StopAtSpace)

EFI_STATUS EFIAPI	ShellConvertStringToUint64 (IN CONST CHAR16 String, OUT UINT64 Value, IN CONST BOOLEAN ForceHex, IN CONST BOOLEAN StopAtSpace)

EFI_STATUS EFIAPI	ShellFileExists (IN CONST CHAR16 *Name)

CHAR16 *EFIAPI	ShellFileHandleReturnLine (IN SHELL_FILE_HANDLE Handle, IN OUT BOOLEAN *Ascii)

EFI_STATUS EFIAPI	ShellFileHandleReadLine (IN SHELL_FILE_HANDLE Handle, IN OUT CHAR16 Buffer, IN OUT UINTN Size, IN BOOLEAN Truncate, IN OUT BOOLEAN *Ascii)

EFI_STATUS EFIAPI	ShellDeleteFileByName (IN CONST CHAR16 *FileName)

EFI_STATUS EFIAPI	ShellPrintHelp (IN CONST CHAR16 CommandToGetHelpOn, IN CONST CHAR16 SectionToGetHelpOn, IN BOOLEAN PrintCommandText)

Variables
EFI_SHELL_PARAMETERS_PROTOCOL *	gEfiShellParametersProtocol

EFI_SHELL_PROTOCOL *	gEfiShellProtocol

SHELL_PARAM_ITEM	EmptyParamList []
	Helper structure for no parameters (besides -? and -b)

SHELL_PARAM_ITEM	SfoParamList []
	Helper structure for -sfo only (besides -? and -b)

Detailed Description

Provides interface to shell functionality for shell commands and applications.

Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
Copyright 2018 Dell Technologies.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file ShellLib.h.

Macro Definition Documentation

◆ SHELL_FREE_NON_NULL

#define SHELL_FREE_NON_NULL ( Pointer )

Value:

  do {                                \
    if ((Pointer) != NULL) {          \
      FreePool((Pointer));            \
      (Pointer) = NULL;               \
    }                                 \
  } while(FALSE)

Definition at line 22 of file ShellLib.h.

◆ ShellCommandLineParse

#define ShellCommandLineParse	(	CheckList,
		CheckPackage,
		ProblemParam,
		AutoPageBreak
	)	ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)

Make it easy to upgrade from older versions of the shell library.

Definition at line 755 of file ShellLib.h.

Enumeration Type Documentation

◆ SHELL_PARAM_TYPE

enum SHELL_PARAM_TYPE

Enumerator
TypeFlag	A flag that is present or not present only (IE "-a").
TypeValue	A flag that has some data following it with a space (IE "-a 1").
TypePosition	Some data that did not follow a parameter (IE "filename.txt").
TypeStart	A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...).
TypeDoubleValue	A flag that has 2 space seperated value data following it (IE "-a 1 2").
TypeMaxValue	A flag followed by all the command line data before the next flag.
TypeTimeValue	A flag that has a time value following it (IE "-a -5:00").

Definition at line 698 of file ShellLib.h.

◆ SHELL_PROMPT_REQUEST_TYPE

enum SHELL_PROMPT_REQUEST_TYPE

What type of answer is requested.

Definition at line 1184 of file ShellLib.h.

◆ SHELL_PROMPT_RESPONSE

enum SHELL_PROMPT_RESPONSE

What answer was given.

Definition at line 1198 of file ShellLib.h.

Function Documentation

◆ FullyQualifyPath()

CHAR16 *EFIAPI FullyQualifyPath ( IN CONST CHAR16 * Path )

Return a clean, fully-qualified version of an input path. If the return value is non-NULL the caller must free the memory when it is no longer needed.

If asserts are disabled, and if the input parameter is NULL, NULL is returned.

If there is not enough memory available to create the fully-qualified path or a copy of the input path, NULL is returned.

If there is no working directory, a clean copy of Path is returned.

Otherwise, the current file system or working directory (as appropriate) is prepended to Path and the resulting path is cleaned and returned.

NOTE: If the input path is an empty string, then the current working directory (if it exists) is returned. In other words, an empty input path is treated exactly the same as ".".

Parameters

[in] Path A pointer to some file or directory path.

Return values

NULL	The input path is NULL or out of memory.
non-NULL	A pointer to a clean, fully-qualified version of Path. If there is no working directory, then a pointer to a clean, but not necessarily fully-qualified version of Path. The caller must free this memory when it is no longer needed.

Definition at line 64 of file UefiShellLib.c.

◆ ShellCloseFile()

EFI_STATUS EFIAPI ShellCloseFile ( IN SHELL_FILE_HANDLE * FileHandle )

Close an open file handle.

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.

Parameters

[in] FileHandle The file handle to close.

Return values

EFI_SUCCESS	The file handle was closed successfully.
INVALID_PARAMETER	One of the parameters has an invalid value.

Close an open file handle.

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.

Parameters

FileHandle the file handle to close.

Return values

EFI_SUCCESS the file handle was closed successfully.

Definition at line 969 of file UefiShellLib.c.

◆ ShellCloseFileMetaArg()

EFI_STATUS EFIAPI ShellCloseFileMetaArg ( IN OUT EFI_SHELL_FILE_INFO ** ListHead )

Free the linked list returned from ShellOpenFileMetaArg.

Parameters

[in,out] ListHead The pointer to free.

Return values

EFI_SUCCESS	The operation was successful.
EFI_INVALID_PARAMETER	A parameter was invalid.

Free the linked list returned from ShellOpenFileMetaArg.

if ListHead is NULL then ASSERT().

Parameters

ListHead the pointer to free.

Return values

EFI_SUCCESS the operation was successful.

Definition at line 1755 of file UefiShellLib.c.

◆ ShellCommandLineCheckDuplicate()

EFI_STATUS EFIAPI ShellCommandLineCheckDuplicate	(	IN CONST LIST_ENTRY *	CheckPackage,
		OUT CHAR16 **	Param
	)

Determines if a parameter is duplicated.

If Param is not NULL, then it will point to a callee-allocated string buffer with the parameter value, if a duplicate is found.

If CheckPackage is NULL, then ASSERT.

Parameters

[in]	CheckPackage	The package of parsed command line arguments.
[out]	Param	Upon finding one, a pointer to the duplicated parameter.

Return values

EFI_SUCCESS	No parameters were duplicated.
EFI_DEVICE_ERROR	A duplicate was found.

Determines if a parameter is duplicated.

If Param is not NULL then it will point to a callee allocated string buffer with the parameter value if a duplicate is found.

If CheckPackage is NULL, then ASSERT.

Parameters

[in]	CheckPackage	The package of parsed command line arguments.
[out]	Param	Upon finding one, a pointer to the duplicated parameter.

Return values

EFI_SUCCESS	No parameters were duplicated.
EFI_DEVICE_ERROR	A duplicate was found.

Definition at line 2736 of file UefiShellLib.c.

◆ ShellCommandLineFreeVarList()

VOID EFIAPI ShellCommandLineFreeVarList ( IN LIST_ENTRY * CheckPackage )

Frees shell variable list that was returned from ShellCommandLineParse.

This function will free all the memory that was used for the CheckPackage list of postprocessed shell arguments.

If CheckPackage is NULL, then return.

Parameters

[in] CheckPackage The list to de-allocate.

Frees shell variable list that was returned from ShellCommandLineParse.

This function will free all the memory that was used for the CheckPackage list of postprocessed shell arguments.

this function has no return value.

if CheckPackage is NULL, then return

Parameters

CheckPackage the list to de-allocate

Definition at line 2445 of file UefiShellLib.c.

◆ ShellCommandLineGetCount()

UINTN EFIAPI ShellCommandLineGetCount ( IN CONST LIST_ENTRY * CheckPackage )

Returns the number of command line value parameters that were parsed.

This will not include flags.

Parameters

[in] CheckPackage The package of parsed command line arguments.

Return values

(UINTN)-1	No parsing has occurred.
other	The number of value parameters found.

returns the number of command line value parameters that were parsed.

this will not include flags.

Parameters

[in] CheckPackage The package of parsed command line arguments.

Return values

(UINTN)-1 No parsing has ocurred

Returns: other The number of value parameters found

Definition at line 2696 of file UefiShellLib.c.

◆ ShellCommandLineGetFlag()

BOOLEAN EFIAPI ShellCommandLineGetFlag	(	IN CONST LIST_ENTRY *CONST	CheckPackage,
		IN CONST CHAR16 *CONST	KeyString
	)

Checks for presence of a flag parameter.

Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.

If CheckPackage is NULL then return FALSE. If KeyString is NULL then ASSERT().

Parameters

[in]	CheckPackage	The package of parsed command line arguments.
[in]	KeyString	The Key of the command line argument to check for.

Return values

TRUE	The flag is on the command line.
FALSE	The flag is not on the command line.

Checks for presence of a flag parameter

flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key

if CheckPackage is NULL then return FALSE. if KeyString is NULL then ASSERT()

Parameters

CheckPackage	The package of parsed command line arguments
KeyString	the Key of the command line argument to check for

Return values

TRUE	the flag is on the command line
FALSE	the flag is not on the command line

Definition at line 2513 of file UefiShellLib.c.

◆ ShellCommandLineGetRawValue()

CONST CHAR16 *EFIAPI ShellCommandLineGetRawValue	(	IN CONST LIST_ENTRY *CONST	CheckPackage,
		IN UINTN	Position
	)

Returns raw value from command line argument.

Raw value parameters are in the form of "value" in a specific position in the list.

If CheckPackage is NULL, then return NULL.

Parameters

[in]	CheckPackage	The package of parsed command line arguments.
[in]	Position	The position of the value.

Return values

NULL	The flag is not on the command line.
!=NULL	The pointer to unicode string of the value.

Definition at line 2651 of file UefiShellLib.c.

◆ ShellCommandLineGetValue()

CONST CHAR16 *EFIAPI ShellCommandLineGetValue	(	IN CONST LIST_ENTRY *	CheckPackage,
		IN CHAR16 *	KeyString
	)

Returns value from command line argument.

Value parameters are in the form of "-<Key> value" or "/<Key> value".

If CheckPackage is NULL, then return NULL.

Parameters

[in]	CheckPackage	The package of parsed command line arguments.
[in]	KeyString	The Key of the command line argument to check for.

Return values

NULL	The flag is not on the command line.
!=NULL	The pointer to unicode string of the value.

Definition at line 2582 of file UefiShellLib.c.

◆ ShellCommandLineParseEx()

EFI_STATUS EFIAPI ShellCommandLineParseEx	(	IN CONST SHELL_PARAM_ITEM *	CheckList,
		OUT LIST_ENTRY **	CheckPackage,
		OUT CHAR16 **ProblemParam	OPTIONAL,
		IN BOOLEAN	AutoPageBreak,
		IN BOOLEAN	AlwaysAllowNumbers
	)

Checks the command line arguments passed against the list of valid ones. Optionally removes NULL values first.

If no initialization is required, then return RETURN_SUCCESS.

Parameters

[in]	CheckList	The pointer to list of parameters to check.
[out]	CheckPackage	The package of checked values.
[out]	ProblemParam	Optional pointer to pointer to unicode string for the paramater that caused failure.
[in]	AutoPageBreak	Will automatically set PageBreakEnabled.
[in]	AlwaysAllowNumbers	Will never fail for number based flags.

Return values

EFI_SUCCESS	The operation completed successfully.
EFI_OUT_OF_RESOURCES	A memory allocation failed.
EFI_INVALID_PARAMETER	A parameter was invalid.
EFI_VOLUME_CORRUPTED	The command line was corrupt.
EFI_DEVICE_ERROR	The commands contained 2 opposing arguments. One of the command line arguments was returned in ProblemParam if provided.
EFI_NOT_FOUND	A argument required a value that was missing. The invalid command line argument was returned in ProblemParam if provided.

Definition at line 2387 of file UefiShellLib.c.

◆ ShellConvertStringToUint64()

EFI_STATUS EFIAPI ShellConvertStringToUint64	(	IN CONST CHAR16 *	String,
		OUT UINT64 *	Value,
		IN CONST BOOLEAN	ForceHex,
		IN CONST BOOLEAN	StopAtSpace
	)

Function to verify and convert a string to its numerical 64 bit representation.

If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.

Parameters

[in]	String	The string to evaluate.
[out]	Value	Upon a successful return the value of the conversion.
[in]	ForceHex	TRUE - always assume hex.
[in]	StopAtSpace	TRUE to halt upon finding a space, FALSE to process the entire String.

Return values

EFI_SUCCESS	The conversion was successful.
EFI_INVALID_PARAMETER	String contained an invalid character.
EFI_NOT_FOUND	String was a number, but Value was NULL.

Function to verify and convert a string to its numerical value.

If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.

Parameters

[in]	String	The string to evaluate.
[out]	Value	Upon a successful return the value of the conversion.
[in]	ForceHex	TRUE - always assume hex.
[in]	StopAtSpace	FALSE to skip spaces.

Return values

EFI_SUCCESS	The conversion was successful.
EFI_INVALID_PARAMETER	String contained an invalid character.
EFI_NOT_FOUND	String was a number, but Value was NULL.

Definition at line 4187 of file UefiShellLib.c.

◆ ShellCopySearchAndReplace()

EFI_STATUS EFIAPI ShellCopySearchAndReplace	(	IN CHAR16 CONST *	SourceString,
		IN OUT CHAR16 *	NewString,
		IN UINTN	NewSize,
		IN CONST CHAR16 *	FindTarget,
		IN CONST CHAR16 *	ReplaceWith,
		IN CONST BOOLEAN	SkipPreCarrot,
		IN CONST BOOLEAN	ParameterReplacing
	)

This is a find and replace function. Upon successful return the NewString is a copy of SourceString with each instance of FindTarget replaced with ReplaceWith.

If SourceString and NewString overlap the behavior is undefined.

If the string would grow bigger than NewSize it will halt and return error.

Parameters

[in]	SourceString	The string with source buffer.
[in,out]	NewString	The string with resultant buffer.
[in]	NewSize	The size in bytes of NewString.
[in]	FindTarget	The string to look for.
[in]	ReplaceWith	The string to replace FindTarget with.
[in]	SkipPreCarrot	If TRUE will skip a FindTarget that has a '^' immediately before it.
[in]	ParameterReplacing	If TRUE will add "" around items with spaces.

Return values

EFI_INVALID_PARAMETER	SourceString was NULL.
EFI_INVALID_PARAMETER	NewString was NULL.
EFI_INVALID_PARAMETER	FindTarget was NULL.
EFI_INVALID_PARAMETER	ReplaceWith was NULL.
EFI_INVALID_PARAMETER	FindTarget had length < 1.
EFI_INVALID_PARAMETER	SourceString had length < 1.
EFI_BUFFER_TOO_SMALL	NewSize was less than the minimum size to hold the new string (truncation occurred).
EFI_SUCCESS	The string was successfully copied with replacement.

Definition at line 2799 of file UefiShellLib.c.

◆ ShellCreateDirectory()

EFI_STATUS EFIAPI ShellCreateDirectory	(	IN CONST CHAR16 *	DirectoryName,
		OUT SHELL_FILE_HANDLE *	FileHandle
	)

This function creates a directory.

If return is EFI_SUCCESS, the Filehandle is the opened directory's handle; otherwise, the Filehandle is NULL. If the directory already existed, this function opens the existing directory.

Parameters

[in]	DirectoryName	The pointer to Directory name.
[out]	FileHandle	The pointer to the file handle.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device, or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

This function create a directory

If return is EFI_SUCCESS, the Filehandle is the opened directory's handle; otherwise, the Filehandle is NULL. If the directory already existed, this function opens the existing directory.

Parameters

DirectoryName	pointer to directory name
FileHandle	pointer to the file handle.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

See also: ShellOpenFileByName

Definition at line 857 of file UefiShellLib.c.

◆ ShellDeleteFile()

EFI_STATUS EFIAPI ShellDeleteFile ( IN SHELL_FILE_HANDLE * FileHandle )

Delete a file and close the handle

This function closes and deletes a file. In all cases the file handle is closed. If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the handle is still closed.

Parameters

[in] FileHandle The file handle to delete.

Return values

EFI_SUCCESS	The file was closed successfully.
EFI_WARN_DELETE_FAILURE	The handle was closed, but the file was not deleted.
INVALID_PARAMETER	One of the parameters has an invalid value.

Delete a file and close the handle

This function closes and deletes a file. In all cases the file handle is closed. If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the handle is still closed.

Parameters

FileHandle the file handle to delete

Return values

EFI_SUCCESS	the file was closed successfully
EFI_WARN_DELETE_FAILURE	the handle was closed, but the file was not deleted
INVALID_PARAMETER	One of the parameters has an invalid value.

Definition at line 992 of file UefiShellLib.c.

◆ ShellDeleteFileByName()

EFI_STATUS EFIAPI ShellDeleteFileByName ( IN CONST CHAR16 * FileName )

Function to delete a file by name

Parameters

[in] FileName Pointer to file name to delete.

Return values

EFI_SUCCESS	the file was deleted successfully
EFI_WARN_DELETE_FAILURE	the handle was closed, but the file was not deleted
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
other	The file failed to open

Function to delete a file by name

Parameters

[in] FileName Pointer to file name to delete.

Return values

EFI_SUCCESS	the file was deleted sucessfully
EFI_WARN_DELETE_FAILURE	the handle was closed, but the file was not deleted
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
other	The file failed to open

Definition at line 4542 of file UefiShellLib.c.

◆ ShellExecute()

EFI_STATUS EFIAPI ShellExecute	(	IN EFI_HANDLE *	ParentHandle,
		IN CHAR16 *	CommandLine,
		IN BOOLEAN	Output,
		IN CHAR16 **	EnvironmentVariables,
		OUT EFI_STATUS *	Status
	)

Cause the shell to parse and execute a command line.

This function creates a nested instance of the shell and executes the specified command (CommandLine) with the specified environment (Environment). Upon return, the status code returned by the specified command is placed in StatusCode. If Environment is NULL, then the current environment is used and all changes made by the commands executed will be reflected in the current environment. If the Environment is non-NULL, then the changes made will be discarded. The CommandLine is executed from the current working directory on the current device.

The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0 environment. The values pointed to by the parameters will be unchanged by the ShellExecute() function. The Output parameter has no effect in a UEFI Shell 2.0 environment.

Parameters

[in]	ParentHandle	The parent image starting the operation.
[in]	CommandLine	The pointer to a NULL terminated command line.
[in]	Output	True to display debug output. False to hide it.
[in]	EnvironmentVariables	Optional pointer to array of environment variables in the form "x=y". If NULL, the current set is used.
[out]	Status	The status of the run command line.

Return values

EFI_SUCCESS	The operation completed successfully. Status contains the status code returned.
EFI_INVALID_PARAMETER	A parameter contains an invalid value.
EFI_OUT_OF_RESOURCES	Out of resources.
EFI_UNSUPPORTED	The operation is not allowed.

◆ ShellFileExists()

EFI_STATUS EFIAPI ShellFileExists ( IN CONST CHAR16 * Name )

Function to determine if a given filename exists.

Parameters

[in] Name Path to test.

Return values

EFI_SUCCESS	The Path represents a file.
EFI_NOT_FOUND	The Path does not represent a file.
other	The path failed to open.

Definition at line 3930 of file UefiShellLib.c.

◆ ShellFileHandleReadLine()

EFI_STATUS EFIAPI ShellFileHandleReadLine	(	IN SHELL_FILE_HANDLE	Handle,
		IN OUT CHAR16 *	Buffer,
		IN OUT UINTN *	Size,
		IN BOOLEAN	Truncate,
		IN OUT BOOLEAN *	Ascii
	)

Function to read a single line (up to but not including the
) from a SHELL_FILE_HANDLE.

If the position upon start is 0, then the Ascii Boolean will be set. This should be maintained and not changed for all operations with the same file.

Parameters

[in]	Handle	SHELL_FILE_HANDLE to read from.
[in,out]	Buffer	The pointer to buffer to read into.
[in,out]	Size	The pointer to number of bytes in Buffer.
[in]	Truncate	If the buffer is large enough, this has no effect. If the buffer is is too small and Truncate is TRUE, the line will be truncated. If the buffer is is too small and Truncate is FALSE, then no read will occur.
[in,out]	Ascii	Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE).

Return values

EFI_SUCCESS	The operation was successful. The line is stored in Buffer.
EFI_END_OF_FILE	There are no more lines in the file.
EFI_INVALID_PARAMETER	Handle was NULL.
EFI_INVALID_PARAMETER	Size was NULL.
EFI_BUFFER_TOO_SMALL	Size was not large enough to store the line. Size was updated to the minimum space required.

Function to read a single line (up to but not including the
) from a SHELL_FILE_HANDLE.

If the position upon start is 0, then the Ascii Boolean will be set. This should be maintained and not changed for all operations with the same file.

NOTE: LINES THAT ARE RETURNED BY THIS FUNCTION ARE UCS2, EVEN IF THE FILE BEING READ IS IN ASCII FORMAT.

Parameters

[in]	Handle	SHELL_FILE_HANDLE to read from.
[in,out]	Buffer	The pointer to buffer to read into. If this function returns EFI_SUCCESS, then on output Buffer will contain a UCS2 string, even if the file being read is ASCII.
[in,out]	Size	On input, pointer to number of bytes in Buffer. On output, unchanged unless Buffer is too small to contain the next line of the file. In that case Size is set to the number of bytes needed to hold the next line of the file (as a UCS2 string, even if it is an ASCII file).
[in]	Truncate	If the buffer is large enough, this has no effect. If the buffer is is too small and Truncate is TRUE, the line will be truncated. If the buffer is is too small and Truncate is FALSE, then no read will occur.
[in,out]	Ascii	Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE).

Return values

EFI_SUCCESS	The operation was successful. The line is stored in Buffer.
EFI_END_OF_FILE	There are no more lines in the file.
EFI_INVALID_PARAMETER	Handle was NULL.
EFI_INVALID_PARAMETER	Size was NULL.
EFI_BUFFER_TOO_SMALL	Size was not large enough to store the line. Size was updated to the minimum space required.

Definition at line 4363 of file UefiShellLib.c.

◆ ShellFileHandleReturnLine()

CHAR16 *EFIAPI ShellFileHandleReturnLine	(	IN SHELL_FILE_HANDLE	Handle,
		IN OUT BOOLEAN *	Ascii
	)

Function to read a single line from a SHELL_FILE_HANDLE. The
is not included in the returned buffer. The returned buffer must be callee freed.

If the position upon start is 0, then the Ascii Boolean will be set. This should be maintained and not changed for all operations with the same file.

Parameters

[in]	Handle	SHELL_FILE_HANDLE to read from.
[in,out]	Ascii	Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE).

Returns: The line of text from the file.

See also: ShellFileHandleReadLine

Function to read a single line from a SHELL_FILE_HANDLE. The
is not included in the returned buffer. The returned buffer must be callee freed.

If the position upon start is 0, then the Ascii Boolean will be set. This should be maintained and not changed for all operations with the same file.

Parameters

[in]	Handle	SHELL_FILE_HANDLE to read from.
[in,out]	Ascii	Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE).

Returns: The line of text from the file.

Return values

NULL	There was not enough memory available.

See also: ShellFileHandleReadLine

Definition at line 4290 of file UefiShellLib.c.

◆ ShellFindFilePath()

CHAR16 *EFIAPI ShellFindFilePath ( IN CONST CHAR16 * FileName )

Find a file by searching the CWD and then the path.

If FileName is NULL, then ASSERT.

If the return value is not NULL then the memory must be caller freed.

Parameters

[in] FileName Filename string.

Return values

NULL	The file was not found.
!NULL	The path to the file.

Find a file by searching the CWD and then the path.

If FileName is NULL then ASSERT.

If the return value is not NULL then the memory must be caller freed.

Parameters

FileName Filename string.

Return values

NULL	the file was not found

Returns: !NULL the full path to the file.

Definition at line 1809 of file UefiShellLib.c.

◆ ShellFindFilePathEx()

CHAR16 *EFIAPI ShellFindFilePathEx	(	IN CONST CHAR16 *	FileName,
		IN CONST CHAR16 *	FileExtension
	)

Find a file by searching the CWD and then the path with a variable set of file extensions. If the file is not found it will append each extension in the list in the order provided and return the first one that is successful.

If FileName is NULL, then ASSERT. If FileExtension is NULL, then the behavior is identical to ShellFindFilePath.

If the return value is not NULL then the memory must be caller freed.

Parameters

[in]	FileName	The filename string.
[in]	FileExtension	Semicolon delimited list of possible extensions.

Return values

NULL	The file was not found.
!NULL	The path to the file.

Find a file by searching the CWD and then the path with a variable set of file extensions. If the file is not found it will append each extension in the list in the order provided and return the first one that is successful.

If FileName is NULL, then ASSERT. If FileExtension is NULL, then behavior is identical to ShellFindFilePath.

If the return value is not NULL then the memory must be caller freed.

Parameters

[in]	FileName	Filename string.
[in]	FileExtension	Semi-colon delimeted list of possible extensions.

Return values

NULL	The file was not found.
!NULL	The path to the file.

Definition at line 1938 of file UefiShellLib.c.

◆ ShellFindFirstFile()

EFI_STATUS EFIAPI ShellFindFirstFile	(	IN SHELL_FILE_HANDLE	DirHandle,
		OUT EFI_FILE_INFO **	Buffer
	)

Retrieve first entry from a directory.

This function takes an open directory handle and gets information from the first entry in the directory. A buffer is allocated to contain the information and a pointer to the buffer is returned in *Buffer. The caller can use ShellFindNextFile() to get subsequent directory entries.

The buffer will be freed by ShellFindNextFile() when the last directory entry is read. Otherwise, the caller must free the buffer, using FreePool, when finished with it.

Parameters

[in]	DirHandle	The file handle of the directory to search.
[out]	Buffer	The pointer to the buffer for the file's information.

Return values

EFI_SUCCESS	Found the first file.
EFI_NOT_FOUND	Cannot find the directory.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

Returns: Others Status of ShellGetFileInfo, ShellSetFilePosition, or ShellReadFile.

See also: ShellReadFile

Retrieve first entry from a directory.

This function takes an open directory handle and gets information from the first entry in the directory. A buffer is allocated to contain the information and a pointer to the buffer is returned in *Buffer. The caller can use ShellFindNextFile() to get subsequent directory entries.

The buffer will be freed by ShellFindNextFile() when the last directory entry is read. Otherwise, the caller must free the buffer, using FreePool, when finished with it.

Parameters

[in]	DirHandle	The file handle of the directory to search.
[out]	Buffer	The pointer to the buffer for the file's information.

Return values

EFI_SUCCESS	Found the first file.
EFI_NOT_FOUND	Cannot find the directory.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

Returns: Others status of ShellGetFileInfo, ShellSetFilePosition, or ShellReadFile

Definition at line 1100 of file UefiShellLib.c.

◆ ShellFindNextFile()

EFI_STATUS EFIAPI ShellFindNextFile	(	IN SHELL_FILE_HANDLE	DirHandle,
		IN OUT EFI_FILE_INFO *	Buffer,
		IN OUT BOOLEAN *	NoFile
	)

Retrieve next entries from a directory.

To use this function, the caller must first call the ShellFindFirstFile() function to get the first directory entry. Subsequent directory entries are retrieved by using the ShellFindNextFile() function. This function can be called several times to get each entry from the directory. If the call of ShellFindNextFile() retrieved the last directory entry, the next call of this function will set *NoFile to TRUE and free the buffer.

Parameters

[in]	DirHandle	The file handle of the directory.
[in,out]	Buffer	The pointer to buffer for file's information.
[in,out]	NoFile	The pointer to boolean when last file is found.

Return values

EFI_SUCCESS	Found the next file.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

See also: ShellReadFile

◆ ShellFlushFile()

EFI_STATUS EFIAPI ShellFlushFile ( IN SHELL_FILE_HANDLE FileHandle )

Flushes data on a file

This function flushes all modified data associated with a file to a device.

Parameters

[in] FileHandle The file handle on which to flush data.

Return values

EFI_SUCCESS	The data was flushed.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened for read only.

Flushes data on a file

This function flushes all modified data associated with a file to a device.

Parameters

FileHandle The file handle on which to flush data

Return values

EFI_SUCCESS	The data was flushed.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened for read only.

Definition at line 1069 of file UefiShellLib.c.

◆ ShellGetCurrentDir()

CONST CHAR16 *EFIAPI ShellGetCurrentDir ( IN CHAR16 *CONST DeviceName OPTIONAL )

Retreives the current directory path.

If the DeviceName is NULL, it returns the current device's current directory name. If the DeviceName is not NULL, it returns the current directory name on specified drive.

Note that the current directory string should exclude the tailing backslash character.

Parameters

[in] DeviceName The name of the file system to get directory on.

Return values

NULL	The directory does not exist.
!=	NULL The directory.

Retreives the current directory path

If the DeviceName is NULL, it returns the current device's current directory name. If the DeviceName is not NULL, it returns the current directory name on specified drive.

Note that the current directory string should exclude the tailing backslash character.

Parameters

DeviceName the name of the drive to get directory on

Return values

NULL	the directory does not exist

Returns: != NULL the directory

Definition at line 1403 of file UefiShellLib.c.

◆ ShellGetEnvironmentVariable()

CONST CHAR16 *EFIAPI ShellGetEnvironmentVariable ( IN CONST CHAR16 * EnvKey )

Return the value of an environment variable.

This function gets the value of the environment variable set by the ShellSetEnvironmentVariable function.

Parameters

[in] EnvKey The key name of the environment variable.

Return values

NULL	The named environment variable does not exist.

Returns: != NULL The pointer to the value of the environment variable.

return the value of an environment variable

this function gets the value of the environment variable set by the ShellSetEnvironmentVariable function

Parameters

EnvKey The key name of the environment variable.

Return values

NULL	the named environment variable does not exist.

Returns: != NULL pointer to the value of the environment variable

Definition at line 1219 of file UefiShellLib.c.

◆ ShellGetExecutionBreakFlag()

BOOLEAN EFIAPI ShellGetExecutionBreakFlag ( VOID )

Retrieves the status of the break execution flag

This function is useful to check whether the application is being asked to halt by the shell.

Return values

TRUE	The execution break is enabled.
FALSE	The execution break is not enabled.

Retrieves the status of the break execution flag

this function is useful to check whether the application is being asked to halt by the shell.

Return values

TRUE	the execution break is enabled
FALSE	the execution break is not enabled

Definition at line 1178 of file UefiShellLib.c.

◆ ShellGetFileInfo()

EFI_FILE_INFO *EFIAPI ShellGetFileInfo ( IN SHELL_FILE_HANDLE FileHandle )

This function will retrieve the information about the file for the handle specified and store it in allocated pool memory.

This function allocates a buffer to store the file's information. It is the caller's responsibility to free the buffer.

Parameters

[in] FileHandle The file handle of the file for which information is being requested.

Return values

NULL	Information could not be retrieved.

Returns: The information about the file.

This function will retrieve the information about the file for the handle specified and store it in allocated pool memory.

This function allocates a buffer to store the file's information. It is the caller's responsibility to free the buffer

Parameters

FileHandle The file handle of the file for which information is being requested.

Return values

NULL	information could not be retrieved.

Returns: the information about the file

Definition at line 573 of file UefiShellLib.c.

◆ ShellGetFilePosition()

EFI_STATUS EFIAPI ShellGetFilePosition	(	IN SHELL_FILE_HANDLE	FileHandle,
		OUT UINT64 *	Position
	)

Gets a file's current position

This function retrieves the current file position for the file handle. For directories, the current file position has no meaning outside of the file system driver and as such the operation is not supported. An error is returned if FileHandle is a directory.

Parameters

[in]	FileHandle	The open file handle on which to get the position.
[out]	Position	The byte position from the beginning of the file.

Return values

EFI_SUCCESS	The operation completed successfully.
INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	The request is not valid on directories.

Gets a file's current position

This function retrieves the current file position for the file handle. For directories, the current file position has no meaning outside of the file system driver and as such the operation is not supported. An error is returned if FileHandle is a directory.

Parameters

FileHandle	The open file handle on which to get the position.
Position	Byte position from beginning of file.

Return values

EFI_SUCCESS	the operation completed successfully.
INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	the request is not valid on directories.

Definition at line 1045 of file UefiShellLib.c.

◆ ShellGetFileSize()

EFI_STATUS EFIAPI ShellGetFileSize	(	IN SHELL_FILE_HANDLE	FileHandle,
		OUT UINT64 *	Size
	)

Retrieve the size of a file.

This function extracts the file size info from the FileHandle's EFI_FILE_INFO data.

Parameters

[in]	FileHandle	The file handle from which size is retrieved.
[out]	Size	The pointer to size.

Return values

EFI_SUCCESS	The operation was completed successfully.
EFI_DEVICE_ERROR	Cannot access the file.

Retrieve the size of a file.

if FileHandle is NULL then ASSERT() if Size is NULL then ASSERT()

This function extracts the file size info from the FileHandle's EFI_FILE_INFO data.

Parameters

FileHandle	file handle from which size is retrieved
Size	pointer to size

Return values

EFI_SUCCESS	operation was completed successfully
EFI_DEVICE_ERROR	cannot access the file

Definition at line 1160 of file UefiShellLib.c.

◆ ShellHexStrToUintn()

UINTN EFIAPI ShellHexStrToUintn ( IN CONST CHAR16 * String )

Function return the number converted from a hex representation of a number.

Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid result. Use ShellConvertStringToUint64 instead.

Parameters

[in] String String representation of a number.

Returns: The unsigned integer result of the conversion.

Return values

(UINTN)(-1) An error occurred.

Definition at line 3344 of file UefiShellLib.c.

◆ ShellInitialize()

EFI_STATUS EFIAPI ShellInitialize ( VOID )

This function causes the shell library to initialize itself. If the shell library is already initialized it will de-initialize all the current protocol pointers and re-populate them again.

When the library is used with PcdShellLibAutoInitialize set to true this function will return EFI_SUCCESS and perform no actions.

This function is intended for internal access for shell commands only.

Return values

EFI_SUCCESS The initialization was complete successfully.

This function causes the shell library to initialize itself. If the shell library is already initialized it will de-initialize all the current protocol pointers and re-populate them again.

When the library is used with PcdShellLibAutoInitialize set to true this function will return EFI_SUCCESS and perform no actions.

This function is intended for internal access for shell commands only.

Return values

EFI_SUCCESS the initialization was complete successfully

Definition at line 532 of file UefiShellLib.c.

◆ ShellIsDecimalDigitCharacter()

BOOLEAN EFIAPI ShellIsDecimalDigitCharacter ( IN CHAR16 Char )

Check if a Unicode character is a decimal character.

This internal function checks if a Unicode character is a decimal character. The valid characters are L'0' to L'9'.

Parameters

Char	The character to check against.

Return values

TRUE	The Char is a hexadecmial character.
FALSE	The Char is not a hexadecmial character.

Check if a Unicode character is a decimal character.

This internal function checks if a Unicode character is a decimal character. The valid characters are L'0' to L'9'.

Parameters

Char	The character to check against.

Return values

TRUE	If the Char is a hexadecmial character.
FALSE	If the Char is not a hexadecmial character.

Definition at line 194 of file UefiShellLib.c.

◆ ShellIsDirectory()

EFI_STATUS EFIAPI ShellIsDirectory ( IN CONST CHAR16 * DirName )

Function to determine if a given filename represents a directory.

If DirName is NULL, then ASSERT.

Parameters

[in] DirName Path to directory to test.

Return values

EFI_SUCCESS	The Path represents a directory.
EFI_NOT_FOUND	The Path does not represent a directory.
other	The path failed to open.

Function to determine if a given filename represents a file or a directory.

Parameters

[in] DirName Path to directory to test.

Return values

EFI_SUCCESS	The Path represents a directory
EFI_NOT_FOUND	The Path does not represent a directory
EFI_OUT_OF_RESOURCES	A memory allocation failed.

Returns: The path failed to open

Definition at line 3200 of file UefiShellLib.c.

◆ ShellIsFile()

EFI_STATUS EFIAPI ShellIsFile ( IN CONST CHAR16 * Name )

Function to determine if a given filename represents a file.

This will search the CWD only.

If Name is NULL, then ASSERT.

Parameters

[in] Name Path to file to test.

Return values

EFI_SUCCESS	The Path represents a file.
EFI_NOT_FOUND	The Path does not represent a file.
other	The path failed to open.

Function to determine if a given filename represents a file.

Parameters

[in] Name Path to file to test.

Return values

EFI_SUCCESS	The Path represents a file.
EFI_NOT_FOUND	The Path does not represent a file.
other	The path failed to open.

Definition at line 3270 of file UefiShellLib.c.

◆ ShellIsFileInPath()

EFI_STATUS EFIAPI ShellIsFileInPath ( IN CONST CHAR16 * Name )

Function to determine if a given filename represents a file.

This will search the CWD and then the Path.

If Name is NULL, then ASSERT.

Parameters

[in] Name Path to file to test.

Return values

EFI_SUCCESS	The Path represents a file.
EFI_NOT_FOUND	The Path does not represent a file.
other	The path failed to open.

Definition at line 3310 of file UefiShellLib.c.

◆ ShellIsHexaDecimalDigitCharacter()

BOOLEAN EFIAPI ShellIsHexaDecimalDigitCharacter ( IN CHAR16 Char )

Check if a Unicode character is a hexadecimal character.

This internal function checks if a Unicode character is a numeric character. The valid hexadecimal characters are L'0' to L'9', L'a' to L'f', or L'A' to L'F'.

Parameters

Char	The character to check against.

Return values

TRUE	The Char is a hexadecmial character.
FALSE	The Char is not a hexadecmial character.

Check if a Unicode character is a hexadecimal character.

This internal function checks if a Unicode character is a numeric character. The valid hexadecimal characters are L'0' to L'9', L'a' to L'f', or L'A' to L'F'.

Parameters

Char	The character to check against.

Return values

TRUE	If the Char is a hexadecmial character.
FALSE	If the Char is not a hexadecmial character.

Definition at line 171 of file UefiShellLib.c.

◆ ShellIsHexOrDecimalNumber()

BOOLEAN EFIAPI ShellIsHexOrDecimalNumber	(	IN CONST CHAR16 *	String,
		IN CONST BOOLEAN	ForceHex,
		IN CONST BOOLEAN	StopAtSpace
	)

Function to determin if an entire string is a valid number.

If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.

Parameters

[in]	String	The string to evaluate.
[in]	ForceHex	TRUE - always assume hex.
[in]	StopAtSpace	TRUE to halt upon finding a space, FALSE to keep going.

Return values

TRUE	It is all numeric (dec/hex) characters.
FALSE	There is a non-numeric character.

Function to determin if an entire string is a valid number.

If Hex it must be preceeded with a 0x or has ForceHex, set TRUE.

Parameters

[in]	String	The string to evaluate.
[in]	ForceHex	TRUE - always assume hex.
[in]	StopAtSpace	TRUE to halt upon finding a space, FALSE to keep going.

Return values

TRUE	It is all numeric (dec/hex) characters.
FALSE	There is a non-numeric character.

Definition at line 4259 of file UefiShellLib.c.

◆ ShellOpenFileByDevicePath()

EFI_STATUS EFIAPI ShellOpenFileByDevicePath	(	IN OUT EFI_DEVICE_PATH_PROTOCOL **	FilePath,
		OUT SHELL_FILE_HANDLE *	FileHandle,
		IN UINT64	OpenMode,
		IN UINT64	Attributes
	)

This function will open a file or directory referenced by DevicePath.

This function opens a file with the open mode according to the file path. The Attributes is valid only for EFI_FILE_MODE_CREATE.

Parameters

[in,out]	FilePath	On input, the device path to the file. On output, the remaining device path.
[out]	FileHandle	Pointer to the file handle.
[in]	OpenMode	The mode to open the file with.
[in]	Attributes	The file's file attributes.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

This function will open a file or directory referenced by DevicePath.

This function opens a file with the open mode according to the file path. The Attributes is valid only for EFI_FILE_MODE_CREATE.

Parameters

FilePath	on input the device path to the file. On output the remaining device path.
FileHandle	pointer to the file handle.
OpenMode	the mode to open the file with.
Attributes	the file's file attributes.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

Definition at line 640 of file UefiShellLib.c.

◆ ShellOpenFileByName()

EFI_STATUS EFIAPI ShellOpenFileByName	(	IN CONST CHAR16 *	FileName,
		OUT SHELL_FILE_HANDLE *	FileHandle,
		IN UINT64	OpenMode,
		IN UINT64	Attributes
	)

This function will open a file or directory referenced by filename.

If return is EFI_SUCCESS, the Filehandle is the opened file's handle; otherwise, the Filehandle is NULL. Attributes is valid only for EFI_FILE_MODE_CREATE.

Parameters

[in]	FileName	The pointer to file name.
[out]	FileHandle	The pointer to the file handle.
[in]	OpenMode	The mode to open the file with.
[in]	Attributes	The file's file attributes.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

This function will open a file or directory referenced by filename.

If return is EFI_SUCCESS, the Filehandle is the opened file's handle; otherwise, the Filehandle is NULL. The Attributes is valid only for EFI_FILE_MODE_CREATE.

if FileName is NULL then ASSERT()

Parameters

FileName	pointer to file name
FileHandle	pointer to the file handle.
OpenMode	the mode to open the file with.
Attributes	the file's file attributes.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	Could not open the file path.
EFI_NOT_FOUND	The specified file could not be found on the device or the file system could not be found on the device.
EFI_NO_MEDIA	The device has no medium.
EFI_MEDIA_CHANGED	The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_OUT_OF_RESOURCES	Not enough resources were available to open the file.
EFI_VOLUME_FULL	The volume is full.

Definition at line 720 of file UefiShellLib.c.

◆ ShellOpenFileMetaArg()

EFI_STATUS EFIAPI ShellOpenFileMetaArg	(	IN CHAR16 *	Arg,
		IN UINT64	OpenMode,
		IN OUT EFI_SHELL_FILE_INFO **	ListHead
	)

Opens a group of files based on a path.

This function uses the Arg to open all the matching files. Each matched file has a SHELL_FILE_ARG structure to record the file information. These structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG structures from ListHead to access each file. This function supports wildcards and will process '?' and '*' as such. The list must be freed with a call to ShellCloseFileMetaArg().

If you are NOT appending to an existing list *ListHead must be NULL. If ListHead is NULL then it must be callee freed.

Parameters

[in]	Arg	The pointer to path string.
[in]	OpenMode	Mode to open files with.
[in,out]	ListHead	Head of linked list of results.

Return values

EFI_SUCCESS	The operation was successful and the list head contains the list of opened files.
!=	EFI_SUCCESS The operation failed.

See also: InternalShellConvertFileListType

Opens a group of files based on a path.

This function uses the Arg to open all the matching files. Each matched file has a SHELL_FILE_INFO structure to record the file information. These structures are placed on the list ListHead. Users can get the SHELL_FILE_INFO structures from ListHead to access each file. This function supports wildcards and will process '?' and '*' as such. the list must be freed with a call to ShellCloseFileMetaArg().

If you are NOT appending to an existing list *ListHead must be NULL. If ListHead is NULL then it must be callee freed.

Parameters

Arg	pointer to path string
OpenMode	mode to open files with
ListHead	head of linked list of results

Return values

EFI_SUCCESS the operation was successful and the list head contains the list of opened files

Returns: != EFI_SUCCESS the operation failed

See also: InternalShellConvertFileListType

Definition at line 1632 of file UefiShellLib.c.

◆ ShellPrintEx()

EFI_STATUS EFIAPI ShellPrintEx	(	IN INT32 Col	OPTIONAL,
		IN INT32 Row	OPTIONAL,
		IN CONST CHAR16 *	Format,
			...
	)

Print at a specific location on the screen.

This function will move the cursor to a given screen location and print the specified string.

If -1 is specified for either the Row or Col the current screen location for BOTH will be used.

If either Row or Col is out of range for the current console, then ASSERT. If Format is NULL, then ASSERT.

In addition to the standard %-based flags as supported by UefiLib Print() this supports the following additional flags: N - Set output attribute to normal H - Set output attribute to highlight E - Set output attribute to error B - Set output attribute to blue color V - Set output attribute to green color

Note: The background color is controlled by the shell command cls.

Parameters

[in]	Col	The column to print at.
[in]	Row	The row to print at.
[in]	Format	The format string.
[in]	...	The variable argument list.

Returns: EFI_SUCCESS The printing was successful.; EFI_DEVICE_ERROR The console device reported an error.

Print at a specific location on the screen.

This function will move the cursor to a given screen location and print the specified string.

If -1 is specified for either the Row or Col the current screen location for BOTH will be used.

If either Row or Col is out of range for the current console, then ASSERT. If Format is NULL, then ASSERT.

In addition to the standard %-based flags as supported by UefiLib Print() this supports the following additional flags: N - Set output attribute to normal H - Set output attribute to highlight E - Set output attribute to error B - Set output attribute to blue color V - Set output attribute to green color

Note: The background color is controlled by the shell command cls.

Parameters

[in]	Col	the column to print at
[in]	Row	the row to print at
[in]	Format	the format string
[in]	...	The variable argument list.

Returns: EFI_SUCCESS The printing was successful.; EFI_DEVICE_ERROR The console device reported an error.

Definition at line 3107 of file UefiShellLib.c.

◆ ShellPrintHelp()

EFI_STATUS EFIAPI ShellPrintHelp	(	IN CONST CHAR16 *	CommandToGetHelpOn,
		IN CONST CHAR16 *	SectionToGetHelpOn,
		IN BOOLEAN	PrintCommandText
	)

Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function.

Parameters

[in]	CommandToGetHelpOn	Pointer to a string containing the command name of help file to be printed.
[in]	SectionToGetHelpOn	Pointer to the section specifier(s).
[in]	PrintCommandText	If TRUE, prints the command followed by the help content, otherwise prints the help content only.

Return values

EFI_DEVICE_ERROR	The help data format was incorrect.
EFI_NOT_FOUND	The help data could not be found.
EFI_SUCCESS	The operation was successful.

Definition at line 4469 of file UefiShellLib.c.

◆ ShellPrintHiiEx()

EFI_STATUS EFIAPI ShellPrintHiiEx	(	IN INT32 Col	OPTIONAL,
		IN INT32 Row	OPTIONAL,
		IN CONST CHAR8 *Language	OPTIONAL,
		IN CONST EFI_STRING_ID	HiiFormatStringId,
		IN CONST EFI_HII_HANDLE	HiiFormatHandle,
			...
	)

Print at a specific location on the screen.

This function will move the cursor to a given screen location and print the specified string.

If -1 is specified for either the Row or Col the current screen location for BOTH will be used.

If either Row or Col is out of range for the current console, then ASSERT. If Format is NULL, then ASSERT.

In addition to the standard %-based flags as supported by UefiLib Print() this supports the following additional flags: N - Set output attribute to normal. H - Set output attribute to highlight. E - Set output attribute to error. B - Set output attribute to blue color. V - Set output attribute to green color.

Note: The background color is controlled by the shell command cls.

Parameters

[in]	Col	The column to print at.
[in]	Row	The row to print at.
[in]	Language	The language of the string to retrieve. If this parameter is NULL, then the current platform language is used.
[in]	HiiFormatStringId	The format string Id for getting from Hii.
[in]	HiiFormatHandle	The format string Handle for getting from Hii.
[in]	...	The variable argument list.

Returns: EFI_SUCCESS The printing was successful.; EFI_DEVICE_ERROR The console device reported an error.

Definition at line 3161 of file UefiShellLib.c.

◆ ShellPromptForResponse()

EFI_STATUS EFIAPI ShellPromptForResponse	(	IN SHELL_PROMPT_REQUEST_TYPE	Type,
		IN CHAR16 *Prompt	OPTIONAL,
		IN OUT VOID **Response	OPTIONAL
	)

Prompt the user and return the resultant answer to the requestor.

This function will display the requested question on the shell prompt and then wait for an appropriate answer to be input from the console.

If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.

If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then Response is of type CHAR16.

In either case *Response must be callee freed if Response was not NULL;

Parameters

Type	What type of question is asked. This is used to filter the input to prevent invalid answers to question.
Prompt	The pointer to a string prompt used to request input.
Response	The pointer to Response, which will be populated upon return.

Return values

EFI_SUCCESS	The operation was successful.
EFI_UNSUPPORTED	The operation is not supported as requested.
EFI_INVALID_PARAMETER	A parameter was invalid.

Returns: other The operation failed.

Prompt the user and return the resultant answer to the requestor.

This function will display the requested question on the shell prompt and then wait for an appropriate answer to be input from the console.

if the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.

if the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then Response is of type CHAR16.

In either case *Response must be callee freed if Response was not NULL;

Parameters

Type	What type of question is asked. This is used to filter the input to prevent invalid answers to question.
Prompt	Pointer to string prompt to use to request input.
Response	Pointer to Response which will be populated upon return.

Return values

EFI_SUCCESS	The operation was successful.
EFI_UNSUPPORTED	The operation is not supported as requested.
EFI_INVALID_PARAMETER	A parameter was invalid.

Returns: other The operation failed.

Definition at line 3525 of file UefiShellLib.c.

◆ ShellPromptForResponseHii()

EFI_STATUS EFIAPI ShellPromptForResponseHii	(	IN SHELL_PROMPT_REQUEST_TYPE	Type,
		IN CONST EFI_STRING_ID	HiiFormatStringId,
		IN CONST EFI_HII_HANDLE	HiiFormatHandle,
		IN OUT VOID **	Response
	)

Prompt the user and return the resultant answer to the requestor.

This function is the same as ShellPromptForResponse, except that the prompt is automatically pulled from HII.

Parameters

[in]	Type	What type of question is asked. This is used to filter the input to prevent invalid answers to question.
[in]	HiiFormatStringId	The format string Id for getting from Hii.
[in]	HiiFormatHandle	The format string Handle for getting from Hii.
[in,out]	Response	The pointer to Response, which will be populated upon return.

Return values

EFI_SUCCESS The operation was successful.

Returns: other The operation failed.

See also: ShellPromptForResponse

Prompt the user and return the resultant answer to the requestor.

This function is the same as ShellPromptForResponse, except that the prompt is automatically pulled from HII.

Parameters

	Type	What type of question is asked. This is used to filter the input to prevent invalid answers to question.
[in]	HiiFormatStringId	The format string Id for getting from Hii.
[in]	HiiFormatHandle	The format string Handle for getting from Hii.
	Response	Pointer to Response which will be populated upon return.

Return values

EFI_SUCCESS the operation was successful.

Returns: other the operation failed.

See also: ShellPromptForResponse

Definition at line 3811 of file UefiShellLib.c.

◆ ShellReadFile()

EFI_STATUS EFIAPI ShellReadFile	(	IN SHELL_FILE_HANDLE	FileHandle,
		IN OUT UINTN *	BufferSize,
		OUT VOID *	Buffer
	)

This function reads information from an opened file.

If FileHandle is not a directory, the function reads the requested number of bytes from the file at the file's current position and returns them in Buffer. If the read goes beyond the end of the file, the read length is truncated to the end of the file. The file's current position is increased by the number of bytes returned. If FileHandle is a directory, the function reads the directory entry at the file's current position and returns the entry in Buffer. If the Buffer is not large enough to hold the current directory entry, then EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. BufferSize is set to be the size of the buffer needed to read the entry. On success, the current position is updated to the next directory entry. If there are no more directory entries, the read returns a zero-length buffer. EFI_FILE_INFO is the structure returned as the directory entry.

Parameters

[in]	FileHandle	The opened file handle.
[in,out]	ReadSize	On input the size of buffer in bytes. On return the number of bytes written.
[out]	Buffer	The buffer to put read data into.

Return values

EFI_SUCCESS	Data was read.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_BUFFER_TO_SMALL	Buffer is too small. ReadSize contains required size.

This function reads information from an opened file.

If FileHandle is not a directory, the function reads the requested number of bytes from the file at the file's current position and returns them in Buffer. If the read goes beyond the end of the file, the read length is truncated to the end of the file. The file's current position is increased by the number of bytes returned. If FileHandle is a directory, the function reads the directory entry at the file's current position and returns the entry in Buffer. If the Buffer is not large enough to hold the current directory entry, then EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. BufferSize is set to be the size of the buffer needed to read the entry. On success, the current position is updated to the next directory entry. If there are no more directory entries, the read returns a zero-length buffer. EFI_FILE_INFO is the structure returned as the directory entry.

Parameters

FileHandle	the opened file handle
BufferSize	on input the size of buffer in bytes. on return the number of bytes written.
Buffer	the buffer to put read data into.

Return values

EFI_SUCCESS	Data was read.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_BUFFER_TO_SMALL	Buffer is too small. ReadSize contains required size.

Definition at line 912 of file UefiShellLib.c.

◆ ShellSetEnvironmentVariable()

EFI_STATUS EFIAPI ShellSetEnvironmentVariable	(	IN CONST CHAR16 *	EnvKey,
		IN CONST CHAR16 *	EnvVal,
		IN BOOLEAN	Volatile
	)

Set the value of an environment variable.

This function changes the current value of the specified environment variable. If the environment variable exists and the Value is an empty string, then the environment variable is deleted. If the environment variable exists and the Value is not an empty string, then the value of the environment variable is changed. If the environment variable does not exist and the Value is an empty string, there is no action. If the environment variable does not exist and the Value is a non-empty string, then the environment variable is created and assigned the specified value.

This is not supported pre-UEFI Shell 2.0.

Parameters

[in]	EnvKey	The key name of the environment variable.
[in]	EnvVal	The Value of the environment variable
[in]	Volatile	Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).

Return values

EFI_SUCCESS	The operation completed successfully
EFI_UNSUPPORTED	This operation is not allowed in pre-UEFI 2.0 Shell environments.

set the value of an environment variable

This function changes the current value of the specified environment variable. If the environment variable exists and the Value is an empty string, then the environment variable is deleted. If the environment variable exists and the Value is not an empty string, then the value of the environment variable is changed. If the environment variable does not exist and the Value is an empty string, there is no action. If the environment variable does not exist and the Value is a non-empty string, then the environment variable is created and assigned the specified value.

This is not supported pre-UEFI Shell 2.0.

Parameters

EnvKey	The key name of the environment variable.
EnvVal	The Value of the environment variable
Volatile	Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).

Return values

EFI_SUCCESS	the operation was completed successfully
EFI_UNSUPPORTED	This operation is not allowed in pre UEFI 2.0 Shell environments

Definition at line 1262 of file UefiShellLib.c.

◆ ShellSetFileInfo()

EFI_STATUS EFIAPI ShellSetFileInfo	(	IN SHELL_FILE_HANDLE	FileHandle,
		IN EFI_FILE_INFO *	FileInfo
	)

This function sets the information about the file for the opened handle specified.

Parameters

[in]	FileHandle	The file handle of the file for which information is being set.
[in]	FileInfo	The information to set.

Return values

EFI_SUCCESS	The information was set.
EFI_INVALID_PARAMETER	A parameter was out of range or invalid.
EFI_UNSUPPORTED	The FileHandle does not support FileInfo.
EFI_NO_MEDIA	The device has no medium.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The file or medium is write protected.
EFI_ACCESS_DENIED	The file was opened read only.
EFI_VOLUME_FULL	The volume is full.

Definition at line 601 of file UefiShellLib.c.

◆ ShellSetFilePosition()

EFI_STATUS EFIAPI ShellSetFilePosition	(	IN SHELL_FILE_HANDLE	FileHandle,
		IN UINT64	Position
	)

Set the current position in a file.

This function sets the current file position for the handle to the position supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only absolute positioning is supported, and moving past the end of the file is allowed (a subsequent write would grow the file). Moving to position 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. If FileHandle is a directory, the only position that may be set is zero. This has the effect of starting the read process of the directory entries over.

Parameters

[in]	FileHandle	The file handle on which the position is being set.
[in]	Position	The byte position from the beginning of the file.

Return values

EFI_SUCCESS	Operation completed successfully.
EFI_UNSUPPORTED	The seek request for non-zero is not valid on directories.
INVALID_PARAMETER	One of the parameters has an invalid value.

Set the current position in a file.

This function sets the current file position for the handle to the position supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only absolute positioning is supported, and seeking past the end of the file is allowed (a subsequent write would grow the file). Seeking to position 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. If FileHandle is a directory, the only position that may be set is zero. This has the effect of starting the read process of the directory entries over.

Parameters

FileHandle	The file handle on which the position is being set
Position	Byte position from beginning of file

Return values

EFI_SUCCESS	Operation completed successfully.
EFI_UNSUPPORTED	the seek request for non-zero is not valid on directories.
INVALID_PARAMETER	One of the parameters has an invalid value.

Definition at line 1020 of file UefiShellLib.c.

◆ ShellSetPageBreakMode()

VOID EFIAPI ShellSetPageBreakMode ( IN BOOLEAN CurrentState )

Sets (enabled or disabled) the page break mode.

When page break mode is enabled the screen will stop scrolling and wait for operator input before scrolling a subsequent screen.

Parameters

[in] CurrentState TRUE to enable and FALSE to disable.

sets (enabled or disabled) the page break mode

when page break mode is enabled the screen will stop scrolling and wait for operator input before scrolling a subsequent screen.

Parameters

CurrentState TRUE to enable and FALSE to disable

Definition at line 1434 of file UefiShellLib.c.

◆ ShellStrToUintn()

UINTN EFIAPI ShellStrToUintn ( IN CONST CHAR16 * String )

Function to determine whether a string is decimal or hex representation of a number and return the number converted from the string.

Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid result. Use ShellConvertStringToUint64 instead.

Parameters

[in] String String representation of a number.

Returns: The unsigned integer result of the conversion.

Return values

(UINTN)(-1) An error occurred.

Function to determine whether a string is decimal or hex representation of a number and return the number converted from the string. Spaces are always skipped.

Parameters

[in] String String representation of a number

Returns: the number

Return values

(UINTN)(-1) An error ocurred.

Definition at line 3368 of file UefiShellLib.c.

◆ ShellWriteFile()

EFI_STATUS EFIAPI ShellWriteFile	(	IN SHELL_FILE_HANDLE	FileHandle,
		IN OUT UINTN *	BufferSize,
		IN VOID *	Buffer
	)

Write data to a file.

This function writes the specified number of bytes to the file at the current file position. The current file position is advanced the actual number of bytes written, which is returned in BufferSize. Partial writes only occur when there has been a data error during the write attempt (such as "volume space full"). The file is automatically grown to hold the data if required. Direct writes to opened directories are not supported.

Parameters

[in]	FileHandle	The opened file for writing.
[in,out]	BufferSize	On input the number of bytes in Buffer. On output the number of bytes written.
[in]	Buffer	The buffer containing data to write is stored.

Return values

EFI_SUCCESS	Data was written.
EFI_UNSUPPORTED	Writes to an open directory are not supported.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The device is write-protected.
EFI_ACCESS_DENIED	The file was open for read only.
EFI_VOLUME_FULL	The volume is full.

Write data to a file.

This function writes the specified number of bytes to the file at the current file position. The current file position is advanced the actual number of bytes written, which is returned in BufferSize. Partial writes only occur when there has been a data error during the write attempt (such as "volume space full"). The file is automatically grown to hold the data if required. Direct writes to opened directories are not supported.

Parameters

FileHandle	The opened file for writing
BufferSize	on input the number of bytes in Buffer. On output the number of bytes written.
Buffer	the buffer containing data to write is stored.

Return values

EFI_SUCCESS	Data was written.
EFI_UNSUPPORTED	Writes to an open directory are not supported.
EFI_NO_MEDIA	The device has no media.
EFI_DEVICE_ERROR	The device reported an error.
EFI_VOLUME_CORRUPTED	The file system structures are corrupted.
EFI_WRITE_PROTECTED	The device is write-protected.
EFI_ACCESS_DENIED	The file was open for read only.
EFI_VOLUME_FULL	The volume is full.

Definition at line 947 of file UefiShellLib.c.

◆ StrnCatGrow()

CHAR16 *EFIAPI StrnCatGrow	(	IN OUT CHAR16 **	Destination,
		IN OUT UINTN *	CurrentSize,
		IN CONST CHAR16 *	Source,
		IN UINTN	Count
	)

Safely append with automatic string resizing given length of Destination and desired length of copy from Source.

Append the first D characters of Source to the end of Destination, where D is the lesser of Count and the StrLen() of Source. If appending those D characters will fit within Destination (whose Size is given as CurrentSize) and still leave room for a NULL terminator, then those characters are appended, starting at the original terminating NULL of Destination, and a new terminating NULL is appended.

If appending D characters onto Destination will result in a overflow of the size given in CurrentSize the string will be grown such that the copy can be performed and CurrentSize will be updated to the new size.

If Source is NULL, there is nothing to append, so return the current buffer in Destination.

If Destination is NULL, then ASSERT(). If Destination's current length (including NULL terminator) is already more than CurrentSize, then ASSERT().

Parameters

[in,out]	Destination	The String to append onto.
[in,out]	CurrentSize	On call, the number of bytes in Destination. On return, possibly the new size (still in bytes). If NULL, then allocate whatever is needed.
[in]	Source	The String to append from.
[in]	Count	The maximum number of characters to append. If 0, then all are appended.

Returns: The Destination after appending the Source.

Safely append with automatic string resizing given length of Destination and desired length of copy from Source.

append the first D characters of Source to the end of Destination, where D is the lesser of Count and the StrLen() of Source. If appending those D characters will fit within Destination (whose Size is given as CurrentSize) and still leave room for a NULL terminator, then those characters are appended, starting at the original terminating NULL of Destination, and a new terminating NULL is appended.

If appending D characters onto Destination will result in a overflow of the size given in CurrentSize the string will be grown such that the copy can be performed and CurrentSize will be updated to the new size.

If Source is NULL, there is nothing to append, just return the current buffer in Destination.

if Destination is NULL, then ASSERT() if Destination's current length (including NULL terminator) is already more then CurrentSize, then ASSERT()

Parameters

[in,out]	Destination	The String to append onto
[in,out]	CurrentSize	on call the number of bytes in Destination. On return possibly the new size (still in bytes). if NULL then allocate whatever is needed.
[in]	Source	The String to append from
[in]	Count	Maximum number of characters to append. if 0 then all are appended.

Returns: Destination return the resultant string.

Definition at line 3422 of file UefiShellLib.c.

Variable Documentation

◆ EmptyParamList

SHELL_PARAM_ITEM EmptyParamList[]

extern

Helper structure for no parameters (besides -? and -b)

Definition at line 19 of file UefiShellLib.c.

◆ gEfiShellParametersProtocol

EFI_SHELL_PARAMETERS_PROTOCOL* gEfiShellParametersProtocol

extern

Definition at line 29 of file UefiShellLib.c.

◆ gEfiShellProtocol

EFI_SHELL_PROTOCOL* gEfiShellProtocol

extern

Definition at line 28 of file UefiShellLib.c.

◆ SfoParamList

SHELL_PARAM_ITEM SfoParamList[]

extern

Helper structure for -sfo only (besides -? and -b)

Definition at line 22 of file UefiShellLib.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SHELL_FREE_NON_NULL

◆ ShellCommandLineParse

Enumeration Type Documentation

◆ SHELL_PARAM_TYPE

◆ SHELL_PROMPT_REQUEST_TYPE

◆ SHELL_PROMPT_RESPONSE

Function Documentation

◆ FullyQualifyPath()

◆ ShellCloseFile()

◆ ShellCloseFileMetaArg()

◆ ShellCommandLineCheckDuplicate()

◆ ShellCommandLineFreeVarList()

◆ ShellCommandLineGetCount()

◆ ShellCommandLineGetFlag()

◆ ShellCommandLineGetRawValue()

◆ ShellCommandLineGetValue()

◆ ShellCommandLineParseEx()

◆ ShellConvertStringToUint64()

◆ ShellCopySearchAndReplace()

◆ ShellCreateDirectory()

◆ ShellDeleteFile()

◆ ShellDeleteFileByName()

◆ ShellExecute()

◆ ShellFileExists()

◆ ShellFileHandleReadLine()

◆ ShellFileHandleReturnLine()

◆ ShellFindFilePath()

◆ ShellFindFilePathEx()

◆ ShellFindFirstFile()

◆ ShellFindNextFile()

◆ ShellFlushFile()

◆ ShellGetCurrentDir()

◆ ShellGetEnvironmentVariable()

◆ ShellGetExecutionBreakFlag()

◆ ShellGetFileInfo()

◆ ShellGetFilePosition()

◆ ShellGetFileSize()

◆ ShellHexStrToUintn()

◆ ShellInitialize()

◆ ShellIsDecimalDigitCharacter()

◆ ShellIsDirectory()

◆ ShellIsFile()

◆ ShellIsFileInPath()

◆ ShellIsHexaDecimalDigitCharacter()

◆ ShellIsHexOrDecimalNumber()

◆ ShellOpenFileByDevicePath()

◆ ShellOpenFileByName()

◆ ShellOpenFileMetaArg()

◆ ShellPrintEx()

◆ ShellPrintHelp()

◆ ShellPrintHiiEx()

◆ ShellPromptForResponse()

◆ ShellPromptForResponseHii()

◆ ShellReadFile()

◆ ShellSetEnvironmentVariable()

◆ ShellSetFileInfo()

◆ ShellSetFilePosition()

◆ ShellSetPageBreakMode()

◆ ShellStrToUintn()

◆ ShellWriteFile()

◆ StrnCatGrow()

Variable Documentation

◆ EmptyParamList

◆ gEfiShellParametersProtocol

◆ gEfiShellProtocol

◆ SfoParamList