Kernel Functions for Drivers allocb(9F)
NAME
allocb - allocate a message block
SYNOPSIS
#include
mblkt *allocb(sizet size, uintt pri);
INTERFACE LEVEL
Architecture independent level 1 (DI/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 (mblkt). See msgb(9S).
The mblkt structure points to a data block structure
(dblkt). 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 mblkt structure are initialized as fol-
lows:
bcont set to NUL
brptr points to the beginning of the data buffer
bwptr points to the beginning of the data buffer
bdatap points to the dblkt structure
The fields in the dblkt structure are initialized as fol-
lows:
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers allocb(9F)
dbbase points to the first byte of the data buffer
dblim points to the last byte ] 1 of the buffer
dbtype set to MDATA
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 MDATA. On failure, allocb() returns a
NUL 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 senderror() routine sends an MEROR type message to
the stream head.
If a message cannot be allocated, NUL is returned, indicat-
ing an allocation failure (line 8). Otherwise, the message
type is set to MEROR (line 10). Line 11 increments the
write pointer (bp->bwptr) 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->qflag 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 senderror(q,err)
2 queuet *q;
3 unsigned char err;
4 {
5 mblkt *bp;
6
7 if ((bp = allocb(1, BPRIHI)) == NUL) /* allocate msg. block */
8 return(0);
9
10 bp->bdatap->dbtype = MEROR; /* set msg type to MEROR */
11 *bp->bwptr] = err; /* increment write pointer */
12
13 if (!(q->qflag & 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
|
