Export (0) Print
Expand All

FSCTL_CREATE_USN_JOURNAL control code

Creates an update sequence number (USN) change journal stream on a target volume, or modifies an existing change journal stream.


BOOL 
WINAPI 
DeviceIoControl( (HANDLE) hDevice,              // handle to volume
                 FSCTL_CREATE_USN_JOURNAL,      // dwIoControlCode
                 (LPVOID) lpInBuffer,           // input buffer
                 (DWORD) nInBufferSize,         // size of input buffer
                 NULL,                          // lpOutBuffer
                 0,                             // nOutBufferSize
                 (LPDWORD) lpBytesReturned,     // number of bytes returned
                 (LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure

Parameters

To perform this operation, call the DeviceIoControl function with the following parameters.

hDevice

A handle to the local volume for the change journal stream that is to be created or modified.

To retrieve a volume handle, call the CreateFile function.

dwIoControlCode

The control code for the operation.

Use FSCTL_CREATE_USN_JOURNAL for this operation.

lpInBuffer

A pointer to the input buffer, a CREATE_USN_JOURNAL_DATA structure.

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

Not used with this operation; set to NULL.

nOutBufferSize

Not used with this operation; set to zero.

lpBytesReturned

A pointer to a variable that receives the size of the data that is stored in the output buffer, in bytes.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation does not return output data and lpOutBuffer is NULL, DeviceIoControl uses lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation is complete. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

If hDevice is opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.

If hDevice is opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation is complete. Otherwise, the function does not return until the operation is complete or an error occurs.

Return value

If the operation completes successfully, DeviceIoControl returns a nonzero value.

If the operation fails or is pending, DeviceIoControl returns zero. To get extended error information, call GetLastError.

The possible return values include the following.

Return codeDescription
ERROR_INVALID_FUNCTION

The specified volume does not support change journals.

ERROR_INVALID_PARAMETER

One or more parameters is invalid, for example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.

ERROR_JOURNAL_DELETE_IN_PROGRESS

An attempt is made to read from, create, delete, or modify the journal while a journal deletion is in process, or an attempt is made to write a USN record while a journal deletion is in process.

 

Remarks

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, the NTFS file system 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 gets larger or is trimmed to the new size limit that CREATE_USN_JOURNAL_DATA imposes.

For more information, see Creating, Modifying, and Deleting a Change Journal.

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. The volume must be NTFS 3.0 or later. To obtain the NTFS version of a volume, open a command prompt with Administrator access rights and execute the following command:

fsutil fsinfo ntfsinfo X:

where X is the drive letter of the volume.

In Windows Server 2012, this function is supported by the following technologies.

TechnologySupported

Server Message Block (SMB) 3.0 protocol

No

SMB 3.0 Transparent Failover (TFO)

No

SMB 3.0 with Scale-out File Shares (SO)

No

Cluster Shared Volume File System (CsvFS)

Yes

 

Requirements

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

Change Journals
CreateFile
CREATE_USN_JOURNAL_DATA
DeviceIoControl
OVERLAPPED
Volume Management Control Codes

 

 

Community Additions

ADD
Show:
© 2014 Microsoft