updating headers from code review.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9449 6f19259b-4bc3-4df7-8a09-765794883524

6 files changed, 282 insertions, 157 deletions

diff --git a/ShellPkg/Include/Guid/ShellPkgTokenSpace.h b/ShellPkg/Include/Guid/ShellPkgTokenSpace.h
index 9803e9c4aa..ac9bbd08ad 100644
--- a/ShellPkg/Include/Guid/ShellPkgTokenSpace.h
+++ b/ShellPkg/Include/Guid/ShellPkgTokenSpace.h
@@ -1,5 +1,5 @@
 /** @file

-  GUID for ShellPkg PCD Token Space 

+  GUID for ShellPkg PCD Token Space.

 

   Copyright (c) 2009, Intel Corporation

   All rights reserved. This program and the accompanying materials

@@ -15,10 +15,10 @@
 #ifndef _SHELLPKG_TOKEN_SPACE_GUID_H_

 #define _SHELLPKG_TOKEN_SPACE_GUID_H_

 

-#define SHELLPKG_TOKEN_SPACE_GUID \

+#define EFI_SHELLPKG_TOKEN_SPACE_GUID \

 { \

   0x171e9188, 0x31d3, 0x40f5, { 0xb1, 0xc, 0x53, 0x9b, 0x2d, 0xb9, 0x40, 0xcd } \

-};

+}

 

 extern EFI_GUID gEfiShellPkgTokenSpaceGuid;

 

diff --git a/ShellPkg/Include/Library/FileHandleLib.h b/ShellPkg/Include/Library/FileHandleLib.h
index c9cf2acefd..ee5b526422 100644
--- a/ShellPkg/Include/Library/FileHandleLib.h
+++ b/ShellPkg/Include/Library/FileHandleLib.h
@@ -17,14 +17,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
   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

+  caller's responsibility to free the buffer.

 

   @param  FileHandle  The file handle of the file for which information is 

-  being requested.

+                      being requested.

 

-  @retval NULL information could not be retrieved.

+  @retval NULL        information could not be retrieved.

 

-  @return the information about the file

+  @retval !NULL       the information about the file

 **/

 EFI_FILE_INFO*

 EFIAPI

