Requests a batch opportunistic lock on a file.

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

BOOL DeviceIoControl( (HANDLE) hDevice,              // handle to file
                      FSCTL_REQUEST_BATCH_OPLOCK,    // dwIoControlCode
                      NULL,                          // lpInBuffer
                      0,                             // nInBufferSize
                      NULL,                          // lpOutBuffer
                      0,                             // nOutBufferSize
                      (LPDWORD) lpBytesReturned,     // number of bytes returned
                      (LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure



A handle to the file or alternate stream for which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED.


The control code for the operation. Use FSCTL_REQUEST_BATCH_OPLOCK for this operation.


Not used with this operation; set to NULL.


Not used with this operation; set to zero.


Not used with this operation; set to NULL.


Not used with this operation; set to zero.


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

This parameter is meaningless until the overlapped operation has completed. 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.


A pointer to an OVERLAPPED structure.

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

DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed.

Return value

If the operation completes successfully, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

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


This operation is used only by client applications requesting an opportunistic lock (oplock) from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

If a new oplock type is desired, the handle must be closed and a new handle reopened using CreateFile, and DeviceIoControl must be called on the new handle with the desired FSCTL_REQUEST_OPLOCK_XXX control code. To request an oplock on a handle that can have the oplock type changed in place (the handle does not have to be closed and reopened), use the FSCTL_REQUEST_OPLOCK control code.

Use FSCTL_REQUEST_BATCH_OPLOCK to request a batch opportunistic lock on a file. A client file system can cache read data, write data, and handle data locally as long as the level 1 lock is held.

The batch oplock owner must acknowledge an oplock break before any operation that is incompatible with a batch oplock can go through on another handle. After the lock is broken, the network redirector is notified not to regard as valid any cached data from the file.

For more information, see Types of Opportunistic Locks.

For a comparison of the various oplock control codes, see FSCTL_REQUEST_OPLOCK.

An FSCTL_REQUEST_BATCH_OPLOCK control code fails if the file is opened in non-overlapped (synchronous) mode.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

In Windows 8 and Windows Server 2012, this code is supported by the following technologies.


Server Message Block (SMB) 3.0 protocol


SMB 3.0 Transparent Failover (TFO)


SMB 3.0 with Scale-out File Shares (SO)


Cluster Shared Volume File System (CsvFS)


Resilient File System (ReFS)




Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]


WinIoCtl.h (include Windows.h)

See also

Oplock Semantics
Opportunistic Locks