MSGB

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

NAME

msgb, mblk_t - STREAMS message block structure

SYNOPSIS


#include <sys/stream.h>
typedef struct msgb {
    struct msgb *b_next;   /* next msgb on queue */
    struct msgb *b_prev;   /* prev msgb on queue */
    struct msgb *b_cont;   /* next msgb in message */
    unsigned char *b_rptr; /* rd pointer into datab */
    unsigned char *b_wptr; /* wr pointer into datab */
    struct datab *b_datap; /* pointer to datab */
    unsigned char b_band;  /* band of this message */
    unsigned char b_pad1;  /* padding */
    unsigned short b_flag; /* message flags */
    unsigned char b_pad2[sizeof(ulong) - 4]; /* padding */
    long b_csum;           /* checksum */
} mblk_t;

MEMBERS

The following members correspond to SVR 4.2 EFT members:

b_next

the next msgb structure on a queue(9);

b_prev

the previous msgb structure on a queue(9);

b_cont

next msgb structure in the chain representing a single message;

b_rptr

a pointer into the data from which to read;

b_wptr

a pointer into the data to which to write;

b_datap

a pointer to the datab structure representing the actual data;

b_band

the qband(9) to which this message belongs;

b_pad1

padding;

b_flag

message flags:

MSGMARK: last byte of message is marked;
MSGNOLOOP: don't loop message at stream head;
MSGDELIM: message is delimited;
MSGNOGET: UnixWare®[1], Solaris®[2], MacOT®[3], UXP/V®[4]: getq does not return message;
MSGATTEN: UXP/V®[4]: attention to on read side;
MSGMARKNEXT: Solaris®[2]: next message is marked;
MSGLOG: UnixWare®[1]: log on arrival of this message;
MSGNOTMARKNEXT: Solaris®[2]: next message is not marked;
MSGCOMPRESS: OSF/1®[5]: compress like messages as space allows;
MSGNOTIFY: OSF/1®[5]: notify when message consumed;
MSGCSUM: Linux Fast-STREAMS: b_csum contains TCP/UDP partial checksum;
MSGCRC32C: Linux Fast-STREAMS: b_csum conatains SCTP partial checksum;

b_pad2

padding.

The following members are Linux Fast-STREAMS[6] specific members:

b_csum: checksum.

MACROS

The following macros are available in <sys/strsun.h> and are Solaris® macros that are used to perform some simple operations on message blocks:

MBLKL(mp): Returns the length of the message block as a difference between the b_wptr and b_rptr pointers. This value could be negative.
MBLKSIZE(mp): Returns the available length from the data block as a difference between the db_lim and db_base pointers. This value could be negative. See also datab(9).
MBLKHEAD(mp): Returns the available headroom in the data block as a difference between the b_rptr and db_base pointers. This value could be negative, but should not normally be less than zero.
MBLKTAIL(mp): Returns the available headroom in the data block as a difference between the db_lim and b_wptr pointers. This value could be negative, but should not normally be less than zero.
MBLKIN(mp, off, len): Tests and returns a boolean indicating whether the offset and length provided defines a region that is contained within the message block.
OFFSET(base, p): Returns the offset of pointer, p, from the base pointer, base.

FUNCTIONS

The following message block utility functions are provided, (each of these functions accept a message block pointer as an argument, or are otherwise useful in manipulating the data buffer):

