M_SETOPTS

Used to alter some characteristics of the Stream head. It is generated by any downstream module, and is interpreted by the Stream head. The data buffer of the message has the following structure as defined in stream.h.

struct stroptions {
	uint     so_flags;        /* options to set */
	shor     so_readopt;      /* read option */
	ushort   so_wroff;        /* write offset */
	ssize_t  so_minpsz;       /* minimum read packet size */
	ssize_t  so_maxpsz;       /* maximum read packet size */
	size_t   so_hiwat;        /* read queue high-water mark */
	size_t   so_lowat;        /* read queue low-water mark */
	unsigned char so_band;    /* band for water marks */
	ushort   so_erropt;       /* error option */
	ssize_t  so_maxblk;       /* maximum message block size */
	ushort   so_copyopt;      /* copy options (see stropts.h) */
};

where so_flags specifies which options are to be altered, and can be any combination of the following:

• SO_ALL: Update all options according to the values specified in the remaining fields of the stroptions structure.

• SO_READOPT: Set the read mode (see read(2)) as specified by the value of so_readopt to:

  • RNORM - byte stream

  • RMSGD - message discard

  • RMSGN - message non-discard

  • RPROTNORM - normal protocol

  • RPROTDAT - turn M_PROTO and M_PCPROTO msgs into M_DATA msgs

  • RPROTDIS - discard M_PROTO and M_PCPROTO blocks in a msg and retain any linked M_DATA blocks

• SO_WROFF: Direct the Stream head to insert an offset (unwritten area), specified by so_wroff into the first message block of all M_DATA messages created as a result of a write(2). 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 zero.

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 msgb(9S)structure is greater than db_base in the datab(9S) structure to determine that an offset has been inserted in the first message block.

• 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 zero.

• 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(9S) structure, qb_hiwat in the qband(9S) 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(9S) structure, qb_lowat in the qband(9S) structure) on the Stream head read queue to the value specified in so_lowat.

• SO_MREADON: Enable the Stream head to generate M_READ messages when processing a read(2) system call. If both SO_MREADON and SO_MREADOFF are set in so_flags, SO_MREADOFF takes precedence.

• SO_MREADOFF: Disable the Stream head generation of M_READ messages when processing a read(2) system call. This is the default. If both SO_MREADON and SO_MREADOFF are set in so_flags, SO_MREADOFF takes precedence.

• SO_NDELON: Set non-STREAMS TTY semantics for O_NDELAY (or O_NONBLOCK) processing on read(2) and write(2). If O_NDELAY(or O_NONBLOCK) is set, a read(2) returns 0 if no data is waiting to be read at the Stream head. If O_NDELAY(or O_NONBLOCK) is clear, a read(2) blocks until data become available at the Stream head. (See note below)

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

  If both SO_NDELON and SO_NDELOFF are set in so_flags, SO_NDELOFF takes precedence.

For conformance with the POSIX standard, it is recommended that new applications 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(2) and write(2) system calls. If O_NDELAY (or O_NONBLOCK) is set, a read(2) 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(2) blocks until data become available at the Stream head. (See note above)

  If O_NDELAY (or O_NONBLOCK) is set, a write(2) returns -1 and sets EAGAIN if flow control is in effect when the call is received. It blocks 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(2) terminate and return the number of bytes written.

  If O_NDELAY (or O_NONBLOCK) is clear, a write(2) will block on flow control and will block if buffers are not available.

  This is the default. If both SO_NDELON and SO_NDELOFF are set in so_flags, SO_NDELOFF takes precedence.

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

• SO_BAND: Set watermarks in a band. If the SO_BAND flag is set with the SO_HIWAT or SO_LOWAT flag, the so_band field contains the priority band number the so_hiwat and so_lowat fields pertain to.

  If the SO_BAND flag is not set and the SO_HIWAT and SO_LOWAT flags are on, the normal high-water 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.

• 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 arriving 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 in conjunction with job control.

• SO_DELIM: Messages are delimited.

• SO_NODELIM: Messages are not delimited.

• SO_STRHOLD: Enable strwrite message coalescing.

M_SIG

Sent upstream by modules or drivers to post a signal to a process. When the message reaches the front of the Stream head read queue, it evaluates the first data byte of the message as a signal number, defined in <sys/signal.h>. (The signal is not generated until it reaches the front of the Stream head read queue.) The associated signal will be sent to processes under the following conditions:

• If the signal is SIGPOLL, it is sent only to those processes that have explicitly registered to receive the signal (see I_SETSIG in streamio(7I)).

• If the signal is not SIGPOLL and the Stream containing the sending module or driver is a controlling TTY, the signal is sent to the associated process group. A Stream becomes the controlling TTY for its process group if, on open(2), a module or driver sends an M_SETOPTS message to the Stream head with the SO_ISTTY flag set.

• If the signal is not SIGPOLL and the Stream is not a controlling TTY, no signal is sent, except in case of SIOCSPGRP and TIOCSPGRP. These two ioctl(2) set the process group field in the Stream head so the Stream can generate signals even if it is not a controlling TTY.