malloc.3 (3704B)
1 .TH MALLOC 3 2 .SH NAME 3 malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- 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 void setmalloctag(void *ptr, ulong tag) 27 .PP 28 .B 29 ulong getmalloctag(void *ptr) 30 .PP 31 .B 32 void setrealloctag(void *ptr, ulong tag) 33 .PP 34 .B 35 ulong getrealloctag(void *ptr) 36 .SH DESCRIPTION 37 .I Malloc 38 and 39 .I free 40 provide a simple memory allocation package. 41 .I Malloc 42 returns a pointer to a new block of at least 43 .I size 44 bytes. 45 The block is suitably aligned for storage of any type of object. 46 No two active pointers from 47 .I malloc 48 will have the same value. 49 The call 50 .B malloc(0) 51 returns a valid pointer rather than null. 52 .PP 53 The argument to 54 .I free 55 is a pointer to a block previously allocated by 56 .IR malloc ; 57 this space is made available for further allocation. 58 It is legal to free a null pointer; the effect is a no-op. 59 The contents of the space returned by 60 .I malloc 61 are undefined. 62 .I Mallocz 63 behaves as 64 .IR malloc , 65 except that if 66 .I clr 67 is non-zero, the memory returned will be zeroed. 68 .PP 69 .I Realloc 70 changes the size of the block pointed to by 71 .I ptr 72 to 73 .I size 74 bytes and returns a pointer to the (possibly moved) 75 block. 76 The contents will be unchanged up to the 77 lesser of the new and old sizes. 78 .I Realloc 79 takes on special meanings when one or both arguments are zero: 80 .TP 81 .B "realloc(0,\ size) 82 means 83 .LR malloc(size) ; 84 returns a pointer to the newly-allocated memory 85 .TP 86 .B "realloc(ptr,\ 0) 87 means 88 .LR free(ptr) ; 89 returns null 90 .TP 91 .B "realloc(0,\ 0) 92 no-op; returns null 93 .PD 94 .PP 95 .I Calloc 96 allocates space for 97 an array of 98 .I nelem 99 elements of size 100 .IR elsize . 101 The space is initialized to zeros. 102 .I Free 103 frees such a block. 104 .PP 105 The memory allocator on Plan 9 maintains two word-sized fields 106 associated with each block, the ``malloc tag'' and the ``realloc tag''. 107 By convention, the malloc tag is the PC that allocated the block, 108 and the realloc tag the PC that last reallocated the block. 109 These may be set or examined with 110 .IR setmalloctag , 111 .IR getmalloctag , 112 .IR setrealloctag , 113 and 114 .IR getrealloctag . 115 When allocating blocks directly with 116 .I malloc 117 and 118 .IR realloc , 119 these tags will be set properly. 120 If a custom allocator wrapper is used, 121 the allocator wrapper can set the tags 122 itself (usually by passing the result of 123 .IR getcallerpc (3) 124 to 125 .IR setmalloctag ) 126 to provide more useful information about 127 the source of allocation. 128 .SH SOURCE 129 .B \*9/src/lib9/malloc.c 130 .br 131 .B \*9/src/lib9/malloctag.c 132 .SH SEE ALSO 133 .I trump 134 (in 135 .MR acid (1) ), 136 .MR getcallerpc (3) 137 .SH DIAGNOSTICS 138 .I Malloc, realloc 139 and 140 .I calloc 141 return 0 if there is no available memory. 142 .I Errstr 143 is likely to be set. 144 If the allocated blocks have no malloc or realloc tags, 145 .I getmalloctag 146 and 147 .I getrealloctag 148 return 149 .BR ~0 . 150 .PP 151 The 152 .I trump 153 library for 154 .I acid 155 can be used to obtain traces of malloc execution; see 156 .MR acid (1) . 157 .SH BUGS 158 The different specification of 159 .I calloc 160 is bizarre. 161 .PP 162 User errors can corrupt the storage arena. 163 The most common gaffes are (1) freeing an already freed block, 164 (2) storing beyond the bounds of an allocated block, and (3) 165 freeing data that was not obtained from the allocator. 166 When 167 .I malloc 168 and 169 .I free 170 detect such corruption, they abort. 171 .PP 172 To avoid name conflicts with the system versions of these functions, 173 .IR malloc , 174 .IR realloc , 175 .IR calloc , 176 and 177 .I free 178 are preprocessor macros defined as 179 .IR p9malloc , 180 .IR p9realloc , 181 .IR p9calloc , 182 and 183 .IR p9free ; 184 see 185 .MR intro (3) .