adjmsg(9)-: trim bytes from the front or back of a message
allocb(9)-: allocate a message and data block
allocb_physreq(9)-: allocate a message and data block
alloc_proto(9)-: allocate a PROTO message
appq(9)-: append a message after another
bcopy(9)-: copy byte strings
bufcall(9)-: install a buffer callback
bzero(9)-: zero a byte string
copyb(9)-: copy a message block
copyin(9)-: copy bytes from user to kernel
copymsg(9)-: copy a message
copyout(9)-: copy bytes from kernel to user
datamsg(9)-: tests a message type for data
dupb(9)-: duplicate a message block
dupmsg(9)-: duplicate a message
esballoc(9)-: allocate a message and data block with a caller supplied data buffer
esbbcall(9)-: installs a buffer callback for an extended message block
freeb(9)-: frees a message block
freemsg(9)-: frees a message
getq(9)-: gets a message from a message queue
insq(9)-: inserts a message into a message queue
isdatablk(9)-: tests a data block for data type
isdatamsg(9)-: tests a data block for data type
linkb(9)-: link a message block to a message
linkmsg(9)-: link a message block to a message
mi_bufcall(9)-: reliable alternative to bufcall(9)
msgdsize(9)-: calculate the size of the data in a message
msgphysreq(9)-: physical alignement request structure
msgpullup(9)-: pull up bytes in a message
msgpullup_physreq(9)-: pull up bytes in a message with physical requirements
msgscgth(9)-: message scatter-gather structure
msgsize(9)-: calculate the size of the message blocks in a message
pcmsg(9)-: determine priority of a message
pullupmsg(9)-: pull up the bytes in a message
put(9)-: invokes a message queue put procedure
putbq(9)-: puts a message back on a message queue
putctl1(9)-: puts a 1 byte control message on a message queue
putctl2(9)-: puts a 2 byte control message on a message queue
putctl(9)-: puts a control message on a message queue
puthere(9)-: invokes a message queue put procedure
putnext(9)-: puts a message on the next message queue
putnextctl1(9)-: puts a 1 byte control message on the next message queue
putnextctl2(9)-: puts a 2 byte control message on the next message queue
putnextctl(9)-: puts a control message on the next message queue
putq(9)-: puts a message on a message queue
qbufcall(9)-: install a synchronous buffer callback
queclass(9)-: return the class of a message
qunbufcall(9)-: cancel a synchronous buffer callback
rmvb(9)-: remove a message block from a message
rmvq(9)-: remove a message from a message queue
testb(9)-: test is a message can be allocated
unbufcall(9)-: removes a buffer callback
unlinkb(9)-: unlink a message block from a message
wantmsg(9)-: provide a filter of wanted messages for a module
xmsgsize(9)-: calculate the size of message blocks in a message

See the corresponding manual page for each utility for more information.

INTERFACE

STREAMS.

DESCRIPTION

STREAMS messages are composed of a 3-type consisting of message block (msgb structure), data block (datab(9) structure) and an associated internal, external, or extended, data buffer. Message blocks (msgb structures) form an instance of a reference to a data block, datab(9), and associated data buffer. As such, the msgb structure contains information pertaining to the reference instance.

The b_datap, b_rptr, b_wptr, and b_cont, members are significant in each message block in a message block chain.

b_datap points to the datab(9) data block structure which has an associated data buffer. See datab(9) for more information on data blocks.

b_rptr and b_wptr point into the data buffer to delimit the bytes of the buffer pertinent to the reference. b_rptr is the read-pointer and points where bytes are to be read from the buffer. b_wptr is the write-pointer and points where bytes are to be written to the buffer.

b_cont is used to link message blocks together to form a message block chain representing a STREAMS message.

Typically, the b_next, b_prev, b_band, and b_flag, members are only significant in the first message block of a message block chain, and are considered to apply to the entire chain of message blocks along the b_cont member.

b_next and b_prev are used to link the (initial) message block (of a message block chain) onto a message queue(9). b_next points to the next message on the message queue, or NULL if the message is at the tail of the message queue. b_prev points to the previous message on the message queue, or NULL if the message is at the head of the message queue.

b_band indicates the queuing priority when the message is placed on a message queue.

b_flag contains some flags that can be used to mark a set of binary conditions on a message block or message. See the description of these flags under Flags , below.

Flags

Message flags are significant in the first message block of a message, and are contained in the b_flag member of the msgb structure forming the first message block. The available flags are as follows:

