sys/man/2/malloc

   1 .TH MALLOC 2
   2 .SH NAME
   3 malloc, mallocalign, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLvoid* 'u
  10 .B
  11 void*   malloc(ulong size)
  12 .PP
  13 .B
  14 void*   mallocalign(ulong size, ulong align, long offset, ulong span)
  15 .PP
  16 .B
  17 void*   mallocz(ulong size, int clr)
  18 .PP
  19 .B
  20 void    free(void *ptr)
  21 .PP
  22 .B
  23 void*   realloc(void *ptr, ulong size)
  24 .PP
  25 .B
  26 void*   calloc(ulong nelem, ulong elsize)
  27 .PP
  28 .B
  29 ulong   msize(void *ptr)
  30 .PP
  31 .B
  32 void    setmalloctag(void *ptr, uintptr tag)
  33 .PP
  34 .B
  35 uintptr getmalloctag(void *ptr)
  36 .PP
  37 .B
  38 void    setrealloctag(void *ptr, uintptr tag)
  39 .PP
  40 .B
  41 uintptr getrealloctag(void *ptr)
  42 .PP
  43 .B
  44 void*   malloctopoolblock(void*)
  45 .PP
  46 .SH DESCRIPTION
  47 .I Malloc
  48 and
  49 .I free
  50 provide a simple memory allocation package.
  51 .I Malloc
  52 returns a pointer to a new block of at least
  53 .I size
  54 bytes.
  55 The block is suitably aligned for storage of any type of object.
  56 No two active pointers from
  57 .I malloc
  58 will have the same value.
  59 The call
  60 .B malloc(0)
  61 returns a valid pointer rather than null.
  62 .PP
  63 The argument to
  64 .I free
  65 is a pointer to a block previously allocated by
  66 .IR malloc ;
  67 this space is made available for further allocation.
  68 It is legal to free a null pointer; the effect is a no-op.
  69 The contents of the space returned by
  70 .I malloc
  71 are undefined.
  72 .I Mallocz
  73 behaves as
  74 .IR malloc ,
  75 except that if
  76 .I clr
  77 is non-zero, the memory returned will be zeroed.
  78 .PP
  79 .I Mallocalign
  80 allocates a block of at least
  81 .I n
  82 bytes of memory respecting alignment contraints.
  83 If
  84 .I align
  85 is non-zero,
  86 the returned pointer is aligned to be equal to
  87 .I offset
  88 modulo
  89 .IR align .
  90 If
  91 .I span
  92 is non-zero,
  93 the
  94 .I n
  95 byte block allocated will not span a
  96 .IR span -byte
  97 boundary.
  98 .PP
  99 .I Realloc
 100 changes the size of the block pointed to by
 101 .I ptr
 102 to
 103 .I size
 104 bytes and returns a pointer to the (possibly moved)
 105 block.
 106 The contents will be unchanged up to the
 107 lesser of the new and old sizes.
 108 .I Realloc
 109 takes on special meanings when one or both arguments are zero:
 110 .TP
 111 .B "realloc(0,\ size)
 112 means
 113 .LR malloc(size) ;
 114 returns a pointer to the newly-allocated memory
 115 .TP
 116 .B "realloc(ptr,\ 0)
 117 means
 118 .LR free(ptr) ;
 119 returns null
 120 .TP
 121 .B "realloc(0,\ 0)
 122 no-op; returns null
 123 .PD
 124 .PP
 125 .I Calloc
 126 allocates space for
 127 an array of
 128 .I nelem
 129 elements of size
 130 .IR elsize .
 131 The space is initialized to zeros.
 132 .I Free
 133 frees such a block.
 134 .PP
 135 When a block is allocated, sometimes there is some extra unused space at the end.
 136 .I Msize
 137 grows the block to encompass this unused space and returns the new number
 138 of bytes that may be used.
 139 .PP
 140 The memory allocator maintains two word-sized fields
 141 associated with each block, the ``malloc tag'' and the ``realloc tag''.
 142 By convention, the malloc tag is the PC that allocated the block,
 143 and the realloc tag the PC that last reallocated the block.
 144 These may be set or examined with
 145 .IR setmalloctag ,
 146 .IR getmalloctag ,
 147 .IR setrealloctag ,
 148 and
 149 .IR getrealloctag .
 150 When allocating blocks directly with
 151 .I malloc
 152 and
 153 .IR realloc ,
 154 these tags will be set properly.
 155 If a custom allocator wrapper is used,
 156 the allocator wrapper can set the tags
 157 itself (usually by passing the result of
 158 .IR getcallerpc (2)
 159 to
 160 .IR setmalloctag )
 161 to provide more useful information about
 162 the source of allocation.
 163 .PP
 164 .I Malloctopoolblock
 165 takes the address of a block returned by
 166 .I malloc
 167 and returns the address of the corresponding
 168 block allocated by the
 169 .IR pool (2)
 170 routines.
 171 .SH SOURCE
 172 .B /sys/src/libc/port/malloc.c
 173 .SH SEE ALSO
 174 .IR leak (1),
 175 .I trump
 176 (in
 177 .IR acid (1)),
 178 .IR brk (2),
 179 .IR getcallerpc (2),
 180 .IR pool (2)
 181 .SH DIAGNOSTICS
 182 .I Malloc, realloc
 183 and
 184 .I calloc
 185 return 0 if there is no available memory.
 186 .I Errstr
 187 is likely to be set.
 188 If the allocated blocks have no malloc or realloc tags,
 189 .I getmalloctag
 190 and
 191 .I getrealloctag
 192 return
 193 .BR ~0 .
 194 .PP
 195 After including
 196 .BR pool.h ,
 197 the call
 198 .B poolcheck(mainmem)
 199 can be used to scan the storage arena for inconsistencies
 200 such as data written beyond the bounds of allocated blocks.
 201 It is often useful to combine this with setting
 202 .EX
 203     mainmem->flags |= POOL_NOREUSE;
 204 .EE
 205 at the beginning of your program.
 206 This will cause malloc not to reallocate blocks even
 207 once they are freed;
 208 .B poolcheck(mainmem)
 209 will then detect writes to freed blocks.
 210 .PP
 211 The
 212 .I trump
 213 library for
 214 .I acid
 215 can be used to obtain traces of malloc execution; see
 216 .IR acid (1).
 217 .SH BUGS
 218 The different specification of
 219 .I calloc
 220 is bizarre.
 221 .PP
 222 User errors can corrupt the storage arena.
 223 The most common gaffes are (1) freeing an already freed block,
 224 (2) storing beyond the bounds of an allocated block, and (3)
 225 freeing data that was not obtained from the allocator.
 226 When
 227 .I malloc
 228 and
 229 .I free
 230 detect such corruption, they abort.