Manpage of M_PROTO

M_PROTO

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

NAME

M_PROTO - STREAMS protocol message

FORMAT

The M_PROTO message block is a datab(9) structure and associated data buffer that contains unstructured data. (Any structure imposed on the M_PROTO data buffer is defined outside of STREAMS.)

An M_PROTO message is a normal priority message that consists of one or more M_PROTO message blocks followed by zero or more M_DATA(9) message blocks.

INTERFACE

STREAMS.

DESCRIPTION

The M_PROTO message is intended to contain control information and associated data. The message format is one or more M_PROTO message blocks followed by zero or more M_DATA(9) message blocks. (Note that a user level process can only generate M_PROTO messages containing a single M_PROTO message block followed by one or more M_DATA(9) message blocks when using the putmsg(2) or putpmsg(2s) system calls.)

The semantics of the M_PROTO and M_DATA(9) message blocks are determined by the STREAMS module that receives the message, and is normally defined as part of the service interface description between modules.

For example, the Transport Provider Interface, tpi(7), describes the format of M_PROTO and M_DATA(9) message blocks contained in M_PROTO messages that are passed to a driver or module implementing the tpi(7) service interface. The service interface exists between the user level process and the receiving driver or module, or, between drivers and modules.

The M_PROTO message block will normally contain service interface control information and the M_DATA(9) message blocks will normally contain service interface user data.

M_PROTO messages are generally sent in both the downstream and upstream directions on a Stream. M_PROTO messages sent upstream and arriving at the Stream head are available to be read by user level processes using the read(2s), getmsg(2), or getpmsg(2s) system calls. M_PROTO messages can be sent downstream from the Stream head by a user level process using the putmsg(2), or putpmsg(2s) system calls. (The write(2s) cannot be used to generate M_PROTO messages.)

When describing STREAMS-specific system calls, the contents of the M_PROTO message block is referred to as the control part, and any M_DATA(9) message blocks contained in the message are referred to collectively as the data part. For the getmsg(2), getpmsg(2s), putmsg(2), and putpmsg(2s) system calls, the control and data parts are passed separately. For the read(2s) system call, the control and data parts are optionally passed together, or the the control part is discarded.

Although its use is not recommended, the format of M_PROTO and M_PCPROTO(9) (generically PROTO) messages sent upstream to the Stream head allows multiple PROTO blocks at the beginning of the message. getmsg(2), getpmsg(2s), and read(2s), will compact multiple PROTO blocks into a single control part, multiple M_DATA(9) blocks, as single data part, when passing them to the user process. The putmsg(2) and putpmsg(2s) system calls will never generate a M_PROTO message with more than one M_PROTO message block, but may generate M_PROTO messages that contain more than one M_DATA(9) message block.

M_PROTO messages, by nature of the initial block message type, are normal (or priority) messages, and are, therefore, subject to flow control restrictions within a Stream. In contrast, the M_PCPROTO(9) message is a high priority message serving the same purpose, that is not subject to flow control restrictions. M_PROTO messages can be generated directly by user level processes using the putmsg(2) and putpmsg(2s) system calls. M_PROTO messages can be consumed by user level processes using the read(2s), getmsg(2), and getpmsg(2s) system calls. M_PROTO message can be generated by drivers and modules.

USAGE

M_PROTO and M_PCPROTO(9) messages are the work horses of a service interface under STREAMS. They are generated by both user level processes as well as drivers and modules. These messages normally represent service primitives within a service interface definition at a message passing boundary within a Stream. The M_PROTO data buffer usually has a defined structure with an initial member that identifies the service primitive, and additional members that provide the parameters associated with the service primitive. The M_DATA(9) data buffers that follow usually contain unstructured user data.

EXAMPLES

For example, one service primitive definition from the Transport Provider Interface, tpi(7), the T_CONN_REQ(7) connection request primitive, is illustrated below:

 1  /* 
 2   *  T_CONN_REQ, M_PROTO
 3   *
 4   *  This primitive requests that the transport
 5   *  provider make a connection to the specified
 6   *  destination.
 7   */
 8  struct T_conn_req {
 9      t_scalar_t PRIM_type;       /* always T_CONN_REQ */
10      t_scalar_t DEST_length;     /* dest addr length */
11      t_scalar_t DEST_offset;     /* dest addr offset */
12      t_scalar_t OPT_length;      /* options length */
13      t_scalar_t OPT_offset;      /* options offset */
14  };

