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 September 11, 2013 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 EBADF 114The 115.Fa fd 116argument 117is not a valid descriptor. 118.It Bq Er ENOTTY 119The 120.Fa fd 121argument 122is not associated with a character 123special device. 124.It Bq Er ENOTTY 125The specified request does not apply to the kind 126of object that the descriptor 127.Fa fd 128references. 129.It Bq Er EINVAL 130The 131.Fa request 132or 133.Fa argp 134argument 135is not valid. 136.It Bq Er EFAULT 137The 138.Fa argp 139argument 140points outside the process's allocated address space. 141.El 142.Sh SEE ALSO 143.Xr execve 2 , 144.Xr fcntl 2 , 145.Xr intro 4 , 146.Xr tty 4 147.Sh HISTORY 148The 149.Fn ioctl 150function appeared in 151.At v7 . 152