|
|
#include <stropts.h>
int ioctl (fildes, command, arg)
int fildes, command, arg;
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.
On failure, errno is set to one of the following values:
#include <sys/conf.h> declaration is required.
On failure, errno is set to one of the following values:
On failure, errno is set to one of the following values:
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.
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:
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:
ctlbuf or databuf is, outside the allocated address space.
The following flags change how the stream head handles control messages:
Read modes are described in read. On failure, errno is set to the following value:
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:
ctlbuf or databuf is, outside the allocated address space.
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.
fildes in the strfdinsert structure.
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.
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:
ic_dp
and ic_len (separately for data sent and data returned), is outside
the allocated address space.
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.
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.
If the value of arg is invalid, errno is set to [EINVAL].
int pointed to be
arg.
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:
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:
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:
sl_nmods is less than or equal to 0.
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.
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.
int pointed to by arg.
On failure, errno is set to
[ENODATA] if no such message exists.
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.
int pointed to by arg.
The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.
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:
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:
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.
AT&T STREAMS Programmer's Guide
AT&T STREAMS Primer