Platform SDK: Hardware |
The FSCTL_CREATE_USN_JOURNAL operation creates a change journal stream on a target volume or modifies an existing change journal stream.
To perform this operation, call the DeviceIoControl function with the following parameters.
BOOL DeviceIoControl( (HANDLE) hDevice, // handle to volume FSCTL_CREATE_USN_JOURNAL, // dwIoControlCode operation (LPVOID) lpInBuffer, // input buffer (DWORD) nInBufferSize, // size of input buffer NULL, // lpOutBuffer; must be NULL 0, // nOutBufferSize; must be zero (LPDWORD) lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure );
If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.
If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.
If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.
If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.
If the operation succeeds, DeviceIoControl returns a nonzero value.
If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.
Possible return values include the following.
Value | Meaning |
---|---|
ERROR_INVALID_FUNCTION | The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted. |
ERROR_INVALID_PARAMETER | One or more parameters was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle. |
ERROR_JOURNAL_DELETE_IN_PROGRESS | An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way. |
For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.
You can use FSCTL_CREATE_USN_JOURNAL to create a new change journal stream for a volume. After the creation of the stream, NTFS maintains a change journal for that volume.
You can also use FSCTL_CREATE_USN_JOURNAL to modify an existing change journal stream. If a change journal stream already exists, FSCTL_CREATE_USN_JOURNAL sets it to the characteristics provided in the CREATE_USN_JOURNAL_DATA structure. The change journal stream eventually grows or is trimmed to the new size limit imposed by CREATE_USN_JOURNAL_DATA.
To obtain a handle to a volume, pass in the CreateFile parameter lpFileName a value of the following form:
\\.\X:
where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.
For more information about creating a change journal, see Creating, Modifying, and Deleting a Change Journal.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winioctl.h.
Device Input and Output Overview, Device Input and Output Control Codes, CREATE_USN_JOURNAL_DATA, CreateFile, DeviceIoControl, OVERLAPPED