Skip to content

Commit cae5841

Browse files
bagasmeJonathan Corbet
authored andcommitted
Documentation: ioctl-number: Don't repeat macro names
Don't repeat mentioning macro names (_IO, _IOW, _IOR, and _IOWR) to keep the wording effective. Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250715024258.16882-3-bagasdotme@gmail.com
1 parent 67ffcab commit cae5841

1 file changed

Lines changed: 12 additions & 10 deletions

File tree

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

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,22 +25,24 @@ be _IOW, although the kernel would actually read data from user space;
2525
a GET_FOO ioctl would be _IOR, although the kernel would actually write
2626
data to user space.
2727

28-
The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
29-
or number from the table below. Because of the large number of drivers,
30-
many drivers share a partial letter with other drivers.
28+
The first argument to the macros is an identifying letter or number from
29+
the table below. Because of the large number of drivers, many drivers
30+
share a partial letter with other drivers.
3131

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

38-
The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
39-
to distinguish ioctls from each other. The third argument to _IOW,
40-
_IOR, or _IOWR is the type of the data going into the kernel or coming
41-
out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use
42-
sizeof(arg) as the third argument as this results in your ioctl thinking
43-
it passes an argument of type size_t.
38+
The second argument is a sequence number to distinguish ioctls from each
39+
other. The third argument (not applicable to _IO) is the type of the data
40+
going into the kernel or coming out of the kernel (e.g. 'int' or
41+
'struct foo').
42+
43+
.. note::
44+
Do NOT use sizeof(arg) as the third argument as this results in your
45+
ioctl thinking it passes an argument of type size_t.
4446

4547
Some devices use their major number as the identifier; this is OK, as
4648
long as it is unique. Some devices are irregular and don't follow any
@@ -53,7 +55,7 @@ Following this convention is good because:
5355
error rather than some unexpected behaviour.
5456

5557
(2) The 'strace' build procedure automatically finds ioctl numbers
56-
defined with _IO, _IOW, _IOR, or _IOWR.
58+
defined with the macros.
5759

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

0 commit comments

Comments
 (0)