allocb(D3DK) —

.IX \f4allocb\fP(D3DK)

NAME

allocb − allocate a message block .IX message (STREAMS)
.IX STREAMS message blocks

SYNOPSIS

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

ARGUMENTS

sizeThe number of bytes in the message block.

priPriority of the request. This can take on one of four values: BPRI_LO, BPRI_MED, BPRI_HI, or BPRI_CONSOLE.

DESCRIPTION

allocb 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(D3DK) function can help a module recover from an allocation failure.

The pri argument is a hint to the allocator indicating how badly the message is needed. BPRI_LO should be used for normal data allocations. BPRI_MED should be used for other non-critical allocations. BPRI_HI should be used for allocations that absolutely must succeed, although success is not guaranteed. Some implementations may choose to ignore this parameter. BPRI_CONSOLE should only be used by console drivers. This priority will fail only if the system is out of physical memory.

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

scale=100
define t181 |
[ box invis ht 48 wid 63 with .sw at 0,0
"b_cont (0)" at 0,42 ljust
"b_rptr" at 0,30 ljust
"b_wptr" at 0,18 ljust
"b_datap" at 0,6 ljust
] |
define t176 |
[ box invis ht 30 wid 96 with .sw at 0,0
"message block" at 48,23
"(mblk_t)" at 48,7
] |
define t190 |
[ box invis ht 30 wid 72 with .sw at 0,0
"data block" at 36,23
"(dblk_t)" at 36,7
] |
define t186 |
[ box invis ht 54 wid 115 with .sw at 0,0
"db_base" at 0,48 ljust
"db_lim" at 0,34 ljust
"db_type (M_DATA)" at 0,20 ljust
] |
box invis ht 116 wid 442 with .sw at 0,0
box ht 72 wid 98 with .nw at 0,84
line -> from 76,36 to 152,36
line from 74,62 to 106,62
line from 106,62 to 106,48
line from 106,48 to 74,48
line from 106,56 to 136,56
line from 136,56 to 136,116
t181 with .nw at 12,77
t176 with .nw at 0,-1
t190 with .nw at 192,-1
"data buffer" at 404,-8
line from 238,74 to 312,74
line -> from 312,74 to 360,84
line from 238,62 to 314,62
line -> from 314,62 to 360,12
box ht 72 wid 152 with .nw at 152,84
box ht 72 wid 82 with .nw at 360,84
line from 360,76 to 440,76 dotted
line from 360,20 to 440,20 dotted
line from 138,116 to 402,116
line -> from 400,116 to 400,84
t186 with .nw at 164,76

.IX \f4msgb\fP(D4DK)
.IX \f4datab\fP(D4DK)

RETURN VALUE

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.

LEVEL

Base or Interrupt.

NOTES

Does not sleep.

Driver-defined basic locks, read/write locks, and sleep locks may be held across calls to this function.

EXAMPLE

.IX \f4allocb\fP(D3DK), example
.IX \f4putnext\fP(D3DK), example
.IX \f4RD\fP(D3DK), 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 7). Otherwise, the message type is set to M_ERROR (line 8). Line 9 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 10). If it is not set, q points to a write queue, and on line 11 the RD(D3DK) function is used to find the corresponding read queue. In line 12, the putnext(D3DK) function is used to send the message upstream. Then send_error returns 1 indicating success.

1 send_error(q, err)
2queue_t ∗q;
3uchar_t err;
4 {
5mblk_t ∗bp;
6if ((bp = allocb(1, BPRI_HI)) == NULL)
7return(0);
8bp->b_datap->db_type = M_ERROR;
9∗bp->b_wptr++ = err;
10if (!(q->q_flag & QREADR))
11q = RD(q);
12putnext(q, bp);
13return(1);
14 }

DDI/DKI — STREAMS

Museum