Manpage of M_SETOPTS

M_SETOPTS

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

M_SETOPTS - STREAMS set stream head options message

FORMAT

The M_SETOPTS message block is a datab(9) structure and associated data buffer that contains structured data.

An M_SETOPTS message is a normal priority message that consists of a single M_SETOPTS message block.

INTERFACE

STREAMS.

DESCRIPTION

The M_SETOPTS message is sent to the Stream head by a driver or module wanting 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:

struct stroptions {
    uint so_flags;              /* options to set */
    short 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 hi water mark */
    size_t so_lowat;            /* read queue lo water mark */
    unsigned char so_band;      /* band for water marks */
    unsigned char so_filler[3]; /* padding */
    ushort so_erropt;           /* Solaris */
    ssize_t so_maxblk;          /* Solaris */
    ushort so_copyopt;          /* Solaris */
    ushort so_wrpad;            /* write (tail) padding */
};

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

SO_ALL: set all old options (Solaris uses true mask)
SO_READOPT: set read option
SO_WROFF: set write offset
SO_MINPSZ: set min packet size
SO_MAXPSZ: set max packet size
SO_HIWAT: set high water mark
SO_LOWAT: set low water mark
SO_MREADON: set read notification ON
SO_MREADOFF: set read notification OFF
SO_NDELON: old TTY semantics for NDELAY reads/writes
SO_NDELOFF: STREAMS semantics for NDELAY reads/writes
SO_ISTTY: the stream is acting as a terminal
SO_ISNTTY: the stream is not acting as a terminal
SO_TOSTOP: stop on background writes to this stream
SO_TONSTOP: do not stop on background writes to stream
SO_BAND: water marks affect band
SO_DELIM: messages are delimited
SO_NODELIM: turn off delimiters
SO_STRHOLD: UnixWare/Solaris: enable strwrite message coalescing
SO_ERROPT: Solaris
SO_LOOP: UnixWare
SO_COPYOPT: Solaris: user io copy options
SO_MAXBLK: Solaris: maximum block size
SO_COWENABLE: OSF/HPUX
SO_COWDISABLE: OSF/HPUX
SO_WRPAD: Linux Fast-STREAMS: write tail padding
SO_NOCSUM: Linux Fast-STREAMS: no checksum on copy
SO_CSUM: Linux Fast-STREAMS: UDP/TCP checksum on copy
SO_CRC32C: Linux Fast-STREAMS: CRC32C checksum on copy
SO_SKBUFF: Linux Fast-STREAMS: allocate sk_buffs for data
SO_NOSKBUFF: Linux Fast-STREAMS: do not allocate sk_buffs for data

SO_ALL

Update all options according to the values specified in the remaining files of the stroptions(9) structure.

SO_READOPT

Sets the read options for the Stream head. The read options consist of two bit fields that determine the read mode and the read control mode for the Stream head.

The read mode determines how the read(2s) system call handles messages and message boundaries. It can contain one of the following mutually exclusive flags:

RNORM: This is the default. In byte-stream mode, message boundaries are normally ignored. When the SO_DELIM flag is used to set the STRDELIM option in the Stream head, message boundaries are no longer ignored. If a message contains more data than is necessary to satisfy the read(2s) request, the remainder is placed back onto the Stream head read queue (with the same messages flags as were present in the original message block of the original message). See SO_DELIM , below, for more information.
RMSGD: In message-discard mode, only one message at a time is read If the message contains more data than was requested by read(2s) with nbytes, the remainder of the message is discarded.
RMSGN: In message-non-discard mode, only one message at a time is read. If the message contains more data than was requested by read(2s) with nbytes, the remainder of the mssage is placed back onto the Stream head read queue.
RFILL: Message fill modes is the same as byte-stream mode, with the exception that read(2s) requests attempt to fill a buffer completely before returning to the application. This mode can be used in conjuction with the SO_MREADON option.

