EFI FILE PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Provides file based access to supported file systems.

Contents

Protocol Interface Structure

typedef struct _EFI_FILE_PROTOCOL {
  UINT64                Revision;
  EFI_FILE_OPEN         Open;
  EFI_FILE_CLOSE        Close;
  EFI_FILE_DELETE       Delete;
  EFI_FILE_READ         Read;
  EFI_FILE_WRITE        Write;
  EFI_FILE_GET_POSITION GetPosition;
  EFI_FILE_SET_POSITION SetPosition;
  EFI_FILE_GET_INFO     GetInfo;
  EFI_FILE_SET_INFO     SetInfo;
  EFI_FILE_FLUSH        Flush;
} EFI_FILE_PROTOCOL;
#define EFI_FILE_PROTOCOL_REVISION 0x00010000

Members

Member Description
Revision The version of the EFI_FILE_PROTOCOL interface. The version specified by this specification is 0x00010000. Future versions are required to be backward compatible to version 1.0.
Open Opens or creates a new file.
Close Closes the current file handle.
Delete Deletes a file.
Read Reads bytes from a file.
Write Writes bytes to a file.
GetPosition Returns the current file position.
SetPosition Sets the current file position.
GetInfo Gets the requested file or volume information.
SetInfo Sets the requested file information.
Flush Flushes all modified data associated with the file to the device.

Description

The EFI_FILE_PROTOCOL provides file IO access to supported file systems.

An EFI_FILE_PROTOCOL provides access to a file’s or directory’s contents, and is also a reference to a location in the directory tree of the file system in which the file resides. With any given file handle, other files may be opened relative to this file’s location, yielding new file handles.

On requesting the file system protocol on a device, the caller gets the EFI_FILE_PROTOCOL to the volume. This interface is used to open the root directory of the file system when needed. The caller must Close() the file handle to the root directory, and any other opened file handles before exiting. While there are open files on the device, usage of underlying device protocol(s) that the file system is abstracting must be avoided. For example, when a file system that is layered on a EFI_DISK_IO_PROTOCOL / EFI_BLOCK_IO_PROTOCOL, direct block access to the device for the blocks that comprise the file system must be avoided while there are open file handles to the same device.

A file system driver may cache data relating to an open file. A Flush() function is provided that flushes all dirty data in the file system, relative to the requested file, to the physical medium. If the underlying device may cache data, the file system must inform the device to flush as well.

Open()

Opens a new file relative to the source file’s location.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_OPEN) (
  IN  EFI_FILE_PROTOCOL *This,
  OUT EFI_FILE_PROTOCOL **NewHandle,
  IN  CHAR16            *FileName,
  IN  UINT64            OpenMode,
  IN  UINT64            Attributes
  );

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to the source location. This would typically be an open handle to a directory.
NewHandle A pointer to the location to return the opened handle for the new file.
FileName The Null-terminated string of the name of the file to be opened. The file name may contain the following path modifiers: “\”, “.”, and “..”.
OpenMode The mode to open the file. The only valid combinations that the file may be opened with are: Read, Read/Write, or Create/Read/Write. See “Related Definitions” below.
Attributes Only valid for EFI_FILE_MODE_CREATE, in which case these are the attribute bits for the newly created file. See “Related Definitions” below.

Related Definitions

#define EFI_FILE_MODE_READ 0x0000000000000001
#define EFI_FILE_MODE_WRITE 0x0000000000000002
#define EFI_FILE_MODE_CREATE 0x8000000000000000
#define EFI_FILE_READ_ONLY 0x0000000000000001
#define EFI_FILE_HIDDEN 0x0000000000000002
#define EFI_FILE_SYSTEM 0x0000000000000004
#define EFI_FILE_RESERVED 0x0000000000000008
#define EFI_FILE_DIRECTORY 0x0000000000000010
#define EFI_FILE_ARCHIVE 0x0000000000000020
#define EFI_FILE_VALID_ATTR 0x0000000000000037

Description
The Open()function opens the file or directory referred to by FileName relative to the location of This and returns a NewHandle. The FileName may include the following path modifiers:

  • “\” If the filename starts with a “\” the relative location is the root directory that This residues on; otherwise “\” separates name components. Each name component is opened in turn, and the handle to the last file opened is returned.
  • “.” Opens the current location.
  • “..” Opens the parent directory for the current location. If the location is the root directory the request will return an error, as there is no parent directory for the root directory.

If EFI_FILE_MODE_CREATE is set, then the file is created in the directory. If the final location of FileName does not refer to a directory, then the operation fails. If the file does not exist in the directory, then a new file is created. If the file already exists in the directory, then the existing file is opened.

If the medium of the device changes, all accesses (including the File handle) will result in EFI_MEDIA_CHANGED. To access the new medium, the volume must be reopened.

