MARK_HANDLE_INFO structure (winioctl.h)
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.
Syntax
typedef struct _MARK_HANDLE_INFO {
union {
DWORD UsnSourceInfo;
DWORD CopyNumber;
} DUMMYUNIONNAME;
DWORD UsnSourceInfo;
HANDLE VolumeHandle;
DWORD HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;
Members
DUMMYUNIONNAME
DUMMYUNIONNAME.UsnSourceInfo
DUMMYUNIONNAME.CopyNumber
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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
Replication is being performed on client systems either from the cloud or servers. |
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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Header | winioctl.h (include Windows.h) |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for