The read control mode determines how the read(2s) system call handles messages on the Stream head read queue that contain control parts. It can contain one of the following mutually exclusive flags:

RPROTNORM: This is the default. In control-normal mode, whenever read(2s) encounters a message on the Stream head read queue that contains a control part (i.e. leading M_PROTO(9) or M_PCPROTO(9) message block), read(2s) either terminates and returns the number of bytes read so far, or fails, returns minus one (-1) and sets errno(3) to [EBADMSG].
RPROTDAT: In control-data mode, whenever read(2s) encounters a message on the Stream head read queue that contains a control part, the Stream head converts the M_PROTO(9) or M_PCPROTO(9) message blocks directly to M_DATA(9) message blocks and processes them with the normal data part of the message.
RPROTDIS: In control-discard mode, whenever read(2s) encounters a message on the Stream head read queue that contains a control part, the Stream head discards the M_PROTO(9) or M_PCPROTO(9) message blocks, processing any remaining M_DATA(9) message blocks as thought the control part did not exist.

Read options can also be set and examined by a user program with the I_SRDOPT(7) or I_GRDOPT(7) commands to ioctl(2s) as detailed in streamio(7).

SO_WROFF

Specifies a write offset (for the b_rptr member of the msgb(9) structure message block) into the message block at which data will be written. write(2s) applies this offset before writing data into the first M_DATA(9) message block passed downstream as a result of the write(2s) operation. putmsg(2) and putpmsg(2s) applies this offset before writing data into the first M_DATA(9) message block that forms part of a message before passing the message downstream.

Although Linux Fast-STREAMS applies the write offset to each message in the fashion described above, the downstream module cannot always assume that M_DATA(9) message blocks contain the appropriate write offset. It is possible that the M_DATA(9) was either generated by or modified by an intervening module and that it did not contain the write offset because it was either not generated by the Stream head, or it was subsequently modified by an intervening module. The driver or module that requested a write offset should ensure that the appropriate offset exists by comparing the db_base pointer to the b_rptr pointer to ensure that the appropriate offset exists in the necessary message blocks.

SO_MINPSZ

Sets the minimum packet size associated with the Stream head read queue. The default is zero (0). This value in the Stream head read queue acts as an advisory value to the driver or module immediately below the stream head on the minimum size of M_DATA(9) messages. Note that for STREAMS-based pipes and FIFOs (with no modules pushed), the Stream head read queue is queue below the the Stream head write queue on the write side of the pipe or FIFO. This means that, although this setting has an advisory effect on the read side of a Stream, it can have a mandatory effect on the write side of a pipe or FIFO (with no modules pushed).

Most drivers and modules simply ignore this advisory minimum.

SO_MAXPSZ

Sets the maximum packet size associated with the Stream head read queue. The default is INFPSZ. This value in the Stream head read queue acts as an advisory value to the driver or module immediately below the stream head on the maximum size of M_DATA(9) messages. Note that for STREAMS-based pipes and FIFOs (with no modules pushed), the Stream head read queue is queue below the the Stream head write queue on the write side of the pipe or FIFO. This means that, although this setting has an advisory effect on the read side of a Stream, it can have a mandatory effect on the write side of a pipe or FIFO (with no modules pushed).

Most drivers and modules simply ignore this advisory maximum.

SO_HIWAT

Sets the high water mark, q_hiwat, for the Stream head read queue. This watermark is important to read side flow control and determines when the read side of the Stream is full.

SO_LOWAT

Sets the low water mark, q_lowat, for the Stream head read queue. This watermark is important to read side flow control and determines when the read side of the Stream should be back-enabled.

SO_MREADON

Enables the Stream head to generate M_READ(9) messages when processing a read(2s) 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

Disables the Stream head generation of an M_READ(9) message when processing a read(2s) 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(2s) and write(2s) system calls. This sets the STRNDEL flag in the sd_flag member of the Stream head stdata(9) structure. If both SO_NDELON and SO_NDELOFF are set in so_flags, SO_NDELOFF has precedence.

