'\"! pic | mmdoc '\"macro stdmacro .if n .pH ddi.rm/d3/gen/allocb @(#)allocb 43.14 of 3/25/93 .\" Copyright 1992, 1991 UNIX System Laboratories, Inc. .TH allocb D3 .IX "\f4allocb\fP(D3)" .SH NAME \f4allocb\f1 \- allocate a message block .SH SYNOPSIS .nf .na .ft 4 #include #include #include .sp 0.4 mblk_t *allocb(int \f2size\fP, uint_t \f2pri\fP); .ft 1 .ad .fi .IX "message (STREAMS)" .IX "STREAMS message blocks" .SS Arguments .RS 0 .IP "\f2size\f1" 10n The number of bytes in the message block. .IP "\f2pri\f1" 10n Priority of the request. .RE .SH DESCRIPTION \f4allocb\f1 tries to allocate a STREAMS message block. .SS "Return Values" If successful, \f4allocb\f1 returns a pointer to the allocated message block of type \f4M_DATA\f1 (defined in \f4sys/stream.h\f1). If a block cannot be allocated, a \f4NULL\f1 pointer is returned. .SH USAGE Buffer allocation fails only when the system is out of memory. If no buffer is available, the \f4bufcall\f1(D3) function can help a module recover from an allocation failure. .P The psi argument is no longer used, but is retained for compatibility. .P The following figure identifies the data structure members that are affected when a message block is allocated. .nf .PS 3.5 scale=100 define t181 | [ box invis ht 48 wid 63 with .sw at 0,0 "\f4\s8\&b_cont (0)\f1\s0" at 0,42 ljust "\f4\s8\&b_rptr\f1\s0" at 0,30 ljust "\f4\s8\&b_wptr\f1\s0" at 0,18 ljust "\f4\s8\&b_datap\f1\s0" at 0,6 ljust ] | .sp 0.4 define t176 | [ box invis ht 30 wid 96 with .sw at 0,0 "\fH\s9\&message block\f1\s0" at 48,23 "\fH\s9\&(\f4mblk_t\f1)\f1\s0" at 48,7 ] | .sp 0.4 define t190 | [ box invis ht 30 wid 72 with .sw at 0,0 "\fH\s9\&data block\f1\s0" at 36,23 "\fH\s9\&(\f4dblk_t\f1)\s0" at 36,7 ] | .sp 0.4 define t186 | [ box invis ht 54 wid 115 with .sw at 0,0 "\f4\s8\&db_base\f1\s0" at 0,48 ljust "\f4\s8\&db_lim\f1\s0" at 0,34 ljust "\f4\s8\&db_type (M_DATA)\f1\s0" at 0,20 ljust ] | .sp 0.4 box invis ht 116 wid 442 with .sw at 0,0 box ht 72 wid 98 with .nw at 0,84 line -> from 76,36 to 152,36 line from 74,62 to 106,62 line from 106,62 to 106,48 line from 106,48 to 74,48 line from 106,56 to 136,56 line from 136,56 to 136,116 t181 with .nw at 12,77 t176 with .nw at 0,-1 t190 with .nw at 192,-1 "\fH\s9\&data buffer\f1\s0" at 404,-8 line from 238,74 to 312,74 line -> from 312,74 to 360,84 line from 238,62 to 314,62 line -> from 314,62 to 360,12 box ht 72 wid 152 with .nw at 152,84 box ht 72 wid 82 with .nw at 360,84 line from 360,76 to 440,76 dotted line from 360,20 to 440,20 dotted line from 138,116 to 402,116 line -> from 400,116 to 400,84 t186 with .nw at 164,76 .PE .fi .IX "\f4msgb\fP(D4)" .IX "\f4datab\fP(D4)" .SS Level Base or Interrupt. .SS "Synchronization Constraints" Does not sleep. .P Driver-defined basic locks, read/write locks, and sleep locks may be held across calls to this function. .SS Example .IX "\f4RD\fP(D3), Example" Given a pointer to a queue (\f2q\f1) and an error number (\f2err\f1), the \f4send_error\f1 routine sends an \f4M_ERROR\f1 type message to the stream head. .P If a message cannot be allocated, 0 is returned, indicating an allocation failure (line 8). Otherwise, the message type is set to \f4M_ERROR\f1 (line 9). Line 10 increments the write pointer (\f4bp->b_wptr\f1) by the size (one byte) of the data in the message. .P A message must be sent up the read side of the stream to arrive at the stream head. To determine whether \f2q\f1 points to a read queue or a write queue, the \%\f4q->q_flag\f1 member is tested to see if \f4QREADR\f1 is set (line 12). If it is not set, \f2q\f1 points to a write queue, and on line 13 the \f4RD\f1(D3) function is used to find the corresponding read queue. In line 14, the \f4putnext\f1(D3) function is used to send the message upstream. Then \f4send_error\fP returns 1 indicating success. .P .nf .ft 4 1 send_error(q, err) 2 queue_t *q; 3 uchar_t err; 4 { 5 mblk_t *bp; 6 long fl=0; .sp 0.4 7 if ((bp = allocb(1, BPRI_HI)) == NULL) 8 return(0); 9 bp->b_datap->db_type = M_ERROR; 10 *bp->b_wptr++ = err; 11 (void) strqget(q, QFLAG, 0, &fl); 12 if (fl & QREADR)) 13 q = RD(q); 14 putnext(q, bp); 15 return(\&1); 16 } .ft 1 .fi .SH REFERENCES .na \f4bufcall\fP(D3), \f4esballoc\fP(D3), \f4esbbcall\fP(D3), \f4freeb\fP(D3), \f4msgb\fP(D4) .ad