Ioctl
Encyclopedia
In computing, ioctl, short for input/output
control, is a system call
for device-specific operations and other operations which cannot be expressed by regular system calls. It takes a parameter specifying a request code; the effect of a call depends completely on the request code. Request codes are often device-specific. For instance, a CD-ROM driver which can get a physical device to eject a disc would provide an ioctl request code to do that. Device-independent request codes are sometimes used to give userland access to kernel functions which are only used by core system software or still under development.
The "ioctl" system call first appeared in Version 7
of Unix
under that name. It is supported by most Unix and Unix-like
systems, including Linux
and Mac OS X
, though the available request codes differ from system to system. Microsoft Windows
provides a similar function, named "DeviceIoControl", in its Win32 API
.
resides in userspace, while the underlying facilities of the operating system, such as the network stack, reside in the kernel. Kernel code handles sensitive resources and implements the security and reliability barriers between applications; for this reason, user mode applications are prevented by the operating system from directly accessing kernel resources.
Userspace applications typically make requests of kernels by means of system call
s, whose code lies in the kernel layer. A system call usually takes the form of a "system call vector", in which the desired system call is indicated with an index number. For instance, "exit" might be system call number 1, and "write" might be system call number 4. The system call vector is used to find the desired kernel function for the request. In this way, conventional operating systems typically provide several hundred system calls to the userspace.
Though an expedient design for accessing standard kernel facilities, it is sometimes inappropriate for accessing non-standard hardware peripherals. By necessity, most hardware peripherals (aka devices) are directly addressable only within the kernel. But user code may need to communicate directly with devices; for instance, an administrator might configure the media type on an Ethernet
interface. Modern operating systems support a diversity of devices, many of which offer a large collection of facilities. Some of these facilities may not be foreseen by the kernel designer, and as a consequence it is difficult for a kernel to provide system calls for using the devices.
To solve this problem, the kernel is designed to be extensible, and may accept an extra module called a "device-driver" which runs in kernel space and can directly address the device. An ioctl interface is a single system call by which the userspace may communicate with device-drivers. Requests on a device-driver are vectored with respect to this ioctl system call, typically by a handle to the device and a request number. The basic kernel can thus allow the userspace to access a device-driver without knowing anything about the facilities supported by the device, and without needing an unmanageably large collection of system calls.
For example, on Win32 systems, ioctl calls are used to communicate with USB devices, or to discover drive geometry information for attached storage devices.
Ioctls are used on Unix systems to configure the network interfaces. For example, on BSD Unix systems such as Mac OS X
, the IP subnet mask
for an interface is configured by opening a network socket
and then invoking the SIOCSIFNETMASK ioctl on it.
Unix
operating systems have traditionally made heavy use of command line interfaces. The Unix command line interface is built on pseudo terminal
s (ptys), which emulate hardware text terminals such as VT100
. Ptys are controlled and configured as if they were hardware devices, using ioctl calls. For instance, the window size of a pty is set using the TIOCSWINSZ ioctl.
For example, on the Solaris operating system, the ipfilter
packet firewall is programmed using the SIOCIPF* ioctl calls.
s:
The kernel generally dispatches an ioctl straight to the device driver, which can interpret the request number and data in whatever way required. The writers of each driver document request numbers for that particular driver and provide them as constants in a header file
.
Some Unix systems, including Linux
, have conventions which encode within the request number the size of the data to be transferred to/from the device driver, the direction of the data transfer and the identity of the driver implementing the request. Regardless of whether such a convention is followed, the kernel and the driver collaborate to deliver a uniform error code (denoted by the symbolic constant
The mnemonic
") derives from the fact that in the earliest systems that incorporated an ioctl call, only the teletype (tty) device raised this error. Though the symbolic mnemonic is fixed by compatibility requirements, some modern systems more helpfully render a more general message such as "Inappropriate device control operation" (or a localisation thereof).
. The normal read and write calls on a serial port receive and send data bytes. An
s, or the output signals on the port (such as the DTR
signal).
The Win32 device control code takes into consideration the mode of the operation being performed.
There are 4 defined modes of operation, impacting the security of the device driver -
On Unix operating systems, two other vectored call interfaces are popular: the fcntl ("file control") system call configures open files, and is used in situations such as enabling non-blocking I/O; and the setsockopt ("set socket option") system call configures open network sockets
, a facility used to configure the ipfw packet firewall on BSD Unix systems.
s. Applications that interact with devices open a location on the filesystem corresponding to the device, as they would for an ioctl call, but then use memory mapping system calls to tie a portion of their address space to that of the kernel.
This interface is a far more efficient way to provide bulk data transfer between a device and a userspace application; individual ioctl or read/write system calls inflict overhead due to repeated userspace-to-kernel transitions, where access to a memory-mapped range of addresses incurs no such overhead.
is a socket-like mechanism for IPC
, designed to be a more flexible successor to ioctl.
Though the interface to ioctl calls appears somewhat different from conventional system calls, there is in practice little difference between an ioctl and a system call; an ioctl is simply a system call with a different dispatching mechanism. Many of the arguments against expanding the kernel system call interface could therefore be applied to ioctl interfaces.
To application developers, system calls appear no different from application subroutines; they are simply function calls that take arguments and return values. The runtime
libraries of the OS mask the complexity involved in invoking system calls. Unfortunately, runtime libraries do not make ioctl calls as transparent. Simple operations like discovering the IP address
es for a machine often require tangled messes of ioctl calls, each requiring magic number
s and argument structures.
Libpcap
and libdnet are two examples of third-party wrapper Unix libraries designed to mask the complexity of ioctl interfaces, for packet capture and packet I/O, respectively.
Ioctl interfaces are more complicated, more diverse, and thus harder to audit than system calls. Furthermore, because ioctls can be provided by third-party developers, often after the core operating system has been released, ioctl call implementations may receive less scrutiny and thus harbor more vulnerabilities. Finally, many ioctl calls, particularly for third-party device drivers, are undocumented.
Because the handler for an ioctl call resides directly in kernel mode, the input from userspace should be validated carefully. Vulnerabilities in device drivers can be exploited by local users by passing invalid buffers to ioctl calls.
Win32 and Unix
operating systems can protect a userspace device name from access by applications with specific access controls applied to the device. Security problems can arise when device driver developers do not apply appropriate access controls to the userspace accessible object.
Some modern operating systems protect the kernel from hostile userspace code (such as applications that have been infected by buffer overflow
exploits) using system call wrappers. System call wrappers implement role-based access control
by specifying which system calls can be invoked by which applications; wrappers can, for instance, be used to "revoke" the right of a mail program to spawn other programs. Ioctl interfaces complicate system call wrappers because there are large numbers of them, each taking different arguments, some of which may be required by normal programs.
Input/output
In computing, input/output, or I/O, refers to the communication between an information processing system , and the outside world, possibly a human, or another information processing system. Inputs are the signals or data received by the system, and outputs are the signals or data sent from it...
control, is a system call
System call
In computing, a system call is how a program requests a service from an operating system's kernel. This may include hardware related services , creating and executing new processes, and communicating with integral kernel services...
for device-specific operations and other operations which cannot be expressed by regular system calls. It takes a parameter specifying a request code; the effect of a call depends completely on the request code. Request codes are often device-specific. For instance, a CD-ROM driver which can get a physical device to eject a disc would provide an ioctl request code to do that. Device-independent request codes are sometimes used to give userland access to kernel functions which are only used by core system software or still under development.
The "ioctl" system call first appeared in Version 7
Version 7 Unix
Seventh Edition Unix, also called Version 7 Unix, Version 7 or just V7, was an important early release of the Unix operating system. V7, released in 1979, was the last Bell Laboratories release to see widespread distribution before the commercialization of Unix by AT&T in the early 1980s...
of Unix
Unix
Unix is a multitasking, multi-user computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs, including Ken Thompson, Dennis Ritchie, Brian Kernighan, Douglas McIlroy, and Joe Ossanna...
under that name. It is supported by most Unix and Unix-like
Unix-like
A Unix-like operating system is one that behaves in a manner similar to a Unix system, while not necessarily conforming to or being certified to any version of the Single UNIX Specification....
systems, including Linux
Linux
Linux is a Unix-like computer operating system assembled under the model of free and open source software development and distribution. The defining component of any Linux system is the Linux kernel, an operating system kernel first released October 5, 1991 by Linus Torvalds...
and Mac OS X
Mac OS X
Mac OS X is a series of Unix-based operating systems and graphical user interfaces developed, marketed, and sold by Apple Inc. Since 2002, has been included with all new Macintosh computer systems...
, though the available request codes differ from system to system. Microsoft Windows
Microsoft Windows
Microsoft Windows is a series of operating systems produced by Microsoft.Microsoft introduced an operating environment named Windows on November 20, 1985 as an add-on to MS-DOS in response to the growing interest in graphical user interfaces . Microsoft Windows came to dominate the world's personal...
provides a similar function, named "DeviceIoControl", in its Win32 API
Windows API
The Windows API, informally WinAPI, is Microsoft's core set of application programming interfaces available in the Microsoft Windows operating systems. It was formerly called the Win32 API; however, the name "Windows API" more accurately reflects its roots in 16-bit Windows and its support on...
.
Background
Conventional operating systems can be divided into two layers, userspace and the kernel. Application code such as a text editorText editor
A text editor is a type of program used for editing plain text files.Text editors are often provided with operating systems or software development packages, and can be used to change configuration files and programming language source code....
resides in userspace, while the underlying facilities of the operating system, such as the network stack, reside in the kernel. Kernel code handles sensitive resources and implements the security and reliability barriers between applications; for this reason, user mode applications are prevented by the operating system from directly accessing kernel resources.
Userspace applications typically make requests of kernels by means of system call
System call
In computing, a system call is how a program requests a service from an operating system's kernel. This may include hardware related services , creating and executing new processes, and communicating with integral kernel services...
s, whose code lies in the kernel layer. A system call usually takes the form of a "system call vector", in which the desired system call is indicated with an index number. For instance, "exit" might be system call number 1, and "write" might be system call number 4. The system call vector is used to find the desired kernel function for the request. In this way, conventional operating systems typically provide several hundred system calls to the userspace.
Though an expedient design for accessing standard kernel facilities, it is sometimes inappropriate for accessing non-standard hardware peripherals. By necessity, most hardware peripherals (aka devices) are directly addressable only within the kernel. But user code may need to communicate directly with devices; for instance, an administrator might configure the media type on an Ethernet
Ethernet
Ethernet is a family of computer networking technologies for local area networks commercially introduced in 1980. Standardized in IEEE 802.3, Ethernet has largely replaced competing wired LAN technologies....
interface. Modern operating systems support a diversity of devices, many of which offer a large collection of facilities. Some of these facilities may not be foreseen by the kernel designer, and as a consequence it is difficult for a kernel to provide system calls for using the devices.
To solve this problem, the kernel is designed to be extensible, and may accept an extra module called a "device-driver" which runs in kernel space and can directly address the device. An ioctl interface is a single system call by which the userspace may communicate with device-drivers. Requests on a device-driver are vectored with respect to this ioctl system call, typically by a handle to the device and a request number. The basic kernel can thus allow the userspace to access a device-driver without knowing anything about the facilities supported by the device, and without needing an unmanageably large collection of system calls.
Hardware device configuration
The most common use of ioctls is to control hardware devices.For example, on Win32 systems, ioctl calls are used to communicate with USB devices, or to discover drive geometry information for attached storage devices.
Ioctls are used on Unix systems to configure the network interfaces. For example, on BSD Unix systems such as Mac OS X
Mac OS X
Mac OS X is a series of Unix-based operating systems and graphical user interfaces developed, marketed, and sold by Apple Inc. Since 2002, has been included with all new Macintosh computer systems...
, the IP subnet mask
Subnetwork
A subnetwork, or subnet, is a logically visible subdivision of an IP network. The practice of dividing a network into subnetworks is called subnetting....
for an interface is configured by opening a network socket
Berkeley sockets
The Berkeley sockets application programming interface comprises a library for developing applications in the C programming language that perform inter-process communication, most commonly for communications across a computer network....
and then invoking the SIOCSIFNETMASK ioctl on it.
Terminals
One use of ioctls exposed to end-user applications is terminal I/O.Unix
Unix
Unix is a multitasking, multi-user computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs, including Ken Thompson, Dennis Ritchie, Brian Kernighan, Douglas McIlroy, and Joe Ossanna...
operating systems have traditionally made heavy use of command line interfaces. The Unix command line interface is built on pseudo terminal
Pseudo terminal
In some operating systems, including Unix, a pseudo terminal is a pseudo-device pair that provides a text terminal interface without an associated device, such as a virtual console, computer terminal or serial port...
s (ptys), which emulate hardware text terminals such as VT100
VT100
The VT100 is a video terminal that was made by Digital Equipment Corporation . Its detailed attributes became the de facto standard for terminal emulators.-History:...
. Ptys are controlled and configured as if they were hardware devices, using ioctl calls. For instance, the window size of a pty is set using the TIOCSWINSZ ioctl.
Kernel extensions
When applications need to extend the kernel, for instance to accelerate network processing, ioctl calls provide a convenient way to bridge userspace code to kernel extensions. Kernel extensions can provide a location in the filesystem that can be opened by name, through which an arbitrary number of ioctl calls can be dispatched, allowing the extension to be programmed without adding system calls to the operating system.For example, on the Solaris operating system, the ipfilter
IPFilter
IPFilter is an open source software package that provides firewall services and network address translation for many UNIX-like operating systems. The author and software maintainer is Darren Reed. IPFilter supports both IPv4 and IPv6 protocols, and is a stateful firewall.IPFilter is delivered...
packet firewall is programmed using the SIOCIPF* ioctl calls.
Unix
A Unix ioctl call takes as parameterParameter
Parameter from Ancient Greek παρά also “para” meaning “beside, subsidiary” and μέτρον also “metron” meaning “measure”, can be interpreted in mathematics, logic, linguistics, environmental science and other disciplines....
s:
- an open file descriptorFile descriptorIn computer programming, a file descriptor is an abstract indicator for accessing a file. The term is generally used in POSIX operating systems...
- a request code number
- either an integer value, possibly unsigned (going to the driver) or a pointer to data (either going to the driver, coming back from the driver, or both).
The kernel generally dispatches an ioctl straight to the device driver, which can interpret the request number and data in whatever way required. The writers of each driver document request numbers for that particular driver and provide them as constants in a header file
Header file
Some programming languages use header files. These files allow programmers to separate certain elements of a program's source code into reusable files. Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers...
.
Some Unix systems, including Linux
Linux
Linux is a Unix-like computer operating system assembled under the model of free and open source software development and distribution. The defining component of any Linux system is the Linux kernel, an operating system kernel first released October 5, 1991 by Linus Torvalds...
, have conventions which encode within the request number the size of the data to be transferred to/from the device driver, the direction of the data transfer and the identity of the driver implementing the request. Regardless of whether such a convention is followed, the kernel and the driver collaborate to deliver a uniform error code (denoted by the symbolic constant
ENOTTY) to an application which makes a request of a driver which does not recognise it.The mnemonic
ENOTTY (traditionally associated with the textual message "Not a typewriterNot a typewriter
In computer science "Not a typewriter" or ENOTTY is an error code defined in the errno.h found on many Unix systems. This code is used to indicate that an attempt has been made to use a non-TTY device as a TTY device.- Details :...
") derives from the fact that in the earliest systems that incorporated an ioctl call, only the teletype (tty) device raised this error. Though the symbolic mnemonic is fixed by compatibility requirements, some modern systems more helpfully render a more general message such as "Inappropriate device control operation" (or a localisation thereof).
TCSETS exemplifies an ioctl on a serial portSerial port
In computing, a serial port is a serial communication physical interface through which information transfers in or out one bit at a time...
. The normal read and write calls on a serial port receive and send data bytes. An
ioctl(fd,TCSETS,data) call, separate from such normal I/O, controls various driver options like handling of special characterCharacter (computing)
In computer and machine-based telecommunications terminology, a character is a unit of information that roughly corresponds to a grapheme, grapheme-like unit, or symbol, such as in an alphabet or syllabary in the written form of a natural language....
s, or the output signals on the port (such as the DTR
Data Terminal Ready
Data Terminal Ready, abbreviated as DTR, is a control signal present inside an RS-232 serial communications cable that goes between a computer and another device, such as a modem...
signal).
Win32
A Win32 DeviceIoControl takes as parameters:- an open object handle (the Win32 equivalent of a file descriptor)
- a request code number (the "control code")
- a buffer for input parameters
- length of the input buffer
- a buffer for output results
- length of the output buffer
- an OVERLAPPED structure, if overlapped I/OOverlapped I/OOverlapped I/O is an asynchronous I/O extension of the Windows APIs, which was introduced in Windows NT.Utilizing overlapped I/O requires passing an OVERLAPPED structure to the ReadFile, WriteFile, and other otherwise-blocking API functions including WSASend/WSARecv from the Winsock API...
is being used.
The Win32 device control code takes into consideration the mode of the operation being performed.
There are 4 defined modes of operation, impacting the security of the device driver -
- METHOD_IN_DIRECT - The buffer address is verified to be readable by the user mode caller.
- METHOD_OUT_DIRECT - The buffer address is verified to be writable by the user mode caller.
- METHOD_NEITHER - User mode virtual addresses are passed to the driver without mapping or validation.
- METHOD_BUFFERED - IO Manager controlled shared buffers are used to move data to and from user mode.
Other vectored call interfaces
Devices and kernel extensions may be linked to userspace using additional new system calls, although this approach is rarely taken, because operating system developers try to keep the system call interface focused and efficient.On Unix operating systems, two other vectored call interfaces are popular: the fcntl ("file control") system call configures open files, and is used in situations such as enabling non-blocking I/O; and the setsockopt ("set socket option") system call configures open network sockets
Berkeley sockets
The Berkeley sockets application programming interface comprises a library for developing applications in the C programming language that perform inter-process communication, most commonly for communications across a computer network....
, a facility used to configure the ipfw packet firewall on BSD Unix systems.
Unix
Device interfaces and input/output capabilities are sometimes provided using memory-mapped fileMemory-mapped file
A memory-mapped file is a segment of virtual memory which has been assigned a direct byte-for-byte correlation with some portion of a file or file-like resource. This resource is typically a file that is physically present on-disk, but can also be a device, shared memory object, or other resource...
s. Applications that interact with devices open a location on the filesystem corresponding to the device, as they would for an ioctl call, but then use memory mapping system calls to tie a portion of their address space to that of the kernel.
This interface is a far more efficient way to provide bulk data transfer between a device and a userspace application; individual ioctl or read/write system calls inflict overhead due to repeated userspace-to-kernel transitions, where access to a memory-mapped range of addresses incurs no such overhead.
Win32
On Win32 platforms, buffered IO methods or named file mapping objects can be used; however, for simple device drivers the standard DeviceIoControl METHOD_ accesses are sufficient.Netlink
NetlinkNetlink
Netlink is a socket-like mechanism for IPC between the kernel and user space processes, as well as between user space processes alone or a mixture of multiple user space and kernel space processes...
is a socket-like mechanism for IPC
Inter-process communication
In computing, Inter-process communication is a set of methods for the exchange of data among multiple threads in one or more processes. Processes may be running on one or more computers connected by a network. IPC methods are divided into methods for message passing, synchronization, shared...
, designed to be a more flexible successor to ioctl.
Complexity
Ioctl calls minimize the complexity of the kernel's system call interface. However, by providing a place for developers to "stash" bits and pieces of kernel programming interfaces, ioctls complicate the overall user-to-kernel API. A kernel that provides several hundred system calls may provide several thousand ioctl calls.Though the interface to ioctl calls appears somewhat different from conventional system calls, there is in practice little difference between an ioctl and a system call; an ioctl is simply a system call with a different dispatching mechanism. Many of the arguments against expanding the kernel system call interface could therefore be applied to ioctl interfaces.
To application developers, system calls appear no different from application subroutines; they are simply function calls that take arguments and return values. The runtime
Run-time system
A run-time system is a software component designed to support the execution of computer programs written in some computer language...
libraries of the OS mask the complexity involved in invoking system calls. Unfortunately, runtime libraries do not make ioctl calls as transparent. Simple operations like discovering the IP address
IP address
An Internet Protocol address is a numerical label assigned to each device participating in a computer network that uses the Internet Protocol for communication. An IP address serves two principal functions: host or network interface identification and location addressing...
es for a machine often require tangled messes of ioctl calls, each requiring magic number
Magic number (programming)
In computer programming, the term magic number has multiple meanings. It could refer to one or more of the following:* A constant numerical or text value used to identify a file format or protocol; for files, see List of file signatures...
s and argument structures.
Libpcap
Pcap
In the field of computer network administration, pcap consists of an application programming interface for capturing network traffic...
and libdnet are two examples of third-party wrapper Unix libraries designed to mask the complexity of ioctl interfaces, for packet capture and packet I/O, respectively.
Security
The user-to-kernel interfaces of mainstream operating systems are often audited heavily for code flaws and security vulnerabilities prior to release. These audits typically focus on the well-documented system call interfaces; for instance, auditors might ensure that sensitive security calls such as changing user IDs are only available to administrative users.Ioctl interfaces are more complicated, more diverse, and thus harder to audit than system calls. Furthermore, because ioctls can be provided by third-party developers, often after the core operating system has been released, ioctl call implementations may receive less scrutiny and thus harbor more vulnerabilities. Finally, many ioctl calls, particularly for third-party device drivers, are undocumented.
Because the handler for an ioctl call resides directly in kernel mode, the input from userspace should be validated carefully. Vulnerabilities in device drivers can be exploited by local users by passing invalid buffers to ioctl calls.
Win32 and Unix
Unix
Unix is a multitasking, multi-user computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs, including Ken Thompson, Dennis Ritchie, Brian Kernighan, Douglas McIlroy, and Joe Ossanna...
operating systems can protect a userspace device name from access by applications with specific access controls applied to the device. Security problems can arise when device driver developers do not apply appropriate access controls to the userspace accessible object.
Some modern operating systems protect the kernel from hostile userspace code (such as applications that have been infected by buffer overflow
Buffer overflow
In computer security and programming, a buffer overflow, or buffer overrun, is an anomaly where a program, while writing data to a buffer, overruns the buffer's boundary and overwrites adjacent memory. This is a special case of violation of memory safety....
exploits) using system call wrappers. System call wrappers implement role-based access control
Role-Based Access Control
In computer systems security, role-based access control is an approach to restricting system access to authorized users. It is used by the majority of enterprises with more than 500 employees, and can be implemented via mandatory access control or discretionary access control...
by specifying which system calls can be invoked by which applications; wrappers can, for instance, be used to "revoke" the right of a mail program to spawn other programs. Ioctl interfaces complicate system call wrappers because there are large numbers of them, each taking different arguments, some of which may be required by normal programs.