Manpage of M_COPYOUT

M_COPYOUT

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

NAME

M_COPYOUT - STREAMS copyout message

FORMAT

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

An M_COPYOUT message is a high priority message that consists of one M_COPYOUT message block followed by one or more M_DATA(9) message blocks.

INTERFACE

STREAMS.

DESCRIPTION

The M_COPYOUT is a high priority message generated by a driver or module and sent upstream to request that the Stream head perform a copyout(9) on behalf of the driver or module. It is valid only after receiving an M_IOCTL(9) message and before an M_IOCACK(9) or M_IOCNAK(9), for a given ioctl operation identifier, ioc_id .

M_COPYOUT is a high priority message that is not subject to flow control within a Stream. The format of the message is one M_COPYOUT message block followed by one or more M_DATA(9) blocks. The M_COPYOUT message block contains a copyreq(9) structure, defined in <sys/stream.h>:

struct copyreq {
    int cq_cmd;         /* ioctl command (from ioc_cmd) */
    cred_t *cq_cr;      /* full credentials */
    uint cq_id;         /* ioctl id (from ioc_id) */
    caddr_t cq_addr;    /* address top copy data to/from */
    uint cq_size;       /* number of bytes to copy */
    int cq_flag;        /* SVR 3.2 compatibility */
    mblk_t *cq_private; /* private state information */
    long cq_filer[4];   /* reserved for future use */
};

The first three members of the structure correspond to those of the iocblk(9) structure in the M_IOCTL(9) message block which allows the same message block to be reused for both structures. The Stream head will guarantee that the message block allocated for the M_IOCTL(9) message is large enough to contain a copyreq(9) structure. The cq_addr field contains the user space address to which the data are to be copied. The cq_size field is the number of bytes to copy to user space.

The cq_private field can be used by a module to point to a message block containing the module's state information relating to this ioctl(2s). The Stream head will copy (without processing) the contents of this field to the M_IOCDATA(9) reponse message so that the module can resume the associated state. If an M_COPYIN(9) or M_COPYOUT(9) message is freed, STREAMS will not free any message block pointed to by cq_private. This is the module's responsibility.

Data to be copied to user space is contained in the linked M_DATA(9) blocks.

The driver or module responding to a tranparent M_IOCTL(9) message issues a M_COPYOUT message when it wishes to copy data out to the user. The message is formulated and issued upstream to the Stream head. When reveived by the Stream head, the Stream head will attempt to copy out the requested amount of data of size cq_size, to the user address cq_addr, using the copyout(9) utility.

If the copyout(9) operation succeeds, the Stream head will reply with an M_IOCDATA(9) message block whose cp_rval member is set to (caddr_t)(0), indicating that the operation was successful.

If the copyout(9) operation fails, the Stream head will reply with an M_IOCDATA(9) message block whose cp_rval member is set to (caddr_t)(1), to indicate the error, and then aborts the ioctl(2s) operation and returns [EFAULT] to the user in errno(3). This provides the driver or module with the opportunity to clean up the cq_private pointer when the ioctl(2s) operation is aborted.

See M_IOCDATA(9), for more information. M_COPYOUT messages cannot be directly generated by a user level process. M_COPYOUT messages arriving at a non-multiplexing driver should be discarded (ignored and freed). M_COPYOUT messages can be generated by a driver or module responding to an M_IOCTL(9) message.

USAGE

The following guidelines represent best practise for processing of the M_COPYOUT message by drivers and modules:

*: Intermediate modules that do not intend to process this message will not queue the M_COPYOUT message upstream. In any event, an intermediate module must not flush or discard an M_COPYOUT message.
: As only one ioctl(2s) operation, and therefore, one M_COPYOUT message can be in progress on a Stream, queueing of the message would cause unnecessary delay in processing a transparent ioctl(2s). Only one high priority message can be outstanding at the Stream head, so ordering of this message with respect to other high priority messages is not an issue.
*: Modules or drivers should only issue a M_COPYOUT message as part of a transparent ioctl(2s) operation.
*: The message should be created by transforming a received M_IOCTL(9) or M_IOCDATA(9) message.
*: The driver or module issuing this message should attach all state information pertaining to the ioctl(2s) operation using the cq_private pointer in the M_COPYOUT message block.
: Issuing drivers or modules will consider in their design that a misbehaving module might flush or discard the message.
*: The driver or module design can expect that an M_IOCDATA(9) reply to a M_COPYOUT message will arrive reliably. The queue pair's qi_qclose(9) procedure will not be invoked until after the M_IOCDATA(9) message has been delivered to the module's qi_putp(9) procedure.

EXAMPLES

