FsRtlOplockFsctrl function (ntifs.h)
FsRtlOplockFsctrl performs various opportunistic lock (oplock) operations on behalf of a file system or filter driver.
Syntax
NTSTATUS FsRtlOplockFsctrl(
[in] POPLOCK Oplock,
[in] PIRP Irp,
[in] ULONG OpenCount
);
Parameters
[in] Oplock
Opaque oplock pointer for the file. This pointer must have been initialized by a previous call to FsRtlInitializeOplock.
[in] Irp
Pointer to the IRP for the I/O operation. This parameter is required and cannot be NULL.
[in] OpenCount
Number of user handles for the file, if an exclusive oplock is being requested. Setting a nonzero value for a level 2, R, or RH oplock request indicates that there are byte-range locks on the file. For information about oplock types, see Oplock Overview.
Return value
FsRtlOplockFsctrl returns one of the following NTSTATUS values:
| Return code | Description |
|---|---|
| STATUS_SUCCESS | For an IRP_MJ_CREATE request, STATUS_SUCCESS indicates that the requested filter oplock was granted. For a FSCTL operation, the meaning of STATUS_SUCCESS depends on the FSCTL code. For more information, see the reference pages for the FSCTL codes listed in the following Remarks section. |
| STATUS_CANCELLED | The I/O operation was canceled. STATUS_CANCELLED is an error code. |
| STATUS_INVALID_PARAMETER | The FSCTL code for the I/O operation was not one of the valid values listed in the following Remarks section. STATUS_INVALID_PARAMETER is an error code. |
| STATUS_OPLOCK_NOT_GRANTED | The oplock could not be granted. STATUS_OPLOCK_NOT_GRANTED is an error code. |
| STATUS_PENDING | Used only for FSCTL operations. The meaning of STATUS_PENDING depends on the FSCTL code. For more information, see the reference pages for the FSCTL codes listed in the following Remarks section. STATUS_PENDING is a success code. |
| STATUS_CANNOT_BREAK_OPLOCK | A new oplock could not be granted. The IRP is an IRP_MJ_CREATE request and FILE_OPEN_REQUIRING_OPLOCK was specified in the create options parameter for the operation. STATUS_CANNOT_BREAK_OPLOCK is a success code. |
Remarks
File systems and legacy filter drivers call FsRtlOplockFsctrl to perform various oplock operations for a create or file system control I/O operation. Minifilters should call FltOplockFsctrl instead of FsRtlOplockFsctrl.
The IRP pointed to by the Irp parameter must be a valid IRP for an IRP_MJ_FILE_SYSTEM_CONTROL or IRP_MJ_CREATE operation.
If the IRP is an IRP_MJ_FILE_SYSTEM_CONTROL request, FsRtlOplockFsctrl can be used with one of the following FSCTL codes, which is set in IrpSp->Parameters.FileSystemControl.FsControlCode:
- FSCTL_OPBATCH_ACK_CLOSE_PENDING
- FSCTL_OPLOCK_BREAK_ACK_NO_2
- FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
- FSCTL_OPLOCK_BREAK_NOTIFY
- FSCTL_REQUEST_BATCH_OPLOCK
- FSCTL_REQUEST_FILTER_OPLOCK
- FSCTL_REQUEST_OPLOCK_LEVEL_1
- FSCTL_REQUEST_OPLOCK_LEVEL_2
For detailed information about these FSCTLs and about opportunistic locks in general, see the Microsoft Windows SDK documentation.
If the IRP is an IRP_MJ_CREATE request, FsRtlOplockFsctrl can be used to request a pending filter oplock if all of the following conditions are true:
- The value of the OpenCount parameter must be 1.
- The value of the DesiredAccess parameter for the IRP_MJ_CREATE request must be FILE_READ_ATTRIBUTES.
- The value of the ShareAccess parameter for the IRP_MJ_CREATE request must be FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
If the request for a pending filter oplock is granted, FsRtlOplockFsctrl returns STATUS_SUCCESS. For more information about create parameters, see the reference entry for IRP_MJ_CREATE.
Filters and file systems that call this function must synchronize calls into the system-supplied oplock package. See Oplock synchronization for more information.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
See also
FSCTL_OPBATCH_ACK_CLOSE_PENDING