MSGMARK: MSGMARK is recognized by the Stream head. MSGMARK indicates that the last bye of the message is marked. Marked mesages identify out-of-band data to the Stream head. Marked messages terminate the read(2s) of unmarked messages, generating a short read, as an indication to the reader that an out-of-band condition has occurred. The I_ATMARK(7) input-output control command can be used to determine whether the data stream is positioned at a marked message, and whether there are further marked messages in the receive buffer. When positioned at a marked message, subsequent reads will consume marked messages.
: The MSGMARK flag is set by drivers and modules and is recognized by the Stream head. The flag is only useful for messages sent upstream to the Stream head. For details, see I_ATMARK(7) and read(2s).
MSGNOLOOP: The MSGNOLOOP flag is set by the Stream head and recognized by the Stream head. The Stream head sets the MSGNOLOOP flag on received M_FLUSH(9) messages looped back downstream from the Stream head. If an M_FLUSH(9) message marked with MSGNOLOOP arrives at the Stream head, the Stream head will not loop the message back downstream, but will discard (ignore and free) it. The Stream head ignores the MSGNOLOOP flag on messages of type other than M_FLUSH(9).
: This flag should not be modified by drivers and modules. For details, see M_FLUSH(9).
MSGDELIM: The MSGDELIM flag is both placed on messages in the data stream generated by the Stream head, as well as recognized by the Stream head in received messages in the data stream. When the SO_DELIM option is set on the Stream head using M_SETOPTS(9), the Stream head will mark the last data message of a complete write(2s) operation with MSGDELIM as an indication to downstream drivers and modules of record delineation. When the Stream head receives a data message with the MSGDELIM flag, the message will terminate a read(2s) operation, with a short read. Zero-length messages received with the MSGDELIM flag set will terminate a read and be removed from the receive queue. (Normally, zero-length messages are left on the receive queue for a subsequent read.)
: Modules and drivers may also generate or recognize messages marked with MSGDELIM. For details, see M_SETOPTS(9), write(2s), and read(2s).
MSGNOGET: The MSGNOGET flag is defined in early header files for MacOT®[3], Solaris®[2], UnixWare®[1], UXP/V®[4], and it is commented that this flag tells getq(9) not to return the message. However, this flag is poorly documented, and does not appear to be implemented. It may have orignally been used to pin a message on the Stream head receive queue for read(2s) processing with multiple readers, but has fallen out of use. getq(9) does not recognize this flag.

The remaining flags are implementation specific and not defined by SVR 4.2 MP[7].

MSGATTEN: UXP/V®[4] defines this flag and it is described as indicating attention to the read side (whatever that means). The flag is poorly documented. It might be intended to terminate a read(2s) early, without having to generate an M_SIG(9) message upstream, and without actually generating a signal and causing read(2s) to fail. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it.
MSGMARKNEXT: Solaris®[2] defines this flag and uses it during Stream head processing of messages marked with MSGMARK. The flag is poorly documented. Its use appears to be private to the Stream head read queue, and this flag should not be set by drivers and modules. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it.
MSGLOG: UnixWare®[1]: defines this flag and it is commented that the message is to be logged on arrival (whatever that means). The flag is poorly documented. It might be intended to request that the Stream head log the message when it arrives in some fashion.
: The flag would then be generated by a driver or module and recognized by the Stream head. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it.
MSGNOTMARKNEXT: Solaris®[2] defines this flags and uses it during Stream head processing of messages marked with MSGMARK. The flag is poorly documented. Its use appears to be private to the Stream head read queue, and this flag should not be set by drivers and modules. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it.
MSGCOMPRESS: OSF/1®[5] defines this flag and it is commented that this flag request that like messages be compressed as space allows (whatever that means). The flag is poorly documented. It is possible that this flag is sent to the Stream head or intermediate module when a steady stream of identical messages is the norm (e.g., this is often the case for Level 2 processing in Signalling System No. 7). Any like messages queued could simply have a repeat count incremeneted and the copy discarded.
: This flag could be generated and recognized by Stream head, drivers or modules. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it.
MSGNOTIFY: AIX®[8], OSF/1®[5], and HP-UX®[9], define this flag and, in those implementations, it is recognized by the Stream head. The flag is poorly documented, however, when a message marked with the MSGNOTIFY flag is received, the Stream head generates an M_NOTIFY(9) message downstream to notify the driver or module that the message marked with MSGNOTIFY has been read by a user level process.
: Modules and drivers can set this flag on messages sent to the Stream head. Although Linux Fast-STREAMS defines the flag, the Stream head does not recognize it. For details, see M_NOTIFY(9).
MSGCSUM: Linux Fast-STREAMS[6] defines this flag. When checksumming is set on the Stream head with the SO_CSUM option flag set in a M_SETOPTS(9) message, the Stream head performs TCP/UDP partial checksum while copying in the data portion of a write(2s)-like operation and places the partial checsum result in the b_csum member of the M_DATA(9) message block and sets this MSGCSUM flag in the b_flag member of the message block to indicate the validity of the partial checksum.
MSGCRC32C: Linux Fast-STREAMS[6] defines this flag. When checksumming is set on the Stream head with the SO_CRC32C option flag set in a M_SETOPTS(9) message, the Stream head performs SCTP partial checksum while copying in the data portion of a write(2s)-like operation and places the partial checsum result in the b_csum member of the M_DATA(9) message block and sets this MSGCRC32C flag in the b_flag member of the message block to indicate the validity of the partial checksum.

