diff options
| author | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-11-12 00:35:11 +0000 |
|---|---|---|
| committer | darylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524> | 2011-11-12 00:35:11 +0000 |
| commit | b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52 (patch) | |
| tree | 382212d856e9546d7a41256a5c129de7832c7ab0 | |
| parent | 031acf6336e92392966825b05600e4da1c24c655 (diff) | |
| download | edk2-platforms-b0934ac4b0cfae7f537fcc7f2b1c9124e59fda52.tar.xz | |
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
| -rw-r--r-- | ShellPkg/Include/Library/FileHandleLib.h | 78 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/ShellLib.h | 125 | ||||
| -rw-r--r-- | ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c | 82 | ||||
| -rw-r--r-- | 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);
|