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.