The following procedure fragment provides an example of handling of M_COPYOUT messages on the read-side of an intermediate module. Note that at line 16, M_COPYOUT (and M_COPYIN(9)) messages are passed upstream without queuing.

   1  int
   2  xxx_rput(queue_t *q, mblk_t *mp)
   3  {
   4      int type;
   5  
   6      if ((type = mp->b_datap->db_type) >= QPCTL) {
   7          switch (type) {
   8          case M_PCPROTO:
   9              do_message_processing(q, mp);
  10              break;
  11              /* ... */
  12          case M_FLUSH:
  13              /* perform canonical flushing */
  14              /* ... */
  15              /* fall through */
  16          default:                /* e.g. M_COPYOUT */
  17              /* unhandled high-priority message */
  18              putnext(q, mp);
  19              break;
  20          }
  21      } else if (!q->q_first && !q->q_flag & QSVCBUSY
  22                 && bcanputnext(q, mp->b_band)) {
  23          switch (type) {
  24          case M_PROTO:
  25          case M_DATA:
  26              do_message_rpocessing(q, mp);
  27              break;
  28              /* ... */
  29          default:
  30              /* unhandled normal priority message */
  31              putnext(q, mp);
  32              break;
  33          }
  34      } else {
  35          putq(q, mp);
  36      }
  37      return (0);
  38  }

The following code fragment provides an example of proper issuance of an M_COPYOUT message and handling of the response from a driver:

   1  void
   2  do_ioctl(queue_t *q, mblk_t *mp)
   3  {
   4      struct iocblk *ioc;
   5      struct copyreq *cq;
   6      struct copyresp *cp;
   7  
   8      switch (mp->b_datap->db_type) {
   9      case M_IOCTL:
  10          ioc = (typeof(ioc)) mp->b_rptr;
  11          switch (ioc->ioc_cmd) {
  12          case KNOWN_IOCTL:
  13              if (ioc->ioc_count == TRANSPARENT) {
  14                  cq = (typeof(cq)) mp->b_rptr;
  15                  cq->cq_addr =
  16                      *(typeof(cq->cq_addr) *)
  17                      mp->b_cont->b_rptr;
  18                  cq->cq_size = KNOWN_IOCTL_SIZE;
  19                  cq->cq_private = (mblk_t *) (1);
  20                  mp->b_datap->db_type = M_COPYIN;
  21                  freemsg(mp->b_cont);
  22                  if (!(mp->b_cont =
  23                        allocb(KNOWN_IOCTL_SIZE,
  24                               BPRI_MED))) {
  25                      mp->b_datap->db_type = M_IOCNAK;
  26                      ioc->ioc_rval = -1;
  27                      ioc->ioc_error = ENOBUFS;
  28                      qreply(q, mp);
  29                      return;
  30                  }
  31                  bcopy(data, mp->b_cont->b_wptr,
  32                        KNOWN_IOCTL_SIZE);
  33                  mp->b_cont->b_wptr +=
  34                      KNOWN_IOCTL_SIZE;
  35                  qreply(q, mp);
  36                  return;
  37              }
  38              /* copied in data is in mp->b_cont for
  39                 I_STR ioctls */
  40              break;
  41          default:
  42              mp->b_datap->db_type = M_IOCNAK;
  43              qreply(q, mp);
  44              return;
  45          }
  46          /* fall through */
  47      case M_IOCDATA:
  48          cp = (typeof(cq)) mp->b_rptr;
  49          if (cp->cp_rval) {
  50              /* copy error, abort */
  51              cp->cp_private = NULL;
  52              freemsg(mp);
  53              return;
  54          }
  55          cp->cp_private = NULL;
  56          mp->b_datap->db_type = M_IOCACK;
  57          ioc = (typeof(ioc)) mp->b_rptr;
  58          ioc->ioc_rval = 0;
  59          ioc->ioc_error = 0;
  60          qreply(q, mp);
  61          return;
  62      default:
  63          freemsg(mp);
  64          return;
  65      }
  66  }

COMPATIBILITY

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

---: LiS[1] erroneously expects an M_IOCNAK(9) message containing an error when it responds to the driver with an M_IOCDATA(9) message with a cp_rval of (caddr_t)(1). See M_IOCDATA(9), for more information.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[2] instead of LiS[1].
---: M_COPYOUT has a different constant value on HP-UX®[3], MacOT®[4], OSF/1®[5], and older versions of LiS[1].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[2] instead of LiS[1].
---: Binary compatiblity is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[6].

HISTORY

The M_COPYOUT message first appeared in SVR 3[7].

REFERENCES

[1]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[3]: 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/>
[4]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>
[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]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[7]: 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: 05:19:38 GMT, May 20, 2013