what is the meaning of this macro _IOR(MY_MACIG, 0, int)?

Question

i was going through ioctl sample programs to check how it communicates with kernel space. in program WRITE_IOCTL is used as command

#define WRITE_IOCTL _IOW(MY_MACIG, 1, int)
ioctl(fd, WRITE_IOCTL, "hello world")

I am not able to understand what is _IOW(MY_MACIG, 1, int). here is the link from where i downloaded the program. please help me. http://people.ee.ethz.ch/~arkeller/linux/multi/kernel_user_space_howto-4.html

Answer 1

As you may know, an ioctl should be unique, as explained in the Linux Device Drivers book:

The ioctl command numbers should be unique across the system in order to prevent errors caused by issuing the right command to the wrong device.Such a mismatch is not unlikely to happen, and a program might find itself trying to change the baudrate of a non-serial-port input stream, such as a FIFO or an audio device. If each ioctl number is unique, the application gets an EINVAL error rather than succeeding in doing something unintended.

Furthermore, an ioctl can require to write data to and/or read data from kernel space.

When one creates it's own driver that performs ioctls, he will need to describe all this in the ioctl command.

_IO, _IOW, _IOR, _IORW are helper macros to create a unique ioctl identifier and add the required R/W needed features (direction).

These can take the following params: magic number, the command id, and the data type that will be passed (if any)

The magic number is a unique number that will allow the driver to detect errors such as the one mentioned in the LDD book's quote.

The command id, is a way for your dirver to understand what command is needed to be called.

Last parameter (the type) will allow the kernel to understand the size to be copied.

hope this helps.

PS: you can have more details in Linux Device Drivers book (chapter 6) https://lwn.net/images/pdf/LDD3/ch06.pdf

Answer 2

From http://www.circlemud.org/jelson/software/fusd/docs/node31.html:

The Linux header file /usr/include/asm/ioctl.h defines macros that must be used to create the ioctl command number. These macros take various combinations of three arguments:

• type, an 8-bit integer selected to be specific to the device driver. type should be chosen so as not to conflict with other drivers that might be ``listening'' to the same file descriptor. (Inside the kernel, for example, the TCP and IP stacks use distinct numbers since an ioctl sent to a socket file descriptor might be examined by both stacks.)
• number, an 8-bit integer command number. Within a driver, distinct numbers should be chosen for each different kind of ioctl command that the driver services
• data_type, the name of a type used to compute how many bytes are exchanged between the client and the driver. This argument is, for example, the name of a structure.

The macros used to generate command numbers are:

• _IO(int type, int number), used for a simple ioctl that sends nothing but the type and number, and receives back nothing but an (integer) retval
• _IOR(int type, int number, data_type), used for an ioctl that reads data from the device driver. The driver will be allowed to return sizeof(data_type) bytes to the user
• _IOW(int type, int number, data_type), similar to _IOR, but used to write data to the driver
• _IORW(int type, int number, data_type), a combination of _IOR and _IOW. That is, data is both written to the driver and then read back from the driver by the client