(As defined in X/Open Common Application Environment (CAE) Specification: System Interfaces and Headers, Issue 5 (2/97).)
Controls a STREAMS device.
#include <stropts.h>int ioctl (fd, request, .../*arg*/)
int fd;
int request;
int .../*arg*/;
The ioctl operation performs a variety of control functions on STREAMS devices. For non-STREAMS devices, the functions performed by this call are unspecified. The request argument and an optional third argument (with varying type) are passed to and interpreted by the appropriate part of the STREAM associated with fd.
Using the ioctl operation on a file descriptor obtained from a call to the shm_open subroutine fails with ENOTTY.
| Item | Description |
|---|---|
| fd | An open file descriptor that refers to a device. |
| request | Selects the control function to be performed and will depend on the STREAMS device being addressed. |
| .../*arg*/ | Represents additional information that is needed by this specific STREAMS device to perform the requested function. The type of arg depends on the particular control request, but it is either an integer or a pointer to a device-specific data structure. |
The following ioctl commands, with error values indicated, are applicable to all STREAMS files:
| Item | Description |
|---|---|
| I_PUSH | Pushes the module whose name is pointed to by arg onto
the top of the current STREAM, just below the STREAM head. It then
calls the open function of the newly-pushed module. The ioctl function with the I_PUSH command will fail if:
|
| I_POP | Removes the module just below the STREAM head of the STREAM
pointed to by fd. The arg argument should be 0 in
an I_POP request. The ioctl function with the I_POP command will fail if:
|
| I_LOOK | Retrieves the name of the module just below the STREAM head
of the STREAM pointed to by fd, and places it in a character
string pointed to by arg. The buffer pointed to by arg should
be at least FMNAMESZ+1 bytes long, where FMNAMESZ is defined in <stropts.h>.
The ioctl function with the I_LOOK command will fail if:
|
| I_FLUSH | This request flushes read and/or write queues, depending on
the value of arg. Valid arg values are:
The ioctl function with the I_FLUSH command will fail if:
|
| I_FLUSHBAND | Flushes a particular band of messages. The arg argument points to a bandinfo structure. The bi_flag member may be one of FLUSHR, FLUSHW, OR FLUSHRW as described above. The bi_pri member determines the priority band to be flushed. |
| I_SETSIG | Request that the STREAMS implementation send the SIGPOLL signal
to the calling process when a particular event has occurred on the
STREAM associated with fd. I_SETSIG supports an asynchronous
processing capability in STREAMS. The value of arg is a bitmask
that specifies the events for which the process should be signaled.
It is the bitwise-OR of an combination of the following constants:
|
| If arg is 0, the calling process will be unregistered and will not receive further SIGPOLL signals for the stream associated with fd. Processes that wish to receive SIGPOLL signals must explicitly register to receive them using I_SETSIG. If several processes register to receive this signal for the same event on the same STREAM, each process will be signaled when the event occurs. The ioctl function with the I_SETSIG command will fail if:
|
|
| I_GETSIG | Returns the events for which the calling process is currently
registered to be sent a SIGPOLL signal. The events are returned as
a bitmask in an int pointed to by arg, where the events
are those specified in the description of I_SETSIG above. The ioctl function with the I_GETSIG command will fail if:
|
| I_FIND | The request compares the names of all modules currently present
in the STREAM to the name pointed to by arg, and returns 1
if the named module is present in the STREAM, or returns 0 if the
named module is not present. The ioctl function with the I_FIND command will fail if:
|
| I_PEEK | This request allows a process to retrieve the information in
the first message on the STREAM head read queue without taking the
message off the queue. It is analogous to getmsg except that
this command does not remove the message from the queue. The arg argument
points to a strpeek structure. The maxlen member in the ctlbuf and databuf strbuf structures must be set to the number of bytes of control information and/or data information, respectively, to retrieve. The flags member may be marked RS_HIPRI or 0, as described by getmsg. If the process sets flags to RS_HIPRI, for example, I_PEEK will only look for a high-priority message on the STREAM head read queue. I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was found on the STREAM head read queue, or if the RS_HIPRI flag was set in flags and a high-priority message was not present on the STREAM head read queue. It does not wait for a message to arrive. On return, ctlbuf specifies information in the control buffer, databuf specifies information in the data buffer, and flags contains the value RS_HIPRI or 0. |
| I_SRDOPT | Sets the read mode using the value of the argument arg.
Read modules are described in read. Valid arg flags
are:
The bitwise inclusive OR of RMSGD and RMSGN will return [EINVAL]. The bitwise inclusive OR of RNORM and either RMSGD or RMSGN will result in the other flag overriding RNORM which is the default. In addition, treatment of control messages by the STREAM head may be changed by setting any of the following flags in arg:
|
| I_GRDOPT | Returns the current read mode setting as, described above, in an int pointed to by the argument arg. Read modes are described in read. |
| I_NREAD | Counts the number of data bytes in the data part of the first message on the STREAM head read queue and places this value in the int pointed to by arg. The return value for the command is the number of messages on the STREAM head read queue. For example, if 0 is returned in arg, but the ioctl return value is greater than 0, this indicates that a zero-length message is next on the queue. |
| I_FDINSERT | Creates a message from a specified buffer(s), adds information
about another STREAM, and sends the message downstream. The message
contains a control part and an optional data part. The data and control
parts to be sent are distinguished by placement in separate buffers,
as described below. The arg argument points to a strfdinsert structure.
The len member in the ctlbuf strbuf structure must be set to the size of a t_uscalar_t plus the number of bytes of control information to be sent with the message. The fd member specifies the file descriptor of the other STREAM, and the offset member, which must be suitably aligned for use as a t_uscalar_t, specifies the offset from the start of the control buffer where I_FDINSERT will store a t_uscalar_t whose interpretation is specific to the STREAM end. The len member in the databuf strbuf structure must be set to the number of bytes of data information to be sent with the message, or to 0 if no data part is to be sent. The flags member specifies the type of message to be created. A normal message is created if flags is set to 0, and a high-priority message is created if flags is set to RS_HIPRI. For non-priority messages, I_FDINSERT will block if the STREAM write queue is full due to internal flow control conditions. For priority messages, I_FDINSERT does not block on this condition. For non-priority messages, I_FDINSERT does not block when the write queue is full and O_NONBLOCK is set. Instead, it fails and sets errno to [EAGAIN]. I_FDINSERT also blocks, unless prevented by lack of internal resources, waiting for the availability of message blocks in the STREAM, regardless of priority or whether O_NONBOCK has been specified. No partial message is sent. |
| The ioctl function with the I_FDINSERT command will fail if:
|
|
| I_STR | Constructs an internal STREAMS ioctl message from the
data pointed to by arg, and sends that message downstream.
This mechanism is provided to send ioctl requests to downstream modules and drivers. It allows information to be sent with ioctl, and returns to the process any information sent upstream by the downstream recipient. I_STR blocks until the system responds with either a positive or negative acknowledgment message, or until the request "times out" after some period of time. If the request times out, it fails with errno set to [ETIME]. At most, one I_STR can be active on a STREAM. Further I_STR calls will block until the active I_STR completes at the STREAM head. The default timeout interval for these requests is 15 seconds. The O_NONBLOCK flag has no effect on this call. To send requests downstream, arg must point to a strioctl structure. The ic_cmd member is the internal ioctl command intended for a downstream module or driver and ic_timeout is the number of seconds:
an I_STR request will wait for acknowledgment before timing out. ic_len is the number of bytes in the data argument, and ic_dp is a pointer to the data argument. The ic_len member has two uses:
The ioctl function with the I_STR command will fail if:
An I_STR can also fail while waiting for an acknowledgment if a message indicating an error or a hangup is received at the STREAM head. In addition, an error code can be returned in the positive or negative acknowledgment message, in the event the ioctl command sent downstream fails. For these cases, I_STR fails with errno set to the value in the message. |
| I_SWROPT | Sets the write mode using the value of the argument arg.
Valid bit settings for arg are:
The ioctl function with the I_SWROPT command will fail if:
|
| I_GWROPT | Returns the current write mode setting, as described above, in the int that is pointed to by the argument arg. |
| I_SENDFD | I_SENDFD creates a new reference to the open file description,
associated with the file descriptor arg, and writes a message
on the STREAMS-based pipe fd containing this reference, together
with the user ID and group ID of the calling process. The ioctl function with the I_SENDFD command will fail if:
|
| I_RECVFD | Retrieves the reference to an open file description from a
message written to a STREAMS-based pipe using the I_SENDFD command,
and allocates a new file descriptor in the calling process that refers
to this open file description. The arg argument is a pointer
to an strrecvfd data structure as defined in stropts.h.
The fd member is a file descriptor. The uid and gid members are the effective user ID and group ID, respectively, of the sending process. If O_NONBLOCK is not set, I_RECVFD blocks until a message is present at the STREAM head. If O_NONBLOCK is set, I_RECVFD fails with errno set to [EAGAIN] if no message is present at the STREAM head. If the message at the STREAM head is a message sent by an I_SENDFD, a new file descriptor is allocated for the open file descriptor referenced in the message. The new file descriptor is placed in the fd member of the strrecfd structure pointed to by arg. The ioctl function with the I_RECVFD command will fail it:
|
| I_LIST | This request allows the process to list all the module names
on the STREAM, up to an including the topmost driver name. If arg is
a null pointer, the return value is the number of modules, including
the driver, that are on the STREAM pointed to by fd. This
lets the process allocate enough space for the module names. Otherwise,
it should point to an str_list structure. The sl_nmods member indicates the number of entries that process has allocated in the array. Upon return, the sl_modlist member of the str_list structure contains the list of module names, and the number of entries that have been filled into the sl_modlist array is found in the sl_nmods member (the number includes the number of modules including the driver)> The return value from ioctl is 0. The entries are filled in starting at the top of the STREAM and continuing downstream until either the end of the STREAM is reached, or the number of requested modules (sl_nmods) is satisfied. The ioctl function with the I_LIST command will fail it:
|
| I_ATMARK | This request allows the process to see if the message at the
head of the STREAM head read queue is marked by some module downstream.
The arg argument determines how the checking is done when
there may be multiple marked messages on the STREAM head read queue.
It may take on the following values:
The bitwise inclusive OR of the flags ANYMARK and LASTMARK is permitted. The return value is 1 if the mark condition is satisfied and 0 otherwise. The ioctl function with the I_ATMARK command will fail if:
|
| I_CKBAND | Check if the message of given priority band exists on the
STREAM head read queue. This returns 1 if a message of the given
priority exists, 0 if no such message exists, or -1 on error. arg should
be of type int. The ioctl function with the I_CKBAND command will fail if:
|
| I_GETBAND | Return the priority band of the first message on the STREAM
head read queue in the integer referenced by arg. The ioctl function with the I_GETBAND command will fail if:
|
| I_CANPUT | Check if a certain band is writable. arg is set to
the priority band in question. The return value is 0 if the band
is flow-controlled, 1 if the band is writable, or -1 on error. The ioctl function with the I_CANPUT command will fail if:
|
| I_SETCLTIME | This request allows the process to set the time the STREAM
head will delay when a STREAM is closing and there is no data on the
write queues. Before closing each module or driver, if there is data
on its write queue, the STREAM head will delay for the specified
amount of time to allow the data to drain. If, after the delay, data
is still present, they will be flushed. The arg argument is
a pointer to an integer specifying the number of milliseconds to delay,
rounded up to the nearest valid value. If I_SETCLTIME is not performed
on a STREAM, an implementation-dependent default timeout interval
is used. The ioctl function with the I_SETCLTIME command will fail if:
|
| I_GETCLTIME | This request returns the close time delay in the integer pointed to by arg. |
Multiplexed STREAMS Configurations
The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations. These commands use an implementation-dependent default timeout interval.
| Item | Description |
|---|---|
| I_LINK | Connects two STREAMS, where fd is the file descriptor
of the STREAM connected to the multiplexing driver, and arg is
the file descriptor of the STREAM connected to another driver. The
STREAM designated by arg gets connected below the multiplexing
driver. I_LINK requires the multiplexing driver to send an acknowledgment
message to the STREAM head regarding the connection. This call returns
a multiplexer ID number (an identifier used to disconnect the multiplexer;
see I_UNLINK) on success, and -1 on failure. The ioctl function with the I_LINK command will fail if:
An I_LINK can also fail while waiting for the multiplexing driver to acknowledge the request, if a message indicating an error or a hangup is received at the STREAM head of fd. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_LINK fails with errno set to the value in the message. |
| I_UNLINK | Disconnects the two STREAMS specified by fd and arg.
fd is the file descriptor of the STREAM connected to the multiplexing
driver. The arg argument is the multiplexer ID number that
was returned by the I_LINK ioctl command when a STREAM was
connected downstream from the multiplexing driver. If arg is
MUXID_ALL, then all STREAMS that were connected to fd are disconnected.
As in I_LINK, this command requires acknowledgment. The ioctl function with the I_UNLINK command will fail if:
An I_UNLINK can also fail while waiting for the multiplexing driver to acknowledge the request is a message indicating an error or a hangup is received at the STREAM head of fd. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_UNLINK fails with errno set to the value in the message. |
| I_PLINK | Creates a persistent connection between two STREAMS,
where fd is the file descriptor of the STREAM connected to
the multiplexing driver, and arg is the file descriptor of
the STREAM connected to another driver. This call creates a persistent
connection which can exist even if the file descriptor fd associated
with the upper STREAM to the multiplexing driver is closed. The STREAM
designated by arg gets connected via a persistent connection
below the multiplexing driver. I_PLINK requires the multiplexing
driver to send an acknowledgment to the STREAM head. This call returns
a multiplexer ID number (an identifier that may be used to disconnect
the multiplexer; see I_PUNLINK) on success, and -1 on failure. The ioctl function with the I_PLINK command will fail if:
An I_PLINK can also fail while waiting for the multiplexing driver to acknowledge the request, if a message indicating an error or a hangup is received at the STREAM head of fd. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_PLINK fails with errno set to the value in the message. |
| I_PUNLINK | Disconnects the two STREAMS specified by fd and arg from
a persistent connection. The fd argument is the file descriptor
of the STREAM connected to the multiplexing driver. The arg argument
is the multiplexer ID number that was returned by the I_PLINK ioctl command
when a STREAM was connected downstream from the multiplexing driver.
If arg is MUXID_ALL than all STREAMS which are persistent
conditions to fd are disconnected. As in I_PLINK, this command
requires the multiplexing driver to acknowledge the request. The ioctl function with the I_PUNLINK command will fail if:
An I_PUNLINK can also fail while waiting for the multiplexing driver to acknowledge the request if a message indicating an error or a hangup is received at the STREAM head of fd. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_PUNLINK fails with errno set to the value in the message. |
Upon successful completion, ioctl returns a value other than -1 that depends upon the STREAMS device control function. Otherwise, it returns -1 and sets errno to indicate the error.
Under the following general conditions, ioctl will fail if:
| Item | Description |
|---|---|
| [EBADF] | The fd argument is not a valid open file descriptor. |
| [EINTR] | A signal was caught during the ioctl operation. |
| [EINVAL] | The STREAM or a multiplexer referenced by fd is linked (directly or indirectly) downstream from a multiplexer. |
If an underlying device driver detects an error, then ioctl will fail if:
| Item | Description |
|---|---|
| [EINVAL] | The request or arg argument is not valid for this device. |
| [EIO] | Some physical I/O error has occurred. |
| [ENOTTY] | The fd argument is not associated with a STREAMS device that accepts control functions. A file descriptor was obtained from a call to the shm_open subroutine. |
| [ENXIO] | The request and arg arguments are valid for this device driver, but the service requested cannot be performed on this particular sub-device. |
| [ENODEV] | The fd argument refers to a valid STREAMS device, but the corresponding device driver does not support the ioctl function. |
If a STREAM is connected downstream from a multiplexer, and ioctl command except I_UNLINK and I_PUNLINK will set errno to [EINVAL].
The implementation-dependent timeout interval for STREAMS has historically been 15 seconds.