If O_NDELAY (or O_NONBLOCK) is set, a read(2s) will return zero (0) if no data is waiting to be read at the Stream head. If O_NDELAY (or O_NONBLOCK) is clear, a read(2s) will block until data becomes available at the Stream head.

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

SO_NDELOFF

Set STREAMS semantics for O_NDELAY (or O_NONBLOCK) processing on read(2s) and write(2s) system calls. This clears the STRNDEL flag in the sd_flag member of the Stream head stdata(9) structure. This is the default for newly created Stream heads. If both SO_NDELON and SO_NDELOFF are set in so_flags, SO_NDELOFF has precedence.

If O_NDELAY (or O_NONBLOCK) is set, a read(2s) will return minus one (-1) and set errno(3) to [EAGAIN] if no data is waiting to be read at the Stream head. If O_NDELAY (or O_NONBLOCK) is clear, a read(2s) will block until data becomes available at the Stream head.

If O_NDELAY (or O_NONBLOCK) is set, a write(2s) will return minus one (-1) and set errno(3) to [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(2s) will terminate and return the number of bytes written. If O_NDELAY (or O_NONBLOCK) is clear, a write(2s) will block on flow control and will block if buffers are not available.

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

SO_ISTTY

Sets the fact that the Stream is a control terminal for a process. That is, it is responsible for providing standard input, output and error connection for the process. This sets the STRISTTY flag in the sd_flag member of the Stream head stdata(9) structure. If both SO_ISNTTY and SO_ISNTTY are set in so_flags, SO_ISNTTY has precedence.

SO_ISNTTY

Sets the fact that the Stream is a non-controlling terminal. That is, it is not responsible for the standard input, output or error of any process. This clears the STRISTTY flag in the sd_flag member of the Stream head stdata(9) structure. If both SO_ISNTTY and SO_ISNTTY are set in so_flags, SO_ISNTTY has precedence.

Non-control terminals do not need to perform a large number of behaviours normally associated with ttys such as access control, job control, signals, tracking the session and group leaders and control processes, etc. In fact, ttys that are not controlling terminals can be treated largely as normal STREAMS.

SO_TOSTOP

Sets the Stream head so that it will stop a process attempting to perform a background write to the Stream. This sets the STRTOSTOP flag in the sd_flag member of the Stream head stdata(9) structure. If both SO_TOSTOP and SO_TONSTOP are set in so_flags, SO_TONSTOP takes precedence.

SO_TONSTOP

Resets the Stream head so that it will not stop a process an attempting to perform a background write to the Stream. This clears the STRTOSTOP flag in the sd_flag member of the Stream head stdata(9) structure. If both SO_TOSTOP and SO_TONSTOP are set in so_flags, SO_TONSTOP takes precedence.

SO_BAND

Specifies that the so_minpsz, so_maxpsz, so_hiwat, so_lowat, fields and the SO_MINPSZ, SO_MAXPSZ, SO_HIWAT, SO_LOWAT, flags apply to the message band---qband(9) structure---specified in so_band.

SO_DELIM

Set the Stream head for message delimitation. This sets the STRDELIM flag in the sd_flag member of the stdata(9) structure. If both SO_DELIM and SO_NODELIM are set in so_flags, SO_NODELIM takes precedence.

Setting the STRDELIM flag alters the Stream head behaviour for handling of read(2s) and write(2s) in byte-stream read mode.

When STRDELIM is set, read(2s) will terminate on a delimited message and will not return a zero-length delimited message to the Stream head read queue on a short read. Also, when the file is set for blocking operation in byte-stream read mode, the caller will block until either nbytes have been read, a message boundary is encountered, a zero-length message is encountered, or a signal or error conditions occurs. Zero-length messages that are delimited (indicating read cessation) will not be returned to the Stream head write queue but non-delimited zero-length messages (indicating end-of-file) will. This is consistent with SVR 4[1] read(2s) behaviour.

When STRDELIM and SNDMREAD are both set on the Stream head, the generation of M_READ(9) messages by the Stream head is altered.

---

The generation of M_READ(9) messages is altered when the STRDELIM flag is also set. If there is insufficient data available at the Stream head read queue and read(2s) goes to block for the first time, regardless of whether some data has already been transferred, read(2s) generates an M_READ(9) message downstream with the number of bytes remaining outstanding to service the read request. This is consistent with SVR 4 behaviour for the generation of M_READ(9).

---

The handling of M_READ(9) messages by the downstream driver or module should be altered. When there is sufficient data available at the downstream module to service the request, the M_READ(9) is transformed into an M_DATA(9) message containing the requested data and returned upstream. When there is insufficient data at the downstream driver or module to service the request, one of three actions should be taken:

1): If there is some amount of data less than the requested amount available, the driver or module may transform the M_READ(9) message into a M_DATA(9) message containing the available data. The MSGDELIM flag can be set on this message to make read(2s) terminate the read with a short read, or can be left unset to cause read(2s) to block awaiting additional data.
2): If there is no data available at the driver or module, the driver or module may transform the M_READ(9) message into a zero-length M_DATA(9) message, setting the MSGDELIM flag on this message, and responding with it upstream. This will signal read(2s) at the Stream head to terminate the read with a short count. Note, however, that if no data has been read so far at the Stream head when the zero-length message arrives, read(2s) will terminate and return zero (0).
3): If there is no data available at the driver or module, or there is insufficient data that the module or driver does not wish to forward at this time, the driver or module may discard the M_READ(9) message and defer taking any action. read(2s) will then block at the Stream head awaiting the arrival of data.

