STREAMIO(7)STREAMIO(7)NAMEstreamio - STREAMS ioctl commands
SYNOPSIS
#include <stropts.h>
int ioctl (fildes, command, arg)
int fildes, command;
DESCRIPTION
STREAMS [see intro(2)] ioctl commands are a subset of ioctl(2) system
calls which 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 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 multiplexor, or if
command is not a valid value for a stream.
Also, as described in ioctl, 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.
In previous IRIX releases it was possible to use these operations on
socket file descriptors by linking with -lsocket; this is no longer true
starting with IRIX 6.2.
COMMAND FUNCTIONS
The following ioctl commands, with error values indicated, are applicable
to all STREAMS files:
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 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.
Page 1
STREAMIO(7)STREAMIO(7)
[ENXIO] Hangup received on fildes.
I_POP Removes 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 Retrieves the name of the module just below the stream head
of the stream pointed to by fildes, and places 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_LIST Retrieves the entire list of modules between the stream head
of the stream pointed to by fildes, and the driver. If arg
is NULL, then the number of modules is returned. Otherwise,
arg should point to a struct str_list. On input, the member
sl_nmods should be set to the maximum number of module name
the caller is ready to accept, and the member sl_modlist
should point to an array of struct str_mlist dats structures
with at least str_nmods elements. On successful return, the
member sl_nmods will be updated to reflect the actual number
of module names returned. On failure, errno is set to one
of the following values:
[EFAULT] arg points outside the allocated address space.
[EINVAL] The value of sl_nmods is less than or equal to
zero.
[ENOSPC] The value of sl_nmods is less than the actual
number of modules.
I_FLUSH This request flushes 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.
Page 2
STREAMIO(7)STREAMIO(7)
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_SETSIG Informs the stream head that the user wishes the kernel to
issue the SIGPOLL signal [see signal(2) and sigset(2)] 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_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_OUTPUT The write queue just below the stream head is
no longer full. This notifies the user that
there is room on the queue for sending (or
writing) data downstream.
S_MSG A STREAMS signal message that contains the
SIGPOLL signal has reached the front of the
stream head read queue.
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:
Page 3
STREAMIO(7)STREAMIO(7)
[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 Returns 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. arg is assumed to point to an int. 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 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. 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 Allows a user to retrieve the 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 strbufctlbuf;
struct strbufdatabuf;
long flags;
The maxlen field in the ctlbuf and databuf strbuf structures
[see getmsg(2)] 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 the following
Page 4
STREAMIO(7)STREAMIO(7)
value:
[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 Sets the read mode using the value of the argument arg.
Legal arg values are:
RNORM Byte-stream mode, the default.
RMSGD Message-discard mode.
RMSGN Message-nondiscard mode.
Read modes are described in read(2). On failure, errno is
set to the following value:
[EINVAL] arg is not one of the above legal values.
I_GRDOPT Returns the current read mode setting in an int pointed to
by the argument arg. Read modes are described in read(2).
On failure, errno is set to the following value:
[EFAULT] arg points outside the allocated address space.
I_NREAD Counts the number of data bytes in data blocks in the first
message on the stream head read queue, and places this value
in the location pointed to by arg. arg is assumed to be a
pointer to an int. 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 Creates a message from user 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.
arg points to a strfdinsert structure which contains the
following members:
struct strbufctlbuf;
struct strbufdatabuf;
Page 5
STREAMIO(7)STREAMIO(7)
long flags;
int fildes;
int offset;
The len field in the ctlbuf strbuf structure [see putmsg(2)]
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
Page 6
STREAMIO(7)STREAMIO(7)
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 Constructs an internal STREAMS ioctl message from the data
pointed to by arg, and sends 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 acknowledgement 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(2)] 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 acknowledgement before timing
Page 7
STREAMIO(7)STREAMIO(7)
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
acknowledgement was received.
An I_STR can also fail while waiting for an acknowledgement
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 acknowledgement message, in the
event the ioctl command sent downstream fails. For these
cases, I_STR will fail with errno set to the value in the
message.
I_SWROPT Sets the write mode bits using the value of the argument
arg. Legal bit settings for arg are:
SNDZERO Send a zero-length message downstream when a
write of 0 bytes occurs on pipes and FIFOs.
SNDPIPE Send SIGPIPE to process if sd_werror is set and
the process is doing a write or putmsg.
SNDHOLD Activate the STRHOLD feature.
Page 8
STREAMIO(7)STREAMIO(7)
On failure, errno may be set to the following value:
EINVAL arg is not a valid value.
I_GWROPT Returns the current write mode setting, as described above,
in the int that is pointed to by the argument arg.
I_SENDFD Requests 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(2)] 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 Retrieves 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;
uid_t uid;
gid_t gid;
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(2)], 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.
Page 9
STREAMIO(7)STREAMIO(7)
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] NOFILES file descriptors are currently open.
[ENXIO] Hangup received on fildes.
I_SETCLTIME Sets the stream head close time to the integer value pointed
to by arg. The stream head close time is the maximum amount
of time, in seconds, that the stream head will wait during
close for the stream's output queues to empty before calling
each module's or driver's close function. The default value
is 15 seconds. On failure, errno is set to one of the
following values:
[EFAULT] arg points outside the allocated address space.
[EINVAL] arg points to a value less than 0.
I_GETCLTIME Returns the current value of the stream head close time
(defined above) in the integer pointed to by arg. On
failure, errno is set to one of the following values:
[EFAULT] arg points outside the allocated address space.
The following two commands are used for connecting and disconnecting
multiplexed STREAMS configurations.
I_LINK Connects 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_LINK requires the multiplexing
driver to send an acknowledgement message to the stream head
regarding the linking operation. This call returns a
multiplexor ID number (an identifier used to disconnect the
multiplexor, see I_UNLINK) on success, and a -1 on failure.
On failure, errno is set to one of the following values:
Page 10
STREAMIO(7)STREAMIO(7)
[ENXIO] Hangup received on fildes.
[ETIME] Time out before acknowledgement message was
received at stream head.
[EAGAIN] Temporarily unable to allocate storage to
perform the I_LINK.
[ENOSR] Unable to allocate storage to perform the
I_LINK 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 multiplexor.
[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 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 acknowledgement message. For
these cases, I_LINK will fail with errno set to the value in
the message.
I_UNLINK Disconnects 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 the ioctl I_LINK command was issued to link the
stream below the multiplexing driver. arg is the
multiplexor ID number that was returned by the I_LINK. If
arg is -1, then all Streams which were linked to fildes are
disconnected. As in I_LINK, this command requires 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 acknowledgement message was
received at stream head.
[ENOSR] Unable to allocate storage to perform the
I_UNLINK due to insufficient STREAMS memory
resources.
Page 11
STREAMIO(7)STREAMIO(7)
[EINVAL] arg is an invalid multiplexor ID number or
fildes is not the stream on which the I_LINK
that returned arg was performed.
An I_UNLINK 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 acknowledgement message. For
these cases, I_UNLINK will fail with errno set to the value
in the message.
FIONREAD Counts the number of data bytes in data blocks in the first
message on the stream head read queue, and places this value
in the location pointed to by arg. arg is assumed to be a
pointer to an int.
FIORDCHK Counts the number of data bytes in data blocks in the first
message on the stream head read queue, and returns this
value.
FIONBIO Enables or disables non-blocking mode, according to the
boolean value of the contents of arg. arg is a pointer to
an int. Enabling this mode has the same effect as the
O_NDELAY flag for open(2).
SEE ALSOclose(2), fcntl(2), intro(2), ioctl(2), open(2), read(2), getmsg(2),
poll(2), putmsg(2), signal(2), sigset(2), write(2), termio(7)DIAGNOSTICS
Unless specified otherwise above, the return value from ioctl is 0 upon
success and -1 upon failure with errno set as indicated.
Page 12
