2.3.48.2 USN_RECORD_V2

The USN_RECORD_V2 element is as follows.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

RecordLength

MajorVersion

MinorVersion

FileReferenceNumber

...

ParentFileReferenceNumber

...

Usn

...

TimeStamp

...

Reason

SourceInfo

SecurityId

FileAttributes

FileNameLength

FileNameOffset

FileName (variable)

...

RecordLength (4 bytes): A 32-bit unsigned integer that contains the total length of the update sequence number (USN) record, in bytes.

MajorVersion (2 bytes): A 16-bit unsigned integer that contains the major version of the change journal software for this record. For a USN_RECORD_V2, the major version number is 2.

MinorVersion (2 bytes): A 16-bit unsigned integer that contains the minor version of the change journal software for this record. For a USN_RECORD_V2, the minor version number is 0 (zero).

FileReferenceNumber (8 bytes): A 64-bit signed integer, opaque to the client, containing the number (assigned by the file system when the file is created) of the file or directory for which this record notes changes. The FileReferenceNumber is an arbitrarily assigned value that associates a journal record with a file. If the value is -1, its meaning is undefined; otherwise this value SHOULD always be unique within the volume on which the file is stored over the life of the volume.<40>

ParentFileReferenceNumber (8 bytes): A 64-bit signed integer, opaque to the client, containing the ordinal number of the directory on which 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. If the value is -1, its meaning is undefined; otherwise this value SHOULD always be unique within the volume on which the file is stored over the life of the volume.

Usn (8 bytes): A 64-bit signed integer, opaque to the client, containing the USN of the record. This value is unique within the volume on which the file is stored. This value MUST be greater than or equal to 0. This value MUST be 0 if no USN change journal records have been logged for the file or directory associated with this record. For more information, see [MSDN-CJ].

TimeStamp (8 bytes): The absolute system time that this change journal event was logged; see section 2.1.1.

Reason (4 bytes): A 32-bit unsigned integer that contains flags that indicate reasons for changes that have accumulated in this file or directory journal record since the file or directory was opened. When a file or directory is closed, a final USN record is generated with the USN_REASON_CLOSE flag set in this field. The next change, occurring 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 the new parent in the ParentFileReferenceNumber member. Possible values for the reason code are as follows (all unused bits are reserved for future use and MUST NOT be used).

Value

Meaning

USN_REASON_BASIC_INFO_CHANGE

0x00008000

A user has either changed one or more files or directory attributes (such as read-only, hidden, archive, or sparse) or one or more time stamps.

USN_REASON_CLOSE

0x80000000

The file or directory is closed.

USN_REASON_COMPRESSION_CHANGE

0x00020000

The compression state of the file or directory is changed from (or to) compressed.

USN_REASON_DATA_EXTEND

0x00000002

The file or directory is extended (added to).

USN_REASON_DATA_OVERWRITE

0x00000001

The data in the file or directory is overwritten.

USN_REASON_DATA_TRUNCATION

0x00000004

The file or directory is truncated.

USN_REASON_EA_CHANGE

0x00000400

The user made a change to the extended attributes of a file or directory. These NTFS file system attributes are not accessible to nonnative applications. This USN reason does not appear under normal system usage, but can appear if an application or utility bypasses the Win32 API and uses the native API to create or modify extended attributes of a file or directory.

USN_REASON_ENCRYPTION_CHANGE

0x00040000

The file or directory is encrypted or decrypted.

USN_REASON_FILE_CREATE

0x00000100

The file or directory is created for the first time.

USN_REASON_FILE_DELETE

0x00000200

The file or directory is deleted.

USN_REASON_HARD_LINK_CHANGE

0x00010000

A hard link is added to (or removed from) the file or directory.

USN_REASON_INDEXABLE_CHANGE

0x00004000

A user changes the FILE_ATTRIBUTE_NOT_CONTEXT_INDEXED attribute. That is, the user changes the file or directory from one in which content can be indexed to one in which content cannot be indexed, or vice versa.

USN_REASON_NAMED_DATA_EXTEND

0x00000020

The one (or more) named data stream for a file is extended (added to).

USN_REASON_NAMED_DATA_OVERWRITE

0x00000010

The data in one (or more) named data stream for a file is overwritten.

USN_REASON_NAMED_DATA_TRUNCATION

0x00000040

One (or more) named data stream for a file is truncated.

USN_REASON_OBJECT_ID_CHANGE

0x00080000

The object identifier of a file or directory is changed.

USN_REASON_RENAME_NEW_NAME

0x00002000

A file or directory is renamed, and the file name in the USN_RECORD structure is the new name.

USN_REASON_RENAME_OLD_NAME

0x00001000

The file or directory is renamed, and the file name in the USN_RECORD structure is the previous name.

USN_REASON_REPARSE_POINT_CHANGE

0x00100000

The reparse point that is contained in a file or directory is changed, or a reparse point is added to (or deleted from) a file or directory.

USN_REASON_SECURITY_CHANGE

0x00000800

A change is made in the access rights to a file or directory.

USN_REASON_STREAM_CHANGE

0x00200000

A named stream is added to (or removed from) a file, or a named stream is renamed.

USN_REASON_INTEGRITY_CHANGE

0x00800000

A change is made in the integrity status of a file or directory.

SourceInfo (4 bytes): A 32-bit unsigned integer that provides additional information about the source of the change. When a thread writes a new USN record, the source information flags in the prior record continue 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. This flag MUST contain one of the following values.

Value

Meaning

USN_SOURCE_DATA_MANAGEMENT

0x00000001

The operation provides information about a change to the file or directory that was made by the operating system. For example, a change journal record with this SourceInfo value is generated when the Remote Storage system moves data from external to local storage. This SourceInfo value indicates that the modifications did not change the application data in the file.

USN_SOURCE_AUXILIARY_DATA

0x00000002

The operation adds a private data stream to a file or directory. For example, a virus detector might add checksum information. As the virus detector modifies the item, the system generates USN records. This SourceInfo value indicates that the modifications did not change the application data in the file.

USN_SOURCE_REPLICATION_MANAGEMENT

0x00000004

The operation modified the file to match the content of the same file that exists in another member of the replica set for the File Replication Service (FRS).

SecurityId (4 bytes): A 32-bit unsigned integer that contains an index of a unique security identifier assigned to the file or directory associated with this record. This index is internal to the underlying object store and MUST be ignored.

FileAttributes (4 bytes): A 32-bit unsigned integer that contains attributes for the file or directory associated with this record. Attributes of streams associated with the file or directory are excluded. Valid file attributes are specified in section 2.6.

FileNameLength (2 bytes): A 16-bit unsigned integer that contains the length of the file or directory name 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 null to delimit the file name in FileName.

FileNameOffset (2 bytes): A 16-bit unsigned integer that contains the offset, in bytes, of the FileName member from the beginning of the structure.

FileName (variable): A variable-length field of Unicode characters containing the name of the file or directory associated with this record in Unicode format. When working with this field, do not assume that the file name will contain a trailing Unicode null character.

The fields Reason, TimeStamp, SourceInfo, and SecurityId for a USN RECORD element returned by this FSCTL MUST all be set to 0.<41>