.TH ALLOCB 10.2.SH NAMEallocb, iallocb, freeb, freeblist, BLEN, blocklen, concatblock, copyblock, trimblock, packblock, padblock, pullblock, pullupblock, adjustblock, checkb \- data block management.SH SYNOPSIS.ta \w'\fLBlock* 'u.BBlock*	allocb(int size).PP.BBlock*	iallocb(int size).PP.Bvoid	freeb(Block *b).PP.Bvoid	freeblist(Block *b).PP.Blong	BLEN(Block *b).PP.Bint	blocklen(Block *b).PP.BBlock*	concatblock(Block *b).PP.BBlock*	copyblock(Block *b, int n).PP.BBlock*	trimblock(Block *b, int offset, int n).PP.BBlock*	packblock(Block *b).PP.BBlock*	padblock(Block *b, int n).PP.Bint	pullblock(Block **bph, int n).PP.BBlock*	pullupblock(Block *b, int n).PP.BBlock*	adjustblock(Block *b, int n).PP.Bvoid	checkb(Block *b, char *msg).SH DESCRIPTIONA.B Blockprovides a receptacle for data:.IP.EX.DTtypedefstruct Block{    Block*  next;    Block*  list;    uchar*  rp;     /* first unconsumed byte */    uchar*  wp;     /* first empty byte */    uchar*  lim;    /* 1 past the end of the buffer */    uchar*  base;   /* start of the buffer */    void    (*free)(Block*);    ulong   flag;} Block;.EE.PPEach.B Blockhas an associated buffer, located at.BR base ,and accessed via.B wpwhen filling the buffer, or.B rpwhen fetching data from it.Each pointer should be incremented to reflect the amount of data written or read.A.B Blockis empty when.B rpreaches.BR wp .The pointer.B limbounds the allocated space.Some operations described below accept lists of.BR Block s,which arechained via their.B nextpointers, with a null pointer ending the list..B Blocksare usually intended for a.B Queue(see.IR qio (10.2)),but can be used independently..PPA.B Blockand its buffer are normally allocated by one call to.IR malloc (10.2)and aligned on an 8 byte (\fLBY2V\fP) boundary.Some devices with particular allocation constraints(eg, requiring certain addresses for DMA) might allocate their own.B Blockand buffer;.B freemust then point to a function that can deallocate the specially allocated.BR Block ..PPMany.B Blockoperations cannot be used in interrupt handlersbecause they either.IR sleep (10.2)or raise an.IR error (10.2).Of operations that allocate blocks, only.IR iallocbis usable..PP.I Allocballocates a.B Blockof at least.IR sizebytes.The blockis initially empty:.B rpand.B wppoint to the start of the data.If it cannot allocate memory,.I allocbraises an.IR error (10.2);it cannot be used by an interrupt handler..PP.IR Iallocbis similar to.IR allocbbut is intended for use by interrupt handlers,and returns a null pointer if no memory is available.It also limits its allocation to a quota allocated at system initialisation to interrupt-time buffering..PP.I Freebfrees a single.B Block(and its buffer)..PP.I Freeblistfrees the wholelist of blocks headed by.IR b ..PP.I BLENreturns the number of unread bytes in a single block.IR b ;it is implemented as a macro..PP.I Blocklenreturns the number of bytes of unread data in the whole list of blocks headed by.IR b ..PP.I Concatblockreturns.I bif it is not a list, and otherwisereturns a single.B Blockcontaining all the data in the list of blocks.IR b ,which it frees..PP.I Copyblockby contrast returns a single.B Blockcontaining a copy of the first.I nbytes of data in the block list.IR b ,padding with zeroes if the list contained less than.I nbytes.The list.I bis unchanged..PP.I Padblockcan pad a single.B Blockat either end, to reserve space for protocol headers or trailers.If.IR n ≥ 0 ,it inserts.I nbytes at the start of the block,setting the read pointer.B rpto point to the new space.If.IR n < 0 ,it adds.I nbytes at the end of the block,leaving the write pointer.B wppointing at the new space.In both cases, it allocates a new.B Blockif necessary, freeing the old, andit always returns a pointer to the resulting.BR Block ..PP.I Trimblocktrims the list.I bto contain no more than.I nbytes starting at.I offsetbytes into the data of the original list.It returns a new list, freeing unneeded parts of the old.If no data remains, it returns a null pointer..PP.I Packblockexamines each.B Blockin the list.IR b ,reallocating any block in the list that has four times more available space than actual data.It returns a pointer to the revised list..PP.I Pullblockdiscards up to.I nbytes from the start of the list headed by.BI * bph \f1.\f0Unneeded blocks are freed..I Pullblocksets.BI * bphto point to the new list headand returns the number of bytes discarded (which might be less than.IR n ).It is used by transport protocols to discard ack'd data atthe head of a retransmission queue..PP.I Pullupblockrearranges the data in the list of blocks.I bto ensure that there are at least.I nbytes of contiguous data in the first block,and returns a pointer to the new list head.It frees any blocks that it empties.It returns a null pointer if there is not enough data in the list..PP.I Adjustblockensures that the block.I bhas at least.I nbytes of data, reallocating or padding with zero if necessary.It returns a pointer to the new.BR Block .(If.I nis negative, it frees the block and returns a null pointer.).PP.I Checkbdoes some consistency checking ofthe state of.IR b ;a.IR panic (10.2)results if things look grim.It is intended for internal use by the queue I/O routines (see.IR qio (10.2))but could be used elsewhere..PPThe only functions that can be called at interrupt level are.IR iallocb ,.IR freeb ,.IR freeblist ,.IR BLEN ,.IR blocklen ,.IR trimblockand.IR pullupblock .The others allocate memory and can potentially block..SH DIAGNOSTICSMany functions directly or indirectly can raise an.IR error (10.2),and callers must therefore provide for proper error recoveryas described therein to prevent memory leaks and other bugs.Except for.IR iallocb ,any functions that allocate new blocks or listsare unsuitable for use by interrupt handlers..IR Iallocbreturns a null pointer when it runs out of memory..SH SOURCE.B /os/port/qio.c.br.B /emu/port/qio.c.SH SEE ALSO.IR qio (10.2)