share/man/man9f/dupb.9f

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (C) 2002, Sun Microsystems, Inc.
   4 .\" All Rights Reserved
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH DUPB 9F "Mar 22, 2002"
   9 .SH NAME
  10 dupb \- duplicate a message block descriptor
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/stream.h>
  15
  16
  17
  18 \fBmblk_t *\fR\fBdupb\fR(\fBmblk_t *\fR\fIbp\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Architecture independent level 1 (DDI/DKI).
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 \fBdupb()\fR creates a new  \fBmblk_t\fR structure (see \fBmsgb\fR(9S)) to
  29 reference the message block pointed to by  \fIbp\fR.
  30 .sp
  31 .LP
  32 Unlike  \fBcopyb\fR(9F), \fBdupb()\fR does not copy the information in the
  33 \fBdblk_t\fR structure (see \fBdatab\fR(9S)), but creates a new  \fBmblk_t\fR
  34 structure to point to it. The reference count in the  \fBdblk_t\fR structure
  35 (\fBdb_ref\fR) is incremented.  The new \fBmblk_t\fR structure contains the
  36 same information as the original.  Note that \fBb_rptr\fRand \fBb_wptr\fR are
  37 copied from the \fIbp\fR.
  38 .sp
  39 Printed copy or docs.sun.com shows a figure that shows a new mblk_t structure
  40 created, with the original and new bp both pointing to the dblk_t structure,
  41 and db_ref incremented by one
  42 .SH PARAMETERS
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIbp\fR \fR
  47 .ad
  48 .RS 7n
  49 Pointer to the message block to be duplicated. \fBmblk_t\fR is an instance of
  50 the  \fBmsgb\fR(9S) structure.
  51 .RE
  52
  53 .SH RETURN VALUES
  54 .sp
  55 .LP
  56 If successful,  \fBdupb()\fR returns a pointer to the new message block. A
  57 \fINULL\fR pointer is returned if  \fBdupb()\fR cannot allocate a new message
  58 block descriptor or if the \fBdb_ref\fR field of the data block structure (see
  59 \fBdatab\fR(9S)) has reached a maximum value (\fB255\fR).
  60 .SH CONTEXT
  61 .sp
  62 .LP
  63 \fBdupb()\fR can be called from user, kernel, or interrupt context.
  64 .SH EXAMPLES
  65 .LP
  66 \fBExample 1 \fRUsing \fBdupb()\fR
  67 .sp
  68 .LP
  69 This  \fBsrv\fR(9E) (service) routine adds a header to  all  \fBM_DATA\fR
  70 messages before passing them along.   \fBdupb\fR is used instead of
  71 \fBcopyb\fR(9F) because the contents of the header block are not changed.
  72
  73 .sp
  74 .LP
  75 For each message on the queue, if it is a priority message, pass it along
  76 immediately (lines 10-11). Otherwise, if it is anything other than an
  77 \fBM_DATA\fR message (line 12), and if it can be sent along (line 13), then do
  78 so (line 14). Otherwise, put the message back on the queue and return (lines
  79 16-17). For all  \fBM_DATA\fR messages, first check to see if the stream is
  80 flow-controlled (line 20). If it is, put the message back on the queue and
  81 return (lines 37-38).  If it is not, the header block is duplicated (line 21).
  82
  83 .sp
  84 .LP
  85 \fBdupb()\fR can fail either due to lack of resources or because the message
  86 block has already been duplicated 255 times.  In order to handle the  latter
  87 case, the example calls \fBcopyb\fR(9F) (line 22).  If \fBcopyb\fR(9F) fails,
  88 it is due to buffer allocation failure.  In this case,  \fBqbufcall\fR(9F) is
  89 used to initiate a callback (lines 30-31) if one is not already pending (lines
  90 26-27).
  91
  92 .sp
  93 .LP
  94 The callback function, \fBxxxcallback()\fR, clears the recorded
  95 \fBqbufcall\fR(9F) callback id and schedules the service procedure (lines
  96 49-50).  Note  that the close routine,  \fBxxxclose()\fR, must cancel any
  97 outstanding  \fBqbufcall\fR(9F) callback requests (lines 58-59).
  98
  99 .sp
 100 .LP
 101 If  \fBdupb()\fR or  \fBcopyb\fR(9F) succeed, link the  \fBM_DATA\fR message to
 102 the new message block (line 34)  and pass it along (line 35).
 103
 104 .sp
 105 .in +2
 106 .nf
 107        1  xxxsrv(q)
 108       2      queue_t *q;
 109       3  {
 110       4   struct xx *xx = (struct xx *)q->q_ptr;
 111       5   mblk_t *mp;
 112       6   mblk_t *bp;
 113       7   extern mblk_t *hdr;
 114       8
 115       9   while ((mp = getq(q)) != NULL) {
 116      10        if (mp->b_datap->db_type >= QPCTL) {
 117      11             putnext(q, mp);
 118      12        } else if (mp->b_datap->db_type != M_DATA) {
 119      13             if (canputnext(q))
 120      14                  putnext(q, mp);
 121      15             else {
 122      16                  putbq(q, mp);
 123      17                  return;
 124      18             }
 125      19        } else {  /* M_DATA */
 126      20             if (canputnext(q)) {
 127      21                  if ((bp = dupb(hdr)) == NULL)
 128      22                       bp = copyb(hdr);
 129      23                  if (bp == NULL) {
 130      24                       size_t size = msgdsize(mp);
 131      25                       putbq(q, mp);
 132      26                       if (xx->xx_qbufcall_id) {
 133      27                            /* qbufcall pending */
 134      28                            return;
 135      29                       }
 136      30                       xx->xx_qbufcall_id = qbufcall(q, size,
 137      31                            BPRI_MED, xxxcallback, (intptr_t)q);
 138      32                       return;
 139      33                  }
 140      34                  linkb(bp, mp);
 141      35                  putnext(q, bp);
 142      36             } else {
 143      37                  putbq(q, mp);
 144      38                  return;
 145      39             }
 146      40        }
 147      41   }
 148      42  }
 149      43   void
 150      44   xxxcallback(q)
 151      45        queue_t *q;
 152      46   {
 153      47        struct xx *xx = (struct xx *)q->q_ptr;
 154      48
 155      49        xx->xx_qbufcall_id = 0;
 156      50        qenable(q);
 157      51   }
 158
 159      52   xxxclose(q, cflag, crp)
 160      53        queue_t *q;
 161      54        int  cflag;
 162      55        cred_t *crp;
 163      56   {
 164      57        struct xx *xx = (struct xx *)q->q_ptr;
 165                ...
 166      58        if (xx->xx_qbufcall_id)
 167      59             qunbufcall(q, xx->xx_qbufcall_id);
 168                ...
 169      60   }
 170 .fi
 171 .in -2
 172
 173 .SH SEE ALSO
 174 .sp
 175 .LP
 176 \fBsrv\fR(9E), \fBcopyb\fR(9F), \fBqbufcall\fR(9F), \fBdatab\fR(9S),
 177 \fBmsgb\fR(9S)
 178 .sp
 179 .LP
 180 \fIWriting Device Drivers\fR \fISTREAMS Programming Guide\fR