DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

streamio(M)


streamio -- STREAMS ioctl commands

Syntax

#include <stropts.h>

int ioctl (fildes, command, arg)
int fildes, command, arg;

Description

STREAMS ioctl(S) commands perform a variety of control functions on ``streams.'' The arguments command and arg are passed to the file designated by fildes and are interpreted by the ``stream head.'' Certain combinations of these arguments may be passed to a module or driver in the stream.

fildes is an open file descriptor that refers to a stream. command determines the control function to be performed as described below. arg represents additional information that is needed by this command. The type of arg depends upon the command, but it is generally an integer (int), or a pointer to a command-specific data structure.

Since these STREAMS commands are a subset of ioctl, they are subject to the errors described there. In addition to those errors, the call will fail with errno set to EINVAL, without processing a control function, if the stream referenced by fildes is linked below a multiplexer, or if command is not a valid value for a stream.

Also, as described in ioctl(S), STREAMS modules and drivers can detect errors. In this case, the module or driver sends an error message to the stream head containing an error value. This causes subsequent system calls to fail with errno set to this value.

STREAMS ioctl commands

The following ioctl commands, with error values indicated, are applicable to all STREAMS files:

I_PUSH
Push the module whose name is pointed to by arg onto the top of the current stream, just below the stream head. Then call the open routine of the newly-pushed module.

On failure, errno is set to one of the following values:


[EINVAL]
Invalid module name.

[EFAULT]
arg points outside the allocated address space.

[ENXIO]
Open routine of new module failed.

[ENXIO]
Hangup received on fildes.

I_POP
Remove the module just below the stream head of the stream pointed to by fildes. arg should be 0 in an I_POP request. On failure, errno is set to one of the following values:

[EINVAL]
No module present in the stream.

[ENXIO]
Hangup received on fildes.

I_LOOK
Retrieve the name of the module just below the stream head of the stream pointed to by fildes, and place it in a null terminated character string pointed at by arg. The buffer pointed to by arg should be at least FMNAMESZ+1 bytes long. An #include <sys/conf.h> declaration is required. On failure, errno is set to one of the following values:

[EFAULT]
arg points outside the allocated address space.

[EINVAL]
No module present in stream.

I_FLUSH
Flush all input and/or output queues, depending on the value of arg. Legal arg values are:

FLUSHR
Flush read queues.

FLUSHW
Flush write queues.

FLUSHRW
Flush read and write queues.

On failure, errno is set to one of the following values:


[ENOSR]
Unable to allocate buffers for flush message due to insufficient STREAMS memory resources.

[EINVAL]
Invalid arg value.

[ENXIO]
Hangup received on fildes.


I_FLUSHBAND
Flush a band of messages where arg points to a bandinfo structure. The bi_pri member should be set to the band to be flushed. The bi_flag member must be one of FLUSHR, FLUSHW, or FLUSHRW as described for I_FLUSH.

I_SETSIG
Inform the stream head that the user wishes the kernel to issue the SIGPOLL signal (see signal(S) and sigset(S)) when a particular event has occurred on the stream associated with fildes. I_SETSIG supports an asynchronous processing capability in STREAMS. The value of arg is a bitmask that specifies the events for which the user should be signaled. It is the bitwise-OR of any combination of the following constants:

S_BANDURG
If S_RDBAND is set, signal SIGUSR1 is generated instead of SIGPOLL.

S_ERROR
An M_ERROR message has reached the stream head.

S_HANGUP
An M_HANGUP message has reached the stream head.

S_INPUT
A non-priority message has arrived on a stream head read queue, and no other messages existed on that queue before this message was placed there. This is set even if the message is of zero length.

S_HIPRI
A priority message is present on the stream head read queue. This is set even if the message is of zero length.

S_MSG
A STREAMS signal message that contains the SIGPOLL signal has reached the front of the stream head read queue.

S_OUTPUT
The write queue for normal (band zero) messages just below the stream head is no longer full. This notifies the user that there is room on the queue for sending (or writing) normal data downstream.

S_RDBAND
A non-zero priority band message (even if zero length) has arrived.

S_RDNORM
A normal (priority band zero) message (even if zero length) has arrived.

S_WRBAND
The write queue for a non-zero priority band is no longer full.

S_WRNORM
Equivalent to S_OUTPUT.

A user process may choose to be signaled only of priority messages by setting the arg bitmask to the value S_HIPRI.

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.

If the value of arg is zero, the calling process will be unregistered and will not receive further SIGPOLL signals. On failure, errno is set to one of the following values:


[EINVAL]
arg value is invalid or arg is zero and process is not registered to receive the SIGPOLL signal.

