SVR5 and SCO OpenServer 5

stroptions(D4str)

stroptions -- stream head option structure

Synopsis

   #include <sys/stream.h>
   #include <sys/stropts.h>
   #include <sys/ddi.h>

Description

The stroptions structure, used in an M_SETOPTS(D7str) message, contains options for the stream head.

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;
   ushort_t         so_readopt;
   ushort_t         so_wroff;
   long             so_minpsz;
   long             so_maxpsz;
   ulong_t          so_hiwat;
   ulong_t          so_lowat;
   uchar            so_band;

Structure members

so_flags

determines which options are to be set, and which of the other members in the structure are used. This is a bitmask and is comprised of the bit-wise OR of the following flags:

SO_READOPT

specifies options for the stream head that alter the way it handles read calls. This is a bitmask 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: byte stream
RMSGD: message discard
RMSGN: message non-discard

The second set of flags determines how protocol messages M_PROTO(D7str) and M_PCPROTO(D7str) protocol messages are treated during a read( ) operation: set the read mode (see read) as specified by the value of so_readopt:

RPROTNORM: normal protocol
RPROTDAT: turn M_PROTO(D7str) and M_PCPROTO(D7str) messages into M_DATA(D7str) messages
RPROTDIS: discard M_PROTO and M_PCPROTO blocks in a messages and retain any linked M_DATA blocks

One of the last three flags can be exclusive ORed with one of the first three flags.

SO_WROFF

direct the Stream head to insert an offset specified by so_wroff into the first message block of all M_DATA messages created as a result of a write system call. The same offset is inserted into the first M_DATA message block, if any, of all messages created by a putmsg system call. The default offset is 0.

The offset must be less than the maximum message buffer size (system-dependent). Under certain circumstances, a write offset may not be inserted. A module or driver must test that b_rptr in the mblk_t structure is greater than db_base in the dblk_t structure to determine whether an offset has been inserted in the first message block. The check is:

   mblk_t *bp;
   
   if (bp->b_rptr > bp->b_datap->db_datap) {
   	/* SO_WROFF has been done */
   }

SO_MINPSZ

change the minimum packet size value associated with the Stream head read queue to so_minpsz. This value is advisory for the module immediately below the Stream head. It is intended to limit the size of M_DATA messages that the module should put to the Stream head. There is no intended minimum size for other message types. The default value in the Stream head is 0.

SO_MAXPSZ

change the maximum packet size value associated with the Stream head read queue to so_maxpsz. This value is advisory for the module immediately below the Stream head. It is intended to limit the size of M_DATA messages that the module should put to the Stream head. There is no intended maximum size for other message types. The default value in the Stream head is INFPSZ, the maximum STREAMS allows.

SO_HIWAT

change the flow control high-water mark q_hiwat in the queue structure, qb_hiwat in the qband structure) on the Stream head read queue to the value specified in so_hiwat.

SO_LOWAT

change the flow control low-water mark q_lowat in the queue structure, qb_lowat in the qband structure) on the Stream head read queue to the value specified in so_lowat.

SO_ALL

SO_MREADON,

enable the Stream head to generate an M_READ(D7str) message when processing a read system call and there is no data to be read. The message contains the number of bytes the reader is expecting as a long value stored in four data bytes.

If both SO_MREADON and SO_MREADOFF are set in so_flags, SO_MREADOFF has precedence.

SO_MREADOFF

disable the Stream head generation of an M_READ message when processing a read system call and there is no data to be read.

This is the default. If both SO_MREADON and SO_MREADOFF are set in so_flags, SO_MREADOFF has precedence.

SO_NDELON

set non-Streams tty semantics for O_NDELAY (or O_NONBLOCK) processing on read and write system calls. If O_NDELAY (or O_NONBLOCK) is set, a read( ) will return 0 if no data is waiting to be read at the Stream head. If O_NDELAY (or O_NONBLOCK) is clear, a read( ) will block until data becomes available at the Stream head.

Regardless of the state of O_NDELAY (or O_NONBLOCK), a write( ) will block on flow control and will block if buffers are not available.

NOTE: For conformance with the POSIX standard, new applications should use the O_NONBLOCK flag whose behavior is the same as that of O_NDELAY unless otherwise noted.

SO_NDELOFF

