← Previous Lecture  |  Next Lecture →

What You Will Learn

Prerequisites

Step 1: Writing the User-Space IOCTL Application

The user-space side of any Linux ioctl system call interaction is straightforward: open the device file, then call ioctl() with the command and an argument pointer, exactly matching the header shared with the kernel driver.

/* epdrv_test.c - user-space test application */
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
#include <errno.h>
#include "epdrv_ioctl.h"

int main(void)
{
    int fd, val, ret;

    fd = open("/dev/epdrv0", O_RDWR);
    if (fd < 0) {
        perror("open");
        exit(EXIT_FAILURE);
    }

    val = 42;
    ret = ioctl(fd, EPDRV_SET_VALUE, &val);
    if (ret < 0) {
        perror("ioctl SET_VALUE");
        close(fd);
        exit(EXIT_FAILURE);
    }
    printf("Set value to %d\n", val);

    val = 0;
    ret = ioctl(fd, EPDRV_GET_VALUE, &val);
    if (ret < 0) {
        perror("ioctl GET_VALUE");
        close(fd);
        exit(EXIT_FAILURE);
    }
    printf("Read back value: %d\n", val);

    ret = ioctl(fd, EPDRV_RESET);
    if (ret < 0) {
        perror("ioctl RESET");
        close(fd);
        exit(EXIT_FAILURE);
    }
    printf("Driver value reset\n");

    close(fd);
    return 0;
}

Notice that EPDRV_SET_VALUE and EPDRV_GET_VALUE pass the address of a local variable, while EPDRV_RESET is called with no third argument at all — this matches exactly how each command was defined with _IOW, _IOR, and _IO in the shared header.

Step 2: Building and Loading the Driver

Build the kernel module using a standard out-of-tree Makefile, then load it and confirm the device node was created.

obj-m += epdrv.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean

$ make
$ sudo insmod epdrv.ko
$ ls -l /dev/epdrv0
crw------- 1 root root 240, 0 Jul 11 10:00 /dev/epdrv0

Step 3: Building and Running the Test Application

$ gcc -o epdrv_test epdrv_test.c
$ sudo ./epdrv_test
Set value to 42
Read back value: 42
Driver value reset

Debugging IOCTL Failures

Symptom	Likely Cause	Fix
ioctl returns -1, errno = ENOTTY	Command number mismatch between app and driver	Confirm both sides include the same shared header
ioctl returns -1, errno = EFAULT	Invalid or NULL pointer passed as arg	Pass the address of a real variable for _IOR/_IOW/_IOWR commands
open() fails with “No such device”	Module not loaded or device node missing	Check dmesg and lsmod, confirm insmod succeeded
Permission denied opening device	Device node permissions default to root only	Run test with sudo, or adjust udev rules for the device class

Best Practices for Testing IOCTL Drivers

Security Considerations

Even in a simple test driver like this one, remember that any process with permission to open the device node can issue any of its defined ioctl commands. In production drivers, consider whether certain commands should be restricted with capability checks (for example via capable(CAP_SYS_ADMIN)) before performing sensitive operations.

Summary and Key Takeaways

Conclusion

With this lesson, you have completed a full, modern, kernel 6.x-compatible walkthrough of the Linux ioctl system call: why it exists, how to implement it in a character driver, and how to build and test a matching user-space application. These same patterns apply directly to real embedded systems work, whether you are configuring a sensor, a serial port, or a custom hardware accelerator. Continue exploring more lessons in this free Linux kernel development course to build on these foundations.

Frequently Asked Questions

← Previous Lecture  |  Next Lecture →