sys/man/2/bin

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