Module nix::sys::ioctl [−] [src]

Provide helpers for making ioctl system calls

Overview of IOCTLs

The ioctl system call is a widely support system call on *nix systems providing access to functions and data that do not fit nicely into the standard read and write operations on a file itself. It is common to see ioctls used for the following purposes:

Provide read/write access to out-of-band data related to a device such as configuration (for instance, setting serial port options)
Provide a mechanism for performing full-duplex data transfers (for instance, xfer on SPI devices).
Provide access to control functions on a device (for example, on Linux you can send commands like pause, resume, and eject to the CDROM device.
Do whatever else the device driver creator thought made most sense.

Ioctls are synchronous system calls and are similar to read and write calls in that regard.

The prototype for the ioctl system call in libc is as follows:

int ioctl(int fd, unsigned long request, ...);

Typically, an ioctl takes 3 parameters as arguments:

An open file descriptor, fd.
An device-dependennt request code or operation. This request code is referred to as op in this module.
Either a pointer to a location in memory or an integer. This number of pointer may either be used by the kernel or written to by the kernel depending on how the operation is documented to work.

The op request code is essentially an arbitrary integer having a device-driver specific meaning. Over time, it proved difficult for various driver implementors to use this field sanely, so a convention with macros was introduced to the Linux Kernel that is used by most newer drivers. See https://github.com/torvalds/linux/blob/master/Documentation/ioctl/ioctl-number.txt for additional details. The macros exposed by the kernel for consumers are implemented in this module and may be used to instead of calls like _IOC, _IO, _IOR, and _IOW.

Interface Overview

This ioctl module seeks to tame the ioctl beast by providing a set of safer (although not safe) functions implementing the most common ioctl access patterns.

The most common access patterns for ioctls are as follows:

read: A pointer is provided to the kernel which is populated with a value containing the "result" of the operation. The result may be an integer or structure. The kernel may also read values from the provided pointer (usually a structure).
write: A pointer is provided to the kernel containing values that the kernel will read in order to perform the operation.
execute: The operation is passed to the kernel but no additional pointer is passed. The operation is enough and it either succeeds or results in an error.

Where appropriate, versions of these interface function are provided taking either refernces or pointers. The pointer versions are necessary for cases (notably slices) where a reference cannot be generically cast to a pointer.

Structs

IoctlDirFlags

Constants

IOC_NONE	Indicates that the ioctl data pointer is not used
IOC_READ	Indicates tha the ioctl data pointer contains data that will be populated by the operating system to be consumed by userspace
IOC_WRITE	Indicates that the ioctl data pointer contains data that will be consumed by the operating system

Functions

execute	Ioctl call for which no data pointer is provided to the kernel. That is, the kernel has sufficient information about what to do based on the op alone.
op	Build an ioctl op with the provide parameters. This is a helper function for IOCTLs in the Linux kernel using the newer conventions for IOCTLs operations. Many ioctls do not use this newer convention and the constants for those should just be used as-is.
op_none	Build an op indicating that the data pointer is not used. That is, the command itself is sufficient.
op_read	Build an op indicating that the data pointer will be populated with data from the kernel
op_read_write	Build an op indicating that the data pointer both contains data to be consumed by the kernel and contains fields that will be populated by the kernel.
op_write	Build an op indicating that the data pointer contains data to be consumed by the kernel (and not written to).
read	Ioctl call that is expected to return a result but which does not take any additional arguments on the input side
read_into	Ioctl where the result from the kernel will be written to the provided reference
read_into_ptr	Ioctl where the result from the kernel will be written to the provided pointer
write	Ioctl call that sends a value to the kernel but does not return anything (pure side effect).
write_ptr	Ioctl call that sends a value to the kernel but does not return anything (pure side effect).

Type Definitions

ioctl_op_t