| .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91 |
| .\" |
| .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk> |
| .\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl> |
| .\" |
| .TH IOCTL 2 2017-05-03 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ioctl \- control device |
| .SH SYNOPSIS |
| .B #include <sys/ioctl.h> |
| .PP |
| .BI "int ioctl(int " fd ", unsigned long " request ", ...);" |
| .\" POSIX says 'request' is int, but glibc has the above |
| .\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 |
| .SH DESCRIPTION |
| The |
| .BR ioctl () |
| system call manipulates the underlying device parameters of special files. |
| In particular, many operating characteristics of character special files |
| (e.g., terminals) may be controlled with |
| .BR ioctl () |
| requests. |
| The argument |
| .I fd |
| must be an open file descriptor. |
| .PP |
| The second argument is a device-dependent request code. |
| The third argument is an untyped pointer to memory. |
| It's traditionally |
| .BI "char *" argp |
| (from the days before |
| .B "void *" |
| was valid C), and will be so named for this discussion. |
| .PP |
| An |
| .BR ioctl () |
| .I request |
| has encoded in it whether the argument is an |
| .I in |
| parameter or |
| .I out |
| parameter, and the size of the argument |
| .I argp |
| in bytes. |
| Macros and defines used in specifying an |
| .BR ioctl () |
| .I request |
| are located in the file |
| .IR <sys/ioctl.h> . |
| .SH RETURN VALUE |
| Usually, on success zero is returned. |
| A few |
| .BR ioctl () |
| requests use the return value as an output parameter |
| and return a nonnegative value on success. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP 0.7i |
| .B EBADF |
| .I fd |
| is not a valid file descriptor. |
| .TP |
| .B EFAULT |
| .I argp |
| references an inaccessible memory area. |
| .TP |
| .B EINVAL |
| .I request |
| or |
| .I argp |
| is not valid. |
| .TP |
| .B ENOTTY |
| .I fd |
| is not associated with a character special device. |
| .TP |
| .B ENOTTY |
| The specified request does not apply to the kind of object that the |
| file descriptor |
| .I fd |
| references. |
| .SH CONFORMING TO |
| No single standard. |
| Arguments, returns, and semantics of |
| .BR ioctl () |
| vary according to the device driver in question (the call is used as a |
| catch-all for operations that don't cleanly fit the UNIX stream I/O |
| model). |
| See |
| .BR ioctl_list (2) |
| for a list of many of the known |
| .BR ioctl () |
| calls. |
| The |
| .BR ioctl () |
| system call appeared in Version 7 AT&T UNIX. |
| .SH NOTES |
| In order to use this call, one needs an open file descriptor. |
| Often the |
| .BR open (2) |
| call has unwanted side effects, that can be avoided under Linux |
| by giving it the |
| .B O_NONBLOCK |
| flag. |
| .SH SEE ALSO |
| .BR execve (2), |
| .BR fcntl (2), |
| .BR ioctl_console (2), |
| .BR ioctl_fat (2), |
| .BR ioctl_ficlonerange (2), |
| .BR ioctl_fideduperange (2), |
| .BR ioctl_getfsmap (2), |
| .BR ioctl_iflags (2), |
| .BR ioctl_list (2), |
| .BR ioctl_ns (2), |
| .BR ioctl_tty (2), |
| .BR ioctl_userfaultfd (2), |
| .BR open (2), |
| .\" .BR mt (4), |
| .BR sd (4), |
| .BR tty (4) |