READ_USN_JOURNAL_DATA_V0 structure (winioctl.h)
Contains information defining a set of update sequence number (USN) change journal records to return to the calling process. It is used by the FSCTL_QUERY_USN_JOURNAL and FSCTL_READ_USN_JOURNAL control codes. Prior to Windows 8 and Windows Server 2012 this structure was named READ_USN_JOURNAL_DATA. Use that name to compile with older SDKs and compilers. Windows Server 2012 introduced READ_USN_JOURNAL_DATA_V1 to support 128-bit file identifiers used by ReFS.
Syntax
typedef struct {
USN StartUsn;
DWORD ReasonMask;
DWORD ReturnOnlyOnClose;
DWORDLONG Timeout;
DWORDLONG BytesToWaitFor;
DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;
Members
StartUsn
The USN at which to begin reading the change journal.
To start the read operation at the first record in the journal, set the StartUsn member to zero. Because a USN is contained in every journal record, the output buffer tells at which record the read operation actually started.
To start the read operation at a specific record, set StartUsn to that record USN.
If a nonzero USN is specified that is less than the first USN in the change journal, then an error occurs and the ERROR_JOURNAL_ENTRY_DELETED error code is returned. This code may indicate a case in which the specified USN is valid at one time but has since been deleted.
For more information on navigating the change journal buffer returned in READ_USN_JOURNAL_DATA_V0, see Walking a Buffer of Change Journal Records.
ReasonMask
A mask of flags, each flag noting a change for which the file or directory has a record in the change journal. To be returned in a FSCTL_READ_USN_JOURNAL operation, a change journal record must have at least one of these flags set.
The list of valid flags is as follows. Unused bits are reserved.
| Value | Meaning |
|---|---|
|
A user has either changed one or more file or directory attributes (such as the read-only, hidden, system, archive, or sparse attribute), or one or more time stamps. |
|
The file or directory is closed. |
|
The compression state of the file or directory is changed from or to compressed. |
|
The file or directory is added to. |
|
Data in the file or directory is overwritten. |
|
The file or directory is truncated. |
|
The user makes a change to the file or directory extended attributes. These NTFS file system attributes are not accessible to Windows-based applications. |
|
The file or directory is encrypted or decrypted. |
|
The file or directory is created for the first time. |
|
The file or directory is deleted. |
|
An NTFS file system hard link is added to or removed from the file or directory. An NTFS file system hard link, similar to a POSIX hard link, is one of several directory entries that see the same file or directory. |
|
A user changed the FILE_ATTRIBUTE_NOT_CONTENT_INDEXED attribute. That is, the user changed the file or directory from one that can be content indexed to one that cannot, or vice versa. (Content indexing permits rapid searching of data by building a database of selected content.) |
|
One or more named data streams for the file were added to. |
|
Data in one or more named data streams for the file is overwritten. |
|
One or more named data streams for the file is truncated. |
|
The object identifier of the file or directory is changed. |
|
The file or directory is renamed, and the file name in the USN_RECORD_V2 or USN_RECORD_V3 structure holding this journal record is the new name. |
|
The file or directory is renamed, and the file name in the USN_RECORD_V2 or USN_RECORD_V3 structure holding this journal record is the previous name. |
|
The reparse point contained in the file or directory is changed, or a reparse point is added to or deleted from the file or directory. |
|
A change is made in the access permissions to the file or directory. |
|
A named stream is added to or removed from the file or directory, or a named stream is renamed. |
ReturnOnlyOnClose
A value that specifies when to return change journal records.
To receive notification when the final handle for the changed file or directory is closed, rather than at the time a change occurs, set ReturnOnlyOnClose to any nonzero value and specify the USN_REASON_CLOSE flag in the ReasonMask member.
All changes indicated by ReasonMask flags eventually generate a call to the change journal software when the file is closed. If your DeviceIoControl call is waiting for the file to be closed, that call in turn will allow your DeviceIoControl call to return. In the event that a file or directory is not closed prior to a volume failure, operating system failure, or shutdown, a cleanup call to the change journal software occurs the next time the volume is mounted. The call occurs even if there is an intervening system restart.
To receive notification the first time each change is logged, as well as at cleanup, set ReturnOnlyOnClose to zero.
Whether ReturnOnlyOnClose is zero or nonzero, the records generated at cleanup log within the change journal all reasons for USN changes that occurred to the file or directory. Each time a final close operation occurs for an item, a USN close record is written to the change journal, and the ReasonMask flags for the item are all reset.
For a file or directory for which no user data exists (for example, a mounted folder), the final close operation occurs when the CloseHandle function is called on the last user handle to the item.
Timeout
The time-out value, in seconds, used with the BytesToWaitFor member to tell the operating system what to do if the FSCTL_READ_USN_JOURNAL operation requests more data than exists in the change journal.
If Timeout is zero and BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits until BytesToWaitFor bytes of unfiltered data have been added to the change journal and then retrieves the specified records.
If Timeout is nonzero and BytesToWaitFor is nonzero, and the FSCTL_READ_USN_JOURNAL operation call reaches the end of the change journal without finding data to return, FSCTL_READ_USN_JOURNAL waits Timeout seconds and then attempts to return the specified records. After Timeout seconds, FSCTL_READ_USN_JOURNAL retrieves any records available within the specified range.
In either case, after the time-out period any new data appended to the change journal is processed. If there are still no records to return from the specified set, the time-out period is repeated. In this mode, FSCTL_READ_USN_JOURNAL remains outstanding until at least one record is returned or I/O is canceled.
If BytesToWaitFor is zero, then Timeout is ignored. Timeout is also ignored for asynchronously opened handles.
BytesToWaitFor
The number of bytes of unfiltered data added to the change journal. Use this value with Timeout to tell the operating system what to do if the FSCTL_READ_USN_JOURNAL operation requests more data than exists in the change journal.
If BytesToWaitFor is zero, then Timeout is ignored. In this case, the FSCTL_READ_USN_JOURNAL operation always returns successfully when the end of the change journal file is encountered. It also retrieves the USN that should be used for the next FSCTL_READ_USN_JOURNAL operation. When the returned next USN is the same as the StartUsn supplied, there are no records available. The calling process should not use FSCTL_READ_USN_JOURNAL again immediately.
Because the amount of data returned cannot be predicted when BytesToWaitFor is zero, you run a risk of overflowing the output buffer. To reduce this risk, specify a nonzero BytesToWaitFor value in repeated FSCTL_READ_USN_JOURNAL operations until all records in the change journal are exhausted. Then specify zero to await new records.
Alternatively, use the lpBytesReturned parameter of DeviceIoControl in the FSCTL_READ_USN_JOURNAL operation call to determine the amount of data available, reallocate the output buffer (with room to spare for new records), and call DeviceIoControl again.
UsnJournalID
The identifier for the instance of the journal that is current for the volume.
The NTFS file system can miss putting events in the change journal if the change journal is stopped and restarted or deleted and re-created. If either of these events occurs, the NTFS file system gives the journal a new identifier. If the journal identifier does not agree with the current journal identifier, the call to DeviceIoControl fails and returns an appropriate error code. To retrieve the new journal identifier, call DeviceIoControl with the FSCTL_QUERY_USN_JOURNAL operation.
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) |