[EAGAIN]
Allocation of a data structure to store the signal request failed.

I_GETSIG
Return the events for which the calling process is currently registered to be sent a SIGPOLL signal. The events are returned as a bitmask pointed to by arg, where the events are those specified in the description of I_SETSIG above. On failure, errno is set to one of the following values:

[EINVAL]
Process not registered to receive the SIGPOLL signal.

[EFAULT]
arg points outside the allocated address space.

I_FIND
Compare 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. It returns 0 if the named module is not present. On failure, errno is set to one of the following values:

[EFAULT]
arg points outside the allocated address space.

[EINVAL]
arg does not contain a valid module name.


I_PEEK
Allow retrieval of information in the first message on the stream head read queue without taking the message off the queue. arg points to a strpeek structure which contains the following members:
struct strbuf	ctlbuf;
struct strbuf	databuf;
long		flags;
The maxlen field in the ctlbuf and databuf strbuf structures (see getmsg(S)) must be set to the number of bytes of control information and/or data information, respectively, to retrieve. If the user sets flags to RS_HIPRI, I_PEEK will only look for a 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 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 0 or RS_HIPRI. On failure, errno is set to one of the following values:


[EFAULT]
arg points, or the buffer area specified in ctlbuf or databuf is, outside the allocated address space.

[EBADMSG]
Queued message to be read is not valid for I_PEEK.

I_SRDOPT
Set the read mode using the value of the argument arg. Legal arg values are:

RMSGD
Message-discard mode.

RMSGN
Message-nondiscard mode.

RNORM
Byte-stream mode, the default.

The following flags change how the stream head handles control messages:


RPROTDAT
Deliver a message's control portion as data when issuing a read(S).

RPROTDIS
Deliver the data portion of a message but drop the control portion when issuing a read.

RPROTNORM
If a control message is at the front of the read queue in the stream head, fail read and set [EBADMSG] in errno.

Read modes are described in read. On failure, errno is set to the following value:


[EINVAL]
arg is not one of the above legal values.


I_GRDOPT
Return the current read mode setting in an int pointed to by the argument arg. Read modes are described in LR read S . On failure, errno is set to the following value:

[EFAULT]
arg points outside the allocated address space.


I_NREAD
Count the number of data bytes in data blocks in the first message on the stream head read queue, and place this value in the location pointed to by arg. The return value for the command is the number of messages on the stream head read queue. For example, if zero is returned in arg, but the ioctl return value is greater than zero, this indicates that a zero-length message is next on the queue. On failure, errno is set to the following value:

[EFAULT]
arg points outside the allocated address space.


I_FDINSERT
Create a message from user-specified buffer(s), add information about another stream, and send 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.

arg points to a strfdinsert structure which contains the following members:

struct strbuf	ctlbuf;
struct strbuf	databuf;
long		flags;
int		fildes;
int		offset;
The len field in the ctlbuf strbuf structure (see putmsg(S)) must be set to the size of a pointer plus the number of bytes of control information to be sent with the message. fildes in the strfdinsert structure specifies the file descriptor of the other stream. offset, which must be word-aligned, specifies the number of bytes beyond the beginning of the control buffer where I_FDINSERT will store a pointer. This pointer will be the address of the read queue structure of the driver for the stream corresponding to fildes in the strfdinsert structure. The len field in the databuf strbuf structure must be set to the number of bytes of data information to be sent with the message or zero if no data part is to be sent.

flags specifies the type of message to be created. A non-priority message is created if flags is set to 0, and a 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_NDELAY 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_NDELAY has been specified. No partial message is sent. On failure, errno is set to one of the following values:


[EAGAIN]
A non-priority message was specified, the O_NDELAY flag is set, and the stream write queue is full due to internal flow control conditions.

[ENOSR]
Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources.

[EFAULT]
arg points, or the buffer area specified in ctlbuf or databuf is, outside the allocated address space.

[EINVAL]
One of the following: fildes in the strfdinsert structure is not a valid, open stream file descriptor; the size of a pointer plus offset is greater than the len field for the buffer specified through ctlptr; offset does not specify a properly aligned location in the data buffer; an undefined value is stored in flags.

[ENXIO]
Hangup received on fildes of the ioctl call or fildes in the strfdinsert structure.

[ERANGE]
The len field for the buffer specified through databuf does not fall within the range specified by the maximum and minimum packet sizes of the topmost stream module, or the len field for the buffer specified through databuf is larger than the maximum configured size of the data part of a message, or the len field for the buffer specified through ctlbuf is larger than the maximum configured size of the control part of a message.

