The ioctl interface is the catchall of I/O operations (Stevens, 1992). Any operation that cannot be expressed using d_read or d_write (that is, any operation that’s not a data transfer) is supported by d_ioctl.^[3] For example, the CD-ROM driver’s d_ioctl function performs 29 distinct operations, such as ejecting the CD, starting audio playback, stopping audio playback, muting the audio, and so on.

The function prototype for d_ioctl is defined in the <sys/conf.h> header as follows:

typedef int d_ioctl_t(struct cdev *dev, u_long cmd, caddr_t data,
                      int fflag, struct thread *td);

Here, cmd is an ioctl command passed from user space. ioctl commands are driver-defined numeric constants that identify the different I/O operations that a d_ioctl function can perform. Generally, you’d use the cmd argument in a switch statement to set up a code block for each I/O operation. Any arguments required for an I/O operation are passed through data.

Here is an example d_ioctl function:

static int
echo_ioctl(struct cdev *dev, u_long cmd, caddr_t data, int fflag,
    struct thread *td)
{
        int error = 0;

        switch (cmd) {
      case ECHO_CLEAR_BUFFER:
                memset(echo_message->buffer, '',
                    echo_message->buffer_size);
                echo_message->length = 0;
                uprintf("Buffer cleared.
");
                break;
      case ECHO_SET_BUFFER_SIZE:
                error = echo_set_buffer_size(*(int *)data);
                if (error == 0)
                        uprintf("Buffer resized.
");
                break;
      default:
                error = ENOTTY;
                break;
        }

        return (error);
}

Notice how the cmd argument is the expression for the switch statement. The constants ECHO_CLEAR_BUFFER and ECHO_SET_BUFFER_SIZE are (obviously) the ioctl commands. All ioctl commands are defined using one of four macros. I’ll discuss these macros in the following section.

Additionally, notice how the data argument is cast—as an integer pointer—before it is dereferenced. This is because data is fundamentally a “pointer to void.”

Finally, according to the POSIX standard, when an inappropriate ioctl command is received, the error code ENOTTY should be returned (Corbet et al., 2005). Hence, the default block sets error to ENOTTY.

Now that you’ve examined the structure of a d_ioctl function, I’ll explain how to define an ioctl command.