@@ -37,18 +37,18 @@ FileHandleGetInfo (
   specified.

 

   @param  FileHandle            The file handle of the file for which information 

-  is being set

+                                is being set.

 

-  @param  FileInfo              The infotmation to set.

+  @param  FileInfo              The information to set.

 

-  @retval EFI_SUCCESS		The information was set.

-  @retval EFI_UNSUPPORTED The InformationType is not known.

-  @retval EFI_NO_MEDIA		The device has no medium.

-  @retval EFI_DEVICE_ERROR	The device reported an error.

+  @retval EFI_SUCCESS		        The information was set.

+  @retval EFI_UNSUPPORTED       The FileHandle does not support FileInfo.

+  @retval EFI_NO_MEDIA		      The device has no medium.

+  @retval EFI_DEVICE_ERROR	    The device reported an error.

   @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

-  @retval EFI_WRITE_PROTECTED	The file or medium is write protected.

-  @retval EFI_ACCESS_DENIED	The file was opened read only.

-  @retval EFI_VOLUME_FULL	The volume is full.

+  @retval EFI_WRITE_PROTECTED	  The file or medium is write protected.

+  @retval EFI_ACCESS_DENIED	    The file was opened read only.

+  @retval EFI_VOLUME_FULL	      The volume is full.

 **/

 EFI_STATUS

 EFIAPI

@@ -73,16 +73,16 @@ FileHandleSetInfo (
   are no more directory entries, the read returns a zero-length buffer. 

   EFI_FILE_INFO is the structure returned as the directory entry.

 

-  @param FileHandle             the opened file handle

-  @param BufferSize             on input the size of buffer in bytes.  on return 

+  @param FileHandle             The opened file handle.

+  @param BufferSize             On input the size of buffer in bytes.  on return 

                                 the number of bytes written.

-  @param Buffer                 the buffer to put read data into.

+  @param Buffer                 The buffer to put read data into.

 

   @retval EFI_SUCCESS	          Data was read.

   @retval EFI_NO_MEDIA	        The device has no media.

-  @retval EFI_DEVICE_ERROR	The device reported an error.

+  @retval EFI_DEVICE_ERROR	    The device reported an error.

   @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

-  @retval EFI_BUFFER_TO_SMALL	Buffer is too small. ReadSize contains required 

+  @retval EFI_BUFFER_TO_SMALL	  Buffer is too small. ReadSize contains required 

                                 size.

 

 **/

@@ -105,18 +105,18 @@ FileHandleRead(
   opened directories are not supported.

 

   @param FileHandle           The opened file for writing

-  @param BufferSize           on input the number of bytes in Buffer.  On output

+  @param BufferSize           On input the number of bytes in Buffer.  On output

                               the number of bytes written.

-  @param Buffer               the buffer containing data to write is stored.

-

- @retval EFI_SUCCESS	        Data was written.

- @retval EFI_UNSUPPORTED	    Writes to an open directory are not supported.

- @retval EFI_NO_MEDIA	        The device has no media.

- @retval EFI_DEVICE_ERROR	    The device reported an error.

- @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

- @retval EFI_WRITE_PROTECTED	The device is write-protected.

- @retval EFI_ACCESS_DENIED	  The file was open for read only.

- @retval EFI_VOLUME_FULL	    The volume is full.

+  @param Buffer               The buffer containing data to write is stored.

+

+  @retval EFI_SUCCESS	        Data was written.

+  @retval EFI_UNSUPPORTED	    Writes to an open directory are not supported.

+  @retval EFI_NO_MEDIA	        The device has no media.

+  @retval EFI_DEVICE_ERROR	    The device reported an error.

+  @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

+  @retval EFI_WRITE_PROTECTED	The device is write-protected.

+  @retval EFI_ACCESS_DENIED	  The file was open for read only.

+  @retval EFI_VOLUME_FULL	    The volume is full.

 **/

 EFI_STATUS

 EFIAPI

@@ -133,9 +133,9 @@ FileHandleWrite(
   flushed to the device, and the file is closed. In all cases the handle is 

   closed.

 

-@param FileHandle               the file handle to close.

+  @param FileHandle               The file handle to close.

 

-@retval EFI_SUCCESS             the file handle was closed sucessfully.

+  @retval EFI_SUCCESS             The file handle was closed sucessfully.

 **/

 EFI_STATUS

 EFIAPI

@@ -144,18 +144,18 @@ FileHandleClose (
   );

 

 /**

-  Delete a file and close the handle

+  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.

 

-  @param FileHandle             the file handle to delete

+  @param FileHandle             The file handle to delete.

 

-  @retval EFI_SUCCESS           the file was closed sucessfully

-  @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not 

-                                deleted

-  @retval INVALID_PARAMETER    	One of the parameters has an invalid value.

+  @retval EFI_SUCCESS               The file was closed sucessfully.

+  @retval EFI_WARN_DELETE_FAILURE   the handle was closed, but the file was not 

+                                    deleted

+  @retval INVALID_PARAMETER    	    One of the parameters has an invalid value.

 **/

 EFI_STATUS

 EFIAPI

@@ -190,7 +190,7 @@ FileHandleSetPosition (
   );

 

 /** 

-  Gets a file's current 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 

@@ -211,11 +211,11 @@ FileHandleGetPosition (
   OUT UINT64                    *Position

   );

 /**

-  Flushes data on a file

+  Flushes data on a file.

   

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

 

-  @param FileHandle             The file handle on which to flush data

+  @param FileHandle             The file handle on which to flush data.

 

   @retval EFI_SUCCESS           The data was flushed.

   @retval EFI_NO_MEDIA          The device has no media.

@@ -231,14 +231,14 @@ FileHandleFlush (
   );

 

 /**

-  function to determine if a given handle is a directory handle

+  Function to determine if a given handle is a directory handle.

 

-  if DirHandle is NULL then ASSERT()

+  If DirHandle is NULL then ASSERT().

 

-  open the file information on the DirHandle and verify that the Attribute

+  Open the file information on the DirHandle and verify that the Attribute

   includes EFI_FILE_DIRECTORY bit set.

 

-  @param DirHandle              Handle to open file

+  @param DirHandle              Handle to open file.

 

   @retval EFI_SUCCESS           DirHandle is a directory

   @retval EFI_INVALID_PARAMETER DirHandle did not have EFI_FILE_INFO available

@@ -251,7 +251,7 @@ FileHandleIsDirectory (
   );

 

 /**

-  Retrieves the first file from a directory

+  Retrieves the first file from a directory.

 

   This function opens a directory and gets the first file's info in the 

   directory. Caller can use FileHandleFindNextFile() to get other files.  When 

@@ -304,14 +304,14 @@ FileHandleFindNextFile(
 /**

   Retrieve the size of a file.

 

-  if FileHandle is NULL then ASSERT()

-  if Size is NULL then ASSERT()

+  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.

 

-  @param FileHandle             file handle from which size is retrieved

-  @param Size                   pointer to size

+  @param FileHandle             The file handle from which size is retrieved.

+  @param Size                   pointer to size.

 

   @retval EFI_SUCCESS           operation was completed sucessfully

   @retval EFI_DEVICE_ERROR      cannot access the file

@@ -327,10 +327,8 @@ FileHandleGetSize (
   Function to get a full filename given a EFI_FILE_HANDLE somewhere lower on the 

   directory 'stack'.

 

-  if Handle is NULL, return EFI_INVALID_PARAMETER

-

   @param[in] Handle             Handle to the Directory or File to create path to.

-  @param[out] FullFileName      pointer to pointer to generated full file name.  It 

+  @param[out] FullFileName      Pointer to pointer to generated full file name.  It 

                                 is the responsibility of the caller to free this memory

                                 with a call to FreePool().

   @retval EFI_SUCCESS           the operation was sucessful and the FullFileName is valid.

@@ -346,16 +344,16 @@ FileHandleGetFileName (
   );

 

 /**

-  Function to read a single line (up to but not including the \n) from a file.

+  Function to read a single line from a file. The \n is not included in the returned buffer.

 

-  @param[in]      Handle        FileHandle to read from

-  @param[in,out] Buffer        pointer to buffer to read into

-  @param[in,out] Size          pointer to number of bytes in buffer

-  @param[in[      Truncate      if TRUE then allows for truncation of the line to fit.

-                                if FALSE will reset the position to the begining of the 

+  @param[in]      Handle        FileHandle to read from.

+  @param[in,out]  Buffer        Pointer to buffer to read into

+  @param[in,out]  Size          Pointer to number of bytes in buffer

+  @param[in]      Truncate      If TRUE then allows for truncation of the line to fit.

+                                If FALSE will reset the position to the begining of the 

                                 line if the buffer is not large enough.

 

-  @retval EFI_SUCCESS           the operation was sucessful.  the line is stored in 

+  @retval EFI_SUCCESS           The operation was sucessful.  the line is stored in 

                                 Buffer.  (Size was NOT updated)

   @retval EFI_INVALID_PARAMETER Handle was NULL.

   @retval EFI_INVALID_PARAMETER Buffer was NULL.

@@ -368,19 +366,19 @@ EFI_STATUS
 EFIAPI

 FileHandleReadLine(

   IN EFI_FILE_HANDLE            Handle,

-  IN OUT VOID                   *Buffer,

+  IN OUT CHAR16                 *Buffer,

   IN OUT UINTN                  *Size,

   IN BOOLEAN                    Truncate

   );

 

 /**

-  function to write a line of unicode text to a file.

+  Function to write a line of unicode text to a file.

 

-  if Handle is NULL, ASSERT.

-  if Buffer is NULL, do nothing.  (return SUCCESS)

+  If Handle is NULL, ASSERT.

 

   @param[in]     Handle         FileHandle to write to

-  @param[in]     Buffer         Buffer to write

+  @param[in]     Buffer         Buffer to write, if NULL the function will 

+                                take no action and return EFI_SUCCESS.

 

   @retval  EFI_SUCCESS          the data was written.

   @retval  other                failure.

@@ -393,3 +391,39 @@ FileHandleWriteLine(
   IN EFI_FILE_HANDLE Handle,

   IN CHAR16          *Buffer

   );

+

+/**

+  function to take a formatted argument and print it to a file.

+

+  @param[in] Handle   the file handle for the file to write to

+  @param[in] Format   the format argument (see printlib for format specifier)

+  @param[in] ...      the variable arguments for the format

+

+  @retval EFI_SUCCESS the operation was sucessful

+  @return other       a return value from FileHandleWriteLine

+

+  @sa FileHandleWriteLine

+**/

+EFI_STATUS

+EFIAPI

+FileHandlePrintLine(

+  IN EFI_FILE_HANDLE  Handle,

+  IN CONST CHAR16     *Format,

+  ...

+  );

+

+/**

+  Function to determine if a FILE_HANDLE is at the end of the file.

+

+  This will NOT work on directories.

+

+  @param[in] Handle     the file handle

+

+  @retval TRUE          the position is at the end of the file

+  @retval FALSE         the position is not at the end of the file

+**/

+BOOLEAN

+EFIAPI

+FileHandleEof(

+  IN EFI_FILE_HANDLE Handle

+  );

diff --git a/ShellPkg/Include/Library/ShellLib.h b/ShellPkg/Include/Library/ShellLib.h
index 6211343f16..eab8271ae9 100644
--- a/ShellPkg/Include/Library/ShellLib.h
+++ b/ShellPkg/Include/Library/ShellLib.h
@@ -69,7 +69,7 @@ ShellSetFileInfo (
   This function opens a file with the open mode according to the file path. The 

   Attributes is valid only for EFI_FILE_MODE_CREATE.

 

-  @param  FilePath 		    on input the device path to the file.  On output 

+  @param  FilePath 		    On input the device path to the file.  On output 

                           the remaining device path.

   @param  DeviceHandle  	pointer to the system device handle.

   @param  FileHandle		  pointer to the file handle.

@@ -148,12 +148,12 @@ ShellOpenFileByName(
   otherwise, the Filehandle is NULL. If the directory already existed, this 

   function opens the existing directory.

 

-  @param  DirectoryName         pointer to Directory name

-  @param  FileHandle		        pointer to the file handle.

+  @param  DirectoryName         Pointer to Directory name.

+  @param  FileHandle		        Pointer to the file handle.

 

   @retval EFI_SUCCESS		        The information was set.

   @retval EFI_INVALID_PARAMETER	One of the parameters has an invalid value.

-  @retval EFI_UNSUPPORTED	Could not open the file path.	

+  @retval EFI_UNSUPPORTED	      Could not open the file path.	

   @retval EFI_NOT_FOUND	        The specified file could not be found on the 

                                 device or the file system could not be found 

                                 on the device.

@@ -191,18 +191,16 @@ ShellCreateDirectory(
   are no more directory entries, the read returns a zero-length buffer. 

   EFI_FILE_INFO is the structure returned as the directory entry.

 

-  @param FileHandle             the opened file handle

-  

-  @param ReadSize               on input the size of buffer in bytes.  on return 

+  @param FileHandle             The opened file handle.

+  @param ReadSize               On input the size of buffer in bytes.  On return 

                                 the number of bytes written.

+  @param Buffer                 The buffer to put read data into.

 

-  @param Buffer                 the buffer to put read data into.

-

- @retval EFI_SUCCESS	          Data was read.

- @retval EFI_NO_MEDIA	          The device has no media.

- @retval EFI_DEVICE_ERROR	      The device reported an error.

- @retval EFI_VOLUME_CORRUPTED	  The file system structures are corrupted.

- @retval EFI_BUFFER_TO_SMALL	  Buffer is too small. ReadSize contains required 

+  @retval EFI_SUCCESS	          Data was read.

+  @retval EFI_NO_MEDIA	        The device has no media.

+  @retval EFI_DEVICE_ERROR	    The device reported an error.

+  @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

+  @retval EFI_BUFFER_TO_SMALL	  Buffer is too small. ReadSize contains required 

                                 size.

 

 **/

@@ -224,21 +222,21 @@ ShellReadFile(
   The file is automatically grown to hold the data if required. Direct writes to 

   opened directories are not supported.

 

-  @param FileHandle             The opened file for writing

+  @param FileHandle             The opened file for writing.

 

-  @param BufferSize             on input the number of bytes in Buffer.  On output

+  @param BufferSize             On input the number of bytes in Buffer.  On output

                                 the number of bytes written.

 

-  @param Buffer                 the buffer containing data to write is stored.

+  @param Buffer                 The buffer containing data to write is stored.

 

- @retval EFI_SUCCESS	        Data was written.

- @retval EFI_UNSUPPORTED	    Writes to an open directory are not supported.

- @retval EFI_NO_MEDIA	        The device has no media.

- @retval EFI_DEVICE_ERROR	    The device reported an error.

- @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

- @retval EFI_WRITE_PROTECTED	The device is write-protected.

- @retval EFI_ACCESS_DENIED	  The file was open for read only.

- @retval EFI_VOLUME_FULL	    The volume is full.

+  @retval EFI_SUCCESS	          Data was written.

+  @retval EFI_UNSUPPORTED	      Writes to an open directory are not supported.

+  @retval EFI_NO_MEDIA	        The device has no media.

+  @retval EFI_DEVICE_ERROR	    The device reported an error.

+  @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

+  @retval EFI_WRITE_PROTECTED	  The device is write-protected.

+  @retval EFI_ACCESS_DENIED	    The file was open for read only.

+  @retval EFI_VOLUME_FULL	      The volume is full.

 **/

 EFI_STATUS

 EFIAPI

@@ -255,10 +253,10 @@ ShellWriteFile(
   flushed to the device, and the file is closed. In all cases the handle is 

   closed.

 

-@param FileHandle               the file handle to close.

+  @param FileHandle               The file handle to close.

 

-@retval EFI_SUCCESS             the file handle was closed sucessfully.

-@retval INVALID_PARAMETER      	One of the parameters has an invalid value.

+  @retval EFI_SUCCESS             The file handle was closed sucessfully.

+  @retval INVALID_PARAMETER      	One of the parameters has an invalid value.

 **/

 EFI_STATUS

 EFIAPI

@@ -273,12 +271,12 @@ ShellCloseFile (
   If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is 

   returned, but the handle is still closed.

 

-  @param FileHandle             the file handle to delete

+  @param FileHandle                 The file handle to delete.

 

-  @retval EFI_SUCCESS           the file was closed sucessfully

-  @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not 

-                                deleted

-  @retval INVALID_PARAMETER    	One of the parameters has an invalid value.

+  @retval EFI_SUCCESS               The file was closed sucessfully.

+  @retval EFI_WARN_DELETE_FAILURE   The handle was closed, but the file was not 

+                                    deleted.

+  @retval INVALID_PARAMETER    	    One of the parameters has an invalid value.

 **/

 EFI_STATUS

 EFIAPI

@@ -414,11 +412,11 @@ ShellFindNextFile(
   This function extracts the file size info from the FileHandle's EFI_FILE_INFO 

   data.

 

-  @param FileHandle             file handle from which size is retrieved

-  @param Size                   pointer to size

+  @param FileHandle             The file handle from which size is retrieved.

+  @param Size                   Pointer to size.

 

-  @retval EFI_SUCCESS           operation was completed sucessfully

-  @retval EFI_DEVICE_ERROR      cannot access the file

+  @retval EFI_SUCCESS           The operation was completed sucessfully.

+  @retval EFI_DEVICE_ERROR      cannot access the file.

 **/

 EFI_STATUS

 EFIAPI

@@ -442,15 +440,15 @@ ShellGetExecutionBreakFlag(
   );

 

 /**

-  return the value of an environment variable

+  Return the value of an environment variable.

 

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

-  ShellSetEnvironmentVariable function

+  This function gets the value of the environment variable set by the 

+  ShellSetEnvironmentVariable function.

 

   @param EnvKey                 The key name of the environment variable.

 

   @retval NULL                  the named environment variable does not exist.

-  @return != NULL               pointer to the value of the environment variable

+  @return != NULL               pointer to the value of the environment variable.

 **/

 CONST CHAR16*

 EFIAPI

@@ -461,13 +459,13 @@ ShellGetEnvironmentVariable (
 /**

   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 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.

 

@@ -487,19 +485,19 @@ ShellSetEnvironmentVariable (
   );

 

 /**

-  cause the shell to parse and execute a command line.

+  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.

+  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.

 

-EnvironmentVariables and Status are only supported for UEFI Shell 2.0.

-Output is only supported for pre-UEFI Shell 2.0

+  EnvironmentVariables and Status are only supported for UEFI Shell 2.0.

+  Output is only supported for pre-UEFI Shell 2.0

 

   @param ImageHandle            Parent image that is starting the operation

   @param CommandLine            pointer to null terminated command line.

@@ -543,9 +541,9 @@ ShellGetCurrentDir (
   );

 

 /**

-  sets (enabled or disabled) the page break mode

+  Sets (enabled or disabled) the page break mode.

 

-  when page break mode is enabled the screen will stop scrolling 

+  When page break mode is enabled the screen will stop scrolling 

   and wait for operator input before scrolling a subsequent screen.

 

   @param CurrentState           TRUE to enable and FALSE to disable

@@ -563,21 +561,19 @@ ShellSetPageBreakMode (
   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 

+  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.

 

-  @param Arg                    pointer to path string

-  @param OpenMode               mode to open files with

-  @param ListHead               head of linked list of results

+  @param Arg                    Pointer to path string.

+  @param OpenMode               Mode to open files with.

+  @param ListHead               Head of linked list of results.

 

-  @retval EFI_SUCCESS           the operation was sucessful and the list head 

-                                contains the list of opened files

-  #retval EFI_UNSUPPORTED       a previous ShellOpenFileMetaArg must be closed first.

-                                *ListHead is set to NULL.

-  @return != EFI_SUCCESS        the operation failed

+  @retval EFI_SUCCESS           The operation was sucessful and the list head 

+                                contains the list of opened files.

+  @return != EFI_SUCCESS        The operation failed.

 

   @sa InternalShellConvertFileListType

 **/

@@ -603,11 +599,31 @@ ShellCloseFileMetaArg (
   IN OUT EFI_SHELL_FILE_INFO    **ListHead

   );

 

+/**

+  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.

+

+  @param FileName               Filename string.

+

+  @retval NULL                  the file was not found

+  @return !NULL                 the path to the file.

+**/

+CHAR16 *

+EFIAPI

+ShellFindFilePath (

+  IN CONST CHAR16 *FileName

+  );

+

 typedef enum {

-  TypeFlag  = 0,

-  TypeValue,

-  TypePosition,

-  TypeStart,

+  TypeFlag  = 0,    /// 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.

   TypeMax,

 } ParamType;

 

@@ -626,11 +642,11 @@ extern SHELL_PARAM_ITEM EmptyParamList[];
   

   If no initialization is required, then return RETURN_SUCCESS.

   

-  @param CheckList              pointer to list of parameters to check

-  @param CheckPackage           Package of checked values

-  @param ProblemParam           optional pointer to pointer to unicode string for 

+  @param CheckList              Pointer to list of parameters to check.

+  @param CheckPackage           Package of checked values.

+  @param ProblemParam           Pptional pointer to pointer to unicode string for 

                                 the paramater that caused failure.

-  @param AutoPageBreak          will automatically set PageBreakEnabled

+  @param AutoPageBreak          Will automatically set PageBreakEnabled.

 

   @retval EFI_SUCCESS           The operation completed sucessfully.

   @retval EFI_OUT_OF_RESOURCES  A memory allocation failed

@@ -638,10 +654,10 @@ extern SHELL_PARAM_ITEM EmptyParamList[];
   @retval EFI_VOLUME_CORRUPTED  the command line was corrupt.  an argument was 

                                 duplicated.  the duplicated command line argument 

                                 was returned in ProblemParam if provided.

-  @retval EFI_DEVICE_ERROR      the commands contained 2 opposing arguments.  one

+  @retval EFI_DEVICE_ERROR      The commands contained 2 opposing arguments.  one

                                 of the command line arguments was returned in 

                                 ProblemParam if provided.

-  @retval EFI_NOT_FOUND         a argument required a value that was missing.  

+  @retval EFI_NOT_FOUND         A argument required a value that was missing.  

                                 the invalid command line argument was returned in

                                 ProblemParam if provided.

 **/

@@ -767,6 +783,7 @@ ShellCommandLineGetCount(
 EFI_STATUS

 EFIAPI

 ShellInitialize (

+  VOID

   );

 

 /**

@@ -861,5 +878,59 @@ ShellIsDirectory(
   IN CONST CHAR16 *DirName

   );

 

+/**

+  Function to determine whether a string is decimal or hex representation of a number 

+  and return the number converted from the string.

+

+  @param[in] String   String representation of a number

+

+  @retval all         the number

+**/

+UINTN

+EFIAPI

+ShellStrToUintn(

+  IN CONST CHAR16 *String

+  );

+

+/**

+  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()

+

+  @param[in,out] Destination   The String to append onto

+  @param[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.

+  @param[in]      Source        The String to append from

+  @param[in]      Count         Maximum number of characters to append.  if 0 then 

+                                all are appended.

+

+  @return Destination           return the resultant string.

+**/

+CHAR16* 

+EFIAPI

+StrnCatGrow (

+  IN OUT CHAR16           **Destination,

+  IN OUT UINTN            *CurrentSize,

+  IN     CONST CHAR16     *Source,

+  IN     UINTN            Count

+  );

 

 #endif // __SHELL_LIB__

diff --git a/ShellPkg/Include/Library/SortLib.h b/ShellPkg/Include/Library/SortLib.h
index ecc538e4b3..1345a52d59 100644
--- a/ShellPkg/Include/Library/SortLib.h
+++ b/ShellPkg/Include/Library/SortLib.h
@@ -1,5 +1,5 @@
 /** @file

-  Library used for sorting routines.

+  Library used for sorting and comparison routines.

 

 Copyright (c) 2009, Intel Corporation

 All rights reserved. This program and the accompanying materials

@@ -59,4 +59,20 @@ PerformQuickSort (
   IN       SORT_COMPARE                 CompareFunction

   );

 

+

+/**

+  Function to compare 2 device paths for use as CompareFunction.

+

+  @param[in] Buffer1            pointer to Device Path to compare

+  @param[in] Buffer2            pointer to second DevicePath to compare

+

+  @retval 0                           Buffer1 equal to Buffer2

+  @return < 0                         Buffer1 is less than Buffer2

+  @return > 0                         Buffer1 is greater than Buffer2                     

+**/

+INTN

+DevicePathCompare (

+  IN  VOID             *Buffer1,

+  IN  VOID             *Buffer2

+  );

 #endif //__SORT_LIB_H__

diff --git a/ShellPkg/Include/Protocol/EfiShell.h b/ShellPkg/Include/Protocol/EfiShell.h
index 658f892f07..8b489dac6b 100644
--- a/ShellPkg/Include/Protocol/EfiShell.h
+++ b/ShellPkg/Include/Protocol/EfiShell.h
@@ -26,12 +26,12 @@
 // replaced EFI_LIST_ENTRY with LIST_ENTRY for simplicity.

 // they are identical outside of the name.

 typedef struct {

-  LIST_ENTRY Link;

-  EFI_STATUS Status;

-  CONST CHAR16 *FullName;

-  CONST CHAR16 *FileName;

-  EFI_FILE_HANDLE Handle;

-  EFI_FILE_INFO *Info;

+  LIST_ENTRY Link;          /// Linked list members

+  EFI_STATUS Status;        /// Status of opening the file.  Valid only if Handle != NULL.

+  CONST CHAR16 *FullName;   /// Fully qualified filename.

+  CONST CHAR16 *FileName;   /// name of this file.

+  EFI_FILE_HANDLE Handle;   /// Handle for interacting with the opened file or NULL if closed.

+  EFI_FILE_INFO *Info;      /// Pointer to the FileInfo struct for this file or NULL.

 } EFI_SHELL_FILE_INFO;

 /**

   Returns whether any script files are currently being processed.

@@ -85,7 +85,7 @@ EFI_STATUS
   @retval EFI_SUCCESS       The file was opened.  FileHandle points to the new file's handle.

   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.

   @retval EFI_UNSUPPORTED   could not open the file path

-  @retval EFI_NOT_FOUND     the specified file could not be found on the devide, or could not

+  @retval EFI_NOT_FOUND     The specified file could not be found on the device, or could not

                             file the file system on the device.

   @retval EFI_NO_MEDIA      the device has no medium.

   @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no

@@ -846,10 +846,10 @@ EFI_STATUS
   For a description of volatile and non-volatile environment variables, see UEFI Shell 

   2.0 specification section 3.6.1.

 

-  @param[in] Name                   Points to the null-terminated environment variable name.

-  @param[in] Value                  Points to the null-terminated environment variable value. If the value is an

+  @param[in] Name               Points to the null-terminated environment variable name.

+  @param[in] Value              Points to the null-terminated environment variable value. If the value is an

                                 empty string then the environment variable is deleted.

-  @param[in] Volatile               Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).

+  @param[in] Volatile           Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).

 

   @retval EFI_SUCCESS           The environment variable was successfully updated.

 **/

diff --git a/ShellPkg/Include/ShellBase.h b/ShellPkg/Include/ShellBase.h
index 0005be0cae..3929df7b77 100644
--- a/ShellPkg/Include/ShellBase.h
+++ b/ShellPkg/Include/ShellBase.h
@@ -12,6 +12,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 **/

 

+#if !defined(__SHELL_BASE__)

+#define __SHELL_BASE__

+

 typedef enum {

 ///

 /// The operation completed successfully.

@@ -140,3 +143,4 @@ SHELL_SECURITY_VIOLATION    = 26,
 SHELL_CRC_ERROR             = 27

 }SHELL_STATUS;

 

+#endif //__SHELL_BASE__
\ No newline at end of file