1 .TH BIN 3
2 .SH NAME
3 binalloc, bingrow, binfree \- grouped memory allocation
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <bin.h>
10 .PP
11 .ta \w'\fLvoid* 'u
12 .PP
13 .B
14 typedef struct Bin	Bin;
15 .PP
16 .B
17 void	*binalloc(Bin **bp, ulong size, int clr);
18 .PP
19 .B
20 void	*bingrow(Bin **bp, void *op, ulong osize,
21 .br
22 .B
23 	    ulong size, int clr);
24 .PP
25 .B
26 void	binfree(Bin **bp);
27 .SH DESCRIPTION
28 These routines provide simple grouped memory allocation and deallocation.
29 Items allocated with
30 .I binalloc
31 are added to the
32 .I Bin
33 pointed to by
34 .IR bp .
35 All items in a bin may be freed with one call to
36 .IR binfree ;
37 there is no way to free a single item.
38 .PP
39 .I Binalloc
40 returns a pointer to a new block of at least
41 .I size
42 bytes.
43 The block is suitably aligned for storage of any type of object.
44 No two active pointers from
45 .I binalloc
46 will have the same value.
47 The call
48 .B binalloc(0)
49 returns a valid pointer rather than null.
50 If
51 .I clr
52 is non-zero, the allocated memory is set to 0;
53 otherwise, the contents are undefined.
54 .PP
55 .I Bingrow
56 is used to extend the size of a block of memory returned by
57 .IR binalloc .
58 .I Bp
59 must point to the same bin group used to allocate the original block,
60 and
61 .I osize
62 must be the last size used to allocate or grow the block.
63 A pointer to a block of at least
64 .I size
65 bytes is returned, with the same contents in the first
66 .I osize
67 locations.
68 If
69 .I clr
70 is non-zero, the remaining bytes are set to 0,
71 and are undefined otherwise.
72 If
73 .I op
74 is
75 .BR nil ,
76 it and
77 .I osize
78 are ignored, and the result is the same as calling
79 .IR binalloc .
80 .PP
81 .I Binalloc
82 and
83 .I bingrow
84 allocate large chunks of memory using
85 .MR malloc (3)
86 and return pieces of these chunks.
87 The chunks are
88 .IR free 'd
89 upon a call to
90 .IR binfree .
91 .SH SOURCE
92 .B \*9/src/libbin
93 .SH SEE ALSO
94 .MR malloc (3)
95 .SH DIAGNOSTICS
96 .I binalloc
97 and
98 .I bingrow
99 return 0 if there is no available memory.