Status Codes Returned

Status Code Description
EFI_SUCCESS The file was opened.
EFI_NOT_FOUND The specified file could not be found on the device.
EFI_NO_MEDIA The device has no medium.
EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no longer supported.
EFI_DEVICE_ERROR The device reported an error.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_WRITE_PROTECTED An attempt was made to create a file, or open a file for write when the media is write-protected.
EFI_ACCESS_DENIED The service denied access to the file.
EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.
EFI_VOLUME_FULL The volume is full.

Close()

Closes a specified file handle.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_CLOSE) (IN EFI_FILE_PROTOCOL *This);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to close.

Description
The Close() function closes a specified file handle. All “dirty” cached file data is flushed to the device, and the file is closed. In all cases the handle is closed.

Status Codes Returned

Status Code Description
EFI_SUCCESS The file was closed.

Delete()

Closes and deletes a file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_DELETE) (IN EFI_FILE_PROTOCOL *This);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the handle to the file to delete.

Description
The Delete() function closes and deletes a file. In all cases the file handle is closed. If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the handle is still closed.

Status Codes Returned

Status Code Description
EFI_SUCCESS The file was closed and deleted, and the handle was closed.
EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not deleted.

Read()

Reads data from a file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_READ) (
  IN EFI_FILE_PROTOCOL *This,
  IN OUT UINTN *BufferSize,
  OUT VOID *Buffer);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to read data from.
BufferSize On input, the size of the Buffer. On output, the amount of data returned in Buffer. In both cases, the size is measured in bytes.
Buffer The buffer into which the data is read.

Description
The Read() function reads data from a file.

If This is not a directory, the function reads the requested number of bytes from the file at the file’s current position and returns them in Buffer. If the read goes beyond the end of the file, the read length is truncated to the end of the file. The file’s current position is increased by the number of bytes returned.

If This is a directory, the function reads the directory entry at the file’s current position and returns the entry in Buffer.

If the Buffer is not large enough to hold the current directory entry, then EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. BufferSize is set to be the size of the buffer needed to read the entry. On success, the current position is updated to the next directory entry. If there are no more directory entries, the read returns a zero-length buffer. EFI_FILE_INFO is the structure returned as the directory entry.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read.
EFI_NO_MEDIA The device has no medium.
EFI_DEVICE_ERROR The device reported an error.
EFI_DEVICE_ERROR An attempt was made to read from a deleted file.
EFI_DEVICE_ERROR On entry, the current file position is beyond the end of the file.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry. BufferSize has been updated with the size needed to complete the request.

Write()

Writes data to a file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_WRITE) (
  IN EFI_FILE_PROTOCOL *This,
  IN OUT UINTN *BufferSize,
  IN VOID *Buffer);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to write data to.
BufferSize On input, the size of the Buffer. On output, the amount of data actually written. In both cases, the size is measured in bytes.
Buffer The buffer of data to write.

Description
The Write() function writes the specified number of bytes to the file at the current file position. The current file position is advanced the actual number of bytes written, which is returned in BufferSize. Partial writes only occur when there has been a data error during the write attempt (such as “file space full”). The file is automatically grown to hold the data if required.

Direct writes to opened directories are not supported.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was written.
EFI_UNSUPPORTED Writes to open directory files are not supported.
EFI_NO_MEDIA The device has no medium.
EFI_DEVICE_ERROR The device reported an error.
EFI_DEVICE_ERROR An attempt was made to write to a deleted file.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_WRITE_PROTECTED The file or medium is write-protected.
EFI_ACCESS_DENIED The file was opened read only.
EFI_VOLUME_FULL The volume is full.

SetPosition()

Sets a file’s current position.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_SET_POSITION) (
  IN EFI_FILE_PROTOCOL *This,
  IN UINT64 Position);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the he file handle to set the requested position on.
Position The byte position from the start of the file to set.

Description
The SetPosition() function sets the current file position for the handle to the position supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only absolute positioning is supported, and seeking past the end of the file is allowed (a subsequent write would grow the file). Seeking to position 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.

If This is a directory, the only position that may be set is zero. This has the effect of starting the read process of the directory entries over.

Status Codes Returned

Status Code Description
EFI_SUCCESS The position was set.
EFI_UNSUPPORTED The seek request for nonzero is not valid on open directories.
EFI_DEVICE_ERROR An attempt was made to set the position of a deleted file.

GetPosition()

Returns a file’s current position.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_GET_POSITION) (
  IN EFI_FILE_PROTOCOL *This,
  OUT UINT64 *Position);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to get the current position on.
Position The address to return the file’s current position value.

Description
The GetPosition() function returns the current file position for the file handle. For directories, the current file position has no meaning outside of the file system driver and as such the operation is not supported. An error is returned if This is a directory.

Status Codes Returned

