Manual Pages for UNIX Operating System command usage for man allocb

Kernel Functions for Drivers                           allocb(9F)



NAME
     allocb - allocate a message block

SYNOPSIS
     #include 



     mblk_t *allocb(size_t size, uint_t pri);


INTERFACE LEVEL
     Architecture independent level 1 (DDI/DKI).

DESCRIPTION
     The allocb() function tries to allocate  a  STREAMS  message
     block.   Buffer allocation fails only when the system is out
     of memory. If no buffer is available, the bufcall(9F)  func-
     tion can help a module recover from an allocation failure.


     A STREAMS message block is composed of three structures. The
     first  structure  is a message block (mblk_t). See msgb(9S).
     The mblk_t  structure  points  to  a  data  block  structure
     (dblk_t).  See  datab(9S).  Together  these  two  structures
     describe the message type (if applicable) and the  size  and
     location  of  the third structure, the data buffer. The data
     buffer contains the data for this message block.  The  allo-
     cated data buffer is at least double-word aligned, so it can
     hold any C data structure.


     The fields in the mblk_t structure are initialized  as  fol-
     lows:

     b_cont     set to  NULL


     b_rptr     points to the beginning of the data buffer


     b_wptr     points to the beginning of the data buffer


     b_datap    points to the dblk_t structure



     The fields in the dblk_t structure are initialized  as  fol-
     lows:





SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                           allocb(9F)



     db_base    points to the first byte of the data buffer


     db_lim     points to the last byte + 1 of the buffer


     db_type    set to M_DATA



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

     Printed copy or docs.sun.com shows a figure that  identifies
     the  data structure members that are affected when a message
     block is allocated

PARAMETERS
     size    The number of bytes in the message block.


     pri     Priority of the request (no longer used).


RETURN VALUES
     Upon success, allocb() returns a pointer  to  the  allocated
     message block of type M_DATA. On failure, allocb() returns a
     NULL pointer.

CONTEXT
     The allocb() function can be called from user, interrupt, or
     kernel context.

EXAMPLES
     Example 1 allocb() Code Sample


     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, NULL is returned, indicat-
     ing  an  allocation failure (line 8). Otherwise, the message
     type is set to  M_ERROR (line 10). Line  11  increments  the
     write  pointer   (bp->b_wptr)  by the size (one byte) of the
     data in the message.







SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                           allocb(9F)



     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 to a write queue, the  q->q_flag  member  is
     tested  to see if QREADR is set (line 13). If it is not set,
     q points to a write queue, and in line 14 the  RD(9F)  func-
     tion  is  used to find the corresponding read queue. In line
     15, the putnext(9F) function is used  to  send  the  message
     upstream, returning 1 if successful.


       1  send_error(q,err)
       2    queue_t *q;
       3    unsigned char err;
       4  {
       5    mblk_t *bp;
       6
       7    if ((bp = allocb(1, BPRI_HI)) == NULL) /* allocate msg. block */
       8         return(0);
       9
       10    bp->b_datap->db_type = M_ERROR;    /* set msg type to M_ERROR */
       11    *bp->b_wptr++ = err;               /* increment write pointer */
       12
       13    if (!(q->q_flag & QREADR))         /* if not read queue     */
       14         q = RD(q);                    /*    get read queue     */
       15    putnext(q,bp);                     /* send message upstream */
       16    return(1);
       17  }


SEE ALSO
     RD(9F),     bufcall(9F),     esballoc(9F),     esbbcall(9F),
     putnext(9F), testb(9F), datab(9S), msgb(9S)


     Writing Device Drivers


     STREAMS Programming Guide

NOTES
     The pri argument is no longer used, but is retained for com-
     patibility with existing drivers.













SunOS 5.11          Last change: 16 Jan 2006                    3