tbin.3 - plan9port - [fork] Plan 9 from user space
 (HTM) git clone git://src.adamsgaard.dk/plan9port
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       tbin.3 (1883B)
       ---
            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.