sravan/system76-edk2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

ShellPkg: Update comments for functions to clarify buffer origin.

Browse Source 
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
This commit is contained in:
darylm503
2011-11-12 00:35:11 +00:00
parent 031acf6336
commit b0934ac4b0
4 changed files with 264 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
ShellPkg/Include/Library/FileHandleLib.h
View File

@ -49,20 +49,20 @@ FileHandleGetInfo (
@param[in] FileInfo The information to set. @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_INVALID_PARAMETER A parameter was out of range or invalid.
@retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
@retval EFI_NO_MEDIA The device has no medium. @retval EFI_NO_MEDIA The device has no medium.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @retval EFI_ACCESS_DENIED The file was opened read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
FileHandleSetInfo ( FileHandleSetInfo (
IN EFI_FILE_HANDLE FileHandle, IN EFI_FILE_HANDLE FileHandle,
IN CONST EFI_FILE_INFO *FileInfo IN CONST EFI_FILE_INFO *FileInfo
); );
@ -87,11 +87,11 @@ FileHandleSetInfo (
the number of bytes written. the number of bytes written.
@param[out] Buffer The buffer to put read data into. @param[out] Buffer The buffer to put read data into.
@retval EFI_SUCCESS Data was read. @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_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 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
size. size.
**/ **/
@ -118,14 +118,14 @@ FileHandleRead(
the number of bytes written. the number of bytes written.
@param[in] Buffer The buffer containing data to write is stored. @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_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_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 device is write-protected. @retval EFI_WRITE_PROTECTED The device is write-protected.
@retval EFI_ACCESS_DENIED The file was opened for read only. @retval EFI_ACCESS_DENIED The file was opened for read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
@ -164,12 +164,12 @@ FileHandleClose (
@retval EFI_SUCCESS The file was closed successfully. @retval EFI_SUCCESS The file was closed successfully.
@retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not
deleted. 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 EFI_STATUS
EFIAPI EFIAPI
FileHandleDelete ( FileHandleDelete (
IN EFI_FILE_HANDLE FileHandle IN EFI_FILE_HANDLE FileHandle
); );
/** /**
@ -194,8 +194,8 @@ FileHandleDelete (
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
FileHandleSetPosition ( FileHandleSetPosition (
IN EFI_FILE_HANDLE FileHandle, IN EFI_FILE_HANDLE FileHandle,
IN UINT64 Position IN UINT64 Position
); );
/** /**
@ -259,14 +259,18 @@ FileHandleIsDirectory (
IN EFI_FILE_HANDLE DirHandle IN EFI_FILE_HANDLE DirHandle
); );
/** /** Retrieve first entry from a directory.
Retrieves the first file from a directory.
This function opens a directory and gets the first file's information in the This function takes an open directory handle and gets information from the
directory. The caller the uses FileHandleFindNextFile() to get other files. When first entry in the directory. A buffer is allocated to contain
complete, the caller is responsible for calling FreePool() on *Buffer. 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. @param[out] Buffer The pointer to pointer to buffer for file's information.
@retval EFI_SUCCESS Found the first file. @retval EFI_SUCCESS Found the first file.
@ -283,17 +287,17 @@ FileHandleFindFirstFile (
IN EFI_FILE_HANDLE DirHandle, IN EFI_FILE_HANDLE DirHandle,
OUT EFI_FILE_INFO **Buffer OUT EFI_FILE_INFO **Buffer
); );
/**
Retrieves the next file in a directory.
To use this function, caller must call the FileHandleFindFirstFile() to get the /** Retrieve next entries from a directory.
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.
@param[in] DirHandle The file handle of the 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[out] Buffer The pointer to buffer for file's information. @param[out] Buffer The pointer to buffer for file's information.
@param[out] NoFile The pointer to boolean when last file is found. @param[out] NoFile The pointer to boolean when last file is found.

119
ShellPkg/Include/Library/ShellLib.h
View File

@ -59,20 +59,20 @@ ShellGetFileInfo (
@param[in] FileInfo The information to set. @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_INVALID_PARAMETER A parameter was out of range or invalid.
@retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
@retval EFI_NO_MEDIA The device has no medium. @retval EFI_NO_MEDIA The device has no medium.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @retval EFI_ACCESS_DENIED The file was opened read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellSetFileInfo ( ShellSetFileInfo (
IN SHELL_FILE_HANDLE FileHandle, IN SHELL_FILE_HANDLE FileHandle,
IN EFI_FILE_INFO *FileInfo IN EFI_FILE_INFO *FileInfo
); );
@ -89,31 +89,31 @@ ShellSetFileInfo (
@param[in] OpenMode The mode to open the file with. @param[in] OpenMode The mode to open the file with.
@param[in] Attributes The file's file attributes. @param[in] Attributes The file's file attributes.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device or the file system could not be found on device or the file system could not be found on
the device. the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellOpenFileByDevicePath( ShellOpenFileByDevicePath(
IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
OUT EFI_HANDLE *DeviceHandle, OUT EFI_HANDLE *DeviceHandle,
OUT SHELL_FILE_HANDLE *FileHandle, OUT SHELL_FILE_HANDLE *FileHandle,
IN UINT64 OpenMode, IN UINT64 OpenMode,
IN UINT64 Attributes IN UINT64 Attributes
); );
/** /**
@ -128,30 +128,30 @@ ShellOpenFileByDevicePath(
@param[in] OpenMode The mode to open the file with. @param[in] OpenMode The mode to open the file with.
@param[in] Attributes The file's file attributes. @param[in] Attributes The file's file attributes.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device or the file system could not be found device or the file system could not be found
on the device. on the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellOpenFileByName( ShellOpenFileByName(
IN CONST CHAR16 *FilePath, IN CONST CHAR16 *FilePath,
OUT SHELL_FILE_HANDLE *FileHandle, OUT SHELL_FILE_HANDLE *FileHandle,
IN UINT64 OpenMode, IN UINT64 OpenMode,
IN UINT64 Attributes IN UINT64 Attributes
); );
/** /**
@ -164,20 +164,20 @@ ShellOpenFileByName(
@param[in] DirectoryName The pointer to Directory name. @param[in] DirectoryName The pointer to Directory name.
@param[out] FileHandle The pointer to the file handle. @param[out] FileHandle The pointer to the file handle.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device, or the file system could not be found device, or the file system could not be found
on the device. on the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
@ -210,9 +210,9 @@ ShellCreateDirectory(
@param[out] Buffer The buffer to put read data into. @param[out] Buffer The buffer to put read data into.
@retval EFI_SUCCESS Data was read. @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_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 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
size. size.
@ -244,7 +244,7 @@ ShellReadFile(
@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_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_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 device is write-protected. @retval EFI_WRITE_PROTECTED The device is write-protected.
@ -289,7 +289,7 @@ ShellCloseFile (
@retval EFI_SUCCESS The file was closed sucessfully. @retval EFI_SUCCESS The file was closed sucessfully.
@retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not
deleted. 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 EFI_STATUS
EFIAPI EFIAPI
@ -320,8 +320,8 @@ ShellDeleteFile (
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellSetFilePosition ( ShellSetFilePosition (
IN SHELL_FILE_HANDLE FileHandle, IN SHELL_FILE_HANDLE FileHandle,
IN UINT64 Position IN UINT64 Position
); );
/** /**
@ -366,16 +366,18 @@ ShellFlushFile (
IN SHELL_FILE_HANDLE FileHandle IN SHELL_FILE_HANDLE FileHandle
); );
/** /** Retrieve first entry from a directory.
Retrieves the first file from a directory
This function takes an open directory handle and gets the first file This function takes an open directory handle and gets information from the
in the directory's info. Caller can use ShellFindNextFile() to get first entry in the directory. A buffer is allocated to contain
subsequent files. 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. @param[out] Buffer The pointer to the buffer for the file's information.
@retval EFI_SUCCESS Found the first file. @retval EFI_SUCCESS Found the first file.
@ -383,41 +385,44 @@ ShellFlushFile (
@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_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.
@return Others Status of ShellGetFileInfo, ShellSetFilePosition,
or ShellReadFile.
@sa ShellReadFile @sa ShellReadFile
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellFindFirstFile ( ShellFindFirstFile (
IN SHELL_FILE_HANDLE DirHandle, IN SHELL_FILE_HANDLE DirHandle,
OUT EFI_FILE_INFO **Buffer OUT EFI_FILE_INFO **Buffer
); );
/** /** Retrieve next entries from a directory.
Retrieves the next file in a directory.
To use this function, caller must call the ShellFindFirstFile() to get the To use this function, the caller must first call the ShellFindFirstFile()
first file, and then use this function get other files. This function can be function to get the first directory entry. Subsequent directory entries are
called for several times to get each file's information in the directory. If retrieved by using the ShellFindNextFile() function. This function can
the call of ShellFindNextFile() got the last file in the directory, the next be called several times to get each entry from the directory. If the call of
call of this function has no file to get. *NoFile will be set to TRUE, and the ShellFindNextFile() retrieved the last directory entry, the next call of
data in Buffer is meaningless. 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[in, out] Buffer The pointer to buffer for file's information. @param[out] Buffer The pointer to buffer for file's information.
@param[in, out] NoFile The pointer to boolean when last file is found. @param[out] NoFile The pointer to boolean when last file is found.
@retval EFI_SUCCESS Found the next file. @retval EFI_SUCCESS Found the next file.
@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_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.
@sa ShellReadFile @sa ShellReadFile
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellFindNextFile( ShellFindNextFile(
IN SHELL_FILE_HANDLE DirHandle, IN SHELL_FILE_HANDLE DirHandle,
IN OUT EFI_FILE_INFO *Buffer, IN OUT EFI_FILE_INFO *Buffer,
IN OUT BOOLEAN *NoFile IN OUT BOOLEAN *NoFile
); );
/** /**

82
ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
View File

@ -101,20 +101,20 @@ FileHandleGetInfo (
@param[in] FileInfo The information to set. @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_INVALID_PARAMETER A parameter was out of range or invalid.
@retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
@retval EFI_NO_MEDIA The device has no medium. @retval EFI_NO_MEDIA The device has no medium.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @retval EFI_ACCESS_DENIED The file was opened read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
FileHandleSetInfo ( FileHandleSetInfo (
IN EFI_FILE_HANDLE FileHandle, IN EFI_FILE_HANDLE FileHandle,
IN CONST EFI_FILE_INFO *FileInfo IN CONST EFI_FILE_INFO *FileInfo
) )
{ {
@ -198,14 +198,14 @@ FileHandleRead(
the number of bytes written. 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_SUCCESS Data was written.
@retval EFI_UNSUPPORTED Writes to an open directory are not supported. @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_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 device is write-protected. @retval EFI_WRITE_PROTECTED The device is write-protected.
@retval EFI_ACCESS_DENIED The file was open for read only. @retval EFI_ACCESS_DENIED The file was open for read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
@ -266,12 +266,12 @@ FileHandleClose (
@retval EFI_SUCCESS the file was closed sucessfully @retval EFI_SUCCESS the file was closed sucessfully
@retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
deleted 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 EFI_STATUS
EFIAPI EFIAPI
FileHandleDelete ( FileHandleDelete (
IN EFI_FILE_HANDLE FileHandle IN EFI_FILE_HANDLE FileHandle
) )
{ {
EFI_STATUS Status; EFI_STATUS Status;
@ -308,8 +308,8 @@ FileHandleDelete (
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
FileHandleSetPosition ( FileHandleSetPosition (
IN EFI_FILE_HANDLE FileHandle, IN EFI_FILE_HANDLE FileHandle,
IN UINT64 Position IN UINT64 Position
) )
{ {
// //
@ -441,15 +441,19 @@ FileHandleIsDirectory (
return (EFI_SUCCESS); return (EFI_SUCCESS);
} }
/** /** Retrieve first entry from a directory.
Retrieves the first file from a directory
This function opens a directory and gets the first file's info in the This function takes an open directory handle and gets information from the
directory. Caller can use FileHandleFindNextFile() to get other files. When first entry in the directory. A buffer is allocated to contain
complete the caller is responsible for calling FreePool() on Buffer. the information and a pointer to the buffer is returned in *Buffer. The
caller can use FileHandleFindNextFile() to get subsequent directory entries.
@param DirHandle The file handle of the directory to search The buffer will be freed by FileHandleFindNextFile() when the last directory
@param Buffer Pointer to buffer for file's information 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. @retval EFI_SUCCESS Found the first file.
@retval EFI_NOT_FOUND Cannot find the directory. @retval EFI_NOT_FOUND Cannot find the directory.
@ -512,19 +516,19 @@ FileHandleFindFirstFile (
} }
return (EFI_SUCCESS); return (EFI_SUCCESS);
} }
/**
Retrieves the next file in a directory.
To use this function, caller must call the FileHandleFindFirstFile() to get the /** Retrieve next entries from a directory.
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.
@param DirHandle the file handle of the directory To use this function, the caller must first call the FileHandleFindFirstFile()
@param Buffer pointer to buffer for file's information function to get the first directory entry. Subsequent directory entries are
@param NoFile pointer to boolean when last file is found 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[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_SUCCESS Found the next file, or reached last file
@retval EFI_NO_MEDIA The device has no media. @retval EFI_NO_MEDIA The device has no media.
@ -534,9 +538,9 @@ FileHandleFindFirstFile (
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
FileHandleFindNextFile( FileHandleFindNextFile(
IN EFI_FILE_HANDLE DirHandle, IN EFI_FILE_HANDLE DirHandle,
OUT EFI_FILE_INFO *Buffer, OUT EFI_FILE_INFO *Buffer,
OUT BOOLEAN *NoFile OUT BOOLEAN *NoFile
) )
{ {
EFI_STATUS Status; EFI_STATUS Status;

191
ShellPkg/Library/UefiShellLib/UefiShellLib.c
View File

@ -421,20 +421,20 @@ ShellGetFileInfo (
@param[in] FileInfo The information to set. @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_INVALID_PARAMETER A parameter was out of range or invalid.
@retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
@retval EFI_NO_MEDIA The device has no medium. @retval EFI_NO_MEDIA The device has no medium.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @retval EFI_ACCESS_DENIED The file was opened read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellSetFileInfo ( ShellSetFileInfo (
IN SHELL_FILE_HANDLE FileHandle, IN SHELL_FILE_HANDLE FileHandle,
IN EFI_FILE_INFO *FileInfo 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 This function opens a file with the open mode according to the file path. The
Attributes is valid only for EFI_FILE_MODE_CREATE. 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. the remaining device path.
@param DeviceHandle pointer to the system device handle. @param DeviceHandle pointer to the system device handle.
@param FileHandle pointer to the file handle. @param FileHandle pointer to the file handle.
@param OpenMode the mode to open the file with. @param OpenMode the mode to open the file with.
@param Attributes the file's file attributes. @param Attributes the file's file attributes.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device or the file system could not be found on device or the file system could not be found on
the device. the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellOpenFileByDevicePath( ShellOpenFileByDevicePath(
IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
OUT EFI_HANDLE *DeviceHandle, OUT EFI_HANDLE *DeviceHandle,
OUT SHELL_FILE_HANDLE *FileHandle, OUT SHELL_FILE_HANDLE *FileHandle,
IN UINT64 OpenMode, IN UINT64 OpenMode,
IN UINT64 Attributes IN UINT64 Attributes
) )
{ {
CHAR16 *FileName; CHAR16 *FileName;
@ -605,35 +605,35 @@ ShellOpenFileByDevicePath(
if FileName is NULL then ASSERT() if FileName is NULL then ASSERT()
@param FileName pointer to file name @param FileName pointer to file name
@param FileHandle pointer to the file handle. @param FileHandle pointer to the file handle.
@param OpenMode the mode to open the file with. @param OpenMode the mode to open the file with.
@param Attributes the file's file attributes. @param Attributes the file's file attributes.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device or the file system could not be found device or the file system could not be found
on the device. on the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellOpenFileByName( ShellOpenFileByName(
IN CONST CHAR16 *FileName, IN CONST CHAR16 *FileName,
OUT SHELL_FILE_HANDLE *FileHandle, OUT SHELL_FILE_HANDLE *FileHandle,
IN UINT64 OpenMode, IN UINT64 OpenMode,
IN UINT64 Attributes IN UINT64 Attributes
) )
{ {
EFI_HANDLE DeviceHandle; EFI_HANDLE DeviceHandle;
@ -692,25 +692,25 @@ ShellOpenFileByName(
otherwise, the Filehandle is NULL. If the directory already existed, this otherwise, the Filehandle is NULL. If the directory already existed, this
function opens the existing directory. function opens the existing directory.
@param DirectoryName pointer to directory name @param DirectoryName pointer to directory name
@param FileHandle pointer to the file handle. @param FileHandle pointer to the file handle.
@retval EFI_SUCCESS The information was set. @retval EFI_SUCCESS The information was set.
@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. @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 @retval EFI_NOT_FOUND The specified file could not be found on the
device or the file system could not be found device or the file system could not be found
on the device. on the device.
@retval EFI_NO_MEDIA The device has no medium. @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_MEDIA_CHANGED The device has a different medium in it or the
medium is no longer supported. medium is no longer supported.
@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_VOLUME_CORRUPTED The file system structures are corrupted.
@retval EFI_WRITE_PROTECTED The file or medium is write protected. @retval EFI_WRITE_PROTECTED The file or medium is write protected.
@retval EFI_ACCESS_DENIED The file was opened read only. @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. file.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
@sa ShellOpenFileByName @sa ShellOpenFileByName
**/ **/
EFI_STATUS EFI_STATUS
@ -758,11 +758,11 @@ ShellCreateDirectory(
the number of bytes written. 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_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_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 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
size. size.
**/ **/
@ -793,14 +793,14 @@ ShellReadFile(
the number of bytes written. 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_SUCCESS Data was written.
@retval EFI_UNSUPPORTED Writes to an open directory are not supported. @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_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 device is write-protected. @retval EFI_WRITE_PROTECTED The device is write-protected.
@retval EFI_ACCESS_DENIED The file was open for read only. @retval EFI_ACCESS_DENIED The file was open for read only.
@retval EFI_VOLUME_FULL The volume is full. @retval EFI_VOLUME_FULL The volume is full.
**/ **/
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
@ -845,12 +845,12 @@ ShellCloseFile (
@retval EFI_SUCCESS the file was closed sucessfully @retval EFI_SUCCESS the file was closed sucessfully
@retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
deleted 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 EFI_STATUS
EFIAPI EFIAPI
ShellDeleteFile ( ShellDeleteFile (
IN SHELL_FILE_HANDLE *FileHandle IN SHELL_FILE_HANDLE *FileHandle
) )
{ {
return (FileFunctionMap.DeleteFile(*FileHandle)); return (FileFunctionMap.DeleteFile(*FileHandle));
@ -878,8 +878,8 @@ ShellDeleteFile (
EFI_STATUS EFI_STATUS
EFIAPI EFIAPI
ShellSetFilePosition ( ShellSetFilePosition (
IN SHELL_FILE_HANDLE FileHandle, IN SHELL_FILE_HANDLE FileHandle,
IN UINT64 Position IN UINT64 Position
) )
{ {
return (FileFunctionMap.SetFilePosition(FileHandle, Position)); return (FileFunctionMap.SetFilePosition(FileHandle, Position));
@ -932,15 +932,19 @@ ShellFlushFile (
return (FileFunctionMap.FlushFile(FileHandle)); return (FileFunctionMap.FlushFile(FileHandle));
} }
/** /** Retrieve first entry from a directory.
Retrieves the first file from a directory
This function opens a directory and gets the first file's info in the This function takes an open directory handle and gets information from the
directory. Caller can use ShellFindNextFile() to get other files. When first entry in the directory. A buffer is allocated to contain
complete the caller is responsible for calling FreePool() on Buffer. 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 The buffer will be freed by ShellFindNextFile() when the last directory
@param Buffer Pointer to buffer for file's information 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_SUCCESS Found the first file.
@retval EFI_NOT_FOUND Cannot find the directory. @retval EFI_NOT_FOUND Cannot find the directory.
@ -962,19 +966,18 @@ ShellFindFirstFile (
// //
return (FileHandleFindFirstFile(DirHandle, Buffer)); return (FileHandleFindFirstFile(DirHandle, Buffer));
} }
/** /** Retrieve next entries from a directory.
Retrieves the next file in a directory.
To use this function, caller must call the ShellFindFirstFile() to get the To use this function, the caller must first call the ShellFindFirstFile()
first file, and then use this function get other files. This function can be function to get the first directory entry. Subsequent directory entries are
called for several times to get each file's information in the directory. If retrieved by using the ShellFindNextFile() function. This function can
the call of ShellFindNextFile() got the last file in the directory, the next be called several times to get each entry from the directory. If the call of
call of this function has no file to get. *NoFile will be set to TRUE and the ShellFindNextFile() retrieved the last directory entry, the next call of
Buffer memory will be automatically freed. this function will set *NoFile to TRUE and free the buffer.
@param DirHandle the file handle of the directory @param[in] DirHandle The file handle of the directory.
@param Buffer pointer to buffer for file's information @param[out] Buffer The pointer to buffer for file's information.
@param NoFile pointer to boolean when last file is found @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_SUCCESS Found the next file, or reached last file
@retval EFI_NO_MEDIA The device has no media. @retval EFI_NO_MEDIA The device has no media.