set STREAMS semantics for O_NDELAY (or O_NONBLOCK) processing on read or write system calls. If O_NDELAY (or O_NONBLOCK) is set, a read( ) will return -1 and set EAGAIN if no data is waiting to be read at the Stream head. If O_NDELAY (or O_NONBLOCK) is clear, a read( ) will block until data becomes available at the Stream head.

If O_NDELAY (or O_NONBLOCK) is set, a write( ) will return -1 and set EAGAIN if flow control is in effect when the call is received. It will block if buffers are not available. If O_NDELAY (or O_NONBLOCK) is set and part of the buffer has been written and a flow control or buffers not available condition is encountered, write( ) will terminate and return the number of bytes written.

If O_NDELAY (or O_NONBLOCK) is clear, a write( ) will block on flow control and will block if buffers are not available. This is the default. If both O_NDELAY (or O_NONBLOCK) are set in so_flags, SO_NDELOFF has precedence.

In the STREAMS -based pipe mechanism, the behavior of read( ) and write( ) is different for the O_NDELAY (or O_NONBLOCK) flags. See read and write for details.

SO_BAND

set water marks in a band. If the SO_BAND flag is set with the SO_HIWAT or SO_LOWAT flag, the so_band member contains the priority band number to which the so_hiwat and so_lowat members pertain.

If the SO_BAND flag is not set and the SO_HIWAT and SO_LOWAT flags are on, the normal high and low water marks are affected. The SO_BAND flag has no effect if SO_HIWAT and SO_LOWAT flags are off.

Only one band's water marks can be updated with a single M_SETOPTS message.

Note that band 0 is the same as normal priority messages.

SO_LOOP

Indicate to the stream head that this is a looparound stream (i.e. it supports passing of file descriptors).

SO_ISTTY

Inform the Stream head that the Stream is acting like a controlling terminal.

SO_ISNTTY

Inform the Stream head that the Stream is no longer acting like a controlling terminal.

For SO_ISTTY, the Stream may or may not be allocated as a controlling terminal via an M_SETOPTS message that arrives upstream during open processing. If the Stream head is opened before receiving this message, the Stream will not be allocated as a controlling terminal until it is queued again by a session leader.

SO_TOSTOP

Stop on background writes to the Stream.

SO_TONSTOP

Do not stop on background writes to the Stream.

SO_TOSTOP and SO_TONSTOP are used with job control.

so_wroff

specifies a byte offset to be included in the first message block of every M_DATA message created by a write and the first M_DATA message block created by each call to putmsg.

so_minpsz

specifies the minimum packet size for the stream head read queue.

so_maxpsz

specifies the maximum packet size for the stream head read queue.

so_hiwat

specifies the high water mark for the stream head read queue.

so_lowat

specifies the low water mark for the stream head read queue.

so_band

specifies the priority band to which the high and/or low water mark changes should be applied.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 8, 8mp
oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp

Differences between versions

The SO_ISTTY, SO_ISNTTY, SO_TOSTOP, and SO_TONSTOP options are not supported in ODDI.

The following options are supported in ODDI but are not supported in DDI.

SO_NSWITCHON: disallow preemption after waiting to send or receive messages at the Stream head. Default for STREAMS pipes only. Preemption means choosing a new process to run on a processor based on its priority, so when this is disabled, the current process keeps running, allowing it to finish sending or receiving data.
SO_NSWITCHOFF: allow preemption when waiting to send or receive messages at the Stream head. Default for STREAMS devices other than STREAMS pipes. This means that another higher-priority process will be scheduled to run after waiting to send or receive data.

The RPROTNORM, RPROTDAT, and RPROTDIS flags to SO_READOPT are not supported in ODDI version 1 and 2 STREAMS implementations. For backwards compatibility, the first three flags can be used without any of the last three flags to preserve the behavior of read with control messages from earlier ODDI versions.

ODDI 1 and 2 support a slightly different stroptions structure:

   struct stroptions                /* ODDI 1,2 */
   {
   	short so_flags;                  /* options to set */
   	short so_readopt;                /* read option */
   	ushort so_wroff;                 /* write offset */
   	short so_minpsz;                 /* minimum read packet size*/
   	short so_maxpsz;                 /* maximum read packet size*/
   	ushort so_hiwat;                 /*read queue high-watermark*/
   	ushort so_lowat;                 /*read queue low-water mark*/
   };