Status Code Description
EFI_SUCCESS The position was returned.
EFI_UNSUPPORTED The request is not valid on open directories.
EFI_DEVICE_ERROR An attempt was made to get the position from a deleted file.

GetInfo()

Returns information about a file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_GET_INFO) (
  IN EFI_FILE_PROTOCOL *This,
  IN EFI_GUID *InformationType,
  IN OUT UINTN *BufferSize,
  OUT VOID *Buffer);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle the requested information is for.
InformationType The type identifier for the information being requested. See the EFI_FILE_INFO and EFI_FILE_SYSTEM_INFO descriptions for the related GUID definitions.
BufferSize On input, the size of Buffer. On output, the amount of data returned in Buffer. In both cases, the size is measured in bytes.
Buffer A pointer to the data buffer to return. The buffer’s type is indicated by InformationType.

Description
The GetInfo() function returns information of type InformationType for the requested file. If the file does not support the requested information type, then EFI_UNSUPPORTED is returned. If the buffer is not large enough to fit the requested structure, EFI_BUFFER_TOO_SMALL is returned and the BufferSize is set to the size of buffer that is required to make the request.

The information types defined by this specification are required information types that all file systems must support.

Status Codes Returned

Status Code Description
EFI_SUCCESS The information was set.
EFI_UNSUPPORTED The InformationType is not known.
EFI_NO_MEDIA The device has no medium.
EFI_DEVICE_ERROR The device reported an error.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry. BufferSize has been updated with the size needed to complete

the request.

SetInfo()

Sets information about a file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_SET_INFO) (
  IN EFI_FILE_PROTOCOL *This,
  IN EFI_GUID *InformationType,
  IN UINTN BufferSize,
  IN VOID *Buffer);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle the information is for.
InformationType The type identifier for the information being set. See the EFI_FILE_INFO and EFI_FILE_SYSTEM_INFO descriptions in this section for the related GUID definitions.
BufferSize The size, in bytes, of Buffer.
Buffer A pointer to the data buffer to write. The buffer’s type is indicated by InformationType.

Description
The SetInfo() function sets information of type InformationType on the requested file. Because a read-only file can be opened only in read-only mode, an InformationType of EFI_FILE_INFO_ID can be used with a read-only file because this method is the only one that can be used to convert a read-only file to a read-write file. In this circumstance, only the Attribute field of the EFI_FILE_INFO structure may be modified. One or more calls to SetInfo() to change the Attribute field are permitted before it is closed. The file attributes will be valid the next time the file is opened with Open().

An InformationType of EFI_FILE_SYSTEM_INFO_ID or EFI_FILE_SYSTEM_VOLUME_LABEL_ID may not be used on read-only media.

Status Codes Returned

Status Code Description
EFI_SUCCESS The information was set.
EFI_UNSUPPORTED The InformationType is not known.
EFI_NO_MEDIA The device has no medium.
EFI_DEVICE_ERROR The device reported an error.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_WRITE_PROTECTED InformationType is EFI_FILE_INFO_ID and the media is read-only.
EFI_WRITE_PROTECTED InformationType is EFI_FILE_PROTOCOL_SYSTEM_INFO_ID and the media is read only.
EFI_WRITE_PROTECTED InformationType is EFI_FILE_SYSTEM_VOLUME_LABEL_ID and the media is read-only.
EFI_ACCESS_DENIED An attempt is made to change the name of a file to a file that is already present.
EFI_ACCESS_DENIED An attempt is being made to change the EFI_FILE_DIRECTORY Attribute.
EFI_ACCESS_DENIED An attempt is being made to change the size of a directory.
EFI_ACCESS_DENIED InformationType is EFI_FILE_INFO_ID and the file was opened read-only and an attempt is being made to modify a field other than Attribute.
EFI_VOLUME_FULL The volume is full.
EFI_BAD_BUFFER_SIZE BufferSize is smaller than the size of the type indicated by InformationType.

Flush()

Flushes all modified data associated with a file to a device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FILE_FLUSH) (IN EFI_FILE_PROTOCOL *This);

Parameters

Parameter Description
This A pointer to the EFI_FILE_PROTOCOL instance that is the file handle to flush.

Description
The Flush() function flushes all modified data associated with a file to a device.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was flushed.
EFI_NO_MEDIA The device has no medium.
EFI_DEVICE_ERROR The device reported an error.
EFI_VOLUME_CORRUPTED The file system structures are corrupted.
EFI_WRITE_PROTECTED The file or medium is write-protected.
EFI_ACCESS_DENIED The file was opened read-only.
EFI_VOLUME_FULL The volume is full.

Copyright (C) 2009 Phoenix Technologies Ltd. All Rights Reserved. Portions (C) 2006-2008 UEFI Forum, Inc. Used by permission.

Personal tools