DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
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
Set all of the above options (SO_READOPT | SO_WROFF | SO_MINPSZ | SO_MAXPSZ | SO_HIWAT | SO_LOWAT).

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
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005