When STRDELIM is set, write(2s) will add MSGDELIM flags to indicated delimited messages. The MSGDELIM flag is set in the last M_DATA(9) message of a full write. Partial writes do not set the MSGDELIM flag in any message. This is also true for buffers longer than q_maxpsz, where q_minpsz is zero and write(2s) breaks the write into multiple q_maxpsz-sized messages. In this case, MSGDELIM is only set on the last M_DATA(9) message in the sequence and only when a full write of nbytes occurs.

SO_NODELIM

Reset the Stream head from message delimitation. This clears the STRDELIM flag in the sd_flag member of the stdata(9) structure. This is the default for newly created Stream heads. If both SO_DELIM and SO_NODELIM are set in so_flags, SO_NODELIM takes precedence.

Clearing the STRDELIM flag alters the Stream head behaviour for handling of read(2s) and write(2s) in byte-stream read mode.

When STRDELIM is clear, read(2s) will terminate when nbytes are read, some data has been read and there is no more data to be read immediately at the Stream head read queue, when a zero-length message is encountered. Message boundaries are ignored. Zero-length messages (that can only indicate end-of-file) are returned to the Stream head read queue to be consumed by a subsequent call. read(2s) only terminates on a signal or error condition when the signal or error condition is detected before data any is read. This is consistent with POSIX[2] read(2s) behaviour.

When SNDMREAD is set and STRDELIM is clear, the generation of M_READ(9) messages at the Stream head and the necessary interpretation of M_READ(9) messages at the downstream driver or module are as described above under SO_MREADON .

When STRDELIM is clear, write(2s) will generate no MSGDELIM flags in messages.

SO_STRHOLD

Sets the Stream head for the message hold option. STREAMS provides a hold option that improves the performance of STREAMS when the process issues many small writes. The message hold option is enabled if the system adminstrator has changed the system control, sysctl_str_strhold, to be non-zero and if the Stream head flag STRHOLD is set by a driver or module. A downstream driver or module sets the Stream head STRHOLD bit by sending a M_SETOPTS(9) message upstream with the SO_STRHOLD flag set in the so_flags member of the stroptions(9) stucture contained in the message. (The ldterm(4) tty line discipline module does this.) The process may also issue a I_SWROPT(7) command to ioctl(2s) with the SNDHOLD flag set in the argument to enable the hold option on a particular Stream, but this is a Linux Fast-STREAMS extension. Normally the hold option can only be activated and deactivated by a downstream module or driver.

