#ifndef _NTIOAPI_H

/**
 * The NtFsControlFile function sends a control code directly to a file system or filter driver, causing the corresponding driver to perform the specified action.
 *
 * \param[in] FileHandle A handle to the file object representing the file or directory on which the specified action is to be performed.
 * \param[in] Event A handle for a caller-created event. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
 * \param[in] ApcRoutine Address of a caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL.
 * \param[in] ApcContext Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object. 
 * \param[out] IoStatusBlock Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation.
 * \param[in] FsControlCode FSCTL_XXX code that indicates which file system control operation is to be carried out.
 * \param[in] InputBuffer Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target driver.
 * \param[in] InputBufferLength Size, in bytes, of the buffer at InputBuffer. This value is ignored if InputBuffer is NULL.
 * \param[out] OutputBuffer Pointer to a caller-allocated output buffer in which information is returned from the target driver.
 * \param[in] OutputBufferLength Size, in bytes, of the buffer at OutputBuffer. This value is ignored if OutputBuffer is NULL.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwfscontrolfile
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtFsControlFile(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG FsControlCode,
    _In_reads_bytes_opt_(InputBufferLength) PVOID InputBuffer,
    _In_ ULONG InputBufferLength,
    _Out_writes_bytes_opt_(OutputBufferLength) PVOID OutputBuffer,
    _In_ ULONG OutputBufferLength
    );

#endif
View code on GitHub

#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwFsControlFile(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG FsControlCode,
    _In_reads_bytes_opt_(InputBufferLength) PVOID InputBuffer,
    _In_ ULONG InputBufferLength,
    _Out_writes_bytes_opt_(OutputBufferLength) PVOID OutputBuffer,
    _In_ ULONG OutputBufferLength
    );

#endif
View code on GitHub

// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);
View the official Windows Driver Kit DDI reference

// ntifs.h

NTSYSAPI NTSTATUS ZwFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-ntfscontrolfile)

NtFsControlFile function

Description

The NtFsControlFile routine sends a control code directly to a specified file system or file system filter driver, causing the corresponding driver to perform the specified action.

Parameters

`FileHandle` [in]

Handle returned by NtCreateFile or NtOpenFile for the file object representing the file or directory on which the specified action is to be performed. The file object must have been opened for asynchronous I/O if the caller specifies an Event, ApcRoutine, and an APC context (in ApcContext), or a completion context (in ApcContext).

`Event` [in, optional]

Handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.

`ApcRoutine` [in, optional]

Address of a caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL. It must be NULL if there is an I/O completion object associated with the file object.

`ApcContext` [in, optional]

Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object. When the operation completes, either the APC context is passed to the APC, if one was specified, or the completion context is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.

This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.

`IoStatusBlock` [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the OutputBuffer is returned in the Information member of this structure.

`FsControlCode` [in]

FSCTL_XXX code that indicates which file system control operation is to be carried out. The value of this parameter determines the formats and required lengths of the InputBuffer and OutputBuffer, as well as which of the following parameter pairs are required. For detailed information about the system-defined FSCTL_XXX codes, see the "Remarks" section of the reference entry for DeviceIoControl.

`InputBuffer` [in, optional]

Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target driver. If FsControlCode specifies an operation that doesn't require input data, this pointer is optional and can be NULL.

`InputBufferLength` [in]

Size, in bytes, of the buffer at InputBuffer. This value is ignored if InputBuffer is NULL.

`OutputBuffer` [out, optional]

Pointer to a caller-allocated output buffer in which information is returned from the target driver. If FsControlCode specifies an operation that doesn't produce output data, this pointer is optional and can be NULL.

`OutputBufferLength` [in]

Size, in bytes, of the buffer at OutputBuffer. This value is ignored if OutputBuffer is NULL.

Return value

NtFsControlFile returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Remarks

NtFsControlFile provides a consistent view of the input and output data to the system and to kernel-mode drivers, while providing applications and underlying drivers with a driver-dependent method of specifying a communications interface.

If the caller opened the file for asynchronous I/O (with neither FILE_SYNCHRONOUS_XXX create/open option set), the specified event, if any, will be set to the signaled state when the device control operation completes. Otherwise, the file object specified by FileHandle will be set to the signaled state. If an ApcRoutine was specified, it is called with the ApcContext and IoStatusBlock pointers.

The following are some of the FSCTL codes documented for kernel-mode drivers:

For more information about system-defined FSCTL_XXX codes, see the "Remarks" section of DeviceIoControl, which is typically used by user-mode applications.

For more information about system-defined IOCTL_XXX codes, and about defining driver-specific IOCTL_XXX or FSCTL_XXX values, see Using I/O Control Codes and Device Input and Output Control Codes.

Minifilters should use FltFsControlFile instead of NtFsControlFile.

Callers of NtFsControlFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

If the call to the NtFsControlFile function occurs in user mode, you should use the name "NtFsControlFile" instead of "ZwFsControlFile".

For calls from kernel-mode drivers, the NtXXX and ZwXXX versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXXX and ZwXXX versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Windows Driver Kit DDI reference (nf-ntifs-zwfscontrolfile)

ZwFsControlFile function

Description

The ZwFsControlFile routine sends a control code directly to a specified file system or file system filter driver, causing the corresponding driver to perform the specified action.

Parameters

`FileHandle` [in]

Handle returned by ZwCreateFile or ZwOpenFile for the file object representing the file or directory on which the specified action is to be performed. The file object must have been opened for asynchronous I/O if the caller specifies an Event, ApcRoutine, and an APC context (in ApcContext), or a completion context (in ApcContext).

`Event` [in, optional]

Handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.

`ApcRoutine` [in, optional]

Address of a caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL. It must be NULL if there is an I/O completion object associated with the file object.

`ApcContext` [in, optional]

This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.

`IoStatusBlock` [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the OutputBuffer is returned in the Information member of this structure.

`FsControlCode` [in]

FSCTL_XXX code that indicates which file system control operation is to be carried out. The value of this parameter determines the formats and required lengths of the InputBuffer and OutputBuffer, as well as which of the following parameter pairs are required. For detailed information about the system-defined FSCTL_XXX codes, see the "Remarks" section of the reference entry for DeviceIoControl in the Microsoft Windows SDK documentation.

`InputBuffer` [in, optional]

Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target driver. If FsControlCode specifies an operation that does not require input data, this pointer is optional and can be NULL.

`InputBufferLength` [in]

Size, in bytes, of the buffer at InputBuffer. This value is ignored if InputBuffer is NULL.

`OutputBuffer` [out, optional]

Pointer to a caller-allocated output buffer in which information is returned from the target driver. If FsControlCode specifies an operation that does not produce output data, this pointer is optional and can be NULL.

`OutputBufferLength` [in]

Size, in bytes, of the buffer at OutputBuffer. This value is ignored if OutputBuffer is NULL.

Return value

ZwFsControlFile returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Remarks

ZwFsControlFile provides a consistent view of the input and output data to the system and to kernel-mode drivers, while providing applications and underlying drivers with a driver-dependent method of specifying a communications interface.

If the caller opened the file for asynchronous I/O (with neither FILE_SYNCHRONOUS_XXX create/open option set), the specified event, if any, will be set to the signaled state when the device control operation completes. Otherwise, the file object specified by FileHandle will be set to the signaled state. If an ApcRoutine was specified, it is called with the ApcContext and IoStatusBlock pointers.

The following FSCTL codes are currently documented for kernel-mode drivers:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

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

FSCTL_SET_REPARSE_POINT

For more information about system-defined FSCTL_XXX codes, see the "Remarks" section of the reference entry for DeviceIoControl in the Microsoft Windows SDK documentation.

For more information about system-defined IOCTL_XXX codes, and about defining driver-specific IOCTL_XXX or FSCTL_XXX values, see Using I/O Control Codes in the Kernel Mode Architecture Guide and Device Input and Output Control Codes in the Windows SDK documentation.

Minifilters should use FltFsControlFile instead of ZwFsControlFile.

Callers of ZwFsControlFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

Note If the call to the ZwFsControlFile function occurs in user mode, you should use the name "NtFsControlFile" instead of "ZwFsControlFile".

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit here and here.

Function NtFsControlFile sends FSCTL_* code to File System Device Driver. See also description of NtDeviceIoControlFile function.

FileHandle

HANDLE to File System Device Object opened as a file.

Event

Optional HANDLE to Event Object.

ApcRoutine

Optional pointer to user's APC Routine.

ApcContext

Parameter for ApcRoutine.

IoStatusBlock

IO result of call.

FsControlCode

Control Code typically defined as FSCTL_*.

InputBuffer

User's allocated buffer contains input data.

InputBufferLength

Length of InputBuffer, in bytes.

OutputBuffer

User's allocated buffer for results of call.

OutputBufferLength

Length of OutputBuffer, in bytes.

Documented by

Tomasz Nowak
ReactOS

NtDoc

Windows Driver Kit DDI reference (nf-ntifs-ntfscontrolfile)

NtFsControlFile function

Description

Parameters

FileHandle [in]

Event [in, optional]

ApcRoutine [in, optional]

ApcContext [in, optional]

IoStatusBlock [out]

FsControlCode [in]

InputBuffer [in, optional]

InputBufferLength [in]

OutputBuffer [out, optional]

OutputBufferLength [in]

Return value

Remarks

See also

Windows Driver Kit DDI reference (nf-ntifs-zwfscontrolfile)

ZwFsControlFile function

Description

Parameters

FileHandle [in]

Event [in, optional]

ApcRoutine [in, optional]

ApcContext [in, optional]

IoStatusBlock [out]

FsControlCode [in]

InputBuffer [in, optional]

InputBufferLength [in]

OutputBuffer [out, optional]

OutputBufferLength [in]

Return value

Remarks

See also

NTinternals.net (undocumented.ntinternals.net)

FileHandle

Event

ApcRoutine

ApcContext

IoStatusBlock

FsControlCode

InputBuffer

InputBufferLength

OutputBuffer

OutputBufferLength

Documented by

See also

`FileHandle` [in]

`Event` [in, optional]

`ApcRoutine` [in, optional]

`ApcContext` [in, optional]

`IoStatusBlock` [out]

`FsControlCode` [in]

`InputBuffer` [in, optional]

`InputBufferLength` [in]

`OutputBuffer` [out, optional]

`OutputBufferLength` [in]

`FileHandle` [in]

`Event` [in, optional]

`ApcRoutine` [in, optional]

`ApcContext` [in, optional]

`IoStatusBlock` [out]

`FsControlCode` [in]

`InputBuffer` [in, optional]

`InputBufferLength` [in]

`OutputBuffer` [out, optional]

`OutputBufferLength` [in]