|
|
#include <sys/types.h> #include <stropts.h>int ioctl (int fildes, int 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 or a pointer to a command-specific data structure. The command and arg are interpreted by the stream head. Certain combinations of these arguments may be passed to a module or driver in the stream.
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(2), 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.
If a pipe or FIFO does not have any modules pushed, the read queue of the stream head on either end is flushed depending on the value of arg.
If FLUSHR is set and fildes is a pipe, the read queue for that end of the pipe is flushed and the write queue for the other end is flushed. If fildes is a FIFO, both queues are flushed.
If FLUSHW is set and fildes is a pipe and the other end of the pipe exists, the read queue for the other end of the pipe is flushed and the write queue for this end is flushed. If fildes is a FIFO, both queues of the FIFO are flushed.
If FLUSHRW is set, all read queues are flushed, that is, the read queue for the FIFO and the read queue on both ends of the pipe are flushed.
Correct flush handling of a pipe or FIFO with modules pushed is achieved via the pipemod module. This module should be the first module pushed onto a pipe so that it is at the midpoint of the pipe itself.
On failure, errno is set to one of the following values:
unsigned char bi_pri; int bi_flag;
The bi_flag field may be one of FLUSHR, FLUSHW, or
FLUSHRW as described earlier.
A user process may choose to be signaled only of high priority messages by setting the arg bitmask to the value S_HIPRI.
Processes that want 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(2))
must be set to
the number of bytes of control information and/or data information,
respectively, to retrieve.
flags may be set to RS_HIPRI or 0.
If RS_HIPRI is set, I_PEEK will look for a
high priority message on the stream head read queue.
Otherwise, I_PEEK will look for the first 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.
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.
On failure, errno is set to the following value:
ctlbuf or databuf is,
outside the allocated address space.
flags.
Setting both RMSGD and RMSGN is an error. RMSGD and RMSGN override RNORM.
In addition, treatment of control messages by the stream head may be changed by setting the following flags in arg:
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(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.
An ordinary (non-priority) message is created if flags is set to 0,
a high priority message is created if flags is set to RS_HIPRI.
For normal messages, I_FDINSERT will block if the stream write
queue is full due to internal flow control conditions.
For high priority messages, I_FDINSERT does not block
on this condition.
For normal messages, I_FDINSERT does not block when the
write queue is full and
O_NDELAY or
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,
regardless of priority or whether
O_NDELAY or
O_NONBLOCK 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 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 and O_NONBLOCK (see open(2)) flags have no effect on this call.
To send requests downstream, arg must point to a strioctl structure which contains the following members:
int ic_cmd; int ic_timout; int ic_len; char *ic_dp;
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 out.
The default timeout is infinite.
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 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.
To not send a zero-length message when a write of 0 bytes occurs, this bit must not be set in 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(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:
int fd; uid_t uid; gid_t 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 and O_NONBLOCK are clear (see open(2)) I_RECVFD will block until a message is present at the stream head. If O_NDELAY or O_NONBLOCK 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:
int fd; uid_t uid; gid_t gid; struct sub_attr s_attrs;
fd is an integer file descriptor. uid and gid are the user ID and group ID, respectively, of the sending stream. sub_attr contains security relevant information. The sub_attr structure is used as an argument for the secadvise(2) system call, which provides advisory access information.
If O_NDELAY and O_NONBLOCK are clear (see open(2)), I_RECVFD will block until a message is present at the stream head. If O_NDELAY or O_NONBLOCK 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 s_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:
int sl_nmods; struct str_mlist *sl_modlist;
The str_mlist structure has the following member:
char l_name[FMNAMESZ+1];
sl_nmods indicates the number of entries the user has allocated in the array.
On success, the return value is 0, sl_modlist 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.
On failure, errno may be set to one of the following values:
sl_nmods member is less than 1.
If both ANYMARK and LASTMARK are set, ANYMARK supersedes LASTMARK.
The return value is 1 if the mark condition is satisfied and 0 otherwise. On failure, errno may be set to the following value:
The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations.
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.
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.
An I_PLINK can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error on 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_PLINK will fail with errno set to the value in the message.
An 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 acknowledgement message. For these cases, I_PUNLINK will fail with errno set to the value.