2 Provides interface to EFI_FILE_HANDLE functionality.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved. <BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
11 #include <Protocol/SimpleFileSystem.h>
12 #include <Protocol/UnicodeCollation.h>
14 #include <Guid/FileInfo.h>
16 #include <Library/DebugLib.h>
17 #include <Library/MemoryAllocationLib.h>
18 #include <Library/BaseLib.h>
19 #include <Library/BaseMemoryLib.h>
20 #include <Library/FileHandleLib.h>
21 #include <Library/PcdLib.h>
22 #include <Library/PrintLib.h>
24 CONST UINT16 gUnicodeFileTag
= EFI_UNICODE_BYTE_ORDER_MARK
;
26 #define MAX_FILE_NAME_LEN 522// (20 * (6+5+2))+1) unicode characters from EFI FAT spec (doubled for bytes)
27 #define FIND_XXXXX_FILE_BUFFER_SIZE (SIZE_OF_EFI_FILE_INFO + MAX_FILE_NAME_LEN)
30 This function will retrieve the information about the file for the handle
31 specified and store it in allocated pool memory.
33 This function allocates a buffer to store the file's information. It is the
34 caller's responsibility to free the buffer
36 @param FileHandle The file handle of the file for which information is
39 @retval NULL information could not be retrieved.
41 @return the information about the file
46 IN EFI_FILE_HANDLE FileHandle
49 EFI_FILE_INFO
*FileInfo
;
53 if (FileHandle
== NULL
) {
58 // Get the required size to allocate
62 Status
= FileHandle
->GetInfo (
68 if (Status
== EFI_BUFFER_TOO_SMALL
) {
70 // error is expected. getting size to allocate
72 FileInfo
= AllocateZeroPool (FileInfoSize
);
73 if (FileInfo
!= NULL
) {
75 // now get the information
77 Status
= FileHandle
->GetInfo (
84 // if we got an error free the memory and return NULL
86 if (EFI_ERROR (Status
)) {
97 This function sets the information about the file for the opened handle
100 @param[in] FileHandle The file handle of the file for which information
103 @param[in] FileInfo The information to set.
105 @retval EFI_SUCCESS The information was set.
106 @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid.
107 @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
108 @retval EFI_NO_MEDIA The device has no medium.
109 @retval EFI_DEVICE_ERROR The device reported an error.
110 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
111 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
112 @retval EFI_ACCESS_DENIED The file was opened read only.
113 @retval EFI_VOLUME_FULL The volume is full.
118 IN EFI_FILE_HANDLE FileHandle
,
119 IN CONST EFI_FILE_INFO
*FileInfo
122 if ((FileHandle
== NULL
) || (FileInfo
== NULL
)) {
123 return (EFI_INVALID_PARAMETER
);
129 return (FileHandle
->SetInfo (
132 (UINTN
)FileInfo
->Size
,
133 (EFI_FILE_INFO
*)FileInfo
138 This function reads information from an opened file.
140 If FileHandle is not a directory, the function reads the requested number of
141 bytes from the file at the file's current position and returns them in Buffer.
142 If the read goes beyond the end of the file, the read length is truncated to the
143 end of the file. The file's current position is increased by the number of bytes
144 returned. If FileHandle is a directory, the function reads the directory entry
145 at the file's current position and returns the entry in Buffer. If the Buffer
146 is not large enough to hold the current directory entry, then
147 EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.
148 BufferSize is set to be the size of the buffer needed to read the entry. On
149 success, the current position is updated to the next directory entry. If there
150 are no more directory entries, the read returns a zero-length buffer.
151 EFI_FILE_INFO is the structure returned as the directory entry.
153 @param FileHandle the opened file handle
154 @param BufferSize on input the size of buffer in bytes. on return
155 the number of bytes written.
156 @param Buffer the buffer to put read data into.
158 @retval EFI_SUCCESS Data was read.
159 @retval EFI_NO_MEDIA The device has no media.
160 @retval EFI_DEVICE_ERROR The device reported an error.
161 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
162 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
169 IN EFI_FILE_HANDLE FileHandle
,
170 IN OUT UINTN
*BufferSize
,
174 if (FileHandle
== NULL
) {
175 return (EFI_INVALID_PARAMETER
);
179 // Perform the read based on EFI_FILE_PROTOCOL
181 return (FileHandle
->Read (FileHandle
, BufferSize
, Buffer
));
185 Write data to a file.
187 This function writes the specified number of bytes to the file at the current
188 file position. The current file position is advanced the actual number of bytes
189 written, which is returned in BufferSize. Partial writes only occur when there
190 has been a data error during the write attempt (such as "volume space full").
191 The file is automatically grown to hold the data if required. Direct writes to
192 opened directories are not supported.
194 @param FileHandle The opened file for writing
195 @param BufferSize on input the number of bytes in Buffer. On output
196 the number of bytes written.
197 @param Buffer the buffer containing data to write is stored.
199 @retval EFI_SUCCESS Data was written.
200 @retval EFI_UNSUPPORTED Writes to an open directory are not supported.
201 @retval EFI_NO_MEDIA The device has no media.
202 @retval EFI_DEVICE_ERROR The device reported an error.
203 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
204 @retval EFI_WRITE_PROTECTED The device is write-protected.
205 @retval EFI_ACCESS_DENIED The file was open for read only.
206 @retval EFI_VOLUME_FULL The volume is full.
211 IN EFI_FILE_HANDLE FileHandle
,
212 IN OUT UINTN
*BufferSize
,
216 if (FileHandle
== NULL
) {
217 return (EFI_INVALID_PARAMETER
);
221 // Perform the write based on EFI_FILE_PROTOCOL
223 return (FileHandle
->Write (FileHandle
, BufferSize
, Buffer
));
227 Close an open file handle.
229 This function closes a specified file handle. All "dirty" cached file data is
230 flushed to the device, and the file is closed. In all cases the handle is
233 @param FileHandle the file handle to close.
235 @retval EFI_SUCCESS the file handle was closed successfully.
240 IN EFI_FILE_HANDLE FileHandle
245 if (FileHandle
== NULL
) {
246 return (EFI_INVALID_PARAMETER
);
250 // Perform the Close based on EFI_FILE_PROTOCOL
252 Status
= FileHandle
->Close (FileHandle
);
257 Delete a file and close the handle
259 This function closes and deletes a file. In all cases the file handle is closed.
260 If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is
261 returned, but the handle is still closed.
263 @param FileHandle the file handle to delete
265 @retval EFI_SUCCESS the file was closed successfully
266 @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
268 @retval INVALID_PARAMETER One of the parameters has an invalid value.
273 IN EFI_FILE_HANDLE FileHandle
278 if (FileHandle
== NULL
) {
279 return (EFI_INVALID_PARAMETER
);
283 // Perform the Delete based on EFI_FILE_PROTOCOL
285 Status
= FileHandle
->Delete (FileHandle
);
290 Set the current position in a file.
292 This function sets the current file position for the handle to the position
293 supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only
294 absolute positioning is supported, and seeking past the end of the file is
295 allowed (a subsequent write would grow the file). Seeking to position
296 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.
297 If FileHandle is a directory, the only position that may be set is zero. This
298 has the effect of starting the read process of the directory entries over.
300 @param FileHandle The file handle on which the position is being set
301 @param Position Byte position from beginning of file
303 @retval EFI_SUCCESS Operation completed successfully.
304 @retval EFI_UNSUPPORTED the seek request for non-zero is not valid on
306 @retval INVALID_PARAMETER One of the parameters has an invalid value.
310 FileHandleSetPosition (
311 IN EFI_FILE_HANDLE FileHandle
,
315 if (FileHandle
== NULL
) {
316 return (EFI_INVALID_PARAMETER
);
320 // Perform the SetPosition based on EFI_FILE_PROTOCOL
322 return (FileHandle
->SetPosition (FileHandle
, Position
));
326 Gets a file's current position
328 This function retrieves the current file position for the file handle. For
329 directories, the current file position has no meaning outside of the file
330 system driver and as such the operation is not supported. An error is returned
331 if FileHandle is a directory.
333 @param FileHandle The open file handle on which to get the position.
334 @param Position Byte position from beginning of file.
336 @retval EFI_SUCCESS the operation completed successfully.
337 @retval INVALID_PARAMETER One of the parameters has an invalid value.
338 @retval EFI_UNSUPPORTED the request is not valid on directories.
342 FileHandleGetPosition (
343 IN EFI_FILE_HANDLE FileHandle
,
347 if ((Position
== NULL
) || (FileHandle
== NULL
)) {
348 return (EFI_INVALID_PARAMETER
);
352 // Perform the GetPosition based on EFI_FILE_PROTOCOL
354 return (FileHandle
->GetPosition (FileHandle
, Position
));
358 Flushes data on a file
360 This function flushes all modified data associated with a file to a device.
362 @param FileHandle The file handle on which to flush data
364 @retval EFI_SUCCESS The data was flushed.
365 @retval EFI_NO_MEDIA The device has no media.
366 @retval EFI_DEVICE_ERROR The device reported an error.
367 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
368 @retval EFI_WRITE_PROTECTED The file or medium is write protected.
369 @retval EFI_ACCESS_DENIED The file was opened for read only.
374 IN EFI_FILE_HANDLE FileHandle
377 if (FileHandle
== NULL
) {
378 return (EFI_INVALID_PARAMETER
);
382 // Perform the Flush based on EFI_FILE_PROTOCOL
384 return (FileHandle
->Flush (FileHandle
));
388 Function to determine if a given handle is a directory handle.
390 Open the file information on the DirHandle and verify that the Attribute
391 includes EFI_FILE_DIRECTORY bit set.
393 @param[in] DirHandle Handle to open file.
395 @retval EFI_SUCCESS DirHandle is a directory.
396 @retval EFI_INVALID_PARAMETER DirHandle is NULL.
397 The file information returns from FileHandleGetInfo is NULL.
398 @retval EFI_NOT_FOUND DirHandle is not a directory.
402 FileHandleIsDirectory (
403 IN EFI_FILE_HANDLE DirHandle
406 EFI_FILE_INFO
*DirInfo
;
408 if (DirHandle
== NULL
) {
409 return (EFI_INVALID_PARAMETER
);
413 // get the file information for DirHandle
415 DirInfo
= FileHandleGetInfo (DirHandle
);
420 if (DirInfo
== NULL
) {
424 return (EFI_INVALID_PARAMETER
);
427 if ((DirInfo
->Attribute
& EFI_FILE_DIRECTORY
) == 0) {
429 // Attributes say this is not a directory
432 return (EFI_NOT_FOUND
);
439 return (EFI_SUCCESS
);
442 /** Retrieve first entry from a directory.
444 This function takes an open directory handle and gets information from the
445 first entry in the directory. A buffer is allocated to contain
446 the information and a pointer to the buffer is returned in *Buffer. The
447 caller can use FileHandleFindNextFile() to get subsequent directory entries.
449 The buffer will be freed by FileHandleFindNextFile() when the last directory
450 entry is read. Otherwise, the caller must free the buffer, using FreePool,
451 when finished with it.
453 @param[in] DirHandle The file handle of the directory to search.
454 @param[out] Buffer The pointer to pointer to buffer for file's information.
456 @retval EFI_SUCCESS Found the first file.
457 @retval EFI_NOT_FOUND Cannot find the directory.
458 @retval EFI_NO_MEDIA The device has no media.
459 @retval EFI_DEVICE_ERROR The device reported an error.
460 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
461 @return Others status of FileHandleGetInfo, FileHandleSetPosition,
466 FileHandleFindFirstFile (
467 IN EFI_FILE_HANDLE DirHandle
,
468 OUT EFI_FILE_INFO
**Buffer
474 if ((Buffer
== NULL
) || (DirHandle
== NULL
)) {
475 return (EFI_INVALID_PARAMETER
);
479 // verify that DirHandle is a directory
481 Status
= FileHandleIsDirectory (DirHandle
);
482 if (EFI_ERROR (Status
)) {
487 // Allocate a buffer sized to struct size + enough for the string at the end
489 BufferSize
= FIND_XXXXX_FILE_BUFFER_SIZE
;
490 *Buffer
= AllocateZeroPool (BufferSize
);
491 if (*Buffer
== NULL
) {
492 return (EFI_OUT_OF_RESOURCES
);
496 // reset to the beginning of the directory
498 Status
= FileHandleSetPosition (DirHandle
, 0);
499 if (EFI_ERROR (Status
)) {
506 // read in the info about the first file
508 Status
= FileHandleRead (DirHandle
, &BufferSize
, *Buffer
);
509 ASSERT (Status
!= EFI_BUFFER_TOO_SMALL
);
510 if (EFI_ERROR (Status
) || (BufferSize
== 0)) {
513 if (BufferSize
== 0) {
514 return (EFI_NOT_FOUND
);
520 return (EFI_SUCCESS
);
523 /** Retrieve next entries from a directory.
525 To use this function, the caller must first call the FileHandleFindFirstFile()
526 function to get the first directory entry. Subsequent directory entries are
527 retrieved by using the FileHandleFindNextFile() function. This function can
528 be called several times to get each entry from the directory. If the call of
529 FileHandleFindNextFile() retrieved the last directory entry, the next call of
530 this function will set *NoFile to TRUE and free the buffer.
532 @param[in] DirHandle The file handle of the directory.
533 @param[out] Buffer The pointer to buffer for file's information.
534 @param[out] NoFile The pointer to boolean when last file is found.
536 @retval EFI_SUCCESS Found the next file, or reached last file
537 @retval EFI_NO_MEDIA The device has no media.
538 @retval EFI_DEVICE_ERROR The device reported an error.
539 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
543 FileHandleFindNextFile (
544 IN EFI_FILE_HANDLE DirHandle
,
545 OUT EFI_FILE_INFO
*Buffer
,
552 if ((DirHandle
== NULL
) || (Buffer
== NULL
) || (NoFile
== NULL
)) {
553 return (EFI_INVALID_PARAMETER
);
557 // This BufferSize MUST stay equal to the originally allocated one in GetFirstFile
559 BufferSize
= FIND_XXXXX_FILE_BUFFER_SIZE
;
562 // read in the info about the next file
564 Status
= FileHandleRead (DirHandle
, &BufferSize
, Buffer
);
565 ASSERT (Status
!= EFI_BUFFER_TOO_SMALL
);
566 if (EFI_ERROR (Status
)) {
571 // If we read 0 bytes (but did not have erros) we already read in the last file.
573 if (BufferSize
== 0) {
578 return (EFI_SUCCESS
);
582 Retrieve the size of a file.
584 This function extracts the file size info from the FileHandle's EFI_FILE_INFO
587 @param[in] FileHandle The file handle from which size is retrieved.
588 @param[out] Size The pointer to size.
590 @retval EFI_SUCCESS Operation was completed successfully.
591 @retval EFI_DEVICE_ERROR Cannot access the file.
592 @retval EFI_INVALID_PARAMETER FileHandle is NULL.
598 IN EFI_FILE_HANDLE FileHandle
,
602 EFI_FILE_INFO
*FileInfo
;
604 if ((FileHandle
== NULL
) || (Size
== NULL
)) {
605 return (EFI_INVALID_PARAMETER
);
609 // get the FileInfo structure
611 FileInfo
= FileHandleGetInfo (FileHandle
);
612 if (FileInfo
== NULL
) {
613 return (EFI_DEVICE_ERROR
);
617 // Assign the Size pointer to the correct value
619 *Size
= FileInfo
->FileSize
;
622 // free the FileInfo memory
626 return (EFI_SUCCESS
);
630 Set the size of a file.
632 This function changes the file size info from the FileHandle's EFI_FILE_INFO
635 @param[in] FileHandle The file handle whose size is to be changed.
636 @param[in] Size The new size.
638 @retval EFI_SUCCESS The operation completed successfully.
639 @retval EFI_DEVICE_ERROR Cannot access the file.
640 @retval EFI_INVALID_PARAMETER FileHandle is NULL.
645 IN EFI_FILE_HANDLE FileHandle
,
649 EFI_FILE_INFO
*FileInfo
;
652 if (FileHandle
== NULL
) {
653 return (EFI_INVALID_PARAMETER
);
657 // get the FileInfo structure
659 FileInfo
= FileHandleGetInfo (FileHandle
);
660 if (FileInfo
== NULL
) {
661 return (EFI_DEVICE_ERROR
);
665 // Assign the FileSize pointer to the new value
667 FileInfo
->FileSize
= Size
;
669 Status
= FileHandleSetInfo (FileHandle
, FileInfo
);
671 // free the FileInfo memory
679 Safely append (on the left) with automatic string resizing given length of Destination and
680 desired length of copy from Source.
682 append the first D characters of Source to the end of Destination, where D is
683 the lesser of Count and the StrLen() of Source. If appending those D characters
684 will fit within Destination (whose Size is given as CurrentSize) and
685 still leave room for a NULL terminator, then those characters are appended,
686 starting at the original terminating NULL of Destination, and a new terminating
689 If appending D characters onto Destination will result in a overflow of the size
690 given in CurrentSize the string will be grown such that the copy can be performed
691 and CurrentSize will be updated to the new size.
693 If Source is NULL, there is nothing to append, just return the current buffer in
696 if Destination is NULL, then return error
697 if Destination's current length (including NULL terminator) is already more then
698 CurrentSize, then ASSERT()
700 @param[in, out] Destination The String to append onto
701 @param[in, out] CurrentSize on call the number of bytes in Destination. On
702 return possibly the new size (still in bytes). if NULL
703 then allocate whatever is needed.
704 @param[in] Source The String to append from
705 @param[in] Count Maximum number of characters to append. if 0 then
708 @return Destination return the resultant string.
713 IN OUT CHAR16
**Destination
,
714 IN OUT UINTN
*CurrentSize
,
715 IN CONST CHAR16
*Source
,
719 UINTN DestinationStartSize
;
723 if (Destination
== NULL
) {
728 // If there's nothing to do then just return Destination
730 if (Source
== NULL
) {
731 return (*Destination
);
735 // allow for NULL pointers address as Destination
737 if (*Destination
!= NULL
) {
738 ASSERT (CurrentSize
!= 0);
739 DestinationStartSize
= StrSize (*Destination
);
740 ASSERT (DestinationStartSize
<= *CurrentSize
);
742 DestinationStartSize
= 0;
743 // ASSERT(*CurrentSize == 0);
747 // Append all of Source?
750 Count
= StrSize (Source
);
754 // Test and grow if required
756 if (CurrentSize
!= NULL
) {
757 NewSize
= *CurrentSize
;
758 while (NewSize
< (DestinationStartSize
+ Count
)) {
759 NewSize
+= 2 * Count
;
762 *Destination
= ReallocatePool (*CurrentSize
, NewSize
, *Destination
);
763 *CurrentSize
= NewSize
;
765 *Destination
= AllocateZeroPool (Count
+sizeof (CHAR16
));
768 if (*Destination
== NULL
) {
772 CopySize
= StrSize (*Destination
);
773 CopyMem ((*Destination
)+((Count
-2)/sizeof (CHAR16
)), *Destination
, CopySize
);
774 CopyMem (*Destination
, Source
, Count
-2);
775 return (*Destination
);
779 Function to get a full filename given a EFI_FILE_HANDLE somewhere lower on the
780 directory 'stack'. If the file is a directory, then append the '\' char at the
781 end of name string. If it's not a directory, then the last '\' should not be
784 if Handle is NULL, return EFI_INVALID_PARAMETER
786 @param[in] Handle Handle to the Directory or File to create path to.
787 @param[out] FullFileName pointer to pointer to generated full file name. It
788 is the responsibility of the caller to free this memory
789 with a call to FreePool().
790 @retval EFI_SUCCESS the operation was sucessful and the FullFileName is valid.
791 @retval EFI_INVALID_PARAMETER Handle was NULL.
792 @retval EFI_INVALID_PARAMETER FullFileName was NULL.
793 @retval EFI_OUT_OF_RESOURCES a memory allocation failed.
797 FileHandleGetFileName (
798 IN CONST EFI_FILE_HANDLE Handle
,
799 OUT CHAR16
**FullFileName
804 EFI_FILE_HANDLE CurrentHandle
;
805 EFI_FILE_HANDLE NextHigherHandle
;
806 EFI_FILE_INFO
*FileInfo
;
811 // Check our parameters
813 if ((FullFileName
== NULL
) || (Handle
== NULL
)) {
814 return (EFI_INVALID_PARAMETER
);
817 *FullFileName
= NULL
;
818 CurrentHandle
= NULL
;
820 Status
= Handle
->Open (Handle
, &CurrentHandle
, L
".", EFI_FILE_MODE_READ
, 0);
821 if (!EFI_ERROR (Status
)) {
823 // Reverse out the current directory on the device
826 FileInfo
= FileHandleGetInfo (CurrentHandle
);
827 if (FileInfo
== NULL
) {
828 Status
= EFI_OUT_OF_RESOURCES
;
832 // Prepare to move to the parent directory.
833 // Also determine whether CurrentHandle refers to the Root directory.
835 Status
= CurrentHandle
->Open (CurrentHandle
, &NextHigherHandle
, L
"..", EFI_FILE_MODE_READ
, 0);
837 // We got info... do we have a name? if yes precede the current path with it...
839 if ((StrLen (FileInfo
->FileName
) == 0) || EFI_ERROR (Status
)) {
841 // Both FileInfo->FileName being '\0' and EFI_ERROR() suggest that
842 // CurrentHandle refers to the Root directory. As this loop ensures
843 // FullFileName is starting with '\\' at all times, signal success
844 // and exit the loop.
845 // While FileInfo->FileName could theoretically be a value other than
846 // '\0' or '\\', '\\' is guaranteed to be supported by the
847 // specification and hence its value can safely be ignored.
849 Status
= EFI_SUCCESS
;
850 if (*FullFileName
== NULL
) {
851 ASSERT ((*FullFileName
== NULL
&& Size
== 0) || (*FullFileName
!= NULL
));
852 *FullFileName
= StrnCatGrowLeft (FullFileName
, &Size
, L
"\\", 0);
858 if (*FullFileName
== NULL
) {
859 ASSERT ((*FullFileName
== NULL
&& Size
== 0) || (*FullFileName
!= NULL
));
860 *FullFileName
= StrnCatGrowLeft (FullFileName
, &Size
, L
"\\", 0);
863 ASSERT ((*FullFileName
== NULL
&& Size
== 0) || (*FullFileName
!= NULL
));
864 *FullFileName
= StrnCatGrowLeft (FullFileName
, &Size
, FileInfo
->FileName
, 0);
865 *FullFileName
= StrnCatGrowLeft (FullFileName
, &Size
, L
"\\", 0);
870 FileHandleClose (CurrentHandle
);
872 // Move to the parent directory
874 CurrentHandle
= NextHigherHandle
;
876 } else if (Status
== EFI_NOT_FOUND
) {
877 Status
= EFI_SUCCESS
;
878 ASSERT ((*FullFileName
== NULL
&& Size
== 0) || (*FullFileName
!= NULL
));
879 *FullFileName
= StrnCatGrowLeft (FullFileName
, &Size
, L
"\\", 0);
882 if ((*FullFileName
!= NULL
) &&
883 ((*FullFileName
)[StrLen (*FullFileName
) - 1] == L
'\\') &&
884 (StrLen (*FullFileName
) > 1) &&
885 (FileHandleIsDirectory (Handle
) == EFI_NOT_FOUND
)
888 (*FullFileName
)[StrLen (*FullFileName
) - 1] = CHAR_NULL
;
891 if (CurrentHandle
!= NULL
) {
892 CurrentHandle
->Close (CurrentHandle
);
895 if (EFI_ERROR (Status
) && (*FullFileName
!= NULL
)) {
896 FreePool (*FullFileName
);
903 Function to read a single line from a file. The \n is not included in the returned
904 buffer. The returned buffer must be callee freed.
906 If the position upon start is 0, then the Ascii Boolean will be set. This should be
907 maintained and not changed for all operations with the same file.
909 @param[in] Handle FileHandle to read from.
910 @param[in, out] Ascii Boolean value for indicating whether the file is Ascii (TRUE) or UCS2 (FALSE);
912 @return The line of text from the file.
914 @sa FileHandleReadLine
918 FileHandleReturnLine (
919 IN EFI_FILE_HANDLE Handle
,
920 IN OUT BOOLEAN
*Ascii
930 Status
= FileHandleReadLine (Handle
, RetVal
, &Size
, FALSE
, Ascii
);
931 if (Status
== EFI_BUFFER_TOO_SMALL
) {
932 RetVal
= AllocateZeroPool (Size
);
933 Status
= FileHandleReadLine (Handle
, RetVal
, &Size
, FALSE
, Ascii
);
936 ASSERT_EFI_ERROR (Status
);
937 if (EFI_ERROR (Status
) && (RetVal
!= NULL
)) {
946 Function to read a single line (up to but not including the \n) from a file.
948 If the position upon start is 0, then the Ascii Boolean will be set. This should be
949 maintained and not changed for all operations with the same file.
950 The function will not return the \r and \n character in buffer. When an empty line is
951 read a CHAR_NULL character will be returned in buffer.
953 @param[in] Handle FileHandle to read from.
954 @param[in, out] Buffer The pointer to buffer to read into.
955 @param[in, out] Size The pointer to number of bytes in Buffer.
956 @param[in] Truncate If the buffer is large enough, this has no effect.
957 If the buffer is is too small and Truncate is TRUE,
958 the line will be truncated.
959 If the buffer is is too small and Truncate is FALSE,
960 then no read will occur.
962 @param[in, out] Ascii Boolean value for indicating whether the file is
963 Ascii (TRUE) or UCS2 (FALSE).
965 @retval EFI_SUCCESS The operation was successful. The line is stored in
967 @retval EFI_INVALID_PARAMETER Handle was NULL.
968 @retval EFI_INVALID_PARAMETER Size was NULL.
969 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
970 Size was updated to the minimum space required.
976 IN EFI_FILE_HANDLE Handle
,
977 IN OUT CHAR16
*Buffer
,
980 IN OUT BOOLEAN
*Ascii
990 UINT64 OriginalFilePosition
;
992 if ( (Handle
== NULL
)
994 || ((Buffer
== NULL
) && (*Size
!= 0))
997 return (EFI_INVALID_PARAMETER
);
1000 if ((Buffer
!= NULL
) && (*Size
!= 0)) {
1001 *Buffer
= CHAR_NULL
;
1004 Status
= FileHandleGetSize (Handle
, &FileSize
);
1005 if (EFI_ERROR (Status
)) {
1007 } else if (FileSize
== 0) {
1012 FileHandleGetPosition (Handle
, &OriginalFilePosition
);
1013 if (OriginalFilePosition
== 0) {
1014 CharSize
= sizeof (CHAR16
);
1015 Status
= FileHandleRead (Handle
, &CharSize
, &CharBuffer
);
1016 ASSERT_EFI_ERROR (Status
);
1017 if (CharBuffer
== gUnicodeFileTag
) {
1021 FileHandleSetPosition (Handle
, OriginalFilePosition
);
1026 for (CountSoFar
= 0; ; CountSoFar
++) {
1029 CharSize
= sizeof (CHAR8
);
1031 CharSize
= sizeof (CHAR16
);
1034 Status
= FileHandleRead (Handle
, &CharSize
, &CharBuffer
);
1035 if ( EFI_ERROR (Status
)
1037 || ((CharBuffer
== L
'\n') && !(*Ascii
))
1038 || ((CharBuffer
== '\n') && *Ascii
)
1043 ((CharBuffer
== L
'\r') && !(*Ascii
)) ||
1044 ((CharBuffer
== '\r') && *Ascii
)
1052 // if we have space save it...
1054 if ((CountSoFar
+1-CrCount
)*sizeof (CHAR16
) < *Size
) {
1055 ASSERT (Buffer
!= NULL
);
1056 ((CHAR16
*)Buffer
)[CountSoFar
-CrCount
] = CharBuffer
;
1057 ((CHAR16
*)Buffer
)[CountSoFar
+1-CrCount
] = CHAR_NULL
;
1062 // if we ran out of space tell when...
1064 if ((CountSoFar
+1-CrCount
)*sizeof (CHAR16
) > *Size
) {
1066 *Size
= (CountSoFar
+1-CrCount
)*sizeof (CHAR16
);
1068 if ((Buffer
!= NULL
) && (OldSize
!= 0)) {
1069 ZeroMem (Buffer
, OldSize
);
1072 FileHandleSetPosition (Handle
, OriginalFilePosition
);
1073 return (EFI_BUFFER_TOO_SMALL
);
1075 DEBUG ((DEBUG_WARN
, "The line was truncated in FileHandleReadLine"));
1076 return (EFI_SUCCESS
);
1084 Function to write a line of text to a file.
1086 If the file is a Unicode file (with UNICODE file tag) then write the unicode
1088 If the file is an ASCII file then write the ASCII text.
1089 If the size of file is zero (without file tag at the beginning) then write
1090 ASCII text as default.
1092 @param[in] Handle FileHandle to write to.
1093 @param[in] Buffer Buffer to write, if NULL the function will
1094 take no action and return EFI_SUCCESS.
1096 @retval EFI_SUCCESS The data was written.
1098 @retval EFI_INVALID_PARAMETER Handle is NULL.
1099 @retval EFI_OUT_OF_RESOURCES Unable to allocate temporary space for ASCII
1100 string due to out of resources.
1106 FileHandleWriteLine (
1107 IN EFI_FILE_HANDLE Handle
,
1117 UINT64 OriginalFilePosition
;
1121 if (Buffer
== NULL
) {
1122 return (EFI_SUCCESS
);
1125 if (Handle
== NULL
) {
1126 return (EFI_INVALID_PARAMETER
);
1132 Status
= FileHandleGetPosition (Handle
, &OriginalFilePosition
);
1133 if (EFI_ERROR (Status
)) {
1137 Status
= FileHandleSetPosition (Handle
, 0);
1138 if (EFI_ERROR (Status
)) {
1142 Status
= FileHandleGetSize (Handle
, &FileSize
);
1143 if (EFI_ERROR (Status
)) {
1147 if (FileSize
== 0) {
1150 CharSize
= sizeof (CHAR16
);
1151 Status
= FileHandleRead (Handle
, &CharSize
, &CharBuffer
);
1152 ASSERT_EFI_ERROR (Status
);
1153 if (CharBuffer
== gUnicodeFileTag
) {
1160 Status
= FileHandleSetPosition (Handle
, OriginalFilePosition
);
1161 if (EFI_ERROR (Status
)) {
1166 Size
= (StrSize (Buffer
) / sizeof (CHAR16
)) * sizeof (CHAR8
);
1167 AsciiBuffer
= (CHAR8
*)AllocateZeroPool (Size
);
1168 if (AsciiBuffer
== NULL
) {
1169 return EFI_OUT_OF_RESOURCES
;
1172 UnicodeStrToAsciiStrS (Buffer
, AsciiBuffer
, Size
);
1173 for (Index
= 0; Index
< Size
; Index
++) {
1174 if ((AsciiBuffer
[Index
] & BIT7
) != 0) {
1175 FreePool (AsciiBuffer
);
1176 return EFI_INVALID_PARAMETER
;
1180 Size
= AsciiStrSize (AsciiBuffer
) - sizeof (CHAR8
);
1181 Status
= FileHandleWrite (Handle
, &Size
, AsciiBuffer
);
1182 if (EFI_ERROR (Status
)) {
1183 FreePool (AsciiBuffer
);
1187 Size
= AsciiStrSize ("\r\n") - sizeof (CHAR8
);
1188 Status
= FileHandleWrite (Handle
, &Size
, "\r\n");
1190 if (OriginalFilePosition
== 0) {
1191 Status
= FileHandleSetPosition (Handle
, sizeof (CHAR16
));
1192 if (EFI_ERROR (Status
)) {
1197 Size
= StrSize (Buffer
) - sizeof (CHAR16
);
1198 Status
= FileHandleWrite (Handle
, &Size
, Buffer
);
1199 if (EFI_ERROR (Status
)) {
1203 Size
= StrSize (L
"\r\n") - sizeof (CHAR16
);
1204 Status
= FileHandleWrite (Handle
, &Size
, L
"\r\n");
1207 if (AsciiBuffer
!= NULL
) {
1208 FreePool (AsciiBuffer
);
1215 function to take a formatted argument and print it to a file.
1217 @param[in] Handle the file handle for the file to write to
1218 @param[in] Format the format argument (see printlib for format specifier)
1219 @param[in] ... the variable arguments for the format
1221 @retval EFI_SUCCESS the operation was successful
1222 @return other a return value from FileHandleWriteLine
1224 @sa FileHandleWriteLine
1228 FileHandlePrintLine (
1229 IN EFI_FILE_HANDLE Handle
,
1230 IN CONST CHAR16
*Format
,
1239 // Get a buffer to print into
1241 Buffer
= AllocateZeroPool (PcdGet16 (PcdUefiFileHandleLibPrintBufferSize
));
1242 if (Buffer
== NULL
) {
1243 return (EFI_OUT_OF_RESOURCES
);
1247 // Print into our buffer
1249 VA_START (Marker
, Format
);
1250 UnicodeVSPrint (Buffer
, PcdGet16 (PcdUefiFileHandleLibPrintBufferSize
), Format
, Marker
);
1254 // Print buffer into file
1256 Status
= FileHandleWriteLine (Handle
, Buffer
);
1259 // Cleanup and return
1266 Function to determine if a FILE_HANDLE is at the end of the file.
1268 This will NOT work on directories.
1270 If Handle is NULL, then return False.
1272 @param[in] Handle the file handle
1274 @retval TRUE the position is at the end of the file
1275 @retval FALSE the position is not at the end of the file
1280 IN EFI_FILE_HANDLE Handle
1283 EFI_FILE_INFO
*Info
;
1287 if (Handle
== NULL
) {
1291 FileHandleGetPosition (Handle
, &Pos
);
1292 Info
= FileHandleGetInfo (Handle
);
1298 FileHandleSetPosition (Handle
, Pos
);
1300 if (Pos
== Info
->FileSize
) {