USN_RECORD_V3 structure (winioctl.h)
Contains the information for an update sequence number (USN) change journal version 3.0 record. The version 2.0 record is defined by the USN_RECORD_V2 structure (also called USN_RECORD structure).
Syntax
typedef struct {
DWORD RecordLength;
WORD MajorVersion;
WORD MinorVersion;
FILE_ID_128 FileReferenceNumber;
FILE_ID_128 ParentFileReferenceNumber;
USN Usn;
LARGE_INTEGER TimeStamp;
DWORD Reason;
DWORD SourceInfo;
DWORD SecurityId;
DWORD FileAttributes;
WORD FileNameLength;
WORD FileNameOffset;
WCHAR FileName[1];
} USN_RECORD_V3, *PUSN_RECORD_V3;
Members
RecordLength
The total length of a record, in bytes.
Because USN_RECORD_V3 is a variable size, the RecordLength member should be used when calculating the address of the next record in an output buffer, for example, a buffer that is returned from operations for the DeviceIoControl function that work with USN_RECORD_V3.
The size in bytes of any change
journal record is at most the size of the USN_RECORD_V3
structure, plus MaximumComponentLength characters minus 1 (for the character declared
in the structure) times the size of a wide character. The value of
MaximumComponentLength may be determined by calling the
GetVolumeInformation function. In C, you can
determine a record size by using the following code example.
| C++ |
|---|
MaximumChangeJournalRecordSize =
QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR)
+ sizeof(USN_RECORD_V3) );
|
MajorVersion
The major version number of the change journal software for this record.
For example, if the change journal software is version 3.0, the major version number is 3.
| Value | Meaning |
|---|---|
|
The structure is a USN_RECORD_V2 structure and the remainder of the structure should be parsed using that layout. |
|
The structure is a USN_RECORD_V3 structure and the remainder of the structure should be parsed using that layout. |
|
The structure is a [USN_RECORD_V4 structure](ns-winioctl-usn_record_v4.md) and the remainder of the structure should be parsed using that layout. |
MinorVersion
The minor version number of the change journal software for this record. For example, if the change journal software is version 3.0, the minor version number is zero.
FileReferenceNumber
The 128-bit ordinal number of the file or directory for which this record notes changes.
This is an arbitrarily assigned value that associates a journal record with a file.
ParentFileReferenceNumber
The 128-bit ordinal number of the directory where the file or directory that is associated with this record is located.
This is an arbitrarily assigned value that associates a journal record with a parent directory.
Usn
The USN of this record.
TimeStamp
The standard UTC time stamp (FILETIME) of this record, in 64-bit format.
Reason
The flags that identify reasons for changes that have accumulated in this file or directory journal record since the file or directory opened.
When a file or directory closes, then a final USN record is generated with the USN_REASON_CLOSE flag set. The next change (for example, after the next open operation or deletion) starts a new record with a new set of reason flags.
A rename or move operation generates two USN records, one that records the old parent directory for the item, and one that records a new parent.
The following table identifies the possible flags.
SourceInfo
Additional information about the source of the change, set by the FSCTL_MARK_HANDLE of the DeviceIoControl operation.
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, for example, an antivirus filter.
One of the two following values can be set.
SecurityId
The unique security identifier assigned to the file or directory associated with this record.
FileAttributes
The attributes for the file or directory associated with this record, as returned by the GetFileAttributes function. Attributes of streams associated with the file or directory are excluded.
FileNameLength
The length of the name of the file or directory associated with this record, in bytes. The FileName member contains this name. Use this member to determine file name length, rather than depending on a trailing '\0' to delimit the file name in FileName.
FileNameOffset
The offset of the FileName member from the beginning of the structure.
FileName[1]
The name of the file or directory associated with this record in Unicode format. This file or directory name is of variable length.
When working with FileName, do not count on the file name that contains a trailing '\0' delimiter, but instead determine the length of the file name by using FileNameLength.
Do not perform any compile-time pointer arithmetic using FileName. Instead, make necessary calculations at run time by using the value of the FileNameOffset member. Doing so helps make your code compatible with any future versions of USN_RECORD_V3.
Remarks
In output buffers returned from DeviceIoControl operations that work with USN_RECORD_V3, all records are aligned on 64-bit boundaries from the start of the buffer.
When range tracking is turned on, NTFS switches to producing only USN_RECORD_V3 records as output.
To provide a path for upward compatibility in change journal clients, Microsoft provides a major and minor version number of the change journal software in the USN_RECORD_V3 structure. Your code should examine these values, detect its own compatibility with the change journal software, and if necessary gracefully handle any incompatibility.
A change in the minor version number indicates that the existing USN_RECORD_V3 structure members are still valid, but that new members may have been added between the penultimate member and the last, which is a variable-length string.
To handle such a change gracefully, your code should not do any compile-time pointer arithmetic that relies on
the location of the last member. For example, this makes the C code
sizeof(USN_RECORD) unreliable. Instead, rely on run-time calculations by
using the RecordLength member.
An increase in the major version number of the change journal software indicates that the USN_RECORD_V3 structure may have undergone major changes, and that the current definition may not be reliable. If your code detects a change in the major version number of the change journal software, it should not work with the change journal.
For more information, see Creating, Modifying, and Deleting a Change Journal.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps only] |
| Minimum supported server | Windows Server 2012 [desktop apps only] |
| Header | winioctl.h (include Windows.h) |