| copyreq (D4) | STREAMS transparent ioctl copy request structure |
| copyresp (D4) | STREAMS transparent ioctl copy response structure |
| datab (D4) | STREAMS data block structure |
| free_rtn (D4) | STREAMS driver's message free routine structure |
| iocblk (D4) | STREAMS ioctl structure |
| linkblk (D4) | STREAMS multiplexor link structure |
| module_info (D4) | STREAMS driver and module information structure |
| msgb (D4) | STREAMS message block structure |
| qinit (D4) | STREAMS queue initialization structure |
| queue (D4) | STREAMS queue structure |
| streamtab (D4) | STREAMS drive and module declaration structure |
| stroptions (D4) | stream head option structure |
The kernel structure commands are described using the following command page format. The format will vary, since most command pages will contain only some of these sections.
NAME
| Home |
|---|
Usage:
The copyreq structure is used in M_COPYIN and M_COPYOUT
messages. The module or driver usually converts an M_IOCTL or M_IOCDATA
message into an M_COPYIN or M_COPYOUT message. The copyreq
structure is thus overlaid on top of the iocblk(D4)
or copyresp(D4) structure. The
stream head guarantees that the message is large enough to contain the
different structures.
Structure Definitions:
The copyreq structure contains the following members:
int cq_cmd; /* ioctl command */
uint_t cq_id; /* ioctl ID */
caddr_t cq_addr; /* copy buffer address */
uint_t cq_size; /* number of bytes to copy */
int cq_flag; /* for future use */
mblk_t *cq_private; /* module private data */
The cq_cmd field is the ioctl command, copied from the ioc_cmd field of the iocblk structure. If the same message is used, then the cq_cmd field directly overlays the ioc_cmd field (that is, it need not be copied).
The cq_id field is the ioctl ID, copied from the ioc_id field of the iocblk structure. It is used to uniquely identify the ioctl request in the stream. If the same message is used, then the cq_id field directly overlays the ioc_id field (that is, it need not be copied).
For an M_COPYIN message, the cq_addr field contains the user address from which the data are to be copied. For an M_COPYOUT message, the cq_addr field contains the user address to which the data are to be copied. In both cases, the cq_size field contains the number of bytes to copy.
The cq_flag field is reserved for future use and should be set to 0 by the module or driver.
The cq_private field is a field set aside for use by the driver. It can be used to hold whatever state information is necessary to process the ioctl. It is copied to the cp_private field in the resultant M_IOCDATA message. When the M_COPYIN or M_COPYOUT message is freed, any message that cq_private refers to is not freed by the STREAMS subsystem. It is the responsibility of the module or driver to free it.
| Home |
|---|
NAME
Usage:
M_IOCDATA messages, generated by the Stream head, contain the
copyresp structure. If an M_IOCDATA message is reused, any
unused fields in the new message should be cleared.
Structure Definitions:
The copyresp structure contains the following members:
int cp_cmd; /* ioctl command */
uint_t cp_id; /* ioctl ID */
caddr_t cp_rval; /* status of request */
mblk_t *cp_private; /* module private data */
The cp_cmd field is the ioctl command, copied from the cq_cmd field of the copyreq structure.
The cp_id field is the ioctl ID, copied from the cq_id field of the copyreq structure. It is used to uniquely identify the ioctl request in the stream.
The cq_rval field contains the return value from the last copy request. If the request succeeded, it is set to 0. Otherwise, if it is nonzero, the request failed. On success, the module or driver should continue processing the ioctl. On failure, the module or driver should abort ioctl processing and free the message. No M_IOCNAK message need be generated.
The cp_private field is copied from the cq_private field of the copyreq structure. It is available so that the module or driver can regain enough state information to continue processing the ioctl request. When the M_IOCDATA message is freed, any message that cp_private refers to is not freed by the STREAMS subsystem. It is the responsibility of the module or driver to free it.
| Home |
|---|
NAME
Usage:
The actual data contained in a STREAMS message is stored in a data buffer pointed to by this structure. A message block structure [msgb(D4)] includes a field that points to a datab structure.
A data block can have more than one message block pointing to it at
one time, so the db_ref member keeps track of a data block's references,
preventing it from being deallocated until all message blocks are finished
with it.
Structure Definitions:
The datab structure is defined as type dblk_t and contains the following members:
uchar_t *db_base; /* first byte of buffer */
uchar_t *db_lim; /* last byte (+1) of buffer */
int db_ref; /* # of message pointers to this data */
uchar_t db_type; /* message type */
The db_base field points to the beginning of the data buffer. Drivers and modules should not change this field.
The db_lim field points to one byte past the end of the data buffer. Drivers and modules should not change this field.
The db_ref field contains a count of the number of message blocks sharing the data buffer. If it is greater than 1, drivers and modules should not change the contents of the data buffer. Drivers and modules should not change this field.
The db_type field contains the message type associated with the data buffer. This field can be changed by the driver. However, if the db_ref field is greater than 1, this field should not be changed.
| Home |
|---|
NAME
Usage:
Since the driver is providing the memory for the data buffer, a way
is needed to notify the driver when the buffer is no longer in use. esballoc
associates the free routine structure with the message when it is allocated.
When freeb(D3) is called to free the
message and the reference count goes to zero, the driver's message free
routine is called, with the argument specified, to free the data buffer.
Structure Definitions:
The free_rtn structure is defined as type frtn_t and contains the following members:
void (*free_func)(); /* driver's free routine */
char *free_arg; /* argument to free_func() */
The free_func field specifies the driver's function to be called when the message has been freed. It is called with interrupts from STREAMS devices blocked on the processor on which the function is running.
The free_arg field is the only argument to the driver's free routine.
| Home |
|---|
NAME
Usage:
The iocblk structure is used in M_IOCTL, M_IOCACK, and M_IOCNAK messages. Modules and drivers usually convert M_IOCTL messages into M_IOCACK or M_IOCNAK messages by changing the type and updating the relevant fields in the iocblk structure.
Data cannot be copied to the user's buffer with an M_IOCACK message if the ioctl is transparent.
No data can be copied to the user's buffer with an M_IOCNAK message.
When processing a transparent ioctl, the iocblk structure
is usually overlaid with a copyreq(D4)
structure. The stream head guarantees that the message is large enough
to contain either structure.
Structure Definitions:
The iocblk structure contains the following members:
int ioc_cmd; /* ioctl command */
uint_t ioc_id; /* ioctl ID */
uint_t ioc_count; /* number of bytes of data */
int ioc_error; /* error code for M_IOCACK or M_IOCNAK */
int ioc_rval; /* return value for M_IOCACK */
The ioc_cmd field is the ioctl command request specified by the user.
The ioc_id field is the ioctl ID, used to uniquely identify the ioctl request in the stream.
The ioc_count field specifies the amount of user data contained in the M_IOCTL message. User data will appear in M_DATA message blocks linked to the M_IOCTL message block. If ioc_count is set to the special value TRANSPARENT, then the ioctl request is "transparent." This means that the user did not use the I_STR format of STREAMS ioctls and the module or driver will have to obtain any user data with M_COPYIN messages, and change any user data with M_COPYOUT messages. In this case, the M_DATA message block linked to the M_IOCTL message block contains the value of the arg parameter in the ioctl system call. For an M_IOCACK message, the ioc_count field specifies the amount of data to copy back to the user's buffer.
The ioc_error field can be used to set an error for either an M_IOCACK or an M_IOCNAK message.
The ioc_rval field can be used to set the return value in an M_IOCACK message. This will be returned to the user as the return value for the ioctl system call that generated the request.
| Home |
|---|
NAME
Usage:
The linkblk structure is embedded in the M_DATA portion
of the M_IOCTL messages generated from the following ioctl(2)
calls: I_LINK, I_UNLINK, I_PLINK, and I_PUNLINK
[see streamio(7)].
Structure Definitions:
The linkblk structure contains the following members:
queue_t *l_qtop; /* lower queue of top stream */
queue_t *l_qbot; /*upper queue of bottom stream */
int l_index; /* unique ID */
The l_qtop field is a pointer to the lowest write queue in the upper stream. In other words, it is the write queue of the multiplexing driver. If the link is persistent across closes of the driver, then this field is set to NULL.
The l_qbot field is a pointer to the upper write queue in the lower stream. The lower stream is the stream being linked under the multiplexor. The topmost read and write queues in the lower stream are given to the multiplexing driver to use for the lower half of its multiplexor processing. The qinit(D4) structures associated with these queues are those specified for the lower processing in the multiplexing driver's streamtab(D4) structure.
The l_index field is a unique ID that identifies the multiplexing link in the system. The driver can use this as a key on which it can multiplex or demultiplex.
| Home |
|---|
NAME
Usage:
After the initial declaration, the module_info structure is intended to be read-only. However, the flow control limits (mi_hiwat and mi_lowat) and the packet size limits (mi_minpsz and mi_maxpsz) are copied to the queue(D4) structure, where they may be modified.
There may be one module_info structure per read and write queue,
or the driver or module may use the same module_info structure for
both the read and write queues.
Structure Definitions:
The module_info structure contains the following members:
ushort_t mi_idnum; /* module ID number */
char mi_idname; /* module name */
long mi_minpsz; /* minimum packet size */
long mi_maxpsz; /* maximum packet size */
ulong_t mi_hiwat; /* high water mark */
ulong_t mi_lowat; /* low water mark */
The mi_idnum field is a unique identifier for the driver or
module that distinguishes the driver or module from the other drivers and
modules in the system.
The mi_idname field points to the driver or module name. The constant FMNAMESZ limits the length of the name, not including the terminating NULL. It is currently set to eight characters.
The mi_minpsz field is the default minimum packet size for the driver or module queues. This is an advisory limit specifying the smallest message that can be accepted by the driver or module.
The mi_maxpsz field is the default maximum packet size for the driver or module queues. This is an advisory limit specifying the largest message that can be accepted by the driver or module.
The mi_hiwat field is the default high water mark for the driver or module queues. This specifies the number of bytes of data contained in messages on the queue such that the queue is considered full and hence flow-controlled.
The mi_lowat field is the default low water mark for the driver or module queues. This specifies the number of bytes of data contained in messages on the queue such that the queue is no longer flow-controlled.
| Home |
|---|
NAME
Structure Definitions:
The msgb structure is defined as type mblk_t and contains the following members:
struct msgb *b_next; /* next message on queue */
struct msgb *b_prev; /* previous message on queue */
struct msgb *b_cont; /* next block in message */
uchar *b_rptr; /* 1st unread data byte of buffer */
uchar *b_wptr; /* 1st unwritten data byte of buffer */
struct datab *b_datap; /* pointer to data block */
uchar_t *b_band; /* message priority */
ushort_t *b_flag; /* used by stream head */
The b_next and b_prev pointers are used to link messages together on a queue(D4). These fields can be used by drivers and modules to create linked lists of messages.
The b_cont pointer links message blocks together when a message is composed of more than one block. Drivers and modules can use this field to create complex messages from single message blocks.
The b_rptr and b_wptr pointers describe the valid data region in the associated data buffer. The b_rptr field points to the first unread byte in the buffer and the b_wptr field points to the next byte to be written in the buffer.
The b_datap field points to the data block [see datab(D4)] associated with the message block. This field should never be changed by modules or drivers.
The b_band field contains the priority band associated with the message. Normal priority messages and high priority messages have b_band set to zero. High priority messages are high priority by virtue of their message type. This field can be used to alter the queuing priority of the message. The higher the priority band, the closer to the head of the queue the message is placed.
The b_flag field contains a bit mask of flags that can be set to alter the way the stream head will process the message. Valid flags are:
| MSGMARK | The last byte in the message is "marked." This condition can be tested from user level via the I_ATMARK ioctl(2). |
| Home |
|---|
NAME
Usage:
There is usually one qinit structure for the read side of a module
or driver, and one qinit structure for the write side.
Structure Definitions:
The quinit structure contains the following members:
int (*qi_putp)(); /* put procedure */
int (*qi_srvp)(); /* service procedure */
int (*qi_qopen)(); /* open procedure */
int (*qi_qclose)(); /* close procedure */
int (*qi_qadmin)(); /* for future use */
struct module_info *qi_minfo; /* module parameters */
struct module_stat *qi_mstat; /* module statistics */
The qi_putp field contains the address of the put(D2)
routine for the queue.
The qi_srvp field contains the address of the service [srv] routine for the queue. If there is no service routine, this field should be set to NULL.
The qi_qopen field contains the address of the open(D2) routine for the driver or module. Only the read-side qinit structure need to define and/or contain the routine address. The write-side value should be set to NULL.
The qi_qclose field contains the address of the close(D2) routine for the driver or module. Only the read-side qinit structure need to define and/or contain the routine address. The write-side value should be set to NULL.
The qi_qadmin field is intended for future use and should be set to NULL.
The qi_minfo field contains the address of the module_info(D4) structure for the driver or module.
The qi_mstat field contains the address of the module_stat structure for the driver or module. The module_stat structure is defined in /usr/include/sys/strstat.h. This field should be set to NULL if the driver or module does not keep statistics.
| Home |
|---|
NAME
Usage:
This structure is the major building block of a stream. It contains
pointers to the processing procedures, pointers to the next queue in the
stream, flow control parameters, and a list of messages to be processed.
Structure Definitions:
The queue structure is defined as type queue_t and contains the following members:
struct qinit *q_qinfo; /* module or driver entry points */
struct msgb *q_first; /* first message in queue */
struct msgb *q_last; /* last message in queue */
struct queue *q_next; /* next queue in stream */
void *q_ptr; /* pointer to private data structure */
ulong_t *q_count; /* approximate size of message queue */
ulong_t *q_flag; /* status of queue */
long *q_minsize; /* smallest packet accepted by QUEUE */
long *q_maxpsz; /* largest packet accepted by QUEUE */
ulong_t *q_hiwat; /* high water mark */
ulong_t *q_lowat; /* low water mark */
The q_qinfo field contains a pointer to the qinit(D4)
structure specifying the processing routines and default values for the
queue. This field should not be changed by drivers or modules.
The q_first field points to the first message on the queue, or is NULL if the queue is empty. This field should not be changed by drivers or modules.
The q_last field points to the last message on the queue, or is NULL if the queue is empty. This field should not be changed by drivers or modules.
The q_next field points to the next queue in the stream. This field should not be changed by drivers or modules.
The q_ptr field is a private field for use by drivers and modules. It provides a way to associate the driver's per-minor data structure with the queue.
The q_count field contains the number of bytes in messages on the queue in priority band 0. This includes normal messages and high priority messages.
The q_flag field contains a bit mask of flags that indicate different queue characteristics. No flags may be set or cleared by drivers or modules. However, the following flags may be tested:
QREADR The queue is the read queue. Absence of this flag implies a write queue.
The q_minpsz field is the minimum packet size for the queue. This is an advisory limit specifying the smallest message that can be accepted by the queue. It is initially set to the value specified by the mi_minpsz field in the module_info(D4) structure. This field can be changed by drivers or modules.
The q_maxpsz field is the maximum packet size for the queue. This is an advisory limit specifying the largest message that can be accepted by the queue. It is initially set to the value specified by the mi_maxpsz field in the module_info structure. This field can be changed by drivers or modules.
The q_hiwat field is the high water mark for the queue. This specifies the number of bytes of data contained in messages on the queue such that the queue is considered full, and hence flow-controlled. It is initially set to the value specified by the mi_hiwat field in the module_info structure. This field can be changed by drivers or modules.
The q_lowat field is the low water mark for the queue. This specifies the number of bytes of data contained in messages on the queue such that the queue is no longer flow-controlled. It is initially set to the value specified by the mi_lowat field in the module_info structure. This field can be changed by drivers or modules.
| Home |
|---|
NAME
Usage:
Each STREAMS driver or module must have a streamtab structure.
The streamtab structure must be named prefixinfo,
where prefix is the driver prefix.
Structure Definitions:
The streamtab structure contains the following members:
struct qinit *st_rdinit; /* read queue */
struct qinit *st_wrinit; /* write queue */
struct qinit *st_muxrinit; /* lower read queue*/
struct qinit *st_muxwinit; /* lower write queue*/
The st_rdinit field contains a pointer to the read-side qinit
structure. For a multiplexing driver, this is the qinit structure
for the upper read side.
The st_wrinit field contains a pointer to the write-side qinit structure. For a multiplexing driver, this is the qinit structure for the upper write side.
The st_muxrinit field contains a pointer to the lower read-side qinit structure for multiplexing drivers. For modules and nonmultiplexing drivers, this field should be set to NULL.
The st_muxwinit field contains a pointer to the lower write-side qinit structure for multiplexing drivers. For modules and nonmultiplexing drivers, this field should be set to NULL.
| Home |
|---|
Usage:
The M_SETOPTS message is sent upstream by drivers and modules
when they want to change stream head options for their stream.
Structure Definitions:
The stroptions structure contains the following members:
ulong_t so_flags; /* options to set */
short so_readopt; /* read option */
ushort_t so_wroff; /* write offset */
long so_minpsz; /* minimum read packet size */
long so_maxpsz; /* maximum read packet size */
ulong_t so_hiwat; /* read queue high water mark */
ulong_t so_lowat; /* read queue low water mark */
uchar_t so_band; /* band for water marks */
The so_flags field determines which options are to be set, and
which of the other fields in the structure are used. This field is a bit
mask and is comprised of the bit-wise OR of the following flags:
| SO_READOPT | Set the read option to that specified by the so_readopt field. |
| SO_WROFF | Set the write offset to that specified by the so_wroff field. |
| SO_MINPSZ | Set the minimum packet size on the stream head read queue to that specified by the so_minpsz field. |
| SO_MAXPSZ | Set the maximum packet size on the stream head read queue to that specified by the so_maxpsz field. |
| SO_HIWAT | Set the high water mark on the stream head read queue to that specified by the so_hiwat field. |
| SO_LOWAT | Set the low water mark on the stream head read queue to that specified by the so_lowat field. |
| SO_ALL | Set all of the above options (SO_READOPT | SO_WROFF | SO_MINPSZ | SO_MAXPSZ | SO_HIWAT | SO_LOWAT). |
| SO_MREADON | Turn on generation of M_READ messages by the stream head. |
| SO_MREADOFF | Turn off generation of M_READ messages by the stream head. |
| SO_NDELON | Use old tty semantics for no-delay reads and writes. |
| SO_NDELOFF | Use STREAMS semantics for no-delay reads and writes. |
| SO_ISTTY | The stream is acting as a terminal. |
| SO_ISNTTY | The stream is no longer acting as a terminal. |
| SO_TOSTOP | Stop processes on background writes to this stream. |
| SO_TONSTOP | Don't stop processes on background writes to this stream. |
| SO_BAND | The water marks changes affect the priority band specified by the so_band field. |
| The so_readopt field specifies options for the stream head that alter the way it handles read(2) calls. This field is a bit mask whose flags are grouped in sets. Within a set, the flags are mutually exclusive. The first set of flags determines how data messages are treated when they are read: | |
| RNORM | Normal (byte stream) mode. read returns the lesser of the number of bytes asked for and the number of bytes available. Messages with partially read data are placed back on the head of the stream head read queue. This is the default behavior. |
| RMSGD | Message discard mode. read returns the lesser of the number of bytes asked for and the number of bytes in the first message on the stream head read queue. Messages with partially read data are freed. |
| RMSGN | Message nondiscard mode. read returns the lesser of the number of bytes asked for and the number of bytes in the first message on the stream head read queue. Messages with partially read data are placed back on the head of the stream head read queue. |
| The second set of flags determines how protocol messages (M_PROTO and M_PCPROTO) are treated during a read: | |
| RPROTNORM | Normal mode. read fails with the error code EBADMSG if there is a protocol message at the front of the stream head read queue. This is the default behavior. |
| RPROTDIS | Protocol discard mode. read discards the M_PROTO or M_PCPROTO por- tions of the message and return any M_DATA portions that may be present M_PASSFP messages are also freed in this mode. |
| RPROTDAT | Protocol data mode. read treats the M_PROTO or M_PCPROTO portions of the message as if they were normal data (that is, they are delivered to the user). |
SEE ALSO
| Home |
|---|
| Contents | Previous Chapter | Next Chapter | Index | Glossary |