MARK_HANDLE_INFO - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
// ntifs.h

typedef struct _MARK_HANDLE_INFO {
  union {
    ULONG UsnSourceInfo;
    ULONG CopyNumber;
  } DUMMYUNIONNAME;
  ULONG  UsnSourceInfo;
  HANDLE VolumeHandle;
  ULONG  HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;
View the official Windows Driver Kit DDI reference
// winioctl.h

typedef struct _MARK_HANDLE_INFO {
  union {
    DWORD UsnSourceInfo;
    DWORD CopyNumber;
  } DUMMYUNIONNAME;
  DWORD  UsnSourceInfo;
  HANDLE VolumeHandle;
  DWORD  HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;
View the official Win32 API reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (ns-ntifs-mark_handle_info)

Description

A MARK_HANDLE_INFO structure is passed as the input buffer during a FSCTL_MARK_HANDLE control code request.

Members

DUMMYUNIONNAME

DUMMYUNIONNAME.UsnSourceInfo

See UsnSourceInfo below.

DUMMYUNIONNAME.CopyNumber

Identifies which copy of a file to read, when reading from a file that resides on redundant media.

UsnSourceInfo

The optional update sequence number (USN) source info flags. To set any of these values, a volume DASD handle must be specified in the VolumeHandle field. Can be a combination of the following values:

Flag Meaning
USN_SOURCE_DATA_MANAGEMENT Service is not modifying the external view of any part of the file. Typical case is HSM moving data to and from external storage.
USN_SOURCE_AUXILIARY_DATA Service is not modifying the external view of the file with regard to the application that created this file. Can be used to add private data streams to a file.
USN_SOURCE_REPLICATION_MANAGEMENT Service is modifying a file to match the contents of the same file which exists in another member of the replica set.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT Replication is being performed on client systems either from the cloud or servers. A volume handle is not required to set this value

VolumeHandle

Volume handle for this operation.

HandleInfo

Contains flags to identify the request. This field can be one of the following values:

Flag Meaning
MARK_HANDLE_PROTECT_CLUSTERS Do not allow any defragmenting (FSCTL_MOVE_FILE) until the handle is closed.
MARK_HANDLE_TXF_SYSTEM_LOG This stream is being used as the Txf log for a resource manager on the volume. Must be called in the kernel using IRP_MN_KERNEL_CALL. Available starting in Windows Vista.
MARK_HANDLE_NOT_TXF_SYSTEM_LOG This component is no longer using this object as a TxF log file. Available starting in Windows Vista.
MARK_HANDLE_REALTIME Only supported by the UDFS file system. Marks the device to do realtime streaming of video. Available starting in Windows 7.
MARK_HANDLE_NOT_REALTIME Only supported by the UDFS file system. Marks the device to no longer do realtime streaming of video. Available starting in Windows 7.
MARK_HANDLE_CLOUD_SYNC Deprecated; do not use this flag.
MARK_HANDLE_READ_COPY The data must be read from the specified copy of data. Only supported for Storage Spaces redundant volumes. Available starting in Windows 8.
MARK_HANDLE_NOT_READ_COPY The data is no longer to be read from a specific copy. Only supported for Storage Spaces redundant volumes. Available starting in Windows 8.
MARK_HANDLE_FILTER_METADATA Reserved for internal Microsoft use only.
MARK_HANDLE_RETURN_PURGE_FAILURE When intermixing memory mapped/cached IO with non-cached IO, and a non-cached IO is issued, the system attempts to purge memory mappings for the range of the non-cached IO. If these purges fail the system normally does not return the failure to the caller which can lead to corrupted state. This flag tells the system to return purge failures for the given handle so the application can better handle this situation. Available starting in Windows 8.1.
MARK_HANDLE_DISABLE_FILE_METADATA_OPTIMIZATION Disables the File Record Segment (FRS) compaction feature on the given file. Available starting in Windows 10 version 1507.
MARK_HANDLE_ENABLE_USN_SOURCE_ON_PAGING_IO Tells NTFS to set the given UsnSourceInfo value on Paging writes in the USN Journal. Traditionally this was not done on paging writes since you did not know what thread made the given changes. This is an override. This only works if the FileObject that the Memory Manager is holding on to has this state associated with it. Available starting in Windows 10 version 1507.
MARK_HANDLE_SKIP_COHERENCY_SYNC_DISALLOW_WRITES Tells the system that writes are not allowed on this file. If someone tries to open the file for write access, the operation is failed with STATUS_ACCESS_DENIED. If a write is seen the operation is failed with STATUS_MARKED_TO_DISALLOW_WRITES. Available starting in Windows 10 version 1507.
MARK_HANDLE_ENABLE_CPU_CACHE Reserved for internal Microsoft use only.
MARK_HANDLE_SUPPRESS_VOLUME_OPEN_FLUSH Normally, on the first read/write operation on a volume handle (DASD open), the file system flushes the volume. This can have performance consequences in certain scenarios. If this flag is set on a volume handle it will suppress that flush on first IO. Available starting in Windows 11.

Remarks

MARK_HANDLE_INFO contains the information used to mark a specified file or directory, and its update sequence number (USN) change journal record with data about changes.

See also

FSCTL_MARK_HANDLE

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Win32 API reference (ns-winioctl-mark_handle_info)

MARK_HANDLE_INFO structure

Description

Contains information that is used to mark a specified file or directory, and its update sequence number (USN) change journal record with data about changes. It is used by the FSCTL_MARK_HANDLE control code.

Members

DUMMYUNIONNAME

UsnSourceInfo

The type of changes being made.

The operation does not modify the file or directory externally from the point of view of the application that created it.

When a thread writes a new USN record, the source information flags in the prior record continues to be present only if the thread also sets those flags. Therefore, the source information structure allows applications to filter out USN records that are set only by a known source, such as an antivirus filter.

The following values are defined.

Value Meaning
USN_SOURCE_DATA_MANAGEMENT

0x00000001		 The operation provides information about a change to the file or directory made by the operating system.

A typical use is when Remote Storage moves data from external to local storage. Remote Storage is the hierarchical storage management software. Such a move usually at a minimum adds the USN_REASON_DATA_OVERWRITE flag to a USN record. However, the data has not changed from the user point of view. By noting USN_SOURCE_DATA_MANAGEMENT in the SourceInfo member of the USN_RECORD structure that holds the record, you can determine that although a write operation is performed on the item, data has not changed.
USN_SOURCE_AUXILIARY_DATA

0x00000002		 The operation adds a private data stream to a file or directory.

An example might be a virus detector adding checksum information. As the virus detector modifies the item, the system generates USN records. USN_SOURCE_AUXILIARY_DATA indicates that the modifications did not change the application data.
USN_SOURCE_REPLICATION_MANAGEMENT

0x00000004		 The operation creates or updates the contents of a replicated file.

For example, the file replication service sets this flag when it creates or updates a file in a replicated directory.

| USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT

0x00000008 | Replication is being performed on client systems either from the cloud or servers. |

CopyNumber

The zero-based copy number to use for subsequent reads. This is for use on Storage Spaces and Streams on NTFS and ReFS and non-integrity streams on ReFS (streams with integrity on ReFS handle this automatically.)

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This member is not supported before Windows 8 and Windows Server 2012.

VolumeHandle

The volume handle to the volume where the file or directory resides. For more information on obtaining a volume handle, see the Remarks section.

This handle is required to check the privileges for this operation.

The caller must have the SE_MANAGE_VOLUME_NAME privilege. For more information, see Privileges.

HandleInfo

The flag that specifies additional information about the file or directory identified by the handle value in the VolumeHandle member.

Value Meaning
MARK_HANDLE_PROTECT_CLUSTERS

0x00000001		 The file is marked as unable to be defragmented until the handle is closed.

Once a handle marked MARK_HANDLE_PROTECT_CLUSTERS is closed, there is no guarantee that the file's clusters won't move.
MARK_HANDLE_TXF_SYSTEM_LOG

0x00000004		 The file is marked as unable to be defragmented until the handle is closed.

Windows Server 2003: This flag is not supported until Windows Server 2003 with SP1.

Windows XP: This flag is not supported.
MARK_HANDLE_NOT_TXF_SYSTEM_LOG

0x00000008		 The file is marked as unable to be defragmented until the handle is closed.

Windows Server 2003: This flag is not supported until Windows Server 2003 with SP1.

Windows XP: This flag is not supported.
MARK_HANDLE_REALTIME

0x00000020		 The file is marked for real-time read behavior regardless of the actual file type. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This flag is not supported.
MARK_HANDLE_NOT_REALTIME

0x00000040		 The file previously marked for real-time read behavior using the MARK_HANDLE_REALTIME flag can be unmarked using this flag, removing the real-time behavior. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This flag is not supported.
MARK_HANDLE_READ_COPY

0x00000080		 Indicates the copy number specified in the CopyNumber member should be used for reads. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This flag is not supported until Windows 8 and Windows Server 2012.
MARK_HANDLE_NOT_READ_COPY

0x00000100		 The file previously marked for read-copy behavior using the MARK_HANDLE_READ_COPY flag can be unmarked using this flag, removing the read-copy behavior. Files marked with this flag must be opened for unbuffered I/O.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This flag is not supported until Windows 8 and Windows Server 2012.

| MARK_HANDLE_RETURN_PURGE_FAILURE

0x00000400 | When intermixing memory mapped/cached IO with non-cached IO the system attempts, when a non-cached io is issued, to purge memory mappings for the range of the non-cached IO. If these purges fail the system normally does not return the failure to the caller which can lead to corrupted state (which is why the documentation says to not do this). This flag tells the system to return purge failures for the given handle so the application can better handle this situation

This flag is not supported until Windows 8 and Windows Server 2012. |

| MARK_HANDLE_DISABLE_FILE_METADATA_OPTIMIZATION

0x00001000 | A highly fragmented file in NTFS uses multiple MFT records to describe all of the extents for a file. This list of child MFT records (also known as FRS records) are controlled by a structure known as an attribute list. An attribute list is limited to 128K in size. When the size of an attribute list hits a certain threshold NTFS will trigger a background compaction on the extents so the minimum number of child FRS records will be used. This flag disables this FRS compaction feature for the given file.

This flag is not supported until Windows 10. |

| MARK_HANDLE_ENABLE_USN_SOURCE_ON_PAGING_IO

0x00002000 | Tells NTFS to set the given UsnSourceInfo value on Paging writes in the USN Journal. Traditionally this was not done on paging writes since the system did not know what thread made the given changes. This is an override. This only works if the FileObject the memory manager is using has this state associated with it.

This flag is not supported until Windows 10. |

| MARK_HANDLE_SKIP_COHERENCY_SYNC_DISALLOW_WRITES

0x00004000 | Setting this flag tells the system that writes are not allowed on this file. If an application tries to open the file for write access, the operation is failed with STATUS_ACCESS_DENIED. If a write is seen the operation is failed with STATUS_MARKED_TO_DISALLOW_WRITES

This flag is not supported until Windows 10. |

Remarks

To retrieve a handle to a volume, call CreateFile with the lpFileName parameter set to a string in the following form:

"\.*X*:"

In the preceding string, X is the letter identifying the drive on which the volume appears.

See also

FSCTL_MARK_HANDLE

USN_RECORD

View the official Win32 API reference

Edit description on GitHub