I_FDINSERT can also fail if an error message was received by the stream head of the stream corresponding to fildes in the strfdinsert structure. In this case, errno will be set to the value in the message.


I_STR
Construct an internal STREAMS ioctl message from the data pointed to by arg, and send that message downstream.

This mechanism is provided to send user ioctl requests to downstream modules and drivers. It allows information to be sent with the ioctl and will return to the user 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_NDELAY (see open(S)) flag has no effect on this call.

To send requests downstream, arg must point to a strioctl structure which contains the following members:

int	ic_cmd;		/* downstream command */
int	ic_timout;	/* ACK/NAK timeout */
int	ic_len;		/* length of data arg */
char	*ic_dp;		/* ptr to data arg */
ic_cmd is the internal ioctl command intended for a downstream module or driver; and ic_timout is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) 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 field has two uses: on input, it contains the length of the data argument passed in, and on return from the command, it contains the number of bytes being returned to the user (the buffer pointed to by ic_dp should be large enough to contain the maximum amount of data that any module or the driver in the stream can return).

The stream head will convert the information pointed to by the strioctl structure to an internal ioctl command message and send it downstream.

On failure, errno is set to one of the following values:


[ENOSR]
Unable to allocate buffers for the ioctl message due to insufficient STREAMS memory resources.

[EFAULT]
arg points, or the buffer area specified by ic_dp and ic_len (separately for data sent and data returned), is outside the allocated address space.

[EINVAL]
ic_len is less than 0 or ic_len is larger than the maximum configured size of the data part of a message or ic_timout is less than -1.

[ENXIO]
Hangup received on fildes.

[ETIME]
A downstream ioctl timed out before acknowledgment was received.

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 that the ioctl command sent downstream fails. For these cases, I_STR will fail with errno set to the value in the message.


I_SWROPT
Set the write mode to the value of arg. Legal settings are:

SNDZERO
Send zero-length message downstream on a write(S) of 0 bytes.
Set arg to 0 to prevent a zero-length message being sent on a write of 0 bytes.

If the value of arg is invalid, errno is set to [EINVAL].


I_GWROPT
Return the current write mode setting (as set by I_SWROPT), as the int pointed to be arg.

I_SENDFD
Request the stream associated with fildes to send a message, containing a file pointer, to the stream head at the other end of a stream pipe. The file pointer corresponds to arg, which must be an integer file descriptor.

I_SENDFD converts arg into the corresponding system file pointer. It allocates a message block and inserts the file pointer in the block. The user id and group id associated with the sending process are also inserted. This message is placed directly on the read queue (see Intro(S)) of the stream head at the other end of the stream pipe to which it is connected. On failure, errno is set to one of the following values:


[EAGAIN]
The sending stream is unable to allocate a message block to contain the file pointer.

[EAGAIN]
The read queue of the receiving stream head is full and cannot accept the message sent by I_SENDFD.

[EBADF]
arg is not a valid, open file descriptor.

[EINVAL]
fildes is not connected to a stream pipe.

[ENXIO]
Hangup received on fildes.


I_RECVFD
Retrieve the file descriptor associated with the message sent by an I_SENDFD ioctl over a stream pipe. arg is a pointer to a data buffer large enough to hold an strrecvfd data structure containing the following members:
int fd;
unsigned short uid;
unsigned short gid;
char fill[8];
fd is an integer file descriptor. uid and gid are the user id and group id, respectively, of the sending stream.

If O_NDELAY is not set (see open(S)), I_RECVFD will block until a message is present at the stream head. If O_NDELAY is set, I_RECVFD will fail 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 user file descriptor is allocated for the file pointer contained in the message. The new file descriptor is placed in the fd field of the strrecvfd structure. The structure is copied into the user data buffer pointed to by arg.

On failure, errno is set to one of the following values:


[EAGAIN]
A message was not present at the stream head read queue, and the O_NDELAY flag is set.

[EBADMSG]
The message at the stream head read queue was not a message containing a passed file descriptor.

[EFAULT]
arg points outside the allocated address space.

[EMFILE]
No files file descriptors are currently open.

[ENXIO]
Hangup received on fildes.

I_LIST
List all module names on a stream pointed to by fildes, including the topmost driver name. If arg is set to NULL, the return value is the number of modules including the driver. Otherwise, arg should point to a str_list structure. Set the sl_nmods member to the number of str_mlist structures allocated to the sl_modlist member pointer. The return value is the number of str_mlist structures that have been filled-in. The sl_mlist structure contains char l_name[FMNAMESZ+1] as the name of the module.

On failure, errno is set to one of the following values:


