FILE_OBJECT structure (wdm.h)

The FILE_OBJECT structure is used by the system to represent a file object. To user-mode protected subsystems, a file object represents an open instance of a file, device, directory, or volume. To device and intermediate drivers, a file object usually represents a device object. To drivers in the file system stack, a file object usually represents a directory or file.

A file object is partially opaque. Certain types of drivers, such as file system drivers and network transport drivers, use some of the fields of file objects.

Syntax

typedef struct _FILE_OBJECT {
  CSHORT                            Type;
  CSHORT                            Size;
  PDEVICE_OBJECT                    DeviceObject;
  PVPB                              Vpb;
  PVOID                             FsContext;
  PVOID                             FsContext2;
  PSECTION_OBJECT_POINTERS          SectionObjectPointer;
  PVOID                             PrivateCacheMap;
  NTSTATUS                          FinalStatus;
  struct _FILE_OBJECT               *RelatedFileObject;
  BOOLEAN                           LockOperation;
  BOOLEAN                           DeletePending;
  BOOLEAN                           ReadAccess;
  BOOLEAN                           WriteAccess;
  BOOLEAN                           DeleteAccess;
  BOOLEAN                           SharedRead;
  BOOLEAN                           SharedWrite;
  BOOLEAN                           SharedDelete;
  ULONG                             Flags;
  UNICODE_STRING                    FileName;
  LARGE_INTEGER                     CurrentByteOffset;
  __volatile ULONG                  Waiters;
  __volatile ULONG                  Busy;
  PVOID                             LastLock;
  KEVENT                            Lock;
  KEVENT                            Event;
  __volatile PIO_COMPLETION_CONTEXT CompletionContext;
  KSPIN_LOCK                        IrpListLock;
  LIST_ENTRY                        IrpList;
  __volatile PVOID                  FileObjectExtension;
} FILE_OBJECT, *PFILE_OBJECT;

Members

Type

A read-only member used by the system to indicate that the object is a file object. If the object is a file object, the value of this member is 5.

Size

A read-only member that specifies the size, in bytes, of the file object. This size does not include the file object extension, if one is present.

DeviceObject

A pointer to the device object on which the file is opened.

Vpb

A pointer to the volume parameter block associated with the file object.

Note that if the Vpb member is non-NULL, the file resides on a mounted volume.

FsContext

A pointer to whatever optional state a driver maintains about the file object; otherwise, NULL. For file system drivers, this member must point to a FSRTL_ADVANCED_FCB_HEADER header structure that is contained within a file-system-specific structure; otherwise system instability can result. Usually, this header structure is embedded in a file control block (FCB). However, on some file systems that support multiple data streams, such as NTFS, this header structure is a stream control block (SCB).

In a WDM device stack, only the functional device object (FDO) can use the two context pointers. File system drivers share this member across multiple opens to the same data stream.

FsContext2

A pointer to whatever additional state a driver maintains about the file object; otherwise, NULL.

This member is opaque for drivers in the file system stack because the underlying file system utilizes this member.

SectionObjectPointer

A pointer to the file object's read-only section object. This member is set only by file systems and used for Cache Manager interaction.

PrivateCacheMap

An opaque member, set only by file systems, that points to handle-specific information and that is used for Cache Manager interaction.

FinalStatus

A read-only member that is used, in certain synchronous cases, to indicate the final status of the file object's I/O request.

RelatedFileObject

A pointer to a FILE_OBJECT structure used to indicate that the current file object has been opened relative to an already open file object. The file object pointed to by this member is usually a directory (meaning the current file has been opened relative to this directory). However, a file can be reopened relative to itself, and alternate data streams for a file can be opened relative to an already open primary data stream for that same file. The RelatedFileObject member is only valid during the processing of the IRP_MJ_CREATE requests.

LockOperation

A read-only member. If FALSE, a lock operation (NtLockFile) has never been performed on the file object. If TRUE, at least one lock operation has been performed on the file object. Once set to TRUE, this member always remains TRUE (for example, releasing file locks on the file object does not reset this member to FALSE).

DeletePending

A read-only member. If TRUE, a delete operation for the file associated with the file object exists. If FALSE, there currently is no pending delete operation for the file object.

ReadAccess

A read-only member. If TRUE, the file associated with the file object has been opened for read access. If FALSE, the file has been opened without read access. This information is used when checking and/or setting the share access of the file.

WriteAccess

A read-only member. If TRUE, the file associated with the file object has been opened for write access. If FALSE, the file has been opened without write access. This information is used when checking and/or setting the share access of the file.

DeleteAccess

