malloc 4.3 KB

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