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