A read-only member. If TRUE, the file associated with the file object has been opened for delete access. If FALSE, the file has been opened without delete access. This information is used when checking and/or setting the share access of the file.

SharedRead

A read-only member. If TRUE, the file associated with the file object has been opened for read sharing access. If FALSE, the file has been opened without read sharing access. This information is used when checking and/or setting the share access of the file.

SharedWrite

A read-only member. If TRUE, the file associated with the file object has been opened for write sharing access. If FALSE, the file has been opened without write sharing access. This information is used when checking and/or setting the share access of the file.

SharedDelete

A read-only member. If TRUE, the file associated with the file object has been opened for delete sharing access. If FALSE, the file has been opened without delete sharing access. This information is used when checking and/or setting the share access of the file.

Flags

A read-only member used by the system to hold one or more (a bitwise inclusive OR combination) of the following private flag values.

FileName

A UNICODE_STRING structure whose Buffer member points to a read-only Unicode string that holds the name of the file opened on the volume. If the volume is being opened, the Length member of the UNICODE_STRING structure will be zero. Note that the file name in this string is valid only during the initial processing of an IRP_MJ_CREATE request. This file name should not be considered valid after the file system starts to process the IRP_MJ_CREATE request. The storage for the string pointed to by the Buffer member of the UNICODE_STRING structure is allocated in paged system memory. For more information about obtaining a file name, see FltGetFileNameInformation.

CurrentByteOffset

A read-only member that specifies the file offset, in bytes, associated with the file object.

Waiters

A read-only member used by the system to count the number of outstanding waiters on a file object opened for synchronous access.

Busy

A read-only member used by the system to indicate whether a file object opened for synchronous access is currently busy.

LastLock

An opaque pointer to the last lock applied to the file object.

Lock

An opaque member used by the system to hold a file object event lock. The event lock is used to control synchronous access to the file object. Applicable only to file objects that are opened for synchronous access.

Event

An opaque member used by the system to hold an event object for the file object. The event object is used to signal the completion of an I/O request on the file object if no user event was supplied or a synchronous API was called.

CompletionContext

An opaque pointer to completion port information (port pointer and key) associated with the file object, if any.

IrpListLock

An opaque pointer to a KSPIN_LOCK structure that serves as the spin lock used to synchronize access to the file object's IRP list.

IrpList

An opaque pointer to the head of the IRP list associated with the file object.

FileObjectExtension

An opaque pointer to the file object's file object extension (FOBX) structure. The FOBX structure contains various opaque contexts used internally as well as the per-file object contexts available through FsRtlXxx routines.

Remarks

Drivers can use the FsContext and FsContext2 members to maintain driver-determined state about an open file object. A driver cannot use these members unless the file object is accessible in the driver's I/O stack location of an IRP.

All remaining members in a file object are either opaque or read-only:

• Opaque members within a file object should be considered inaccessible. Drivers with dependencies on object field locations or access to opaque members might not remain portable and interoperable with other drivers over time.

• Drivers can use read-only members to acquire relevant information but must not modify read-only members and, if a pointer, the object that the member points to.

During the processing of an IRP_MJ_CREATE request, a file system driver calls the IoSetShareAccess routine (if the client is the first to open the file) or the IoCheckShareAccess routine (for subsequent clients that want to share the file). IoSetShareAccess and IoCheckShareAccess update the ReadAccess, WriteAccess, and DeleteAccess members to indicate the access rights that are granted to the client if the client has exclusive access to the file. Additionally, IoCheckShareAccess updates the SharedRead, SharedWrite, and SharedDelete members to indicate the access rights that are simultaneously granted to two or more clients that share the file. If the driver for a device other than a file system has to monitor the access rights of clients, this driver typically stores access rights information in context buffers that are pointed to by the FsContext and FsContext2 members.

The type of object (for example, a file, directory, or volume) that a given file object represents cannot be determined by only examining the contents of the file object structure. For information about how to determine the type of object that a file object represents, see ZwQueryInformationFile.

The Common Log File System (CLFS) uses the LOG_FILE_OBJECT structure to represent logs. The ClfsCreateLogFile function returns a pointer to a LOG_FILE_OBJECT structure, which clients then pass to other CLFS functions.

CLFS clients do not directly access the members of a LOG_FILE_OBJECT structure.

typedef FILE_OBJECT LOG_FILE_OBJECT, *PLOG_FILE_OBJECT, **PPLOG_FILE_OBJECT;

Requirements

See also

DEVICE_OBJECT

FOBX

FSRTL_ADVANCED_FCB_HEADER

IRP_MJ_CREATE

IoCheckShareAccess

IoGetDeviceObjectPointer

IoSetShareAccess

ObDereferenceObject

ZwQueryInformationFile