163 lines
4.3 KiB
Groff
163 lines
4.3 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.ioctl @(#)ioctl 41.3 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 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
|
|
.Op c p a
|
|
.SH SYNOPSIS
|
|
\f4#include <stropts.h>\fP
|
|
.PP
|
|
\f4int ioctl (int fildes, int request, ...); \f1
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
\f4integer *4 function ioctl (fildes, request, arg) \f1
|
|
.PP
|
|
\f4integer*4 fildes, request, arg \f1
|
|
.Op
|
|
.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.
|
|
.PP
|
|
For \s-1STREAMS\s0 files, specific functions are performed by
|
|
the \f4ioctl\fP call as described in \f4streamio\fP(7). Argument types and
|
|
other \f2request\fP-specific information found in \f4streamio\fP(7) take precedence
|
|
over information found in this manual page.
|
|
.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. Many devices do not
|
|
require that the device be opened in a writable mode in order to
|
|
successfully perform
|
|
.I ioctls
|
|
that change the device parameters, or even the contents of the media
|
|
for devices with permanent storage.
|
|
.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 generally 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
|
|
The following operations are generally available on all
|
|
descriptors [see \f4streamio\fP(7)]:
|
|
.TP 15
|
|
\f4FIONBIO\fP
|
|
Enables or disables non-blocking I/O on \f2fildes\fP.
|
|
.I arg \^
|
|
is a pointer to an \f3int\fP whose value should be 1 to enable non-blocking
|
|
I/O or 0 to disable non-blocking I/O. This operation is not currently
|
|
supported on old-style (non-STREAMS) pipes.
|
|
.TP 15
|
|
\f4FIONREAD\fP
|
|
Returns the number of bytes of data currently available to be read on
|
|
\f2fildes\fP.
|
|
.I arg\^
|
|
is a pointer to a \f3size_t\fP into which the byte-count will be stored.
|
|
.PP
|
|
\f4ioctl\fP
|
|
fails for any type of file
|
|
if one or more of the following are true:
|
|
.TP 15
|
|
\f4EACCES\fP
|
|
The type of access requested on the file designated by \f2fildes\fP
|
|
is denied.
|
|
.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.
|
|
.TP
|
|
\f4ETIMEDOUT\fP
|
|
\f2fildes\f1 is on a remote machine
|
|
which is not available [see \f4intro\fP(2)].
|
|
.PP
|
|
\s-1STREAMS\s0 errors are described in \f4streamio\fP(7).
|
|
.SH "SEE ALSO"
|
|
\f4streamio\fP(7),
|
|
\f4termio\fP(7)
|
|
.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
|