The message hold option exploits the fact that allocb(9) allocates a buffer with a data size that is always equal to or greater than FASTBUF. The buffer is allocated and the data is copied into it. write(2s) then checks to see if another write(2s) of the same size will fit into the same buffer. If it will, the buffer is held temporarily on the Stream head write queue, a timer is started (usually, 10 milliseconds, but settable with the sysctl_str_rtime system control), and the Stream head is linked into the scanqhead list in the STREAMS scheduler.

One of three things will then happen:

1): A second write(2s) occurs with a data part that is small enough to fit into the remaining portion of the saved buffer. The data is put into the buffer and sent downstream. Since two writes have been sent downstream in one message, the optimization is successful.
2): A second write(2s) occurs with a data portion that is too big to fit into the remaining portion of the saved buffer. The saved message is sent downstream followed by another message holding the data of the second write(2s).
3): No second write(2s) occurs so the timer expires. The timeout processing performed by queuerun(9) scans the scanqhead list in the STREAMS scheduler and sends downstream any messages held on the Stream head write queues whose timeouts have expired.

In implementation it is not too difficult to multiplex a single timer against the scanqhead list, rather than setting a timer per Stream.

Solaris®[3] no longer implements this option. LiS[4] implements this option but chooses the expensive route of running a 10 millisecond timer per Stream with the feature. Since 10 milliseconds is a single tick on older Linux kernels, it is a particularly bad idea to run many single-tick timers.

SO_ERROPT

When the SO_ERROPT flag is specified in the so_flags member of the stroptions structure, the so_erropt member is interpreted by the Stream head.

The so_erropt member can contain one of the following flags:

RERRNORM: Specifies normal read error operation at the Stream head: any read error will be returned for any read system call issued on the Stream head until the error is reset by the driver or module.
RERRNONPERSIST: Specifies non-persistent read error operation at the Stream head: any read error will be returned for the first read system call issued on the Stream head and automatically reset thereafter.

and one of the following flags:

WERRNORM: Specifies normal write error operation at the Stream head: any write error will be returned for any write system call issued on the Stream head until the error is reset by the driver or module.
WERRNONPERSIST: Specifies non-persistent write error operation at the Stream head: any write error will be returned for the first write system call issued on the Stream head and automatically reset thereafter.

The SO_ERROPT flag and the associated so_erropt member are Solaris®[3] specific options implemented by Linux Fast-STREAMS for compatibility. The error options can also be examine or set by the user with the I_GERROPT(7) and I_SERROPT(7) STREAMS input output controls, streamio(7). See COMPATIBILITY , below.

SO_LOOP

SO_LOOP is an undocumented UnixWare®[5] specific option, not implemented by Linux Fast-STREAMS. See COMPATIBILITY , below.

SO_COPYOPT

so_copyopt can contain zero or more of the following flags:

MAPINOK: Specifies that user data forming the data part of a write(2s), putmsg(2) or putpmsg(2s) call should be mapped into the kernel instead of copied in with copyin(9).
NOMAPIN: Specifies the normal behaviour that user data forming the data part of a write operation will be copied in with copyin(9).

If both MAPINOK and NOMAPIN are set, If neither are set, the existing Stream head setting is unchanged in this regard. NOMAPIN takes precedence.

REMAPOK: Specifies that user data forming the data part of a read(2s), getmsg(2), or getpmsg(2s) call should be page-flipped from the kernel into user sapce instead of copied out with copyout(9).
NOREMAP: Specifies the normal behaviour that user data forming the data part of a read operation will be copied out with copyout(9).

If both REMAPOK and NOREMAP are set, NOREMAP takes precedence. If neither are set, the existing Stream head setting is unchanged in this regard.

