HP 3000 Manuals HP 3000 Manuals
IOCTL
C Interface
#include <sys/ioctl.h>
int ioctl (s, request, arg)
int s;
int request;
void *arg;
Description
The ioctl function provides an interface for setting different
characteristics for a socket, and retrieving information on a socket.
The parameter s is a socket descriptor. The request parameter specifies
which command to perform on the socket. The commands are defined in
<sys/ioctl.h>. The different commands that are available are described
below.
Note: Any data structure referenced by arg must not contain any
pointers.
FIONREAD Returns the number of bytes immediately readable from
the socket in the long integer whose address is arg.
For SOCK_STREAM sockets, the number of bytes
currently readable from this socket is returned in
the integer with the address arg. For SOCK_DGRAM
sockets, the number of bytes currently readable, plus
the size of the sockaddr structure (defined in
<sys/socket.h>), is returned in the integer with the
address arg.
FIOSNBIO Enables or disables non-blocking I/O for the socket.
If the integer whose address is arg is non-zero, then
non-blocking I/O is enabled; that is, subsequent
reads and writes to the device file are handled in a
non-blocking manner (see below). If the integer
whose address is arg is 0, then non-blocking I/O is
disabled.
For reads, non-blocking I/O prevents all read
requests to that socket from blocking, whether the
requests succeed or fail. Such read requests
complete in one of three ways:
* If there is enough data available to satisfy
the entire request, the read completes
successfully, having read all of the data, and
returns the number of bytes read;
* If there is not enough data available to
satisfy the entire request, the read completes
successfully, having read as much data as
possible, and returns the number of bytes it
was able to read;
* If there is no data available, the read fails
and errno is set to EWOULDBLOCK.
For writes, non-blocking I/O prevents all write
requests to that socket from blocking, whether the
requests succeed or fail. Such a write request
completes in one of three ways:
* If there is enough space available in the
system to buffer all the data, the write
completes successfully having written out all
of the data, and returns the number of bytes
written;
* If there is not enough space in the buffer to
write out the entire request, the write
completes successfully, having written as much
data as possible, and returns the number of
bytes it was able to write;
* If there is no space in the buffer, the write
fails and errno is set to EWOULDBLOCK.
To prohibit non-blocking I/O from interfering with
the O_NDELAY flag (see fcntl section), the
functionality of O_NDELAY always supercedes the
functionality of non-blocking I/O. This means that if
O_NDELAY is set, the transport performs read requests
in accordance with the definition of O_NDELAY. When
O_NDELAY is not set, the definition of non-blocking
I/O applies.
When a socket is created, non-blocking I/O is
disabled.
Blocking mode is the default. See accept, connect,
recv, and send for an explanation of how non-blocking
mode is used.
FIOGNBIO Gets the status of non-blocking I/O. If non-blocking
I/O is enabled, then the integer whose address is arg
is set to 1. If non-blocking I/O is disabled, then
the integer whose address is arg is set to 0.
SIOCATMARK For SOCK_STREAM TCP sockets, upon return the integer
with the address arg is non-zero if urgent data has
arrived. For sockets other than SOCK_STREAM TCP
sockets, on return the integer with the address arg
is always zero.
SIOCSPGRP This request sets the process group or process ID
associated with the socket to be the value of the
integer with the address arg. A process group or
process ID associated with the socket in this manner
is signaled when the state of the socket changes:
SIGIO is delivered if the socket is asynchronous, as
described in FIOASYNC below. If the value of the
integer with the address arg is positive, the signal
is sent to the process whose process ID matches the
value specified. If the value is negative, the
signal is sent to all the processes that have a
process group equal to the absolute value of the
value specified. If the value is zero, no signal is
sent to any process. It is necessary to issue this
request with a non-zero integer value to enable the
signal delivery mechanism described above; the
default for the process group or process ID value is
zero.
SIOCGPGRP This request returns the process group or process ID
associated with the socket in the integer with the
address arg. If the value of the integer with the
address arg is positive, then the value returned
corresponds to a process ID. If the value is
negative, then the value corresponds to all processes
that have a process group equal to the absolute value
of that value.
FIOASYNC If the integer whose address is arg is non-zero, this
request sets the state of the socket as asynchronous.
Otherwise, the socket is put into synchronous mode
(the default). Asynchronous mode enables the
delivery of the SIGIO signal when a) new data
arrives, or b) for connection-oriented protocols,
whenever additional outgoing buffer space becomes
available, or when the connection is established or
broken. The process group or process ID associated
with the socket must be non-zero in order for SIGIO
signals to be sent; the signal is delivered according
to the semantics of SIOCGPGRP described above.
Since both the fcntl O_NONBLOCK and O_NDELAY flags and ioctl FIOSNBIO
requests are supported, some clarification on how these features interact
is necessary. If the O_NONBLOCK or O_NDELAY flag has been set, recv and
send requests behave accordingly, regardless of any FIOSNBIO requests.
If neither the O_NONBLOCK flag nor the O_NDELAY flag has been set,
FIOSNBIO requests control of the behavior of recv and send.
Return Value
If the call is successful, a 0 is returned. If an error has occurred, a
value of -1 is returned and errno is set to indicate the error.
Errors
ioctl fails if one or more of the following are true: IOC_OUT is ignored
if an error occurs.
[EBADF] The argument s is not a valid open file descriptor.
[EFAULT] The system detected a NULL address while attempting
to use the arg parameter passed by the caller.
[ENOTTY] The request is not appropriate to the selected
device.
[EINVAL] The request parameter of the arg parameter is
invalid, or a socket type that is not supported was
specified.
[EINTR] The ioctl call was interrupted by a signal.
[EPERM] Typically, this error indicates that an ioctl
request was attempted that is forbidden in some way
to the calling process.
MPE/iX Specific
Programs using ioctl() must be linked with the POSIX C library.
Author
ioctl was developed by AT&T and HP.
See Also
fcntl, getsockopt, socket