[EAGAIN]
Cannot allocate buffers.

[EINVAL]
sl_nmods is less than or equal to 0.


I_ATMARK
Determine if the current message on the stream head read queue is marked by a downstream module. The following arg values determine how to perform checking given that there may be multiple marked messages on the queue:

ANYMARK
Check if message is marked.

LASTMARK
Check if message is last one marked on queue.

The ioctl call returns 1 if the mark condition is satisfied; otherwise, it returns 0. On failure, errno is set to [EINVAL] if the value of arg is invalid.


I_CKBAND
Check if a message of the specified priority band (indicated by the int value of arg) exists on the stream head read queue. ioctl returns 1 if such a message exists; otherwise, it returns 0. On failure, errno is set to [EINVAL] if the value of arg is invalid.

I_GETBAND
Return the priority band of the first message on the stream head read queue as the int pointed to by arg. On failure, errno is set to [ENODATA] if no such message exists.

I_CANPUT
Check if the specified priority band (indicated by the int value of arg) can be written to. ioctl returns 0 if flow-control exists on the band; otherwise, it returns 1 if the band is writable. On failure, errno is set to [EINVAL] if the value of arg is invalid.

I_SETCLTIME
Set the time that the stream head will delay before closing each module or driver if data still exists on its write queue and must be allowed to drain. Set arg to the delay time in milliseconds, rounded up to the nearest legal system value; the default value is 15000. On failure, errno is set to [EINVAL] if the value of arg is invalid.

I_GETCLTIME
Return the stream head delay time (in milliseconds) in the int pointed to by arg.

The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.


I_LINK

I_PLINK
Connect two streams, where fildes 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_PLINK creates a persistent link that can exist even if fildes is closed.

Both I_LINK and I_PLINK require the multiplexing driver to send an acknowledgment message to the stream head regarding the linking operation.

These calls return a multiplexer ID number (an identifier used to disconnect the multiplexer, see I_UNLINK and I_PUNLINK) on success, and a -1 on failure. On failure, errno is set to one of the following values:


[ENXIO]
Hangup received on fildes.

[ETIME]
Time out before acknowledgment message was received at stream head.

[EAGAIN]
Temporarily unable to allocate storage to perform the I_LINK or I_PLINK.

[ENOSR]
Unable to allocate storage to perform the I_LINK or I_PLINK due to insufficient STREAMS memory resources.

[EBADF]
arg is not a valid, open file descriptor.

[EINVAL]
fildes stream does not support multiplexing.

[EINVAL]
arg is not a stream, or is already linked under a multiplexer.

[EINVAL]
The specified link operation would cause a ``cycle'' in the resulting configuration; that is, if a given stream head is linked into a multiplexing configuration in more than one place.

An I_LINK or I_PLINK can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error, or a hangup is received at the stream head of fildes. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_LINK or I_PLINK will fail with errno set to the value in the message.

I_UNLINK

I_PUNLINK
Disconnect the two streams specified by fildes and arg. fildes is the file descriptor of the stream connected to the multiplexing driver. fildes must correspond to the stream on which a previous ioctl I_LINK (for I_UNLINK) or I_PLINK (for I_PUNLINK) command was issued to link the stream below the multiplexing driver. arg is the multiplexer ID number that was returned by I_LINK or I_PLINK. If arg is MUXID_ALL, all streams of the same type are unlinked that were linked to fildes. When used with I_UNLINK, MUXID_ALL only unlinks all normal links. If arg is -1, all streams which were linked to fildes are disconnected.

As in I_LINK and I_PLINK, these commands require the multiplexing driver to acknowledge the unlink. On failure, errno is set to one of the following values:


[ENXIO]
Hangup received on fildes.

[ETIME]
Time out before acknowledgment message was received at stream head.

[ENOSR]
Unable to allocate storage to perform the I_UNLINK due to insufficient STREAMS memory resources.

[EINVAL]
arg is an invalid multiplexer ID number or fildes is not the stream on which the \I_LINK that returned arg was performed.

I_UNLINK or I_PUNLINK can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error or a hangup is received at the stream head of fildes. In addition, an error code can be returned in the positive or negative acknowledgment message. For these cases, I_UNLINK or I_PUNLINK will fail with errno set to the value in the message.

Return values

Unless specified otherwise above, the return value from ioctl is 0 upon success and -1 upon failure with errno set as indicated.

See also

close(S), fcntl(S), getmsg(S), Intro(S), ioctl(S), open(S), poll(S), putmsg(S), read(S), signal(S), sigset(S), write(S)

AT&T STREAMS Programmer's Guide
AT&T STREAMS Primer


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003