streamio.7 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

streamio(7) streamio(7)

NAME

streamio - STREAMS ioctl commands

SYNOPSIS

#include <sys/types.h>

#include <stropts.h>

int ioctl(int ﬁldes, int command,

... /* arg */);

DESCRIPTION

STREAMS ioctl commands are a subset of the

ioctl() system calls which perform a variety of con-

trol functions on streams.

ﬁldes is an open ﬁle 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-

speciﬁc 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 ﬁldes 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.

The following

ioctl commands, with error values indicated, are applicable to all STREAMS ﬁles:

I_ATMARK Allows the user to see if the current message on the stream head read queue is

"marked" by some module downstream. arg determines how the checking is done

when there are multiple marked messages on the stream head read queue. It may

take the following values:

ANYMARK Checks if the message is marked.

LASTMARK Checks if the message is the last one that is marked on the queue.

If both

ANYMARK and LASTMARK are set, ANYMARK supersedes LASTMARK.

The return value is 1 if the mark condition is satisﬁed and 0 otherwise.

I_CANPUT Checks if a certain band is writable. arg is set to the priority band in question. The

return value is 0 if the priority band arg is ﬂow controlled, 1 if the band is writable,

or −1 on error.

I_CKBAND Check if the message of a given priority band exists on the stream head read queue.

This returns 1 if a message of a given priority exists, or −1 on error. arg should be

an integer containing the value of the priority band in question.

I_FDINSERT Creates a message from user speciﬁed 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 strbuf ctlbuf;

struct strbuf databuf;

long flags;

int fildes;

int offset;

The len ﬁeld 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. ﬁldes in the strfdinsert structure speciﬁes the ﬁle descriptor of the

other stream. offset, which must be word-aligned, speciﬁes 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

streams corresponding to ﬁldes in the strfdinsert structure. The len ﬁeld in

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (10 pages)

PAGE 1
streamio(7) streamio(7) NAME streamio - STREAMS ioctl commands SYNOPSIS #include #include int ioctl(int fildes , int command, ... /* arg */); DESCRIPTION STREAMS ioctl commands are a subset of the ioctl() system calls which perform a variety of control functions on streams. 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.
PAGE 2
streamio(7) streamio(7) 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.
PAGE 3
streamio(7) streamio(7) value on the system. The default is fifteen seconds. I_GETSIG Returns the events for which the calling process has registered to receive a SIGPOLL signal. Events are returned as in arg bitmask as defined for the I_SETSIG command. I_GRDOPT Returns the current read mode setting in an int pointed to by the argument arg. Read modes are described in read (2).
PAGE 4
streamio(7) streamio(7) The I_PEEK returns a 1 if a message was retrieved, and returns a value of 0 (zero) if no message was found; it does not wait for a message. Upon successful completion, ctlbuf specifies control information in the control buffer, databuf specifies data information in the data buffer, and flags contains RS_HIPRI or 0 (zero).
PAGE 5
streamio(7) streamio(7) I_SETCLTIME Lets the user process set the time that the stream head delays when the stream is closing and the write queues contain data. The arg parameter contains a pointer to the number of milliseconds to delay, rounded up to the nearest legal value on the system. The default time is 15 seconds. Before STREAMS modules and drivers are closed, the stream head delays for the specified amount of time. This allows the data on the write queues to drain.
PAGE 6
streamio(7) streamio(7) Message-nondiscard mode. RMSGN Setting both RMSGD and RMSGN is an error. RMSGD and RMSGN override NORM. In addition, treatment of control messages by the stream head may be changed by setting the following flags in arg: I_STR RPROTNORM Fail read with EBADMSG if a control message is at the front of the stream head read queue. This is the default behavior. RPROTDAT Deliver the control portion of a message as data when a user issues read.
PAGE 7
streamio(7) streamio(7) ERRORS A STREAMS ioctl command fails without performing the function and with errno set to [EINVAL] if: • The stream referred to by fildes is linked below a multiplexing driver. • The command parameter is not a valid value for the stream. In addition, if any of the following conditions occur, the STREAMS ioctl commands return the corresponding value: I_ATMARK [EINVAL] arg has an illegal value. I_CANPUT [EINVAL] arg has an illegal value.
PAGE 8
streamio(7) streamio(7) [EINVAL] The bi_pri parameter value exceeds the maximum band, or the bi_flag parameter is not FLUSHR, FLUSHW, or FLUSHRW. I_GETBAND [ENODATA] No message exists on the stream head read queue. I_GETSIG [EINVAL] User process is not registered to receive the SIGPOLL signal. [EFAULT] arg points outside the allocated address space. I_GRDOPT [EFAULT] arg is pointing outside the allocated address space.
PAGE 9
streamio(7) streamio(7) [EINVAL] The file referred to by arg is not a stream or is already linked under a multiplexing driver. [EINVAL] The link operation would cause a "cycle" in the resulting multiplexing configuration. In other words, the driver referred to by arg is linked into the configuration at multiple places. I_POP [EINVAL] There are not modules in the stream. [ENXIO] Error value returned by the module being popped. [ENXIO] A hangup was received on fildes .
PAGE 10
streamio(7) streamio(7) [EAGAIN] A data structure to store the signal request could not be allocated. I_SRDOPT [EINVAL] arg contains an illegal value. I_STR [EINVAL] The ic_len field is less than 0 (zero) bytes or larger than the maximum allowable size of the data part of a message (ic_dp). [EINVAL] The ic_timout field is less than −1. [EFAULT] arg points, or the buffer area specified by ic_dp or ic_len is, outside the allocated address space.