'\"macro stdmacro
.if n .pH g2.ioctl @(#)ioctl	40.23 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ioctl 2 "" "\&"
.if \nX=1 .ds x} ioctl 2 ""
.if \nX=2 .ds x} ioctl 2 "" "\&"
.if \nX=3 .ds x} ioctl "" "" "\&"
.TH \*(x}
.SH NAME
\f4ioctl\f1 \- control device
.SH SYNOPSIS
\f4#include <unistd.h>\f1
.PP
\f4int ioctl (int fildes, int request, ... /* arg */);  \f1
.SH DESCRIPTION
\f4ioctl\fP
performs a variety of control functions on devices and \s-1STREAMS\s0.
For non-\s-1STREAMS\s0 files, the functions performed by this call are 
device-specific
control functions.
\f2request\f1 and an optional third argument with varying type
are passed to the file designated by \f2fildes\f1
and are interpreted by the device driver.
This control is not frequently used on non-\s-1STREAMS\s0 devices,
where the basic input/output functions are usually performed through the
\f4read\fP(2) and \f4write\fP(2) system calls.
.PP
For \s-1STREAMS\s0 files, specific functions are performed by
the \f4ioctl\fP call as described in \f4streamio\fP(7).
.PP
.I fildes\^
is an open file descriptor that refers to a device.
.I request\^
selects the control function to be performed
and depends on the device being addressed.
.I arg\^
represents a third argument that has additional information
that is needed by this specific device
to perform the requested function.
The data type of
.I arg\^
depends upon the particular control request,
but it is either an \f4int\f1
or a pointer to a device-specific data structure.
.PP
In addition to device-specific and \s-1STREAMS\s0 functions,
generic functions are provided by more than one device driver,
for example, the general terminal interface [see
\f4termio\fP(7)].
.PP
\f4ioctl\fP
fails for any type of file
if one or more of the following are true:
.TP 15
\f4EBADF\fP
.I fildes\^
is not a valid open file descriptor.
.TP
\f4ENOTTY\fP
.I fildes\^
is not associated with a device driver
that accepts control functions.
.TP
\f4EINTR\fP
A signal was caught during the
\f4ioctl\fP
system call.
.PP
\f4ioctl\fP
also fails if the device driver detects
an error.  In this case, the
error is passed through
\f4ioctl\fP
without change to the caller.
A particular driver might not have all of the following error cases.
Under the following conditions,
requests to device drivers may fail
and set \f4errno\f1 to:
.TP 15
.TP
\f4EFAULT\fP
.I request\^
requires a data transfer to or from
a buffer pointed to by
.IR arg ,
but some part of the buffer is outside
the process's allocated space.
.TP
\f4EINVAL\fP
.I request\^
or
.I arg\^
is not valid for this device.
.TP
\f4EIO\fP
Some physical I/O error has occurred.
.TP
\f4ENXIO\fP
The
.I request\^
and
.I arg\^
are valid for this device driver,
but the service requested can not be performed
on this particular subdevice.
.TP
\f4ENOLINK\fP
\f2fildes\f1 is on a remote machine and the link
to that machine is no longer active.
.PP
\s-1STREAMS\s0 errors are described in \f4streamio\fP(7).
.SH "SEE ALSO"
\f4streamio\fP(7) in the \f2Programmer's Guide: STREAMS\f1.
.br
\f4termio\fP(7) in the \f2System Administrator's Reference Manual\f1.
.SH DIAGNOSTICS
Upon successful completion,
the value returned depends upon the device control function,
but must be a non-negative integer. 
Otherwise,
a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)ioctl.2
.Ee
