allocb(9F) Kernel Functions for Drivers allocb(9F)NAMEallocb - allocate a message block
SYNOPSIS
#include <sys/stream.h>
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. Buf‐
fer allocation fails only when the system is out of memory. If no buf‐
fer is available, the bufcall(9F) function 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 struc‐
ture 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 allocated 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 follows:
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 follows:
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.
Please see the online man page on docs.sun.com or a print copy
for the diagram.
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, indicating an allo‐
cation 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.
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) function 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 ALSORD(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 compatibility
with existing drivers.
SunOS 5.10 16 Jan 2006 allocb(9F)