The old structure definition is supported and handled by the ODDI 3 and later Stream head for backwards compatibility. The new structure is source code compatible, meaning that any driver or module that is recompiled will use the new structure, even if no code modifications are made.

The following tables compare the stroptions structure members and supported options for all DDI and ODDI versions:

stroptions structure members for DDI and ODDI

Member DDI 8 DDI 7 ODDI 3,4,5 ODDI 1,2

so_flags ulong ulong ulong short

so_readopt ushort short short short

so_wroff ushort ushort ushort ushort

so_minpsz long long long short

so_maxpasz long long long short

so_hiwat ulong ulong ulong ushort

so_lowat ulong ulong ulong ushort

so_band uchar uchar uchar --

Member	DDI 8	DDI 7	ODDI 3,4,5	ODDI 1,2
so_flags	ulong	ulong	ulong	short
so_readopt	ushort	short	short	short
so_wroff	ushort	ushort	ushort	ushort
so_minpsz	long	long	long	short
so_maxpasz	long	long	long	short
so_hiwat	ulong	ulong	ulong	ushort
so_lowat	ulong	ulong	ulong	ushort
so_band	uchar	uchar	uchar	--

stroptions options for DDI and ODDI

options DDI 8 DDI 7 ODDI 3,4,5 ODDI 1,2

SO_READOPT Yes Yes Yes Yes

   RNORM Yes Yes Yes Yes

   RMSGD Yes Yes Yes Yes

   RMSGN Yes Yes Yes Yes

   RPROTNORM Yes Yes Yes --

   RPROTDAT Yes Yes Yes --

   RPROTDIS Yes Yes Yes --

SO_ALL Yes Yes Yes Yes

SO_WROFF Yes Yes Yes Yes

SO_MINPSZ Yes Yes Yes Yes

SO_MAXPSZ Yes Yes Yes Yes

SO_HIWAT Yes Yes Yes Yes

SO_LOWAT Yes Yes Yes Yes

SO_MREADON Yes Yes Yes Yes

SO_MREADOFF Yes Yes Yes Yes

SO_NDELON Yes Yes Yes Yes

SO_NDELOFF Yes Yes Yes Yes

SO_BAND Yes Yes Yes Yes

SO_ISTTY Yes Yes -- --

SO_ISNTTY Yes Yes -- --

SO_TOSTOP Yes Yes -- --

SO_TONSTOP Yes Yes -- --

SO_NSWITCHON -- -- Yes --

SO_NSWITCHOFF -- -- Yes --

options	DDI 8	DDI 7	ODDI 3,4,5	ODDI 1,2
SO_READOPT	Yes	Yes	Yes	Yes
RNORM	Yes	Yes	Yes	Yes
RMSGD	Yes	Yes	Yes	Yes
RMSGN	Yes	Yes	Yes	Yes
RPROTNORM	Yes	Yes	Yes	--
RPROTDAT	Yes	Yes	Yes	--
RPROTDIS	Yes	Yes	Yes	--
SO_ALL	Yes	Yes	Yes	Yes
SO_WROFF	Yes	Yes	Yes	Yes
SO_MINPSZ	Yes	Yes	Yes	Yes
SO_MAXPSZ	Yes	Yes	Yes	Yes
SO_HIWAT	Yes	Yes	Yes	Yes
SO_LOWAT	Yes	Yes	Yes	Yes
SO_MREADON	Yes	Yes	Yes	Yes
SO_MREADOFF	Yes	Yes	Yes	Yes
SO_NDELON	Yes	Yes	Yes	Yes
SO_NDELOFF	Yes	Yes	Yes	Yes
SO_BAND	Yes	Yes	Yes	Yes
SO_ISTTY	Yes	Yes	--	--
SO_ISNTTY	Yes	Yes	--	--
SO_TOSTOP	Yes	Yes	--	--
SO_TONSTOP	Yes	Yes	--	--
SO_NSWITCHON	--	--	Yes	--
SO_NSWITCHOFF	--	--	Yes	--

References

datab(D4str), Intro(D7str), M_SETOPTS(D7str), msgb(D4str), read, streamio