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) .