allocb(D3) allocb(D3)
NAME
allocb - allocate a message block
SYNOPSIS
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/ddi.h>
mblk_t *allocb(int size, uint_t pri);
Arguments
size The number of bytes in the message block.
pri Priority of the request.
DESCRIPTION
allocb tries to allocate a STREAMS message block.
Return Values
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.
USAGE
Buffer allocation fails only when the system is out of memory.
If no buffer is available, the bufcall(D3) 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.
The following figure identifies the data structure members
that are affected when a message block is allocated.
Warnings
Drivers should not assume that the memory allocated for the
data buffer is usable for DMA operations, nor should drivers
assume that the memory has any specific physical properties
such as starting address alignment, physical address range, or
physical contiguity. Beginning with ddi version 6, memory
with specific physical properties can be obtained through
allocb_physreq(D3).
Copyright 1994 Novell, Inc. Page 1
allocb(D3) allocb(D3)
Level
Base or Interrupt.
Synchronization Constraints
Does not sleep.
Driver-defined basic locks, read/write locks, and sleep locks
may be held across calls to this function.
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 8). Otherwise, the message type is
set to M_ERROR (line 9). Line 10 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 12). If it is not set, q points to
a write queue, and on line 13 the RD(D3) function is used to
find the corresponding read queue. In line 14, the
putnext(D3) function is used to send the message upstream.
Then send_error returns 1 indicating success.
1 send_error(q, err)
2 queue_t *q;
3 uchar_t err;
4 {
5 mblk_t *bp;
6 long fl=0;
7 if ((bp = allocb(1, BPRI_HI)) == NULL)
8 return(0);
9 bp->b_datap->db_type = M_ERROR;
10 *bp->b_wptr++ = err;
11 (void) strqget(q, QFLAG, 0, &fl);
12 if (fl & QREADR))
13 q = RD(q);
14 putnext(q, bp);
15 return(1);
16 }
Copyright 1994 Novell, Inc. Page 2
allocb(D3) allocb(D3)
REFERENCES
allocb_physreq(D3), bufcall(D3), esballoc(D3), esbbcall(D3),
freeb(D3), msgb(D4)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
In versions 1, 2, 3, 4, 5, and 5mp, the memory for the data
buffer returned by allocb will be DMA-able; that is, it will
satisfy worst-case DMA-ability requirements on systems with
restricted DMA and will be physically contiguous; see
phys_dmasize of physreq(D4). For other versions, there are no
guarantees on the memory properties.
Copyright 1994 Novell, Inc. Page 3