From b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52 Mon Sep 17 00:00:00 2001 From: darylm503 Date: Sat, 12 Nov 2011 00:35:11 +0000 Subject: [PATCH] ShellPkg: Update comments for functions to clarify buffer origin. Signed-off-by: darylm503 Reviewed-by: jljusten git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12687 6f19259b-4bc3-4df7-8a09-765794883524 --- ShellPkg/Include/Library/FileHandleLib.h | 78 +++--- ShellPkg/Include/Library/ShellLib.h | 125 +++++----- .../UefiFileHandleLib/UefiFileHandleLib.c | 82 ++++--- ShellPkg/Library/UefiShellLib/UefiShellLib.c | 229 +++++++++--------- 4 files changed, 265 insertions(+), 249 deletions(-) diff --git a/ShellPkg/Include/Library/FileHandleLib.h b/ShellPkg/Include/Library/FileHandleLib.h index a21e20ed95..6c79397570 100644 --- a/ShellPkg/Include/Library/FileHandleLib.h +++ b/ShellPkg/Include/Library/FileHandleLib.h @@ -49,20 +49,20 @@ FileHandleGetInfo ( @param[in] FileInfo The information to set. - @retval EFI_SUCCESS The information was set. + @retval EFI_SUCCESS The information was set. @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. @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_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. **/ EFI_STATUS EFIAPI FileHandleSetInfo ( - IN EFI_FILE_HANDLE FileHandle, + IN EFI_FILE_HANDLE FileHandle, IN CONST EFI_FILE_INFO *FileInfo ); @@ -87,11 +87,11 @@ FileHandleSetInfo ( the number of bytes written. @param[out] 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. **/ @@ -118,14 +118,14 @@ FileHandleRead( the number of bytes written. @param[in] Buffer The buffer containing data to write is stored. - @retval EFI_SUCCESS Data was written. + @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 opened for read only. - @retval EFI_VOLUME_FULL The volume is full. + @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 opened for read only. + @retval EFI_VOLUME_FULL The volume is full. **/ EFI_STATUS EFIAPI @@ -164,12 +164,12 @@ FileHandleClose ( @retval EFI_SUCCESS The file was closed successfully. @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 INVALID_PARAMETER One of the parameters has an invalid value. **/ EFI_STATUS EFIAPI FileHandleDelete ( - IN EFI_FILE_HANDLE FileHandle + IN EFI_FILE_HANDLE FileHandle ); /** @@ -194,8 +194,8 @@ FileHandleDelete ( EFI_STATUS EFIAPI FileHandleSetPosition ( - IN EFI_FILE_HANDLE FileHandle, - IN UINT64 Position + IN EFI_FILE_HANDLE FileHandle, + IN UINT64 Position ); /** @@ -259,14 +259,18 @@ FileHandleIsDirectory ( IN EFI_FILE_HANDLE DirHandle ); -/** - Retrieves the first file from a directory. +/** Retrieve first entry from a directory. - This function opens a directory and gets the first file's information in the - directory. The caller the uses FileHandleFindNextFile() to get other files. When - complete, the caller is responsible for calling FreePool() on *Buffer. + 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 FileHandleFindNextFile() to get subsequent directory entries. - @param[in] DirHandle The file handle of the directory to search. + The buffer will be freed by FileHandleFindNextFile() when the last directory + entry is read. Otherwise, the caller must free the buffer, using FreePool, + when finished with it. + + @param[in] DirHandle The file handle of the directory to search. @param[out] Buffer The pointer to pointer to buffer for file's information. @retval EFI_SUCCESS Found the first file. @@ -283,17 +287,17 @@ FileHandleFindFirstFile ( IN EFI_FILE_HANDLE DirHandle, OUT EFI_FILE_INFO **Buffer ); -/** - Retrieves the next file in a directory. - To use this function, caller must call the FileHandleFindFirstFile() to get the - first file, and then use this function get other files. This function can be - called for several times to get each file's information in the directory. If - the call of FileHandleFindNextFile() got the last file in the directory, the next - call of this function has no file to get. *NoFile will be set to TRUE and the - Buffer memory will be automatically freed. +/** Retrieve next entries from a directory. + + To use this function, the caller must first call the FileHandleFindFirstFile() + function to get the first directory entry. Subsequent directory entries are + retrieved by using the FileHandleFindNextFile() function. This function can + be called several times to get each entry from the directory. If the call of + FileHandleFindNextFile() retrieved the last directory entry, the next call of + this function will set *NoFile to TRUE and free the buffer. - @param[in] DirHandle The file handle of the directory. + @param[in] DirHandle The file handle of the directory. @param[out] Buffer The pointer to buffer for file's information. @param[out] NoFile The pointer to boolean when last file is found. diff --git a/ShellPkg/Include/Library/ShellLib.h b/ShellPkg/Include/Library/ShellLib.h index 5f3c5588bb..70006266f4 100644 --- a/ShellPkg/Include/Library/ShellLib.h +++ b/ShellPkg/Include/Library/ShellLib.h @@ -59,20 +59,20 @@ ShellGetFileInfo ( @param[in] FileInfo The information to set. - @retval EFI_SUCCESS The information was set. + @retval EFI_SUCCESS The information was set. @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. @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_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. **/ EFI_STATUS EFIAPI ShellSetFileInfo ( - IN SHELL_FILE_HANDLE FileHandle, + IN SHELL_FILE_HANDLE FileHandle, IN EFI_FILE_INFO *FileInfo ); @@ -89,31 +89,31 @@ ShellSetFileInfo ( @param[in] OpenMode The mode to open the file with. @param[in] Attributes The file's file attributes. - @retval EFI_SUCCESS The information was set. - @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @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_NOT_FOUND The specified file could not be found on the + @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. @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 longer supported. @retval EFI_DEVICE_ERROR The device reported an error. - @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @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_OUT_OF_RESOURCES Not enough resources were available to open the + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file. @retval EFI_VOLUME_FULL The volume is full. **/ EFI_STATUS EFIAPI ShellOpenFileByDevicePath( - IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, - OUT EFI_HANDLE *DeviceHandle, - OUT SHELL_FILE_HANDLE *FileHandle, - IN UINT64 OpenMode, - IN UINT64 Attributes + IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, + OUT EFI_HANDLE *DeviceHandle, + OUT SHELL_FILE_HANDLE *FileHandle, + IN UINT64 OpenMode, + IN UINT64 Attributes ); /** @@ -128,30 +128,30 @@ ShellOpenFileByDevicePath( @param[in] OpenMode The mode to open the file with. @param[in] Attributes The file's file attributes. - @retval EFI_SUCCESS The information was set. - @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @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_NOT_FOUND The specified file could not be found on the + @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. @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 longer supported. @retval EFI_DEVICE_ERROR The device reported an error. - @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @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_OUT_OF_RESOURCES Not enough resources were available to open the + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file. @retval EFI_VOLUME_FULL The volume is full. **/ EFI_STATUS EFIAPI ShellOpenFileByName( - IN CONST CHAR16 *FilePath, + IN CONST CHAR16 *FilePath, OUT SHELL_FILE_HANDLE *FileHandle, IN UINT64 OpenMode, - IN UINT64 Attributes + IN UINT64 Attributes ); /** @@ -164,20 +164,20 @@ ShellOpenFileByName( @param[in] DirectoryName The pointer to Directory name. @param[out] FileHandle The 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_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_NOT_FOUND The specified file could not be found on the + @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. @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 longer supported. @retval EFI_DEVICE_ERROR The device reported an error. - @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @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_OUT_OF_RESOURCES Not enough resources were available to open the + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file. @retval EFI_VOLUME_FULL The volume is full. **/ @@ -210,9 +210,9 @@ ShellCreateDirectory( @param[out] 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_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_VOLUME_CORRUPTED The file system structures are corrupted. @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required size. @@ -244,7 +244,7 @@ ShellReadFile( @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_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. @@ -289,7 +289,7 @@ ShellCloseFile ( @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 INVALID_PARAMETER One of the parameters has an invalid value. **/ EFI_STATUS EFIAPI @@ -320,8 +320,8 @@ ShellDeleteFile ( EFI_STATUS EFIAPI ShellSetFilePosition ( - IN SHELL_FILE_HANDLE FileHandle, - IN UINT64 Position + IN SHELL_FILE_HANDLE FileHandle, + IN UINT64 Position ); /** @@ -366,16 +366,18 @@ ShellFlushFile ( IN SHELL_FILE_HANDLE FileHandle ); -/** - Retrieves the first file from a directory +/** Retrieve first entry from a directory. - This function takes an open directory handle and gets the first file - in the directory's info. Caller can use ShellFindNextFile() to get - subsequent files. + 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. - Caller must use FreePool on *Buffer opon completion of all file searching. + 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. - @param[in] DirHandle The file handle of the directory to search. + @param[in] DirHandle The file handle of the directory to search. @param[out] Buffer The pointer to the buffer for the file's information. @retval EFI_SUCCESS Found the first file. @@ -383,41 +385,44 @@ ShellFlushFile ( @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. + @return Others Status of ShellGetFileInfo, ShellSetFilePosition, + or ShellReadFile. + @sa ShellReadFile **/ EFI_STATUS EFIAPI ShellFindFirstFile ( - IN SHELL_FILE_HANDLE DirHandle, - OUT EFI_FILE_INFO **Buffer + IN SHELL_FILE_HANDLE DirHandle, + OUT EFI_FILE_INFO **Buffer ); -/** - Retrieves the next file in a directory. +/** Retrieve next entries from a directory. - To use this function, caller must call the ShellFindFirstFile() to get the - first file, and then use this function get other files. This function can be - called for several times to get each file's information in the directory. If - the call of ShellFindNextFile() got the last file in the directory, the next - call of this function has no file to get. *NoFile will be set to TRUE, and the - data in Buffer is meaningless. + 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. - @param[in] DirHandle The file handle of the directory. - @param[in, out] Buffer The pointer to buffer for file's information. - @param[in, out] NoFile The pointer to boolean when last file is found. + @param[in] DirHandle The file handle of the directory. + @param[out] Buffer The pointer to buffer for file's information. + @param[out] NoFile The pointer to boolean when last file is found. @retval EFI_SUCCESS Found the next file. @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. + @sa ShellReadFile **/ EFI_STATUS EFIAPI ShellFindNextFile( - IN SHELL_FILE_HANDLE DirHandle, - IN OUT EFI_FILE_INFO *Buffer, - IN OUT BOOLEAN *NoFile + IN SHELL_FILE_HANDLE DirHandle, + IN OUT EFI_FILE_INFO *Buffer, + IN OUT BOOLEAN *NoFile ); /** @@ -988,7 +993,7 @@ ShellIsFileInPath( 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 + Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid result. Use ShellConvertStringToUint64 instead. @param[in] String String representation of a number. @@ -1235,9 +1240,9 @@ ShellIsHexOrDecimalNumber ( @param[in] String The string to evaluate. @param[out] Value Upon a successful return the value of the conversion. @param[in] ForceHex TRUE - always assume hex. - @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to + @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to process the entire String. - + @retval EFI_SUCCESS The conversion was successful. @retval EFI_INVALID_PARAMETER String contained an invalid character. @retval EFI_NOT_FOUND String was a number, but Value was NULL. diff --git a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c index 116c78f38b..0e2f93debc 100644 --- a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c +++ b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c @@ -101,20 +101,20 @@ FileHandleGetInfo ( @param[in] FileInfo The information to set. - @retval EFI_SUCCESS The information was set. + @retval EFI_SUCCESS The information was set. @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. @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_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. **/ EFI_STATUS EFIAPI FileHandleSetInfo ( - IN EFI_FILE_HANDLE FileHandle, + IN EFI_FILE_HANDLE FileHandle, IN CONST EFI_FILE_INFO *FileInfo ) { @@ -198,14 +198,14 @@ FileHandleRead( 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. + @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 @@ -266,12 +266,12 @@ FileHandleClose ( @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 INVALID_PARAMETER One of the parameters has an invalid value. **/ EFI_STATUS EFIAPI FileHandleDelete ( - IN EFI_FILE_HANDLE FileHandle + IN EFI_FILE_HANDLE FileHandle ) { EFI_STATUS Status; @@ -308,8 +308,8 @@ FileHandleDelete ( EFI_STATUS EFIAPI FileHandleSetPosition ( - IN EFI_FILE_HANDLE FileHandle, - IN UINT64 Position + IN EFI_FILE_HANDLE FileHandle, + IN UINT64 Position ) { // @@ -441,15 +441,19 @@ FileHandleIsDirectory ( return (EFI_SUCCESS); } -/** - Retrieves the first file from a directory +/** 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 FileHandleFindNextFile() to get subsequent directory entries. - This function opens a directory and gets the first file's info in the - directory. Caller can use FileHandleFindNextFile() to get other files. When - complete the caller is responsible for calling FreePool() on Buffer. + The buffer will be freed by FileHandleFindNextFile() when the last directory + entry is read. Otherwise, the caller must free the buffer, using FreePool, + when finished with it. - @param DirHandle The file handle of the directory to search - @param Buffer Pointer to buffer for file's information + @param[in] DirHandle The file handle of the directory to search. + @param[out] Buffer The pointer to pointer to buffer for file's information. @retval EFI_SUCCESS Found the first file. @retval EFI_NOT_FOUND Cannot find the directory. @@ -512,19 +516,19 @@ FileHandleFindFirstFile ( } return (EFI_SUCCESS); } -/** - Retrieves the next file in a directory. - To use this function, caller must call the FileHandleFindFirstFile() to get the - first file, and then use this function get other files. This function can be - called for several times to get each file's information in the directory. If - the call of FileHandleFindNextFile() got the last file in the directory, the next - call of this function has no file to get. *NoFile will be set to TRUE and the - Buffer memory will be automatically freed. +/** Retrieve next entries from a directory. + + To use this function, the caller must first call the FileHandleFindFirstFile() + function to get the first directory entry. Subsequent directory entries are + retrieved by using the FileHandleFindNextFile() function. This function can + be called several times to get each entry from the directory. If the call of + FileHandleFindNextFile() retrieved the last directory entry, the next call of + this function will set *NoFile to TRUE and free the buffer. - @param DirHandle the file handle of the directory - @param Buffer pointer to buffer for file's information - @param NoFile pointer to boolean when last file is found + @param[in] DirHandle The file handle of the directory. + @param[out] Buffer The pointer to buffer for file's information. + @param[out] NoFile The pointer to boolean when last file is found. @retval EFI_SUCCESS Found the next file, or reached last file @retval EFI_NO_MEDIA The device has no media. @@ -534,9 +538,9 @@ FileHandleFindFirstFile ( EFI_STATUS EFIAPI FileHandleFindNextFile( - IN EFI_FILE_HANDLE DirHandle, - OUT EFI_FILE_INFO *Buffer, - OUT BOOLEAN *NoFile + IN EFI_FILE_HANDLE DirHandle, + OUT EFI_FILE_INFO *Buffer, + OUT BOOLEAN *NoFile ) { EFI_STATUS Status; diff --git a/ShellPkg/Library/UefiShellLib/UefiShellLib.c b/ShellPkg/Library/UefiShellLib/UefiShellLib.c index d131f9b189..77cf5e7795 100644 --- a/ShellPkg/Library/UefiShellLib/UefiShellLib.c +++ b/ShellPkg/Library/UefiShellLib/UefiShellLib.c @@ -163,7 +163,7 @@ ShellFindSE2 ( } /** - Function to do most of the work of the constructor. Allows for calling + Function to do most of the work of the constructor. Allows for calling multiple times without complete re-initialization. @param[in] ImageHandle A copy of the ImageHandle. @@ -421,20 +421,20 @@ ShellGetFileInfo ( @param[in] FileInfo The information to set. - @retval EFI_SUCCESS The information was set. + @retval EFI_SUCCESS The information was set. @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. @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_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. **/ EFI_STATUS EFIAPI ShellSetFileInfo ( - IN SHELL_FILE_HANDLE FileHandle, + IN SHELL_FILE_HANDLE FileHandle, IN EFI_FILE_INFO *FileInfo ) { @@ -447,38 +447,38 @@ 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. - @param OpenMode the mode to open the file with. - @param Attributes the file's file attributes. - - @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_NOT_FOUND The specified file could not be found on the + @param DeviceHandle pointer to the system device handle. + @param FileHandle pointer to the file handle. + @param OpenMode the mode to open the file with. + @param Attributes the file's file attributes. + + @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_NOT_FOUND The specified file could not be found on the device or the file system could not be found 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 + @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 longer supported. - @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_OUT_OF_RESOURCES Not enough resources were available to open the + @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_OUT_OF_RESOURCES Not enough resources were available to open the file. - @retval EFI_VOLUME_FULL The volume is full. + @retval EFI_VOLUME_FULL The volume is full. **/ EFI_STATUS EFIAPI ShellOpenFileByDevicePath( - IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, - OUT EFI_HANDLE *DeviceHandle, + IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, + OUT EFI_HANDLE *DeviceHandle, OUT SHELL_FILE_HANDLE *FileHandle, - IN UINT64 OpenMode, - IN UINT64 Attributes + IN UINT64 OpenMode, + IN UINT64 Attributes ) { CHAR16 *FileName; @@ -605,35 +605,35 @@ ShellOpenFileByDevicePath( if FileName is NULL then ASSERT() - @param FileName pointer to file name - @param FileHandle pointer to the file handle. - @param OpenMode the mode to open the file with. - @param Attributes the file's file attributes. + @param FileName pointer to file name + @param FileHandle pointer to the file handle. + @param OpenMode the mode to open the file with. + @param Attributes the file's file attributes. - @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_NOT_FOUND The specified file could not be found on the + @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_NOT_FOUND The specified file could not be found on the device or the file system could not be found 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 + @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 longer supported. - @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_OUT_OF_RESOURCES Not enough resources were available to open the + @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_OUT_OF_RESOURCES Not enough resources were available to open the file. - @retval EFI_VOLUME_FULL The volume is full. + @retval EFI_VOLUME_FULL The volume is full. **/ EFI_STATUS EFIAPI ShellOpenFileByName( - IN CONST CHAR16 *FileName, + IN CONST CHAR16 *FileName, OUT SHELL_FILE_HANDLE *FileHandle, IN UINT64 OpenMode, - IN UINT64 Attributes + IN UINT64 Attributes ) { EFI_HANDLE DeviceHandle; @@ -692,25 +692,25 @@ 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_NOT_FOUND The specified file could not be found on the + @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_NOT_FOUND The specified file could not be found on the device or the file system could not be found 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 + @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 longer supported. - @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_OUT_OF_RESOURCES Not enough resources were available to open the + @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_OUT_OF_RESOURCES Not enough resources were available to open the file. - @retval EFI_VOLUME_FULL The volume is full. + @retval EFI_VOLUME_FULL The volume is full. @sa ShellOpenFileByName **/ EFI_STATUS @@ -758,11 +758,11 @@ ShellCreateDirectory( the number of bytes written. @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. **/ @@ -793,14 +793,14 @@ ShellReadFile( 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. + @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 @@ -845,12 +845,12 @@ ShellCloseFile ( @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 INVALID_PARAMETER One of the parameters has an invalid value. **/ EFI_STATUS EFIAPI ShellDeleteFile ( - IN SHELL_FILE_HANDLE *FileHandle + IN SHELL_FILE_HANDLE *FileHandle ) { return (FileFunctionMap.DeleteFile(*FileHandle)); @@ -878,8 +878,8 @@ ShellDeleteFile ( EFI_STATUS EFIAPI ShellSetFilePosition ( - IN SHELL_FILE_HANDLE FileHandle, - IN UINT64 Position + IN SHELL_FILE_HANDLE FileHandle, + IN UINT64 Position ) { return (FileFunctionMap.SetFilePosition(FileHandle, Position)); @@ -932,15 +932,19 @@ ShellFlushFile ( return (FileFunctionMap.FlushFile(FileHandle)); } -/** - Retrieves the first file from a directory +/** Retrieve first entry from a directory. - This function opens a directory and gets the first file's info in the - directory. Caller can use ShellFindNextFile() to get other files. When - complete the caller is responsible for calling FreePool() on Buffer. + 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. - @param DirHandle The file handle of the directory to search - @param Buffer Pointer to buffer for file's information + 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. + + @param[in] DirHandle The file handle of the directory to search. + @param[out] Buffer The pointer to the buffer for the file's information. @retval EFI_SUCCESS Found the first file. @retval EFI_NOT_FOUND Cannot find the directory. @@ -962,19 +966,18 @@ ShellFindFirstFile ( // return (FileHandleFindFirstFile(DirHandle, Buffer)); } -/** - Retrieves the next file in a directory. +/** Retrieve next entries from a directory. - To use this function, caller must call the ShellFindFirstFile() to get the - first file, and then use this function get other files. This function can be - called for several times to get each file's information in the directory. If - the call of ShellFindNextFile() got the last file in the directory, the next - call of this function has no file to get. *NoFile will be set to TRUE and the - Buffer memory will be automatically freed. + 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. - @param DirHandle the file handle of the directory - @param Buffer pointer to buffer for file's information - @param NoFile pointer to boolean when last file is found + @param[in] DirHandle The file handle of the directory. + @param[out] Buffer The pointer to buffer for file's information. + @param[out] NoFile The pointer to boolean when last file is found. @retval EFI_SUCCESS Found the next file, or reached last file @retval EFI_NO_MEDIA The device has no media. @@ -1807,7 +1810,7 @@ InternalIsOnCheckList ( // If the Type is TypeStart only check the first characters of the passed in param // If it matches set the type and return TRUE // - if (TempListItem->Type == TypeStart) { + if (TempListItem->Type == TypeStart) { if (StrnCmp(Name, TempListItem->Name, StrLen(TempListItem->Name)) == 0) { *Type = TempListItem->Type; return (TRUE); @@ -2031,7 +2034,7 @@ InternalCommandLineParse ( // TempPointer = Argv[LoopCounter]; - if ((*TempPointer == L'^' && *(TempPointer+1) == L'-') + if ((*TempPointer == L'^' && *(TempPointer+1) == L'-') || (*TempPointer == L'^' && *(TempPointer+1) == L'/') || (*TempPointer == L'^' && *(TempPointer+1) == L'+') ){ @@ -2061,7 +2064,7 @@ InternalCommandLineParse ( if (ProblemParam != NULL) { *ProblemParam = AllocateZeroPool(StrSize(Argv[LoopCounter])); if (*ProblemParam != NULL) { - StrCpy(*ProblemParam, Argv[LoopCounter]); + StrCpy(*ProblemParam, Argv[LoopCounter]); } } ShellCommandLineFreeVarList(*CheckPackage); @@ -3418,7 +3421,7 @@ InternalShellIsHexOrDecimalNumber ( if (String != NULL && *String == L'-') { String++; } - + if (String == NULL) { return (FALSE); } @@ -3497,7 +3500,7 @@ ShellFileExists( } /** - Convert a Unicode character to upper case only if + Convert a Unicode character to upper case only if it maps to a valid small-case ASCII character. This internal function only deal with Unicode character @@ -3529,7 +3532,7 @@ InternalShellCharToUpper ( This internal function only deal with Unicode character which maps to a valid hexadecimal ASII character, i.e. - L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other + L'0' to L'9', L'a' to L'f' or L'A' to L'F'. For other Unicode character, the value returned does not make sense. @param Char The character to convert. @@ -3593,9 +3596,9 @@ InternalShellStrHexToUint64 ( if (String == NULL || StrSize(String) == 0 || Value == NULL) { return (EFI_INVALID_PARAMETER); } - + // - // Ignore the pad spaces (space or tab) + // Ignore the pad spaces (space or tab) // while ((*String == L' ') || (*String == L'\t')) { String++; @@ -3619,17 +3622,17 @@ InternalShellStrHexToUint64 ( } Result = 0; - + // // Skip spaces if requested // while (StopAtSpace && *String == L' ') { String++; } - + while (ShellIsHexaDecimalDigitCharacter (*String)) { // - // If the Hex Number represented by String overflows according + // If the Hex Number represented by String overflows according // to the range defined by UINTN, then ASSERT(). // if (!(Result <= (RShiftU64((((UINT64) ~0) - InternalShellHexCharToUintn (*String)), 4)))) { @@ -3720,10 +3723,10 @@ InternalShellStrDecimalToUint64 ( } while (ShellIsDecimalDigitCharacter (*String)) { // - // If the number represented by String overflows according + // If the number represented by String overflows according // to the range defined by UINT64, then ASSERT(). // - + if (!(Result <= (DivU64x32((((UINT64) ~0) - (*String - L'0')),10)))) { return (EFI_DEVICE_ERROR); } @@ -3740,7 +3743,7 @@ InternalShellStrDecimalToUint64 ( } *Value = Result; - + return (EFI_SUCCESS); } @@ -3753,7 +3756,7 @@ InternalShellStrDecimalToUint64 ( @param[out] Value Upon a successful return the value of the conversion. @param[in] ForceHex TRUE - always assume hex. @param[in] StopAtSpace FALSE to skip spaces. - + @retval EFI_SUCCESS The conversion was successful. @retval EFI_INVALID_PARAMETER String contained an invalid character. @retval EFI_NOT_FOUND String was a number, but Value was NULL. @@ -3795,7 +3798,7 @@ ShellConvertStringToUint64( // if (Walker == NULL || *Walker == CHAR_NULL || !InternalShellIsHexOrDecimalNumber(Walker, Hex, StopAtSpace)) { return (EFI_INVALID_PARAMETER); - } + } // // do the conversion. @@ -3880,7 +3883,7 @@ ShellFileHandleReturnLine( return (NULL); } Status = ShellFileHandleReadLine(Handle, RetVal, &Size, FALSE, Ascii); - + } if (EFI_ERROR(Status) && (RetVal != NULL)) { FreePool(RetVal); -- 2.39.2