ZwOpenFile

The ZwOpenFile routine opens an existing file, device, directory, or volume, and returns a handle for the file object.

NTSTATUS
  ZwOpenFile(
    OUT PHANDLE  FileHandle,
    IN ACCESS_MASK  DesiredAccess,
    IN POBJECT_ATTRIBUTES  ObjectAttributes,
    OUT PIO_STATUS_BLOCK  IoStatusBlock,
    IN ULONG  ShareAccess,
    IN ULONG  OpenOptions
    );

Parameters

FileHandle

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

Specifies 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 the DesiredAccess parameter of ZwCreateFile.

ObjectAttributes

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 ObjectAttributes parameter of ZwCreateFile.

IoStatusBlock

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

ShareAccess

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

OpenOptions

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

Headers

Declared in ntddk.h. Include ntddk.h.

Return value

ZwOpenFile either returns STATUS_SUCCESS or an appropriate error status. If it returns an error status, the caller can get more information about the error by checking status information returned in IoStatusBlock.

Comments

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(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

ZwOpenFile provides a subset of the functionality provided by ZwCreateFile.

Callers of ZwOpenFile must be running at IRQL = PASSIVE_LEVEL.

See Also

ACCESS_MASK, InitializeObjectAttributes, ZwCreateFile