FsRtlChangeBackingFileObject function

The FsRtlChangeBackingFileObject routine replaces the current file object with a new file object.


NTKERNELAPI NTSTATUS FsRtlChangeBackingFileObject(
  PFILE_OBJECT              CurrentFileObject,
  PFILE_OBJECT              NewFileObject,
  ULONG                     Flags



The current file object. If this object does not belong to the stream, the operation fails.


The new file object.


An FSRTL_CHANGE_BACKING_TYPE enumeration value that indicates which internal memory area the new file object will designate.


Reserved for future use.

Return Value

The FsRtlChangeBackingFileObject routine returns STATUS_SUCCESS if the operation succeeds. Otherwise, FsRtlChangeBackingFileObject returns the appropriate error code.The following table contains error codes that FsRtlChangeBackingFileObject might return.

Return code Description
The change operation failed because the file object that NewFileObject specifies does not represent the same stream as CurrentFileObject.
The change operation failed because the caller specified an invalid backing type in ChangeBackingType.
The change operation failed because the caller specified an invalid value in Flags.
The change operation failed because the caller obtained the file object in a way that does not allow subsequent swapping of the file object. For example, if the caller obtained the file object with a call to CcGetFileObjectFromSectionPtrs, it is not safe to swap the file object.


The FsRtlChangeBackingFileObject routine changes the file object for one of the following:

  • One of the memory manager's image control areas for the stream

  • The memory manager's data control area for the stream

  • The cache manager's shared cache map for the stream

The FsRtlChangeBackingFileObject routine is not synchronous. It processes the request for a change of file object and returns immediately. The cache manager and the memory manager synchronize the change of the file object and will not free the old file object until all incomplete operations that are associated with the old file object have finished. A return status of STATUS_SUCCESS from FsRtlChangeBackingFileObject does not mean that the operating system has already changed the file object.

However, after FsRtlChangeBackingFileObject runs successfully, the operating system associates all future operations with the new file object.

To change the file object for more than one backing type, the caller must call FsRtlChangeBackingFileObject multiple times, one time for each backing type to change.


Windows version The FsRtlChangeBackingFileObject routine is available starting with Windows Vista.
Target Platform Universal
Header ntifs.h (include Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe

See Also