NtOpenFile - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTIOAPI_H

/**
 * The NtOpenFile routine deletes the specified file.
 *
 * \param[out] FileHandle Pointer to a variable that receives a handle to the file.
 * \param[in] DesiredAccess The requested access to the object. 
 * \param[in] ObjectAttributes Pointer to an OBJECT_ATTRIBUTES structure that contains the file's attributes, including file name.
 * \param[out] IoStatusBlock Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation.
 * \param[in] ShareAccess Specifies the type of share access for the file.
 * \param[in] OpenOptions Specifies the options to apply when opening the file.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntopenfile
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenFile(
    _Out_ PHANDLE FileHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG ShareAccess,
    _In_ ULONG OpenOptions
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenFile(
    _Out_ PHANDLE FileHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG ShareAccess,
    _In_ ULONG OpenOptions
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenFile(
  [out] PHANDLE            FileHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [out] PIO_STATUS_BLOCK   IoStatusBlock,
  [in]  ULONG              ShareAccess,
  [in]  ULONG              OpenOptions
);
View the official Windows Driver Kit DDI reference
// wdm.h

NTSYSAPI NTSTATUS ZwOpenFile(
  [out] PHANDLE            FileHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [out] PIO_STATUS_BLOCK   IoStatusBlock,
  [in]  ULONG              ShareAccess,
  [in]  ULONG              OpenOptions
);
View the official Windows Driver Kit DDI reference
// winternl.h

__kernel_entry NTSTATUS NtOpenFile(
  [out] PHANDLE            FileHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [out] PIO_STATUS_BLOCK   IoStatusBlock,
  [in]  ULONG              ShareAccess,
  [in]  ULONG              OpenOptions
);
View the official Win32 API reference

NtDoc

No description available.

Edit description on GitHub

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

NtOpenFile function

Description

The NtOpenFile routine opens an existing file, directory, device, or volume.

Parameters

FileHandle [out]

Pointer to a HANDLE variable that receives a handle to the file.

DesiredAccess [in]

Specifies an ACCESS_MASK value that determines the requested access to the object. For more information, see the DesiredAccess parameter of NtCreateFile.

ObjectAttributes [in]

Pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use InitializeObjectAttributes to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

IoStatusBlock [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested operation.

ShareAccess [in]

Specifies the type of share access for the file. For more information, see the ShareAccess parameter of NtCreateFile.

OpenOptions [in]

Specifies the options to apply when opening the file. For more information, see the CreateOptions parameter of NtCreateFile.

Return value

NtOpenFile returns STATUS_SUCCESS or the appropriate NTSTATUS error code. In the latter case, the caller can find more information about the cause of the failure by checking the IoStatusBlock parameter.

Remarks

NtOpenFile supplies a handle that the caller can use to manipulate a file's data, or the file object's state and attributes. NtOpenFile provides a subset of the functionality provided by NtCreateFile. For more information, see Using Files in a Driver.

Once the handle pointed to by FileHandle is no longer in use, the driver must call NtClose to close it.

If the caller is not running in a system thread context, it must ensure that any handles it creates are private handles. Otherwise, the handle can be accessed by the process in whose context the driver is running. For more information, see Object Handles.

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

If the call to this function occurs in user mode, you should use the name "NtOpenFile" instead of "ZwOpenFile".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

InitializeObjectAttributes

NtClose

NtCreateFile

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-wdm-zwopenfile)

Description

The ZwOpenFile routine opens an existing file, directory, device, or volume.

Parameters

FileHandle [out]

Pointer to a HANDLE variable that receives a handle to the file.

DesiredAccess [in]

Specifies an ACCESS_MASK value that determines the requested access to the object. For more information, see the DesiredAccess parameter of ZwCreateFile.

ObjectAttributes [in]

Pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use InitializeObjectAttributes to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.

IoStatusBlock [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested operation.

ShareAccess [in]

Specifies the type of share access for the file. For more information, see the ShareAccess parameter of ZwCreateFile.

OpenOptions [in]

Specifies the options to apply when opening the file. For more information, see the CreateOptions parameter of ZwCreateFile.

Return value

ZwOpenFile returns STATUS_SUCCESS or the appropriate NTSTATUS error code. In the latter case, the caller can find more information about the cause of the failure by checking the IoStatusBlock parameter.

Remarks

ZwOpenFile supplies a handle that the caller can use to manipulate a file's data, or the file object's state and attributes. ZwOpenFile provides a subset of the functionality provided by ZwCreateFile. For more information, see Using Files in a Driver.

Once the handle pointed to by FileHandle is no longer in use, the driver must call ZwClose to close it.

If the caller is not running in a system thread context, it must ensure that any handles it creates are private handles. Otherwise, the handle can be accessed by the process in whose context the driver is running. For more information, see Object Handles.

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

If the call to this function occurs in user mode, you should use the name "NtOpenFile" instead of "ZwOpenFile".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

InitializeObjectAttributes

Using Nt and Zw Versions of the Native System Services Routines

ZwCreateFile

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Win32 API reference (nf-winternl-ntopenfile)

NtOpenFile function

Description

Opens an existing file, device, directory, or volume, and returns a handle for the file object.

This function is equivalent to the ZwOpenFile function documented in the Windows Driver Kit (WDK).

Parameters

FileHandle [out]

A pointer to a handle for the opened file. The driver must close the handle with ZwClose once the handle is no longer in use.

DesiredAccess [in]

The ACCESS_MASK value that expresses the types of file access desired by the caller. For information about the types of access that can be specified, see ZwCreateFile in the WDK.

ObjectAttributes [in]

A pointer to a structure that a caller initializes with InitializeObjectAttributes. If the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes. For more information about specifying object attributes, see the CreateOptions parameter of ZwCreateFile in the WDK.

IoStatusBlock [out]

A pointer to a structure that contains information about the requested operation and the final completion status.

ShareAccess [in]

The type of share access for the file. For more information, see ZwCreateFile in the WDK.

OpenOptions [in]

The options to be applied when opening the file. For more information, see ZwCreateFile in the WDK.

Return value

NtOpenFile either returns STATUS_SUCCESS or an appropriate error status. If it returns an error status, the caller can find additional information about the cause of the failure by checking the IoStatusBlock.

Remarks

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the ObjectAttributes parameter of ZwOpenFile. This restricts the use of the handle returned by ZwOpenFile to processes running only in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running. Drivers can call InitializeObjectAttributes to set the OBJ_KERNEL_HANDLE attribute as follows.

InitializeObjectAttributes(&ObjectAddributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Callers of ZwCreateFile must be running at IRQL = PASSIVE_LEVEL.

Note that the WDK header file Ntdef.h is necessary for many constant definitions. You can also use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll.

View the official Win32 API reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

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

(Also available in 2000 DDK.)

FileHandle

Result of call.

DesiredAccess

Access mask to opened file object.

ObjectAttributes

File name, path etc. See NtCreateFile for more information.

IoStatusBlock

Completion status of call.

ShareAccess

Sharing option defined as FILE_SHARE_*.

OpenOptions

Open options.

Documented by

See also

Edit description on GitHub