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