NtOpenFile function (ntifs.h)

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

Syntax

__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
);

Parameters

[out] FileHandle

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

[in] DesiredAccess

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

[in] ObjectAttributes

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.

[out] IoStatusBlock

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

[in] ShareAccess

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

[in] OpenOptions

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 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.

Requirements

Requirement Value
Minimum supported client Windows 2000
Target Platform Universal
Header ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (see Remarks section)
DDI compliance rules HwStorPortProhibitedDDIs, PowerIrpDDis

See also

ACCESS_MASK

InitializeObjectAttributes

NtClose

NtCreateFile