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.\" @(#)ioctl.2 8.2 (Berkeley) 12/11/93 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd September 11, 2013 33.Dt IOCTL 2 34.Os 35.Sh NAME 36.Nm ioctl 37.Nd control device 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/ioctl.h 42.Ft int 43.Fn ioctl "int fd" "unsigned long request" ... 44.Sh DESCRIPTION 45The 46.Fn ioctl 47system call manipulates the underlying device parameters of special files. 48In particular, many operating 49characteristics of character special files (e.g.\& terminals) 50may be controlled with 51.Fn ioctl 52requests. 53The argument 54.Fa fd 55must be an open file descriptor. 56.Pp 57The third argument to 58.Fn ioctl 59is traditionally named 60.Va "char *argp" . 61Most uses of 62.Fn ioctl , 63however, require the third argument to be a 64.Vt caddr_t 65or an 66.Vt int . 67.Pp 68An 69.Fn ioctl 70.Fa request 71has encoded in it whether the argument is an 72.Dq in 73argument 74or 75.Dq out 76argument, and the size of the argument 77.Fa argp 78in bytes. 79Macros and defines used in specifying an ioctl 80.Fa request 81are located in the file 82.In sys/ioctl.h . 83.Sh GENERIC IOCTLS 84Some generic ioctls are not implemented for all types of file 85descriptors. 86These include: 87.Bl -tag -width "xxxxxx" 88.It Dv FIONREAD int 89Get the number of bytes that are immediately available for reading. 90.It Dv FIONWRITE int 91Get the number of bytes in the descriptor's send queue. 92These bytes are data which has been written to the descriptor but 93which are being held by the kernel for further processing. 94The nature of the required processing depends on the underlying device. 95For TCP sockets, these bytes have not yet been acknowledged by the 96other side of the connection. 97.It Dv FIONSPACE int 98Get the free space in the descriptor's send queue. 99This value is the size of the send queue minus the number of bytes 100being held in the queue. 101Note: while this value represents the number of bytes that may be 102added to the queue, other resource limitations may cause a write 103not larger than the send queue's space to be blocked. 104One such limitation would be a lack of network buffers for a write 105to a network connection. 106.El 107.Sh RETURN VALUES 108If an error has occurred, a value of -1 is returned and 109.Va errno 110is set to indicate the error. 111.Sh ERRORS 112The 113.Fn ioctl 114system call 115will fail if: 116.Bl -tag -width Er 117.It Bq Er EBADF 118The 119.Fa fd 120argument 121is not a valid descriptor. 122.It Bq Er ENOTTY 123The 124.Fa fd 125argument 126is not associated with a character 127special device. 128.It Bq Er ENOTTY 129The specified request does not apply to the kind 130of object that the descriptor 131.Fa fd 132references. 133.It Bq Er EINVAL 134The 135.Fa request 136or 137.Fa argp 138argument 139is not valid. 140.It Bq Er EFAULT 141The 142.Fa argp 143argument 144points outside the process's allocated address space. 145.El 146.Sh SEE ALSO 147.Xr execve 2 , 148.Xr fcntl 2 , 149.Xr intro 4 , 150.Xr tty 4 151.Sh HISTORY 152The 153.Fn ioctl 154function appeared in 155.At v7 . 156