View source for Ioctl

{{lowercase}}
{{Short description|System call for device-specific input/output operations}}
{{More footnotes|date=February 2010}}

In [[computing]], <code>'''ioctl'''</code> (an abbreviation of '''input/output control''') is a [[system call]] for device-specific [[input/output]] operations and other operations which cannot be expressed by regular file semantics. 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 [[device driver]] which can instruct a physical device to eject a disc would provide an <code>ioctl</code> request code to do so. Device-independent request codes are sometimes used to give [[user space and kernel space|userspace]] access to kernel functions which are only used by core system software or still under development.

The <code>ioctl</code> system call first appeared in [[Version 7 Unix|Version 7]] of [[Unix]] under that name. It is supported by most Unix and [[Unix-like]] systems, including [[Linux]] and [[macOS]], though the available request codes differ from system to system. [[Microsoft Windows]] provides a similar function, named "<code>DeviceIoControl</code>", in its [[Windows API|Win32 API]].

== Background ==

Conventional operating systems can be divided into two layers, [[user space and kernel space|userspace]] and the [[Kernel (operating system)|kernel]]. Application code such as a [[text editor]] 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 to the kernel 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, <code>exit()</code> might be system call number 1, and <code>write()</code> number 4. The system call vector is then 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, system calls are 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 diverse 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 <code>ioctl</code> interface is a single system call by which userspace may communicate with device drivers. Requests on a device driver are vectored with respect to this <code>ioctl</code> 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.

== Uses ==

=== Hardware device configuration ===

A common use of <code>ioctl</code> is to control hardware devices.

For example, on [[Win32]] systems, <code>ioctl</code> calls can communicate with [[USB]] devices, or they can discover drive-geometry information of the attached storage-devices.

