STREAMS-UX Programmer's Guide (February 2007)

Messages
Message Processing and Flow Control
Chapter 3
54
Common STREAMS Utilities
This section provides an overview of the most common utilities used by modules or drivers. Appendix B,
“STREAMS Utilities Supported by HP-UX,” contains the complete set of STREAMS utilities relevant to
STREAMS programmers. All these utilities are exported via <sys/stream.h>.
Message Allocation and Deallocation
mblk_t * allocb(int size, unsigned int pri);
allocb () Allocates a message block header, data block header and the data buffer of length
determined by size (in bytes). When successful, it returns a pointer to the newly allocated
message block of type M_DATA. The b_band field is set to zero. Modules and drivers can set
this field, if needed. The pri is an unused parameter and is maintained only for
compatibility with the applications developed prior to UNIX System V Release 4.0.
The allocb () utility returns a NULL pointer if it fails to allocate the requested memory.
Module and Drivers need to take care of this condition where allocb () fails to allocate the
requested memory.
int bufcall(unsigned int size, int pri, bufcall_fcn_t func, bufcall_arg_t arg);
bufcall () Serves as a memory availability notification mechanism. It can be used if allocb () fails to
allocate memory. If the allocb () returns NULL, modules and drivers may invoke bufcall ()
to recover from the allocb () failure. This utility invokes the callback function when a
buffer of size bytes is available. The callback function must not sleep and cannot reference
u_area. The pri is not used.
The bufcall () utlity returns 1 on success, and 0 on failure. On a failure return, func is
never invoked and this indicates the system is temporarily unable to allocate the required
internal memory.
mblk_t *esballoc(uchar_t *base, int size, int pri, frtn_t *fr_rtn);
esballoc () Allocates a new message block and data block header. The user-supplied buffer pointed at
by the base is used as data buffer. The b_rptr, b_wptr, db_base and db_lim are set
appropriately, based on base and size parameters.
The free_func () pointed by fr_rtn is called with free_arg by freeb () when db_ref count
is 1.
void freeb(mblk_t *bp);
freeb () Deallocates the message block descriptor bp. The data block associated with bp is not freed
if the db_ref count is greater than 1. If the db_ref is greater than 1, freeb () will free only
the message block header and decrements the db_ref count.
void freemsg(mblk_t *bp);
freemsg () Will free the message pointed at by bp. This utility internally uses freeb () to free the
individual message blocks by traversing the b_cont list.
mblk_t *copyb(mblk_t *bp);
copyb () Allocates a new message block and updates all the information pointed at by bp. All the
data between the b_rptr and b_wptr pointers of a message block are copied to the new
message block.
The copyb () returns a pointer to the newly allocated message block for successful return. In
case of failure, it returns a NULL pointer.