ref: caf8df647886963848a2e266124de54fcc737247
dir: /sys/man/9/allocb/
.TH ALLOCB 9 .SH NAME allocb, iallocb, freeb, freeblist, BLEN, BALLOC, blocklen, blockalloclen, readblist, concatblock, copyblock, trimblock, packblock, padblock, pullblock, pullupblock, adjustblock, checkb \- data block management .SH SYNOPSIS .ta \w'\fLBlock* 'u .B Block* allocb(int size) .PP .B Block* iallocb(int size) .PP .B void freeb(Block *b) .PP .B void freeblist(Block *b) .PP .B int blocklen(Block *b) .PP .B int blockalloclen(Block *b) .PP .B long readblist(Block *b, uchar *p, long n, ulong offset) .PP .B Block* concatblock(Block *b) .PP .B Block* copyblock(Block *b, int n) .PP .B Block* trimblock(Block *b, int offset, int n) .PP .B Block* packblock(Block *b) .PP .B Block* padblock(Block *b, int n) .PP .B int pullblock(Block **bph, int n) .PP .B Block* pullupblock(Block *b, int n) .PP .B Block* adjustblock(Block *b, int n) .PP .B void checkb(Block *b, char *msg) .sp 0.1 .PP .B #define BLEN(s) ((s)->wp - (s)->rp) .PP .B #define BALLOC(s) ((s)->lim - (s)->base) .SH DESCRIPTION A .B Block provides a receptacle for data: .IP .EX .DT typedef struct 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*); ushort flag; ushort checksum; /* IP checksum of complete packet */ } Block; .EE .PP Each .B Block has an associated buffer, located at .BR base , and accessed via .B wp when filling the buffer, or .B rp when fetching data from it. Each pointer should be incremented to reflect the amount of data written or read. A .B Block is empty when .B rp reaches .BR wp . The pointer .B lim bounds the allocated space. Some operations described below accept lists of .BR Block s, which are chained via their .B next pointers, with a null pointer ending the list. .B Blocks are usually intended for a .B Queue (see .IR qio (9)), but can be used independently. .PP A .B Block and its buffer are normally allocated by one call to .IR malloc (9) 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 Block and buffer; .B free must then point to a function that can deallocate the specially allocated .BR Block . .PP Many .B Block operations cannot be used in interrupt handlers because they either .IR sleep (9) or raise an .IR error (9). Of operations that allocate blocks, only .IR iallocb is usable. .PP .I Allocb allocates a .B Block of at least .IR size bytes. The block is initially empty: .B rp and .B wp point to the start of the data. If it cannot allocate memory, .I allocb raises an .IR error (9); it cannot be used by an interrupt handler. .PP .IR Iallocb is similar to .IR allocb but 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 Freeb frees a single .B Block (and its buffer). .PP .I Freeblist frees the whole list of blocks headed by .IR b . .PP .I BLEN returns the number of unread bytes in a single block. .PP .I BALLOC returns the number of allocated bytes in a single block. .PP .I Blocklen returns the number of bytes of unread data in the whole list of blocks headed by .IR b . .PP .I Blockalloclen returns the number of total bytes allocated in the whole list of blocks headed by .IR b . .PP .I Readblist copies .I n bytes of data at offset .I offset from the list of blocks headed by .I b into .IR p , then returns the amount of bytes copied. It leaves the block list intact. .PP .I Concatblock returns .I b if it is not a list, and otherwise returns a single .B Block containing all the data in the list of blocks .IR b , which it frees. .PP .I Copyblock by contrast returns a single .B Block containing a copy of the first .I n bytes of data in the block list .IR b , padding with zeroes if the list contained less than .I n bytes. The list .I b is unchanged. .PP .I Padblock can pad a single .B Block at either end, to reserve space for protocol headers or trailers. If .IR n ≥ 0 , it inserts .I n bytes at the start of the block, setting the read pointer .B rp to point to the new space. If .IR n < 0 , it adds .I n bytes at the end of the block, leaving the write pointer .B wp pointing at the new space. In both cases, it allocates a new .B Block if necessary, freeing the old, and it always returns a pointer to the resulting .BR Block . .PP .I Trimblock trims the list .I b to contain no more than .I n bytes starting at .I offset bytes 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 Packblock examines each .B Block in 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 Pullblock discards up to .I n bytes from the start of the list headed by .BI * bph \f1.\f0 Unneeded blocks are freed. .I Pullblock sets .BI * bph to point to the new list head and returns the number of bytes discarded (which might be less than .IR n ). It is used by transport protocols to discard ack'd data at the head of a retransmission queue. .PP .I Pullupblock rearranges the data in the list of blocks .I b to ensure that there are at least .I n bytes 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 Adjustblock ensures that the block .I b has at least .I n bytes of data, reallocating or padding with zero if necessary. It returns a pointer to the new .BR Block . (If .I n is negative, it frees the block and returns a null pointer.) .PP .I Checkb does some consistency checking of the state of .IR b ; a .IR panic (9) results if things look grim. It is intended for internal use by the queue I/O routines (see .IR qio (9)) but could be used elsewhere. .PP The only functions that can be called at interrupt level are .IR iallocb , .IR freeb , .IR freeblist , .IR BLEN , .IR BALLOC , .IR blocklen , .IR blockalloclen , .IR readblist and .IR trimblock . The others allocate memory and can potentially block. .SH SOURCE .B /sys/src/9/port/allocb.c .br .B /sys/src/9/port/qio.c .SH DIAGNOSTICS Many functions directly or indirectly can raise an .IR error (9), and callers must therefore provide for proper error recovery as described therein to prevent memory leaks and other bugs. Except for .IR iallocb , any functions that allocate new blocks or lists are unsuitable for use by interrupt handlers. .IR Iallocb returns a null pointer when it runs out of memory. .SH SEE ALSO .IR qio (9)