The T_CONN_REQ(7) service primitive consists of one M_PROTO message blocks followed by zero or more M_DATA(9) blocks representing connection data. The format of the M_PROTO data buffer is the T_conn_req structure shown above. The first element of the structure, the PRIM_type is used to distinguish on M_PROTO message from another. In this case, the PRIM_type is always set to T_CONN_REQ to identify the connection request primitive.

The T_conn_req structure definition is used both by user level processes accessing the tpi(7) service interface, as well as drivers or modules implementing the service interface.

The following code fragment is an example of a user level process formulating and passing a connection request to a Stream.

 1  struct {
 2      struct T_conn_req prim;
 3      unsigned char adds[sizeof(destaddr)];
 4      unsigned char opts[sizeof(toptions)];
 5  }
 6  myprim;
 7  
 8  unsigned char data[DATASIZE];
 9  
10  struct strbuf ctlbuf =
11      { -1, sizeof(myprim), (char *) &myprim };
12  struct strbuf databuf =
13      { -1, sizeof(data), (char *) data };
14  
15  myprim.prim.PRIM_type = T_CONN_REQ;
16  
17  myprim.prim.DEST_length = sizeof(destaddr);
18  myprim.prim.DEST_offset = sizeof(myprim.prim);
19  memcpy(opts, &toptions, sizeof(toptions));
20  
21  myprim.prim.OPT_length = sizeof(toptions);
22  myprim.prim.OPT_offset =
23      sizeof(myprim.prim) + sizeof(adds);
24  memcpy(adds, &destaddr, sizeof(destaddr));
25  
26  if (putmsg(fd, &ctlbuf, &databuf, 0) == -1) {
27      perror("putmsg failed");
28      exit(1);
29  }

Following code fragment is an example of a module generating a connection request and passing it downstream. In this case, the primitive is expedited (priority band 1).

 1  mblk_t *mp, *dp;
 2  struct T_conn_req *p;
 3  size_t size =
 4      sizeof(p) + sizeof(destaddr) +
 5      sizeof(toptions);
 6  
 7  if ((mp = allocb(size, BPRI_MED))) {
 8      if ((dp = allocb(sizeof(data), BPRI_MED))) {
 9          mp->b_datap->db_type = M_PROTO;
10          mp->b_band = 1;     /* expedite */
11          p = (typeof(p)) mp->b_wptr;
12          p->PRIM_type = T_CONN_REQ;
13          p->DEST_length = sizeof(destaddr);
14          p->DEST_offset = sizeof(*p);
15          p->OPT_length = sizeof(toptions);
16          p->OPT_offset =
17              sizeof(*p) + sizeof(destaddr);
18          mp->b_wptr += sizeof(p);
19          bcopy(&destaddr, mp->b_wptr,
20                sizeof(destaddr));
21          mp->b_wptr += sizeof(destaddr);
22          bcopy(&toptions, mp->b_wptr,
23                sizeof(toptions));
24          mp->b_wptr += sizeof(toptions);
25          bcopy(&data, dp->b_wptr, sizeof(data));
26          dp->b_wptr += sizeof(data);
27          linkb(mp, dp);
28          putnext(q, mp);
29          return (0);
30      } else
31          freeb(mp);
32  }
33  return (-ENOBUFS);

In both code fragments, the same structure definition as part of a service interface definition is used by both the user level process and the STREAMS driver or module. This service interface definition is normally contained in a header file that is used by both kernel modules and user processes (in this example <sys/tihdr.h>).

COMPATIBILITY

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

---: The M_PROTO message is standard across STREAMS implementations, and has no portability issues.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[1].

HISTORY

The M_PROTO message first appeared in SVR 3[2].

REFERENCES

[1]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

This document was created by man2html, using the manual pages.
Time: 11:32:57 GMT, May 22, 2013