Note that the MAPINOK, NOMAPIN, REMAPOK and NOREMAP flags are located in <sys/stropts.h> instead of <sys/stream.h>.

SO_COPYOPT and the associated so_copyopt member of the stroptions structure are Solaris® specific options not implemented by Linux Fast-STREAMS. See COMPATIBILITY , below.

SO_MAXBLK

SO_MAXBLK and the associated so_maxblk member of the stroptions structure are Solaris® specific options not implemented by Linux Fast-STREAMS. Solaris® provides the capability of changing the maximum block size on a per-stream basis. Linux Fast-STREAMS takes the SVR 4.2 approach of enforcing only a global maximum block size for all streams. See COMPATIBILITY , below.

SO_COWENABLE

SO_COWDISABLE

SO_COWENABLE and SO_COWDISABLE are OSF/1®[6] and HPUX®[7] specific flags that are not well documented.

Linux Fast-STREAMS reserves these two flags for a zero-copy implementation at the Stream head that works as follows:

When the Stream head is set for copy-on-write with the SO_COWENABLE flag, data portions of messages are mapped from user-space into kernel space and the copy-on-write characteristic set on the mapped kernel page. Any attempt to write to the page will result in a copy of the user-space page to the kernel page before writing. If no attempt is made to write to the page, and effective zero-copy architecture results in which the data can be copied directly from user space to interface devices at the driver.

This mechanism is not yet implemented by Linux Fast-STREAMS, however, these two flags are reserved for such a future implementation.

SO_WRPAD

Specifies the write padding (for the b_wptr member of the msgb(9) structure message block) for the message block after the extent where data will be written. write(2s) applies this padding after writing data into the last M_DATA(9) message block passed downstream as a result of the write(2s) operation. putmsg(2) and putpmsg(2s) applies this padding after writing data into the last M_DATA(9) message block that forms part of a message before passing the message downstream.

Although Linux Fast-STREAMS applies the write padding to each message in the fashion described above, the downstream module cannot always assume that M_DATA(9) message blocks contain the appropriate write padding. It is possible that M_DATA(9) was either generated by or modified by an intervening module and that it did not contain the write padding because it was either not generated by the Stream head, or it was subsequently modified by an intervening module. The driver or module that requested a write offset should ensure that the appropriate offset exists by comparing the db_lim pointer to the b_wptr pointer to ensure that the appropriate padding exists in the necessary message blocks.

The SO_WRPAD flag and the associated so_wrpad member are specific to Linux Fast-STREAMS. SO_WRPAD and so_wrpad are similar to SO_WROFF and so_wroff with the exception that instead of adding an offset to the beginning of a data buffer for the data part of a message, (that is, specifying headroom for the buffer) SO_WRPAD and so_wrpad specify the amount of padded added to the end of the data buffer for the data part of a message, (that is, specifies the tailroom for the buffer).

SO_NOCSUM

SO_CSUM

SO_CRC32C

Specifies the checksum algorithm to be used to calculate a partial checksum when copying data from the user into M_DATA(9) message blocks. The result of the partial checksum will be written to the b_csum member of the msgb(9) structure and the appropriate message flag (MSGCSUM or MSGCRC32C) will be set in the corresponding b_flag member. This permits a Van Jacobson style checksum and copy operation for networking protocol streams, and is used by Linux Fast-STREAMS high-performance network pseudo-device drivers.

The SO_NOCSUM, SO_CSUM and SO_CRC32C flags, the b_csum member, and the MSGCSUM and MSGCRC32C message flags are specific to Linux Fast-STREAMS.

SO_SKBUFF

SO_NOSKBUFF

Specifies whether Linux style socket buffers (struct sk_buff) are to be allocated to form the data buffer of the data block instead of the normal kernel memory allocation associated with allocb(9).

