Expand Minimize

FsRtlOplockFsctrl function

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

Oplock [in]

Opaque opportunistic lock pointer for the file. This pointer must have been initialized by a previous call to FsRtlInitializeOplock.

Irp [in]

Pointer to the IRP for the I/O operation. This parameter is required and cannot be NULL.

OpenCount [in]

Number of user handles for the file, if an exclusive opportunistic lock 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 Semantics Overview.

Return value

FsRtlOplockFsctrl returns one of the following NTSTATUS values:

Return codeDescription
STATUS_SUCCESS

For an IRP_MJ_CREATE request, STATUS_SUCCESS indicates that the requested filter opportunistic lock 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 opportunistic lock 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 opportunistic lock (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 filter drivers call FsRtlOplockFsctrl to perform various opportunistic lock operations for a create or file system control I/O operation. 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 the following FSCTL codes. The FSCTL code is set in IrpSp->Parameters.FileSystemControl.FsControlCode. For more information about file system control parameters, see the reference entry for IRP_MJ_FILE_SYSTEM_CONTROL.

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 opportunistic lock 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 opportunistic lock is granted, FsRtlOplockFsctrl returns STATUS_SUCCESS. For more information about create parameters, see the reference entry for IRP_MJ_CREATE.

Minifilters should call FltOplockFsctrl instead of FsRtlOplockFsctrl.

Requirements

Target platform

Universal

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

See also

FltOplockFsctrl
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
FsRtlCheckOplock
FsRtlCurrentBatchOplock
FsRtlInitializeOplock
FsRtlOplockIsFastIoPossible
FsRtlUninitializeOplock
IRP_MJ_CREATE
IRP_MJ_FILE_SYSTEM_CONTROL

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft