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