This article describes how to open a disk file from a kernel-mode device driver and how to read from or write to the file.
Refer to a file by its object name
Kernel-mode device drivers refer to a file by its object name. This name is \DosDevices together with the full path of the file. For example, the object name of the C:\Windows\Example.txt file is \DosDevices\C:\Windows\Example.txt. Then the object name is encapsulated into an
OBJECT_ATTRIBUTES structure by calling the
InitializeObjectAttributes function.
Note If the device driver is loaded early, the
\DosDevices namespace may not yet exist. Therefore, the
\DosDevices namespace is inaccessible to the device driver because no drive letter is exposed. The only part of the file system that is guaranteed to be available is the
\SystemRoot namespace. The
\SystemRoot namespace is mapped to the folder where the operation system is installed. For example, this folder may be C:\Windows or D:\Winnt.
The following code example illustrates how to refer to a file by its object name.
UNICODE_STRING uniName;
OBJECT_ATTRIBUTES objAttr;
RtlInitUnicodeString(&uniName, L"\\DosDevices\\C:\\WINDOWS\\example.txt"); // or L"\\SystemRoot\\example.txt"
InitializeObjectAttributes(&objAttr, &uniName,
OBJ_CASE_INSENSITIVE | OBJ_KERNEL_HANDLE,
NULL, NULL);Obtain a file handle
To obtain a file handle, you can pass an
OBJECT_ATTRIBUTES structure to the
ZwCreateFile function. The
DesiredAccess parameter can be set to either
GENERIC_READ,
GENERIC_WRITE, or
GENERIC_ALL, depending on what you want to do. If you set the
CreateOptions parameter to
FILE_SYNCHRONOUS_IO_NONALERT or
FILE_SYNCHRONOUS_IO_ALERT, the file system keeps track of the current file-position offset. Therefore, you can sequentially read or write to the file later. Additionally, you can access the file at a random location.
The following code example illustrates how to obtain a file handle.
HANDLE handle;
NTSTATUS ntstatus;
IO_STATUS_BLOCK ioStatusBlock;
// Do not try to perform any file operations at higher IRQL levels.
// Instead, you may use a work item or a system worker thread to perform file operations.
if(KeGetCurrentIrql() != PASSIVE_LEVEL)
return STATUS_INVALID_DEVICE_STATE;
ntstatus = ZwCreateFile(&handle,
GENERIC_WRITE,
&objAttr, &ioStatusBlock, NULL,
FILE_ATTRIBUTE_NORMAL,
0,
FILE_OVERWRITE_IF,
FILE_SYNCHRONOUS_IO_NONALERT,
NULL, 0); Read from or write to a file
You can now call the
ZwReadFile function or the
ZwWriteFile function. When you have finished modifying the file, close the handle by using the
ZwClose function.
The following code example illustrates how to write to a file.
#define BUFFER_SIZE 30
CHAR buffer[BUFFER_SIZE];
size_t cb;
if(NT_SUCCESS(ntstatus)) {
ntstatus = RtlStringCbPrintfA(buffer, sizeof(buffer), "This is %d test\r\n", 0x0);
if(NT_SUCCESS(ntstatus)) {
ntstatus = RtlStringCbLengthA(buffer, sizeof(buffer), &cb);
if(NT_SUCCESS(ntstatus)) {
ntstatus = ZwWriteFile(handle, NULL, NULL, NULL, &ioStatusBlock,
buffer, cb, NULL, NULL);
}
}
ZwClose(handle);
}The following code example illustrates how to read from a file.
LARGE_INTEGER byteOffset;
ntstatus = ZwCreateFile(&handle,
GENERIC_READ,
&objAttr, &ioStatusBlock,
NULL,
FILE_ATTRIBUTE_NORMAL,
0,
FILE_OPEN,
FILE_SYNCHRONOUS_IO_NONALERT,
NULL, 0);
if(NT_SUCCESS(ntstatus)) {
byteOffset.LowPart = byteOffset.HighPart = 0;
ntstatus = ZwReadFile(handle, NULL, NULL, NULL, &ioStatusBlock,
buffer, BUFFER_SIZE, &byteOffset, NULL);
if(NT_SUCCESS(ntstatus)) {
buffer[BUFFER_SIZE-1] = '\0';
DbgPrint("%s\n", buffer);
}
ZwClose(handle);
}For more information about how to use files in a driver, see the "Using Files In A Driver" section in the Windows Driver Development Kit.
For more information about the Windows Driver Development Kit, visit the following Microsoft Web site: