allocb(D3)

NAME
     allocb - allocate a message block

SYNOPSIS
     #include <sys/types.h>
     #include <sys/stream.h>
     #include <sys/ddi.h>
     mblk_t *allocb(int size, uint_t pri);

   Arguments
     size      The number of bytes in the message block.

     pri       Priority of the request.

DESCRIPTION
     allocb tries to allocate a STREAMS message block.

   Return Values
     If successful, allocb returns a pointer to the allocated message block of
     type M_DATA (defined in sys/stream.h).  If a block cannot be allocated, a
     NULL pointer is returned.

USAGE
     Buffer allocation fails only when the system is out of memory.  If no
     buffer is available, the bufcall(D3) function can help a module recover
     from an allocation failure.

     The psi argument is no longer used, but is retained for compatibility.

     The following figure identifies the data structure members that are
     affected when a message block is allocated.
     |
     ________
             |
     ________
           ______







           __


           __



                |
      b_cont (0)
      b_rptr
      b_wptr
      b_datap
   message block
     (mblk_t)
                  data block
                   (dblk_t)
                                data buffer
                        ______




                        ______










                 |
                 ____________
                             |
                 ____________
                                 |
                                 ______
                                        |
                                  ______
                                 .
                                  .
                                  .
                                   .
                                   .
                                   .
                                    .
                                    .
                                     .
                                     .
                                     .
                                      .
                                      .
                                       .
                                       .
                                       .
                                        .
                                 .
                                  .
                                  .
                                   .
                                   .
                                   .
                                    .
                                    .
                                     .
                                     .
                                     .
                                      .
                                      .
                                       .
                                       .
                                       .
                                        .
                _____________________
                                     |


                  db_base
                  db_lim
                  db_type (M_DATA)









   Level
     Base or Interrupt.

   Synchronization Constraints
     Does not sleep.

     Driver-defined basic locks, read/write locks, and sleep locks may be held
     across calls to this function.
   Example
     Given a pointer to a queue (q) and an error number (err), the send_error
     routine sends an M_ERROR type message to the stream head.

     If a message cannot be allocated, 0 is returned, indicating an allocation
     failure (line 8).  Otherwise, the message type is set to M_ERROR (line
     9).  Line 10 increments the write pointer (bp->b_wptr) by the size (one
     byte) of the data in the message.

     A message must be sent up the read side of the stream to arrive at the
     stream head.  To determine whether q points to a read queue or a write
     queue, the q->q_flag member is tested to see if QREADR is set (line 12).
     If it is not set, q points to a write queue, and on line 13 the RD(D3)
     function is used to find the corresponding read queue.  In line 14, the
     putnext(D3) function is used to send the message upstream.  Then
     send_error returns 1 indicating success.

      1  send_error(q, err)
      2   queue_t *q;
      3   uchar_t err;
      4  {
      5   mblk_t *bp;
      6   long fl=0;
      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  }

REFERENCES
     bufcall(D3), esballoc(D3), esbbcall(D3), freeb(D3), msgb(D4)