1allocb(9F) Kernel Functions for Drivers allocb(9F)
2
6 allocb - allocate a message block
7
9 #include <sys/stream.h>
10 mblk_t *allocb(size_t size, uint_t pri);
14
17 Architecture independent level 1 (DDI/DKI).
18
20 The allocb() function tries to allocate a STREAMS message block. Buf‐
21 fer allocation fails only when the system is out of memory. If no buf‐
22 fer is available, the bufcall(9F) function can help a module recover
23 from an allocation failure.
24 A STREAMS message block is composed of three structures. The first
27 structure is a message block (mblk_t). See msgb(9S). The mblk_t struc‐
28 ture points to a data block structure (dblk_t). See datab(9S). Together
29 these two structures describe the message type (if applicable) and the
30 size and location of the third structure, the data buffer. The data
31 buffer contains the data for this message block. The allocated data
32 buffer is at least double-word aligned, so it can hold any C data
33 structure.
34 The fields in the mblk_t structure are initialized as follows:
37 b_cont set to NULL
39 b_rptr points to the beginning of the data buffer
42 b_wptr points to the beginning of the data buffer
45 b_datap points to the dblk_t structure
48 The fields in the dblk_t structure are initialized as follows:
52 db_base points to the first byte of the data buffer
54 db_lim points to the last byte + 1 of the buffer
57 db_type set to M_DATA
60 The following figure identifies the data structure members that are
64 affected when a message block is allocated.
65 Printed copy or docs.sun.com shows a figure that identifies the data
67 structure members that are affected when a message block is allocated
68
70 size The number of bytes in the message block.
71 pri Priority of the request (no longer used).
74
77 Upon success, allocb() returns a pointer to the allocated message block
78 of type M_DATA. On failure, allocb() returns a NULL pointer.
79
81 The allocb() function can be called from user, interrupt, or kernel
82 context.
83
85 Example 1 allocb() Code Sample
86 Given a pointer to a queue (q) and an error number (err), the
89 send_error() routine sends an M_ERROR type message to the stream head.
90 If a message cannot be allocated, NULL is returned, indicating an allo‐
94 cation failure (line 8). Otherwise, the message type is set to M_ERROR
95 (line 10). Line 11 increments the write pointer (bp->b_wptr) by the
96 size (one byte) of the data in the message.
97 A message must be sent up the read side of the stream to arrive at the
101 stream head. To determine whether q points to a read queue or to a
102 write queue, the q->q_flag member is tested to see if QREADR is set
103 (line 13). If it is not set, q points to a write queue, and in line 14
104 the RD(9F) function is used to find the corresponding read queue. In
105 line 15, the putnext(9F) function is used to send the message upstream,
106 returning 1 if successful.
107 1 send_error(q,err)
110 2 queue_t *q;
111 3 unsigned char err;
112 4 {
113 5 mblk_t *bp;
114 6
115 7 if ((bp = allocb(1, BPRI_HI)) == NULL) /* allocate msg. block */
116 8 return(0);
117 9
118 10 bp->b_datap->db_type = M_ERROR; /* set msg type to M_ERROR */
119 11 *bp->b_wptr++ = err; /* increment write pointer */
120 12
121 13 if (!(q->q_flag & QREADR)) /* if not read queue */
122 14 q = RD(q); /* get read queue */
123 15 putnext(q,bp); /* send message upstream */
124 16 return(1);
125 17 }
126
129 RD(9F), bufcall(9F), esballoc(9F), esbbcall(9F), putnext(9F),
130 testb(9F), datab(9S), msgb(9S)
131 Writing Device Drivers
134 STREAMS Programming Guide
137
139 The pri argument is no longer used, but is retained for compatibility
140 with existing drivers.
141SunOS 5.11 16 Jan 2006 allocb(9F)