When specified, the Stream head will allocate a socket buffer and perform a call to esballoc(9) with the data buffer portion of the socket buffer described and a special frtn_t(9) structure that will free the socket buffer when the data block is freed. The stream head will also set the DB_SKBUFF flag in the db_flag member of the datab(9) structure to indicate to downstream drivers that a socket buffer has already been allocated and associated with the data block.

Downstream drivers or modules that recognize the DB_SKBUFF flag can acquire a reference to the socket buffer using skb_get() or skb_clone() on the socket buffer pointer stored in db_frtn->free_arg. Note that the socket buffer is initially empty and is left by the Stream head in the state that it was when freshly allocated.

This option is used by Linux Fast-STREAMS high-performance network drivers to avoid excessive handling and conversion of data buffers between STREAMS and underlying Linux packet handling.

The SO_SKBUFF and SO_NOSKBUFF flags are specific to Linux Fast-STREAMS.

USAGE

M_SETOPTS messages cannot be generated directly by a user level process. M_SETOPTS messages arriving at a driver can be discarded (ignored and freed). M_SETOPTS messages are consumed by the Stream head. M_SETOPTS can be generated by drivers and modules.

The following are guidelines for processing of the M_SETOPTS message in drivers and modules:

*: Intermediate modules that do not recognize the M_SETOPTS message must pass it on as any normal priority message. That is, it is subject to flow control and order must be maintained with other normal priority messages on the queue.
*: Drivers that do not recognize the M_SETOPTS message will discard it.
*: Modules recognizing the M_SETOPTS message may record or alter its contents, but must pass the message upstream or downstream to the Stream head. Note that the message can arrive at a Stream head in the downstream direction for a STREAMS-based pipe(4).
: One reason for a module to alter the contents of a M_SETOPTS message is to, for example, add its own write offset requirements to the write offset requirements of the driver.

The M_SETOPTS message is used whenever a driver or module wishes to change a Stream head setting synchronized with the data stream.

NOTICES

The zero-copy architectures offerred by the Solaris® SO_COPYOPT option, and the OSF/1® and HPUX® SO_COWENABLE and SO_COWDISABLE option, are attractive and a similar mechanism should be implemented for Linux Fast-STREAMS.

COMPATIBILITY

The M_SETOPTS STREAMS message is compatible with SVR 4.2 MP STREAMS, and implementations based on SVR 4, with the following portability considerations:

---: M_SETOPTS has a different constant value on older versions of OSF/1®[6], and older versions of LiS[4].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[8] instead of LiS[4].
---: The SO_STRHOLD option is only implemented by SVR 4[9], UnixWare®[5], and Solaris®[3], LiS[4] and Linux Fast-STREAMS[8], although the flag is defined by other STREAMS implementations.
: Portable STREAMS drivers and modules may set this option but should not rely on the option being truly implemented by the Stream head.
---: SO_ERROPT, SO_COPYOPT and SO_MAXBLK and the associated so_erropt, so_copyopt and so_maxblk members of the stroptions structure are Solaris®[3] specific. These options are implemented by Linux Fast-STREAMS for compatibility with Solaris®.
: Portable STREAMS drivers and modules will not use these options.
---: SO_LOOP is an undocumented and unimplemented UnixWare®[5] specific option.
: Portable STREAMS drivers and modules will not attempt to use this option.
---: SO_COWENABLE and SO_COWDISABLE are undocumented and unimplemented OSF/1®[6] and HPUX®[7] specific options.
: Portable STREAMS drivers and modules will not attempt to use these options.
---: SO_WRPAD, SO_NOCSUM, SO_CSUM, SO_CRC32C, SO_SKBUFF and SO_NOSKBUF, the associated so_wrapd and b_csum members, and the MSGCSUM and MSGCRC32C message flags, are Linux Fast-STREAMS specific options.
: Portable STREAMS drivers and modules will not attempt to use these options.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[10].

HISTORY

The M_SETOPTS message first appeared in SVR 3[11].

REFERENCES

[1]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[2]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[4]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[6]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[7]: HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>
[8]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[9]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[10]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[11]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.