{"id":283,"date":"2008-06-07T02:00:21","date_gmt":"2008-06-07T02:00:21","guid":{"rendered":"https:\/\/driverentry.com.br\/en\/2008\/06\/07\/creating-and-using-ioctls\/"},"modified":"2026-07-27T20:44:44","modified_gmt":"2026-07-27T20:44:44","slug":"creating-and-using-ioctls","status":"publish","type":"post","link":"https:\/\/driverentry.com.br\/en\/2008\/06\/07\/creating-and-using-ioctls\/","title":{"rendered":"Creating and Using IOCTLs"},"content":{"rendered":"
\"\"<\/a><\/div>\n

Last week I had received the following question from a reader:<\/p>\n

\n

“Is it possible for my application to send a customized IOCTL (made by myself) to a driver, and that driver being able to recognize it with no problems?”<\/em><\/strong><\/p>\n<\/blockquote>\n

The short-term answer for this question is: “Yes, and good luck!”<\/em>. However, what is the fun a blog has if we can not talk more about this subject and even give a simple example? You’re assumed by this you’re already aware of some basic concepts, such as compiling, installing and testing drivers; but, if you have not known this yet, do not worry, just read this post<\/a>.<\/p>\n

The driver that used to calculate<\/h3>\n

Let’s create a sample driver that uses the same idea my friend Heldai had already used to illustrate IOCTLs use when I was still learning how to make blue screens. At today’s example, we are making a driver that adds two numbers contained into a structure that will be received via an IOCTL.<\/p>\n

With no more yada yada, I think we can start by defining the structure. Like the kindergarten teacher had taught us, we are just creating a header file that is included by both, the application project and the driver project. This header file should not include any other specific one from User Mode nor Kernel Mode. That means, it cannot include files like Windows.h<\/em> nor Ntddk.h<\/em>. All this is aleady done, tested and able to be built in a project available for downloading at the end of the post.<\/p>\n

\n
typedef<\/span> struct<\/span> _KERNEL_MATH_REQUEST<\/pre>\n
{<\/pre>\n
    \/\/-f--> I can define this structure in any way I<\/span><\/pre>\n
    \/\/      want to.<\/span><\/pre>\n
    \/\/      These are the two numbers to be added to it.<\/span><\/pre>\n
    ULONG   x;<\/pre>\n
    ULONG   y;<\/pre>\n
 <\/pre>\n
} KERNEL_MATH_REQUEST, *PKERNEL_MATH_REQUEST;<\/pre>\n
 <\/pre>\n
 <\/pre>\n
typedef<\/span> struct<\/span> _KERNEL_MATH_RESPONSE<\/pre>\n
{<\/pre>\n
    \/\/-f--> To the newbies: I know it's possible to be done it using<\/span><\/pre>\n
    \/\/      just one structure. But I'm only doing in that<\/span><\/pre>\n
    \/\/      way for a better illustration.<\/span><\/pre>\n
    ULONG   r;<\/pre>\n
 <\/pre>\n
} KERNEL_MATH_RESPONSE, *PKERNEL_MATH_RESPONSE;<\/pre>\n<\/div>\n
Creating the IOCTL<\/h3>\n
IOCTL is more than just a number to identify the desired operation. It consists of a bit mask interpreted by Windows. This mask is defined as it is shown below. You can get more details at this macro on this link<\/a>.<\/p>\n
\"\"<\/div>\n
To define an IOCTL, we use the CTL_CODE macro which has its parameters shown below:<\/p>\n
\n
#define<\/span> IOCTL_Device_Function CTL_CODE(DeviceType, Function, Method, Access)<\/pre>\n<\/div>\n
Let’s define our IOCTL, as it is shown below:<\/p>\n
\n
\/\/-f--> Here, we define IOCTL for our driver.<\/span><\/pre>\n
#define<\/span> IOCTL_ADD_THESE_TWO_NUMBERS \\<\/pre>\n
    CTL_CODE(FILE_DEVICE_UNKNOWN, 0x800<\/span>, METHOD_BUFFERED, FILE_ANY_ACCESS)<\/pre>\n
 <\/pre>\n
\/\/-f--> Although this driver haa the word \"Sum\" as part of its name,<\/span><\/pre>\n
\/\/      I've decided to put an IOCTL for subtraction, just as an example.<\/span><\/pre>\n
#define<\/span> IOCTL_SUBTRACT_THESE_TWO_NUMBERS \\<\/pre>\n
    CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801<\/span>, METHOD_BUFFERED, FILE_ANY_ACCESS)<\/pre>\n<\/div>\n
Now, let’s take a look at every used parameter and talk a litle about it.<\/p>\n
FILE_DEVICE_UNKNOWN<\/strong> – If you take a look at the DriverEntry<\/em> routine, you can notice this is the same device type used at the call for the IoCreateDevice()<\/a> routine.<\/p>\n
\n
\/****<\/span><\/pre>\n
***     DriverEntry<\/span><\/pre>\n
**<\/span><\/pre>\n
**      That's the driver entry point.<\/span><\/pre>\n
**      \"A knife among the teeth and some blood in the eyes\".<\/span><\/pre>\n
*\/<\/span><\/pre>\n
extern<\/span> \"C\"<\/span> NTSTATUS<\/pre>\n
DriverEntry(__in PDRIVER_OBJECT     pDriverObj,<\/pre>\n
            __in PUNICODE_STRING    pusRegistryPath)<\/pre>\n
{<\/pre>\n
    UNICODE_STRING  usDeviceName = RTL_CONSTANT_STRING(L\"\\\\Device\\\\KernelSum\"<\/span>);<\/pre>\n
    UNICODE_STRING  usSymbolicLink = RTL_CONSTANT_STRING(L\"\\\\DosDevices\\\\KernelSum\"<\/span>);<\/pre>\n
    NTSTATUS        nts;<\/pre>\n
    PDEVICE_OBJECT  pDeviceObj;<\/pre>\n
 <\/pre>\n
    \/\/-f--> Setting the unload routine to allow the <\/span><\/pre>\n
    \/\/      driver to be dynamincaly unloaded.<\/span><\/pre>\n
    pDriverObj->DriverUnload = OnDriverUnload;<\/pre>\n
 <\/pre>\n
    \/\/-f--> The Open, Cleanup e Close routines behave in the same way.<\/span><\/pre>\n
    \/\/      So, through the minimum effort law use, they will be the same one.<\/span><\/pre>\n
    \/\/      Besides this one, we must handle the DeviceControl which is<\/span><\/pre>\n
    \/\/      responsible for dealing with the received IOCTLs.<\/span><\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CREATE] =<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CLEANUP] =<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CLOSE] = OnCreateCleanupClose;<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_DEVICE_CONTROL] = OnDeviceIoControl;<\/pre>\n
 <\/pre>\n
    \/\/-f--> Here we are creating the driver control device. Notice that we used<\/span><\/pre>\n
    \/\/      FILE_DEVICE_UNKNOWN as the device type. This same one is used<\/span><\/pre>\n
    \/\/      at the CTL_CODE macro. See: IoCtl.h<\/span><\/pre>\n
    nts = IoCreateDevice(pDriverObj,<\/pre>\n
                         0<\/span>,<\/pre>\n
                         &usDeviceName,<\/pre>\n
                         FILE_DEVICE_UNKNOWN,<\/pre>\n
                         0<\/span>,<\/pre>\n
                         FALSE,<\/pre>\n
                         &pDeviceObj);<\/pre>\n
 <\/pre>\n
    \/\/-f--> Is everything fine so far? OK...<\/span><\/pre>\n
    if<\/span> (!NT_SUCCESS(nts))<\/pre>\n
    {<\/pre>\n
        ASSERT(FALSE);<\/pre>\n
        return<\/span> nts;<\/pre>\n
    }<\/pre>\n
 <\/pre>\n
    \/\/-f--> Here we are creating a symbolic link so that, the application<\/span><\/pre>\n
    \/\/      can get a handle for the control device.<\/span><\/pre>\n
    nts = IoCreateSymbolicLink(&usSymbolicLink,<\/pre>\n
                               &usDeviceName);<\/pre>\n
 <\/pre>\n
    \/\/-f--> Is it all right?<\/span><\/pre>\n
    if<\/span> (!NT_SUCCESS(nts))<\/pre>\n
    {<\/pre>\n
        \/\/-f--> Oops... I think my pant is sort of wet...<\/span><\/pre>\n
        IoDeleteDevice(pDeviceObj);<\/pre>\n
 <\/pre>\n
        ASSERT(FALSE);<\/pre>\n
        return<\/span> nts;<\/pre>\n
    }<\/pre>\n
 <\/pre>\n
    \/\/-f--> Great, that is it!<\/span><\/pre>\n
    return<\/span> STATUS_SUCCESS;<\/pre>\n
}<\/pre>\n<\/div>\n
The secong CTL_CODE parameter Function<\/em>, receives a 0x800 <\/strong>number, since numbers below this one are reserved for Microsoft.<\/p>\n
METHOD_BUFFERED<\/strong> – indicates to the I\/O Manager the driver will receive an input buffer copy passed to DeviceIoControl<\/em> function. I\/O Manager allocates a system buffer, which means in kernel space, that it is big enough to fit both the input and output data. When the DeviceIoControl <\/em>function is called, the I\/O Manager allocates the system buffer and copies the input buffer inside it. The driver receives the IRP<\/a>, gets the input parameters, processes them and writes the output data at the same system buffer. When the IRP is completed, the I\/O Manager copies the output data from the system buffer to the output buffer provided by the application.<\/p>\n
Besides the Buffered <\/strong>method, there are still the Direct I\/O<\/strong> and Neither<\/strong> methods. For our currently example, the Buffered method is great. I am owing a post to you that talks about how to use every one of the other methods.<\/p>\n
FILE_ANY_ACCESS<\/strong> – That indicates the handle doesn’t need to be opened with any special kind of access to allow the IOCTL to be excetuted.<\/p>\n
From the application to the driver<\/h3>\n
To send an IOCTL to the driver, you need to use the DeviceIoControl <\/em>function as it is shown at the example below. This is a very simple program that shows its use.<\/p>\n
\n
\/****<\/span><\/pre>\n
***     main<\/span><\/pre>\n
**<\/span><\/pre>\n
**      I hope all of you have already known that this is the entry<\/span><\/pre>\n
**      point of the application. Otherwise you might be<\/span><\/pre>\n
**      precipitated on reading a Windows driver blog.<\/span><\/pre>\n
**<\/span><\/pre>\n
*\/<\/span><\/pre>\n
int<\/span> __cdecl<\/span> main(int<\/span> argc, CHAR* argv[])<\/pre>\n
{<\/pre>\n
    HANDLE                  hDevice;<\/pre>\n
    DWORD                   dwError = ERROR_SUCCESS,<\/pre>\n
                            dwBytes;<\/pre>\n
    KERNEL_MATH_REQUEST     Request;<\/pre>\n
    KERNEL_MATH_RESPONSE    Response;<\/pre>\n
 <\/pre>\n
    printf(\"Opening \\\\\\\\.\\\\KernelSum device...\\n\"<\/span>);<\/pre>\n
 <\/pre>\n
    \/\/-f--> Here, we are opening a handle for our device, which<\/span><\/pre>\n
    \/\/      has been created by the driver. Remember that our<\/span><\/pre>\n
    \/\/      sample driver must be installed and started<\/span><\/pre>\n
    \/\/      so that the call below can work properly.<\/span><\/pre>\n
    hDevice = CreateFile(\"\\\\\\\\.\\\\KernelSum\"<\/span>,<\/pre>\n
                         GENERIC_ALL,<\/pre>\n
                         0<\/span>,<\/pre>\n
                         NULL,<\/pre>\n
                         OPEN_EXISTING,<\/pre>\n
                         0<\/span>,<\/pre>\n
                         NULL);<\/pre>\n
 <\/pre>\n
    \/\/-f--> It Verifies whether the open was opened.<\/span><\/pre>\n
    if<\/span> (hDevice == INVALID_HANDLE_VALUE)<\/pre>\n
    {<\/pre>\n
        printf(\"Error #%d opening device...\\n\"<\/span>,<\/pre>\n
               (dwError = GetLastError()));<\/pre>\n
        return<\/span> dwError;<\/pre>\n
    }<\/pre>\n
 <\/pre>\n
    \/\/-f--> I got lazy and I put the values fixed at the sample code.<\/span><\/pre>\n
    Request.x = 3<\/span>;<\/pre>\n
    Request.y = 2<\/span>;<\/pre>\n
 <\/pre>\n
    printf(\"Calling DeviceIoControl...\\n\"<\/span>);<\/pre>\n
 <\/pre>\n
    \/\/-f--> It sends the IOCTL<\/span><\/pre>\n
    if<\/span> (!DeviceIoControl(hDevice,<\/pre>\n
                         IOCTL_SOMA_QUE_EU_TO_MANDANDO,<\/pre>\n
                         &Request,<\/pre>\n
                         sizeof<\/span>(KERNEL_MATH_REQUEST),<\/pre>\n
                         &Response,<\/pre>\n
                         sizeof<\/span>(KERNEL_MATH_RESPONSE),<\/pre>\n
                         &dwBytes,<\/pre>\n
                         NULL))<\/pre>\n
    {<\/pre>\n
        \/\/-f--> Oops...<\/span><\/pre>\n
        printf(\"Error #%d calling DeviceIoControl...\\n\"<\/span>,<\/pre>\n
               (dwError = GetLastError()));<\/pre>\n
 <\/pre>\n
        CloseHandle(hDevice);<\/pre>\n
        return<\/span> dwError;<\/pre>\n
    }<\/pre>\n
 <\/pre>\n
    \/\/-f--> Show the results.<\/span><\/pre>\n
    printf(\"%d + %d = %d\\n\"<\/span>,<\/pre>\n
           Request.x,<\/pre>\n
           Request.y,<\/pre>\n
           Response.r);<\/pre>\n
 <\/pre>\n
    printf(\"Closing device...\\n\"<\/span>);<\/pre>\n
    \/\/-f--> Close the handle.<\/span><\/pre>\n
    CloseHandle(hDevice);<\/pre>\n
    return<\/span> 0<\/span>;<\/pre>\n
}<\/pre>\n<\/div>\n
Note that there is no strong relation between the IOCTL and the used input or output buffers, but we must be attentive to the buffer sizes when the driver makes use of them. Nobody wants to corrupt the kernel heap allocations or throwing off exceptions in kernel mode, do they?<\/p>\n
You can see how data are processed by the driver when receiving the IRP_MJ_DEVICE_CONTROL<\/a>. Reading the comments is a good idea; they are a part of the explanation. Wow, that sentence representing my laziness got nice!! Basically, it is the same to say: “Oh my! Seriously, besides preparing this example, you still want me to duplicate all the comment information? I don’t think so!”
\n <\/em><\/p>\n
\n
\/****<\/span><\/pre>\n
***     OnDeviceIoControl<\/span><\/pre>\n
**<\/span><\/pre>\n
**      This routine is called when an application<\/span><\/pre>\n
**      sends an IOCTL to our driver via DeviceIoControl.<\/span><\/pre>\n
*\/<\/span><\/pre>\n
NTSTATUS<\/pre>\n
OnDeviceIoControl(__in PDEVICE_OBJECT   pDeviceObj,<\/pre>\n
                  __in PIRP             pIrp)<\/pre>\n
{<\/pre>\n
    PIO_STACK_LOCATION      pStack;<\/pre>\n
    NTSTATUS                nts;<\/pre>\n
    PKERNEL_MATH_REQUEST    pRequest;<\/pre>\n
    PKERNEL_MATH_RESPONSE   pResponse;<\/pre>\n
 <\/pre>\n
    \/\/-f--> We get the parameters referring to our driver.<\/span><\/pre>\n
    pStack = IoGetCurrentIrpStackLocation(pIrp);<\/pre>\n
 <\/pre>\n
    switch<\/span>(pStack->Parameters.DeviceIoControl.IoControlCode)<\/pre>\n
    {<\/pre>\n
    case<\/span> IOCTL_SUM_THIS_TWO_NUMBERS:<\/pre>\n
    case<\/span> IOCTL_SUBTRACT_THIS_TWO_NUMBERS:<\/pre>\n
 <\/pre>\n
        \/\/-f--> Let's do the checking about the input<\/span><\/pre>\n
        \/\/      and output buffer sizes.<\/span><\/pre>\n
        if<\/span> (pStack->Parameters.DeviceIoControl.InputBufferLength !=<\/pre>\n
            sizeof<\/span>(KERNEL_MATH_REQUEST) ||<\/pre>\n
            pStack->Parameters.DeviceIoControl.OutputBufferLength !=<\/pre>\n
            sizeof<\/span>(KERNEL_MATH_RESPONSE))<\/pre>\n
        {<\/pre>\n
            nts = STATUS_INVALID_BUFFER_SIZE;<\/pre>\n
            pIrp->IoStatus.Information = 0<\/span>;<\/pre>\n
            break<\/span>;<\/pre>\n
        }<\/pre>\n
 <\/pre>\n
        \/\/-f--> The safe then sorry.<\/span><\/pre>\n
        ASSERT(pIrp->AssociatedIrp.SystemBuffer != NULL);<\/pre>\n
 <\/pre>\n
        \/\/-f--> Making use of METHOD_BUFFERED, the system allocates only one<\/span><\/pre>\n
        \/\/      buffer to transport either the input and output data. The buffer<\/span><\/pre>\n
        \/\/      size is the same as the biggest one of them. Thus, be careful having read<\/span><\/pre>\n
        \/\/      all the input data before starting to write the output to the buffer.<\/span><\/pre>\n
        pRequest = (PKERNEL_MATH_REQUEST)pIrp->AssociatedIrp.SystemBuffer;<\/pre>\n
        pResponse = (PKERNEL_MATH_RESPONSE)pIrp->AssociatedIrp.SystemBuffer;<\/pre>\n
 <\/pre>\n
        \/\/-f--> It does the math and indicates its success.<\/span><\/pre>\n
        if<\/span> (pStack->Parameters.DeviceIoControl.IoControlCode == IOCTL_SOMA_QUE_EU_TO_MANDANDO)<\/pre>\n
            pResponse->r = pRequest->x + pRequest->y;<\/pre>\n
        else<\/span><\/pre>\n
            pResponse->r = pRequest->x - pRequest->y;<\/pre>\n
 <\/pre>\n
        nts = STATUS_SUCCESS;<\/pre>\n
 <\/pre>\n
        \/\/-f--> It informs the I\/O Manager how many bytes have to be transferred <\/span><\/pre>\n
        \/\/      back to the application.<\/span><\/pre>\n
        pIrp->IoStatus.Information = sizeof<\/span>(KERNEL_MATH_RESPONSE);<\/pre>\n
        break<\/span>;<\/pre>\n
 <\/pre>\n
    default<\/span>:<\/pre>\n
        \/\/-f--> Oops... We have received an unknown IOCTL.<\/span><\/pre>\n
        nts = STATUS_INVALID_DEVICE_REQUEST;<\/pre>\n
        pIrp->IoStatus.Information = 0<\/span>;<\/pre>\n
    }<\/pre>\n
 <\/pre>\n
    \/\/-f--> It copies the final IRP status and completes it.<\/span><\/pre>\n
    pIrp->IoStatus.Status = nts;<\/pre>\n
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);<\/pre>\n
 <\/pre>\n
    \/\/-f--> NOTE: Remember that we cannot touch the IRP after completing it;<\/span><\/pre>\n
    \/\/      so, don't be the \"smart ass\" changing the line below to return the<\/span><\/pre>\n
    \/\/      IRP status taking the value from the IRP. (return pIrp->IoStatus.Status;)<\/span><\/pre>\n
    return<\/span> nts;<\/pre>\n
}<\/pre>\n<\/div>\n
Building in this or in that way<\/h3>\n
The sample project available for downloading at the end of this post can be compiled in two ways. One way is using the standard way to compile drivers<\/a> offered by WDK. Briefly you go through “Start->All Programs->Windows Driver Kits->WDK 6000->Build Environments->Windows XP->Windows XP x86 Checked Build Environment”<\/em>. This should open a console prompt, as it is shown below. Then, just go to the directory where you download these Internet sources and to the project root directory. There you need to call Build.exe<\/strong> and it is done.<\/p>\n
\"\"<\/div>\n
The other way to compile the entire project allows you to build it using Visual Studio 2008, which has been the environment I have used to compose this project. However, to build the project by using the IDE you have to use DDKBUILD<\/a>, as it is shown in this post<\/a> referring to  it.<\/p>\n
While I was out, I had received another reader’s question who wanted to know how to read or write into the registry using a driver. In the next post, I’ll talk about that and other details regarding to the registry from a driver’s point of view.<\/p>\n
CYA!<\/p>\n
KernelSum.zip<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Last week I had received the following question from a reader: “Is it possible for my application to send a customized IOCTL (made by myself) to a driver, and that driver being able to recognize it with no problems?” The short-term answer for this question is: “Yes, and good luck!”. However, what is the fun […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":""},"categories":[1],"tags":[],"class_list":["post-283","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/283","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/comments?post=283"}],"version-history":[{"count":2,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/283\/revisions"}],"predecessor-version":[{"id":295,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/283\/revisions\/295"}],"wp:attachment":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/media?parent=283"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/categories?post=283"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/tags?post=283"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}