Documentation/userspace-api/ioctl/ioctl-number.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/ioctl/ioctl-number.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/ioctl/ioctl-number.rst
Extension
.rst
Size
29168 bytes
Lines
415
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=============
Ioctl Numbers
=============

19 October 1999

Michael Elizabeth Chastain
<mec@shout.net>

If you are adding new ioctl's to the kernel, you should use the _IO
macros defined in <linux/ioctl.h>:

    ====== ===========================
    macro  parameters
    ====== ===========================
    _IO    none
    _IOW   write (read from userspace)
    _IOR   read (write to userspace)
    _IOWR  write and read
    ====== ===========================

'Write' and 'read' are from the user's point of view, just like the
system calls 'write' and 'read'.  For example, a SET_FOO ioctl would
be _IOW, although the kernel would actually read data from user space;
a GET_FOO ioctl would be _IOR, although the kernel would actually write
data to user space.

The first argument to the macros is an identifying letter or number from
the table below. Because of the large number of drivers, many drivers
share a partial letter with other drivers.

If you are writing a driver for a new device and need a letter, pick an
unused block with enough room for expansion: 32 to 256 ioctl commands
should suffice. You can register the block by patching this file and
submitting the patch through :doc:`usual patch submission process
</process/submitting-patches>`.

The second argument is a sequence number to distinguish ioctls from each
other. The third argument (not applicable to _IO) is the type of the data
going into the kernel or coming out of the kernel (e.g.  'int' or
'struct foo').

.. note::
   Do NOT use sizeof(arg) as the third argument as this results in your
   ioctl thinking it passes an argument of type size_t.

Some devices use their major number as the identifier; this is OK, as
long as it is unique.  Some devices are irregular and don't follow any
convention at all.

Following this convention is good because:

(1) Keeping the ioctl's globally unique helps error checking:
    if a program calls an ioctl on the wrong device, it will get an
    error rather than some unexpected behaviour.

(2) The 'strace' build procedure automatically finds ioctl numbers
    defined with the macros.

(3) 'strace' can decode numbers back into useful names when the
    numbers are unique.

(4) People looking for ioctls can grep for them more easily when
    this convention is used to define the ioctl numbers.

(5) When following the convention, the driver code can use generic
    code to copy the parameters between user and kernel space.

This table lists ioctls visible from userland, excluding ones from
drivers/staging/.

Annotation

Implementation Notes