What You Will Learn

• Why ioctl() exists alongside read()/write()
• The _IO, _IOW, _IOR, _IOWR macros and magic numbers
• Writing a shared ioctl header for kernel and user space
• Implementing .unlocked_ioctl on kernel 6.x
• copy_to_user()/copy_from_user() inside ioctl handlers
• 32-bit compatibility with .compat_ioctl

Prerequisites

• struct cdev registration and file_operations basics
• copy_to_user()/copy_from_user() and put_user()/get_user()
• A working kernel 6.x build environment
• Comfort compiling and loading kernel modules with insmod/rmmod

Why Character Drivers Need ioctl()

A typical Linux system exposes a few hundred system calls in total, but only a small number of them are file-operation calls like read(), write(), and lseek(). Real hardware frequently needs commands that do not fit this data-streaming model — resetting a device, querying a size, changing a mode, or renaming an internal partition. The ioctl system call linux device driver mechanism exists exactly for this: it lets a driver author define an open-ended set of custom commands without adding new system calls to the kernel.

If a driver does not implement ioctl() at all, the kernel returns -ENOTTY to any user-space ioctl() call against that device, which you will use later as your own “unknown command” fallback.

The Four ioctl Command-Building Macros

Every ioctl command must be encoded into a single unsigned integer that is unique across the system, so the kernel can tell devices and commands apart safely. Linux provides four helper macros, defined in linux/ioctl.h, to build this integer:

Each macro packs three pieces of information: an 8-bit magic number identifying your driver, an 8-bit sequence number identifying the specific command, and (for W/R/WR variants) the C type used to compute the transfer size. The official list of magic numbers already claimed by in-tree drivers lives in the kernel source under Documentation/userspace-api/ioctl/ioctl-number.rst — always check it before picking your own magic number, to avoid colliding with an existing driver.

Step 1: A Shared ioctl Header

Best practice is to define your commands in one header file that both the kernel module and any user-space test program include, so the numbers can never drift out of sync. Here is an original header for this lecture’s demo driver:

Save this file once and place a copy next to your kernel module source and next to your user-space test program, or use a symlink so both sides always agree on the exact same numbers.

Step 2: An Original ioctl-Capable Driver

Here is a fresh, kernel-6.x-clean driver called ep_ioctl_demo. It keeps one internal integer value in the driver and exposes four commands to reset it, set it, read it back, and atomically swap it — all without needing read() or write() at all.

Kernel 6.x note: the old .ioctl field with the Big Kernel Lock disappeared long ago. Every modern driver must use .unlocked_ioctl, and provide its own locking (here, a plain mutex) around any shared state instead of relying on a kernel-wide lock.

Step 3: Building and Loading

Step 4: A Complete User-Space Test Program

Notice that EP_SWAP_VALUE uses the same buffer for both directions: the user writes 100 in, and the driver overwrites that same memory with the old value 42 before returning — a classic use of _IOWR.

unlocked_ioctl vs the Legacy .ioctl Field

Common Mistakes and Troubleshooting

Best Practices

• Keep one shared header for command numbers between kernel and user space
• Pick a magic number not already listed in the kernel’s ioctl-number documentation
• Validate cmd with a switch statement and always default to -ENOTTY
• Use copy_to_user()/copy_from_user() for structs, put_user()/get_user() for single values
• Prefer ioctl() only for control operations; keep bulk data transfer in read()/write()

Performance Considerations

ioctl() calls are control-plane operations, not data-plane ones, so they are typically infrequent compared to read()/write() traffic. Keep the handler itself short: avoid long-held locks, avoid sleeping unnecessarily, and never perform large data copies through ioctl() when a proper read()/write() or mmap() interface would be more appropriate for high-throughput data.

Security Considerations

ioctl() is a common attack surface because it accepts an arbitrary unsigned long arg that user space fully controls. Never trust arg as a pointer without copy_from_user()/copy_to_user(), never trust a size value from user space without bounds-checking it, and consider whether a given command should be restricted with capable(CAP_SYS_ADMIN) or similar checks if it can affect other users or system state.

Summary / Key Takeaways

• ioctl() lets a driver define custom commands beyond read/write/llseek/poll
• _IO/_IOW/_IOR/_IOWR encode direction and data type into one command number
• A shared header keeps kernel and user-space command numbers in sync
• .unlocked_ioctl replaces the removed legacy .ioctl field on kernel 6.x
• Always validate cmd, copy data safely, and lock shared state explicitly

Conclusion

You have now completed the core file_operations methods covered in this free linux device drivers course: open, release, read, write, llseek, poll, select, and finally ioctl(). The ioctl system call linux device driver interface gives your driver an extensible command channel for anything that does not fit the streaming read()/write() model, and the shared-header, magic-number, and locking patterns shown here scale directly to real production drivers. Keep following this free linux kernel development course for the next chapter, where we move from character drivers into kernel synchronization internals.

Frequently Asked Questions