On [[OpenBSD]] and [[NetBSD]], <code>ioctl</code> is used by the <code>{{URL|http://mdoc.su/o,n/bio.4|bio(4)}}</code> pseudo-device driver and the <code>[[bioctl]]</code> utility to implement [[RAID]] volume management in a unified vendor-agnostic interface similar to <code>[[ifconfig]]</code>.<ref name=bio.4>{{cite web
|url= http://bxr.su/o/share/man/man4/bio.4
|author1 = Niklas Hallqvist (2002)
|author2 = Marco Peereboom (2006)
|title = bio(4) — block I/O ioctl tunnel pseudo-device
|website= BSD Cross Reference
|publisher= [[OpenBSD]]
}}
*{{cite book |section=bio — block I/O ioctl tunnel pseudo-device |title=OpenBSD manual page server |url=http://mdoc.su/o,n/bio.4}}</ref><ref name=bioctl>{{cite web
|url= http://bxr.su/o/sbin/bioctl/bioctl.8
|author= Marco Peereboom
|title = bioctl(8) — RAID management interface
|website= BSD Cross Reference
|publisher= [[OpenBSD]]
|date= 2005
}}
*{{cite book |section=bioctl — RAID management interface |title=OpenBSD manual page server |url=http://mdoc.su/o,n/bioctl.8}}</ref>

On [[NetBSD]], <code>ioctl</code> is also used by the <code>[[sysmon]]</code> framework.<ref name=sysmon>{{cite web|url=http://mdoc.su/n/sysmon.4|title=sysmon(4) — system monitoring and power management interface|publisher=[[NetBSD]]|quote= An ioctl(2) interface available via /dev/sysmon.}}</ref>

=== Terminals ===

One use of <code>ioctl</code> in code exposed to end-user applications is terminal I/O.

[[Unix]] operating systems have traditionally made heavy use of [[command-line interface]]s, originally with hardware text terminals such as [[VT100]]s attached to [[serial port]]s, and later with [[terminal emulator]]s and [[remote login]] servers using [[pseudoterminal]]s. Serial port devices and pseudoterminals are both controlled and configured using <code>ioctl</code> calls. For instance, the display size is set using the <code>TIOCSWINSZ</code> call. The TIOCSTI (terminal I/O control, simulate terminal input) ioctl function can push a character into a device stream.<ref>
{{cite book
| last1 = Christiansen
| first1 = Tom
| author-link1 = Tom Christiansen
| last2 = Torkington
| first2 = Nathan
| year = 1998
| chapter = 12: Packages, Libraries, and Modules
| title = Perl Cookbook: Solutions & Examples for Perl Programmers
| url = https://books.google.com/books?id=IzdJIax6J5oC
| edition = 2
| location = Sebastopol, California
| publisher = O'Reilly Media, Inc.
| publication-date = 2003
| page = 482
| isbn = 9780596554965
| access-date = 2016-11-15
| quote = [...]  TIOCSTI [...] stands for 'terminal I/O control, simulate terminal input.' On systems that implement this function, it will push one character into your device stream so that the next time any process reads from that device, it gets the character you put there.
}}
</ref>

=== Kernel extensions ===

When applications need to extend the kernel, for instance to accelerate network processing, <code>ioctl</code> calls provide a convenient way to bridge [[userspace]] code to kernel extensions. [[Kernel extension]]s can provide a location in the filesystem that can be opened by name, through which an arbitrary number of <code>ioctl</code> calls can be dispatched, allowing the extension to be programmed without adding system calls to the operating system.

==== sysctl alternative ====
{{anchor|sysctl}}
According to an [[OpenBSD]] developer, <code>ioctl</code> and <code>[[sysctl]]</code> are the two [[system call]]s for extending the kernel, with <code>sysctl</code> possibly being the simpler of the two.<ref name=onlamp-36>{{cite web
|url= http://www.onlamp.com/lpt/a/5302
|title=  OpenBSD 3.6 Live
|author= Federico Biancuzzi
|website= [[ONLamp]] |publisher= [[O'Reilly Media]]
|date= 2004-10-28 |archive-url= https://web.archive.org/web/20041029232336/http://www.onlamp.com/lpt/a/5302
|access-date=2019-03-20
|archive-date= 2004-10-29
|quote= There are two system calls that can be used to add functionality to the kernel (without adding yet another system call): ioctl(2) and sysctl(3). The latter was chosen because it was very simple to implement the new feature.
}}</ref>

In [[NetBSD]], the <code>[[sysmon_envsys]]</code> framework for [[hardware monitoring]] uses <code>ioctl</code> through <code>[[proplib]]</code>; whereas [[OpenBSD]] and [[DragonFly BSD]] instead use <code>[[sysctl]]</code> for their corresponding <code>[[hw.sensors]]</code> framework.  The original revision of <code>envsys</code> in NetBSD was implemented with <code>ioctl</code> before <code>proplib</code> was available, and had a message suggesting that the framework is experimental, and should be replaced by a <code>sysctl(8)</code> interface, should one be developed,<ref name=n40/envsys.4>{{cite web
|url=http://mdoc.su/n40/envsys.4
|author1=Tim Rightnour
|author2=Bill Squier
|version = NetBSD 4.0
|date = 2007-12-19
|title=     envsys -- Environmental Systems API
|quote=     This API is experimental and may be deprecated at any time ...      This entire API should be replaced by a sysctl(8) interface or a kernel     events mechanism, should one be developed.
}}</ref><ref name=sensors-ieee07>{{Cite conference
|author= Constantine A. Murenin |date= 2007-04-17
|section = 3.5. NetBSD's sysmon(4) 
|url = http://sensors.cnst.su/IEEE_ICNSC_2007
|title= Generalised Interfacing with Microprocessor System Hardware Monitors
|conference= Proceedings of 2007 IEEE International Conference on Networking, Sensing and Control, 15–17 April 2007.
|location= London, United Kingdom
|publisher=[[Institute of Electrical and Electronics Engineers|IEEE]]
|pages = 901–906 |doi = 10.1109/ICNSC.2007.372901 |isbn = 978-1-4244-1076-7
|id = IEEE ICNSC 2007, pp. 901—906.
}}</ref> which potentially explains the choice of <code>sysctl</code> in OpenBSD with its subsequent introduction of <code>[[hw.sensors]]</code> in 2003.  However, when the <code>[[envsys]]</code> framework was redesigned in 2007 around <code>proplib</code>, the system call remained as <code>ioctl</code>, and the message was removed.<ref name=sensors-mmath>{{cite thesis
|degree= [[Master of Mathematics#Canada|MMath]]
|author= Constantine A. Murenin |date= 2010-05-21
|section = 6.1. Framework timeline; 7.1. NetBSD envsys / sysmon
|title= OpenBSD Hardware Sensors — Environmental Monitoring and Fan Control.
|location= [[University of Waterloo]] |publisher= UWSpace
|url = http://cnst.su/MMathCS |hdl = 10012/5234
|id = Document ID: ab71498b6b1a60ff817b29d56997a418.
}}</ref>

== Implementations ==

=== Unix ===
The <code>ioctl</code> system call first appeared in [[Version 7 Unix]], as a replacement for the <code>stty</code><ref name="reader">{{cite tech report |first1=M. D. |last1=McIlroy |author-link1=Doug McIlroy |year=1987 |url=https://www.cs.dartmouth.edu/~doug/reader.pdf |title=A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 |series=CSTR |number=139 |institution=Bell Labs |archive-url=https://web.archive.org/web/20230730004547/https://www.cs.dartmouth.edu/~doug/reader.pdf |archive-date=2023-07-30 |url-status=dead}}</ref> and <code>gtty</code> system calls, with an additional request code argument.  An <code>ioctl</code> call takes as [[parameter]]s:

# an open [[file descriptor]]
# a request code number
# an untyped [[pointer (computer programming)|pointer]] to data (either going to the driver, coming back from the driver, or both).

The [[kernel (operating system)|kernel]] generally dispatches an <code>ioctl</code> call 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 [[constant (computer programming)|constants]] in a [[header file]].

Request numbers usually combine a code identifying the device or class of devices for which the request is intended and a number indicating the particular request; the code identifying the device or class of devices is usually a single ASCII character. Some Unix systems, including [[4.2BSD]] and later [[Berkeley Software Distribution|BSD]] releases, operating systems derived from those releases, and [[Linux]], have conventions that also encode within the request number the size of the data to be transferred to/from the device driver and the direction of the data transfer.  Regardless of whether any such conventions are followed, the kernel and the driver collaborate to deliver a uniform error code (denoted by the symbolic constant <code>ENOTTY</code>) to an application which makes a request of a driver which does not recognise it.

The mnemonic <code>ENOTTY</code> (traditionally associated with the textual message "''[[Not a typewriter]]''") derives from the earliest systems that incorporated an <code>ioctl</code> call, where only the [[Teleprinter|teletype]] (<code>tty</code>) 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 [[Internationalization and localization|localization]] thereof).

<code>TCSETS</code> exemplifies an <code>ioctl</code> call on a [[serial port]]. The normal read and write calls on a serial port receive and send data bytes. An <code>ioctl(fd,TCSETS,data)</code> call, separate from such normal I/O, controls various driver options like handling of special [[character (computing)|character]]s, or the output signals on the port (such as the [[Data Terminal Ready|DTR]] signal).

=== Win32 ===

A Win32 <code>DeviceIoControl</code> 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 <code>OVERLAPPED</code> structure, if [[overlapped I/O]] 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 -

# <code>METHOD_IN_DIRECT</code>: The buffer address is verified to be readable by the user mode caller.
# <code>METHOD_OUT_DIRECT</code>: The buffer address is verified to be writable by the user mode caller.
# <code>METHOD_NEITHER</code>: User mode virtual addresses are passed to the driver without mapping or validation.
# <code>METHOD_BUFFERED</code>: IO Manager controlled shared buffers are used to move data to and from user mode.

== Alternatives ==

=== Other vectored call interfaces ===

Devices and kernel extensions may be linked to [[user space and kernel space|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 <code>fcntl</code> ("file control") system call configures open files, and is used in situations such as enabling [[Asynchronous I/O|non-blocking I/O]]; and the <code>setsockopt</code> ("set socket option") system call configures open [[Berkeley sockets|network sockets]], a facility used to configure the <code>[[ipfw]]</code> packet firewall on [[Berkeley Software Distribution|BSD]] Unix systems.

=== Memory mapping ===
; Unix: Device interfaces and input/output capabilities are sometimes provided using [[memory-mapped file]]s. Applications that interact with devices open a location on the filesystem corresponding to the device, as they would for an <code>ioctl</code> 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 <code>ioctl</code> 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: Buffered IO methods or named file mapping objects can be used; however, for simple device drivers the standard <code>DeviceIoControl METHOD_</code> accesses are sufficient.

=== Netlink ===

[[Netlink]] is a socket-like mechanism for [[inter-process communication]] (IPC), designed to be a more flexible successor to <code>ioctl</code>.

== Implications ==

=== Complexity ===

<code>ioctl</code> 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, <code>ioctl</code> calls 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 <code>ioctl</code> calls appears somewhat different from conventional system calls, there is in practice little difference between an <code>ioctl</code> call and a system call; an <code>ioctl</code> call 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 <code>ioctl</code> 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 system|runtime]] libraries of the OS mask the complexity involved in invoking system calls. Unfortunately, runtime libraries do not make <code>ioctl</code> calls as transparent. Simple operations like discovering the [[IP address]]es for a machine often require tangled messes of <code>ioctl</code> calls, each requiring [[magic number (programming)|magic number]]s and argument structures.{{Citation needed|date=July 2010}}

[[pcap|Libpcap]] and [[libdnet]] are two examples of third-party wrapper Unix libraries designed to mask the complexity of <code>ioctl</code> 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.

<code>ioctl</code> interfaces are more complicated, more diverse, and thus harder to audit than system calls. Furthermore, because <code>ioctl</code> calls can be provided by third-party developers, often after the core operating system has been released, <code>ioctl</code> call implementations may receive less scrutiny and thus harbor more vulnerabilities. Finally, many <code>ioctl</code> calls, particularly for third-party device drivers, are undocumented.

Because the handler for an <code>ioctl</code> call resides directly in kernel mode, the input from [[user space and kernel space|userspace]] should be validated carefully. Vulnerabilities in device drivers can be exploited by local users by passing invalid buffers to <code>ioctl</code> 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. <code>ioctl</code> 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.

== Further reading ==

* [[W. Richard Stevens]], ''Advanced Programming in the UNIX Environment'' (Addison-Wesley, 1992, {{ISBN|0-201-56317-7}}), section 3.14.
* [https://www.gnu.org/s/libc/manual/html_node/IOCTLs.html Generic I/O Control operations] in the online manual for the [[GNU C Library]]
* {{man|2|ioctl|v7}}
* {{man|2|ioctl|Linux}}
* {{man|2|ioctl|FreeBSD}}
* {{man|2|ioctl|OpenBSD}}
* {{man|2|ioctl|Solaris}}
* [http://msdn2.microsoft.com/en-us/library/aa363216.aspx "DeviceIoControl Documentation] at the [[Microsoft Developer Network]]

==References==
{{Reflist}}

[[Category:Unix]]
[[Category:System calls]]