xref: /minix3/lib/libc/sys/ioctl.2 (revision 2fe8fb192fe7e8720e3e7a77f928da545e872a6a)
1.\"	$NetBSD: ioctl.2,v 1.23 2010/12/19 22:19:27 wiz Exp $
2.\"
3.\" Copyright (c) 1980, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"     @(#)ioctl.2	8.2 (Berkeley) 12/11/93
31.\"
32.Dd December 19, 2010
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 d" "unsigned long request" "..."
44.Sh DESCRIPTION
45The
46.Fn ioctl
47function 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 d
55must be an open file descriptor.
56.Pp
57An
58.Fn ioctl
59.Fa request
60has encoded in it whether the argument is an
61.Dq in ,
62.Dq out ,
63or
64.Dq inout
65parameter, and the size of the first variadic argument
66in bytes.
67Note that there can be only one variadic argument but cannot be represented as
68a
69.Ft "void *"
70argument in the prototype because this would require a cast to pass integral
71types without warnings.
72Macros and defines used in specifying an
73.Fn ioctl
74.Fa request
75are located in the header
76.In sys/ioctl.h .
77.Sh GENERIC IOCTLS
78Some ioctls are applicable to any file descriptor.
79These include:
80.Bl -tag -width "xxxxxx"
81.It Dv FIOCLEX
82Set close-on-exec flag.
83The file will be closed when
84.Xr exec 3
85is invoked
86(This is equivalent to
87.Fn fcntl
88.Dv F_SETFD
89.Dv FD_CLOEXEC
90and the
91.Fn fcntl
92form should be preferred).
93.It Dv FIONCLEX
94Clear close-on-exec flag.
95The file will remain open across
96.Xr exec 3
97(This is equivalent to
98.Fn fcntl
99.Dv F_SETFD
100.Dv 0
101and the
102.Fn fcntl
103form should be preferred).
104.El
105.Pp
106Some generic ioctls are not implemented for all types of file
107descriptors.
108These include:
109.Bl -tag -width "xxxxxx"
110.It Dv FIONREAD "int"
111Get the number of bytes that are immediately available for reading.
112.It Dv FIONWRITE "int"
113Get the number of bytes in the descriptor's send queue.
114These bytes are data which has been written to the descriptor but
115which are being held by the kernel for further processing.
116The nature of the required processing depends on the underlying device.
117For tty devices, these bytes are typically queued for delivery
118to the tty hardware.
119For TCP sockets, these bytes have not yet been acknowledged by the
120other side of the connection.
121For files, this operation always returns zero as files do not have
122send queues.
123.It Dv FIONSPACE "int"
124Get the free space in the descriptor's send queue.
125This value is the size of the send queue minus the number of bytes
126being held in the queue.
127Note: while this value represents the number of bytes that may be
128added to the queue, other resource limitations may cause a write
129not larger than the send queue's space to be blocked.
130One such limitation would be a lack of network buffers for a write
131to a network connection.
132.It Dv FIONBIO "int"
133Set non-blocking I/O mode if the argument is non-zero.
134In non-blocking mode,
135.Xr read 2
136or
137.Xr write 2
138calls return
139.Dv \-1
140and set
141.Va errno
142to
143.Er EAGAIN
144immediately when no data is available
145(This is equivalent to
146.Fn fcntl
147.Dv F_SETFL
148.Dv O_NONBLOCK
149and the
150.Fn fcntl
151form should be preferred).
152.It Dv FIOASYNC "int"
153Set asynchronous I/O mode if the argument is non-zero
154(This is equivalent to
155.Fn fcntl
156.Dv F_SETFL
157.Dv O_ASYNC
158and the
159.Fn fcntl
160form should be preferred).
161In asynchronous mode, the process or process group specified by
162.Dv FIOSETOWN
163will start receiving
164.Dv SIGIO
165signals when data is available.
166The
167.Dv SIGIO
168signal will be delivered when data is available on the file
169descriptor.
170.It Dv FIOSETOWN, FIOGETOWN "int"
171Set/get the process or the process group (if negative) that should receive
172.Dv SIGIO
173signals when data is available
174(This is equivalent to
175.Fn fcntl
176.Dv F_SETOWN
177.Ft pid_t
178and the
179.Ft fcntl
180form should be preferred).
181.El
182.Sh RETURN VALUES
183If an error has occurred, a value of \-1 is returned and
184.Va errno
185is set to indicate the error.
186.Sh ERRORS
187.Fn ioctl
188will fail if:
189.Bl -tag -width Er
190.It Bq Er EBADF
191.Fa d
192is not a valid descriptor.
193.It Bq Er EFAULT
194.Fa argp
195points outside the process's allocated address space.
196.It Bq Er EINVAL
197.Fa request
198or
199.Fa argp
200is not valid.
201.It Bq Er ENOTTY
202.Fa d
203is not associated with a character
204special device; or
205the specified request does not apply to the kind
206of object that the descriptor
207.Fa d
208references.
209.El
210.Sh SEE ALSO
211.Xr mt 1 ,
212.Xr execve 2 ,
213.Xr fcntl 2 ,
214.Xr intro 4 ,
215.Xr tty 4
216.Sh HISTORY
217An
218.Fn ioctl
219function call appeared in
220.At v7 .
221