1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd December 29, 2025 29.Dt IOCTL 2 30.Os 31.Sh NAME 32.Nm ioctl 33.Nd control device 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/ioctl.h 38.Ft int 39.Fn ioctl "int fd" "unsigned long request" ... 40.Sh DESCRIPTION 41The 42.Fn ioctl 43system call manipulates the underlying device parameters of special files. 44In particular, many operating 45characteristics of character special files (e.g.\& terminals) 46may be controlled with 47.Fn ioctl 48requests. 49The argument 50.Fa fd 51must be an open file descriptor. 52.Pp 53The third argument to 54.Fn ioctl 55is traditionally named 56.Va "char *argp" . 57Most uses of 58.Fn ioctl , 59however, require the third argument to be a 60.Vt caddr_t 61or an 62.Vt int . 63.Pp 64An 65.Fn ioctl 66.Fa request 67has encoded in it whether the argument is an 68.Dq in 69argument 70or 71.Dq out 72argument, and the size of the argument 73.Fa argp 74in bytes. 75Macros and defines used in specifying an ioctl 76.Fa request 77are located in the file 78.In sys/ioctl.h . 79.Sh GENERIC IOCTLS 80Some generic ioctls are not implemented for all types of file 81descriptors. 82These include: 83.Bl -tag -width "xxxxxx" 84.It Dv FIONREAD int 85Get the number of bytes that are immediately available for reading. 86.It Dv FIONWRITE int 87Get the number of bytes in the descriptor's send queue. 88These bytes are data which has been written to the descriptor but 89which are being held by the kernel for further processing. 90The nature of the required processing depends on the underlying device. 91For TCP sockets, these bytes have not yet been acknowledged by the 92other side of the connection. 93.It Dv FIONSPACE int 94Get the free space in the descriptor's send queue. 95This value is the size of the send queue minus the number of bytes 96being held in the queue. 97Note: while this value represents the number of bytes that may be 98added to the queue, other resource limitations may cause a write 99not larger than the send queue's space to be blocked. 100One such limitation would be a lack of network buffers for a write 101to a network connection. 102.El 103.Sh RETURN VALUES 104If an error has occurred, a value of -1 is returned and 105.Va errno 106is set to indicate the error. 107.Sh ERRORS 108The 109.Fn ioctl 110system call 111will fail if: 112.Bl -tag -width Er 113.It Bq Er EACCES 114The process does not have permission to call this 115.Nm . 116.It Bq Er EBADF 117The 118.Fa fd 119argument 120is not a valid descriptor. 121.It Bq Er ENOTTY 122The 123.Fa fd 124argument 125is not associated with a character 126special device. 127.It Bq Er ENOTTY 128The specified request does not apply to the kind 129of object that the descriptor 130.Fa fd 131references. 132.It Bq Er EINVAL 133The 134.Fa request 135or 136.Fa argp 137argument 138is not valid. 139.It Bq Er EFAULT 140The 141.Fa argp 142argument 143points outside the process's allocated address space. 144.El 145.Sh SEE ALSO 146.Xr execve 2 , 147.Xr fcntl 2 , 148.Xr intro 4 , 149.Xr tty 4 150.Sh HISTORY 151The 152.Fn ioctl 153function appeared in 154.At v7 . 155