share/man/man9f/allocb.9f

   1 '\" te
   2 .\" Copyright (C) 2006, Sun Microsystems, Inc.
   3 .\" All Rights Reserved.
   4 .\" Copyright 1989 AT&T
   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 ALLOCB 9F "Jan 16, 2006"
   9 .SH NAME
  10 allocb \- allocate a message block
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/stream.h>
  15
  16
  17
  18 \fBmblk_t *\fR\fBallocb\fR(\fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\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 The \fBallocb()\fR function tries to allocate a \fBSTREAMS\fR message block.
  29 Buffer allocation fails only when the system is out of memory. If no buffer is
  30 available, the \fBbufcall\fR(9F) function can help a module recover from an
  31 allocation failure.
  32 .sp
  33 .LP
  34 A \fBSTREAMS\fR message block is composed of three structures. The first
  35 structure is a message block (\fBmblk_t\fR). See \fBmsgb\fR(9S). The
  36 \fBmblk_t\fR structure points to a data block structure (\fBdblk_t\fR). See
  37 \fBdatab\fR(9S). Together these two structures describe the message type (if
  38 applicable) and the size and location of the third structure, the data buffer.
  39 The data buffer contains the data for this message block. The allocated data
  40 buffer is at least double-word aligned, so it can hold any C data structure.
  41 .sp
  42 .LP
  43 The fields in the \fBmblk_t\fR structure are initialized as follows:
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBb_cont\fR\fR
  48 .ad
  49 .RS 11n
  50 set to  \fINULL\fR
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBb_rptr\fR\fR
  57 .ad
  58 .RS 11n
  59 points to the beginning of the data buffer
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBb_wptr\fR\fR
  66 .ad
  67 .RS 11n
  68 points to the beginning of the data buffer
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBb_datap\fR\fR
  75 .ad
  76 .RS 11n
  77 points to the \fBdblk_t\fR structure
  78 .RE
  79
  80 .sp
  81 .LP
  82 The fields in the \fBdblk_t\fR structure are initialized as follows:
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBdb_base\fR\fR
  87 .ad
  88 .RS 11n
  89 points to the first byte of the data buffer
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBdb_lim\fR\fR
  96 .ad
  97 .RS 11n
  98 points to the last byte + 1 of the buffer
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBdb_type\fR\fR
 105 .ad
 106 .RS 11n
 107 set to \fBM_DATA\fR
 108 .RE
 109
 110 .sp
 111 .LP
 112 The following figure identifies the data structure members that are affected
 113 when a message block is allocated.
 114 .sp
 115 Printed copy or docs.sun.com shows a figure that identifies the data structure
 116 members that are affected when a message block is allocated
 117 .SH PARAMETERS
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fIsize\fR\fR
 122 .ad
 123 .RS 8n
 124 The number of bytes in the message block.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fIpri\fR\fR
 131 .ad
 132 .RS 8n
 133 Priority of the request (no longer used).
 134 .RE
 135
 136 .SH RETURN VALUES
 137 .sp
 138 .LP
 139 Upon success, \fBallocb()\fR returns a pointer to the allocated message block
 140 of type \fBM_DATA\fR. On failure, \fBallocb()\fR returns a \fINULL\fR pointer.
 141 .SH CONTEXT
 142 .sp
 143 .LP
 144 The \fBallocb()\fR function can be called from user, interrupt, or kernel
 145 context.
 146 .SH EXAMPLES
 147 .LP
 148 \fBExample 1 \fR\fBallocb()\fR Code Sample
 149 .sp
 150 .LP
 151 Given a pointer to a queue (\fIq\fR) and an error number (\fIerr\fR), the
 152 \fBsend_error()\fR routine sends an  \fBM_ERROR\fR type message to the stream
 153 head.
 154
 155 .sp
 156 .LP
 157 If a message cannot be allocated, \fINULL\fR is returned, indicating an
 158 allocation failure (line 8). Otherwise, the message type is set to
 159 \fBM_ERROR\fR (line 10). Line 11 increments the write pointer
 160 (\fBbp->b_wptr\fR) by the size (one byte) of the data in the message.
 161
 162 .sp
 163 .LP
 164 A message must be sent up the read side of the stream to arrive at the stream
 165 head. To determine whether  \fIq\fR points to a read queue or to a write queue,
 166 the \fBq->q_flag\fR member is tested to see if \fBQREADR\fR is set (line 13).
 167 If it is not set, \fIq\fR points to a write queue, and in line 14 the
 168 \fBRD\fR(9F) function is used to find the corresponding read queue. In line 15,
 169 the \fBputnext\fR(9F) function is used to send the message upstream, returning
 170 \fB1\fR if successful.
 171
 172 .sp
 173 .in +2
 174 .nf
 175 1  send_error(q,err)
 176 2    queue_t *q;
 177 3    unsigned char err;
 178 4  {
 179 5    mblk_t *bp;
 180 6
 181 7    if ((bp = allocb(1, BPRI_HI)) == NULL) /* allocate msg. block */
 182 8         return(0);
 183 9
 184 10    bp->b_datap->db_type = M_ERROR;    /* set msg type to M_ERROR */
 185 11    *bp->b_wptr++ = err;               /* increment write pointer */
 186 12
 187 13    if (!(q->q_flag & QREADR))         /* if not read queue     */
 188 14         q = RD(q);                    /*    get read queue     */
 189 15    putnext(q,bp);                     /* send message upstream */
 190 16    return(1);
 191 17  }
 192 .fi
 193 .in -2
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBRD\fR(9F), \fBbufcall\fR(9F), \fBesballoc\fR(9F), \fBesbbcall\fR(9F),
 199 \fBputnext\fR(9F), \fBtestb\fR(9F), \fBdatab\fR(9S), \fBmsgb\fR(9S)
 200 .sp
 201 .LP
 202 \fIWriting Device Drivers\fR
 203 .sp
 204 .LP
 205 \fISTREAMS Programming Guide\fR
 206 .SH NOTES
 207 .sp
 208 .LP
 209 The \fIpri\fR argument is no longer used, but is retained for compatibility
 210 with existing drivers.