USAGE

Ever modifying the b_datap pointer, can have dire consequences. Modifying the b_next, b_prev, b_cont, b_rptr, b_wptr, b_band, or b_flag, members of a message block while the message exists on a message queue, can have dire consequences. These members must be treated as read-only by drivers and modules whenever the message is on a message queue. To modify these members, the message must first be removed from any message queue.

The b_next and b_prev pointers can be modified while the message exists stand-alone; however, any values the module or driver may have assigned to these pointers in the first message block of a message will be overwritten when the message is placed on a message queue. The appq(9), insq(9), putq(9), putbq(9), utility functions place a message on a message queue.

The b_wptr and b_rptr pointers can be modified on stand-alone messages. The pullupmsg(9), msgpullup(9), msgsize(9), msgdsize(9), xmsgsize(9), message utility functions are useful for manipulating or examining these pointers.

THe b_cont pointer can be modified on stand-alone messages to link message chains. The rmvb(9), linkb(9), unlinkb(9), linkmsg(9), and unlinkmsg(9), message utilities are useful for manipulating the b_cont pointer.

b_band may be modified while the message exists stand-alone; however, when a high priority message is placed on a message queue, this member will always be overwritten with zero (0).

Macros

The following macros are available in <sys/strsun.h> and are Solaris® macros that are used to perform some simple operations on message blocks:

MBLKL(mp): Returns the length of the message block as a difference between the b_wptr and b_rptr pointers. This value could be negative.
MBLKSIZE(mp): Returns the available length from the data block as a difference between the db_lim and db_base pointers. This value could be negative. See also datab(9).
MBLKHEAD(mp): Returns the available headroom in the data block as a difference between the b_rptr and db_base pointers. This value could be negative, but should not normally be less than zero.
MBLKTAIL(mp): Returns the available headroom in the data block as a difference between the db_lim and b_wptr pointers. This value could be negative, but should not normally be less than zero.
MBLKIN(mp, off, len): Tests and returns a boolean indicating whether the offset and length provided defines a region that is contained within the message block.
OFFSET(base, p): Returns the offset of pointer, p, from the base pointer, base.

CONTEXT

Functions that operate on a message or data block can be called from any context. However, it is the caller's responsibility to ensure that the calling thread has exclusive access to the message block.

MP-STREAMS

All STREAMS utility functions that operate on or manipulate msgb message blocks, assume that the caller has exclusive access to the passed in message block pointer. When a message is placed to a queue, or the reference is otherwise passed to the called function, it is the obligation of the caller to relinquish any references invalidated by the call.

Most of the issues associated with messages impinge of the data block. See datab(9) for more information.

NOTICES

Members of the msgb structure should not be accessed directly by STREAMS drivers or modules. Portable STREAMS drivers and modules should, where possible, use the facilities provided for implementation and architectural independence.

COMPATIBILITY

The msgb structure is compatible with SVR 4.2 MP DDI/DKI[10], and systems based on SVR 4.2[11], with the following portability considerations:

---: SVR 4.2[7] has a long b_pad2 member at the end of the structure. So do many implementations based on SVR 4.2. Some implementations use this padding for its own purposes. Linux Fast-STREAMS has removed the added padding so that the resulting 3-tuple can be cache-aligned on both 32-bit and 64-bit architectures, also so that the internal buffer can be a minimum of 64-bytes on 32-bit architectures, and 128-bytes on 64-bit architectures.
: Portable STREAMS drivers and modules will not rely on the overall size of a message block, nor access fields intended as padding.
---: The flags defined for the b_flag member of the msgb structure are not necessarily binary compatible with any given implementation.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 EFT MP[11].

HISTORY

The msgb structure was introduced in SVR 3[12].

REFERENCES

[1]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[2]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[3]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>
[4]: UXP/V® V10L10, UXP/V Programmer's Guide: STREAMS V10, 1997, Fujitsu Limited, Fujitsu.
[5]: 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/>
[6]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[8]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[9]: 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/>
[10]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[11]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.