| blob | 79b7a6f4fa36226c0344db48e0ac4bee7c08f5d3 |
1 .\"
2 .\" The contents of this file are subject to the terms of the
3 .\" Common Development and Distribution License (the "License").
4 .\" You may not use this file except in compliance with the License.
5 .\"
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 .\" or http://www.opensolaris.org/os/licensing.
8 .\" See the License for the specific language governing permissions
9 .\" and limitations under the License.
10 .\"
11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 .\" If applicable, add the following below this CDDL HEADER, with the
14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 .\"
17 .\"
18 .\" Copyright 1989 AT&T
19 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
20 .\" Copyright 2017 Nexenta Systems, Inc.
21 .\"
22 .Dd July 28, 2017
23 .Dt MALLOC 3C
24 .Os
25 .Sh NAME
26 .Nm malloc ,
27 .Nm calloc ,
28 .Nm free ,
29 .Nm freezero ,
30 .Nm memalign ,
31 .Nm realloc ,
32 .Nm reallocarray ,
33 .Nm recallocarray ,
34 .Nm valloc ,
35 .Nm alloca
36 .Nd memory allocator
37 .Sh SYNOPSIS
38 .In stdlib.h
39 .Ft void *
40 .Fo malloc
41 .Fa "size_t size"
42 .Fc
43 .Ft void *
44 .Fo calloc
45 .Fa "size_t nelem"
46 .Fa "size_t elsize"
47 .Fc
48 .Ft void
49 .Fo free
50 .Fa "void *ptr"
51 .Fc
52 .Ft void
53 .Fo freezero
54 .Fa "void *ptr"
55 .Fa "size_t size"
56 .Fc
57 .Ft void *
58 .Fo memalign
59 .Fa "size_t alignment"
60 .Fa "size_t size"
61 .Fc
62 .Ft void *
63 .Fo realloc
64 .Fa "void *ptr"
65 .Fa "size_t size"
66 .Fc
67 .Ft void *
68 .Fo reallocarray
69 .Fa "void *ptr"
70 .Fa "size_t nelem"
71 .Fa "size_t elsize"
72 .Fc
73 .Ft void *
74 .Fo recallocarray
75 .Fa "void *ptr"
76 .Fa "size_t oldnelem"
77 .Fa "size_t newnelem"
78 .Fa "size_t elsize"
79 .Fc
80 .Ft void *
81 .Fo valloc
82 .Fa "size_t size"
83 .Fc
84 .In alloca.h
85 .Ft void *
86 .Fo alloca
87 .Fa "size_t size"
88 .Fc
89 .Sh DESCRIPTION
90 The
91 .Fn malloc
92 and
93 .Fn free
94 functions provide a simple, general-purpose memory allocation package.
95 The
96 .Fn malloc
97 function returns a pointer to a block of at least
98 .Fa size
99 bytes suitably aligned for any use.
100 If the space assigned by
101 .Fn malloc
102 is overrun, the results are undefined.
103 .Pp
104 The argument to
105 .Fn free
106 is a pointer to a block previously allocated by
107 .Fn malloc ,
108 .Fn calloc ,
109 .Fn realloc ,
110 .Fn reallocarray ,
111 or
112 .Fn recallocarray .
113 After
114 .Fn free
115 is executed, this space is made available for further allocation by the
116 application, though not returned to the system.
117 Memory is returned to the system only upon termination of the application.
118 If
119 .Fa ptr
120 is a null pointer, no action occurs.
121 If a random number is passed to
122 .Fn free ,
123 the results are undefined.
124 .Pp
125 The
126 .Fn freezero
127 function is similar to the
128 .Fn free
129 function except it ensures memory is explicitly discarded.
130 If
131 .Fa ptr
132 is
133 .Dv NULL ,
134 no action occurs.
135 If
136 .Fa ptr
137 is not
138 .Dv NULL ,
139 the
140 .Fa size
141 argument must be equal or smaller than the size of the earlier allocation that
142 returned
143 .Fa ptr .
144 .Fn freezero
145 guarantees the memory range starting at
146 .Fa ptr
147 with length
148 .Fa size
149 is discarded while deallocating the whole object originally allocated.
150 .Pp
151 The
152 .Fn calloc
153 function allocates space for an array of
154 .Fa nelem
155 elements of size
156 .Fa elsize .
157 The space is initialized to zeros.
158 .Pp
159 The
160 .Fn memalign
161 function allocates
162 .Fa size
163 bytes on a specified alignment boundary and returns a pointer to the allocated
164 block.
165 The value of the returned address is guaranteed to be an even multiple of
166 .Fa alignment .
167 The value of
168 .Fa alignment
169 must be a power of two and must be greater than or equal to the size of a word.
170 .Pp
171 The
172 .Fn realloc
173 function changes the size of the block pointed to by
174 .Fa ptr
175 to
176 .Fa size
177 bytes and returns a pointer to the
178 .Pq possibly moved
179 block.
180 The contents will be unchanged up to the lesser of the new and old sizes.
181 If the new size of the block requires movement of the block, the space for the
182 previous instantiation of the block is freed.
183 If the new size is larger, the contents of the newly allocated portion of the
184 block are unspecified.
185 If
186 .Fa ptr
187 is
188 .Dv NULL ,
189 .Fn realloc
190 behaves like
191 .Fn malloc
192 for the specified size.
193 If
194 .Fa size
195 is 0 and
196 .Fa ptr
197 is not a null pointer, the space pointed to is freed.
198 .Pp
199 The
200 .Fn reallocarray
201 function is similar to
202 .Fn realloc ,
203 but operates on
204 .Fa nelem
205 elements of size
206 .Fa elsize
207 and checks for overflow in
208 .Fa nelem Ns * Ns Fa elsize
209 calculation.
210 .Pp
211 The
212 .Fn recallocarray
213 function is similar to
214 .Fn reallocarray
215 except it ensures newly allocated memory is cleared similar to
216 .Fn calloc .
217 If
218 .Fa ptr
219 is
220 .Dv NULL ,
221 .Fa oldnelem
222 is ignored and the call is equivalent to
223 .Fn calloc .
224 If
225 .Fa ptr
226 is not
227 .Dv NULL ,
228 .Fa oldnelem
229 must be a value such that
230 .Fa oldnelem Ns * Ns Fa elsize
231 is the size of the earlier allocation that returned
232 .Fa ptr ,
233 otherwise the behaviour is undefined.
234 .Pp
235 The
236 .Fn valloc
237 function has the same effect as
238 .Fn malloc ,
239 except that the allocated memory will be aligned to a multiple of the value
240 returned by
241 .Nm sysconf Ns Pq Dv _SC_PAGESIZE .
242 .Pp
243 The
244 .Fn alloca
245 function allocates
246 .Fa size
247 bytes of space in the stack frame of the caller, and returns a pointer to the
248 allocated block.
249 This temporary space is automatically freed when the caller returns.
250 If the allocated block is beyond the current stack limit, the resulting behavior
251 is undefined.
252 .Sh RETURN VALUES
253 Upon successful completion, each of the allocation functions returns a pointer
254 to space suitably aligned
255 .Pq after possible pointer coercion
256 for storage of any type of object.
257 .Pp
258 If there is no available memory,
259 .Fn malloc ,
260 .Fn calloc ,
261 .Fn realloc ,
262 .Fn reallocarray ,
263 .Fn recallocarray ,
264 .Fn memalign ,
265 and
266 .Fn valloc
267 return a null pointer.
268 .Pp
269 When
270 .Fn realloc
271 is called with
272 .Fa size
273 > 0 and returns
274 .Dv NULL ,
275 the block pointed to by
276 .Fa ptr
277 is left intact.
278 If
279 .Fa size ,
280 .Fa nelem ,
281 or
282 .Fa elsize
283 is 0, either a null pointer or a unique pointer that can be passed to
284 .Fn free
285 is returned.
286 .Pp
287 If
288 .Fn malloc ,
289 .Fn calloc ,
290 .Fn realloc ,
291 .Fn reallocarray ,
292 or
293 .Fn recallocarray
294 returns unsuccessfully,
295 .Va errno
296 will be set to indicate the error.
297 The
298 .Fn free
299 and
300 .Fn freezero
301 functions do not set
302 .Va errno .
303 .Sh ERRORS
304 The
305 .Fn malloc ,
306 .Fn calloc ,
307 .Fn realloc ,
308 and
309 .Fn reallocarray
310 functions will fail if:
311 .Bl -tag -width Er
312 .It Er ENOMEM
313 The physical limits of the system are exceeded by
314 .Fa size
315 bytes of memory which cannot be allocated, or there's integer overflow in
316 .Fn reallocarray .
317 .It Er EAGAIN
318 There is not enough memory available to allocate
319 .Fa size
320 bytes of memory; but the application could try again later.
321 .El
322 .Pp
323 The
324 .Fn recallocarray
325 function will fail if:
326 .Bl -tag -width Er
327 .It Er EINVAL
328 .Fa ptr
329 is not
330 .Dv NULL
331 and multiplying
332 .Fa oldnelem
333 and
334 .Fa elsize
335 results in integer overflow.
336 .El
337 .Sh USAGE
338 Portable applications should avoid using
339 .Fn valloc
340 but should instead use
341 .Fn malloc
342 or
343 .Xr mmap 2 .
344 On systems with a large page size, the number of successful
345 .Fn valloc
346 operations might be 0.
347 .Pp
348 These default memory allocation routines are safe for use in multithreaded
349 applications but are not scalable.
350 Concurrent accesses by multiple threads are single-threaded through the use of a
351 single lock.
352 Multithreaded applications that make heavy use of dynamic memory allocation
353 should be linked with allocation libraries designed for concurrent access, such
354 as
355 .Xr libumem 3LIB
356 or
357 .Xr libmtmalloc 3LIB .
358 Applications that want to avoid using heap allocations
359 .Pq with Xr brk 2
360 can do so by using either
361 .Xr libumem 3LIB
362 or
363 .Xr libmapmalloc 3LIB .
364 The allocation libraries
365 .Xr libmalloc 3LIB
366 and
367 .Xr libbsdmalloc 3LIB
368 are available for special needs.
369 .Pp
370 Comparative features of the various allocation libraries can be found in the
371 .Xr umem_alloc 3MALLOC
372 manual page.
373 .Sh INTERFACE STABILITY
374 The
375 .Fn malloc ,
376 .Fn calloc ,
377 .Fn free ,
378 .Fn realloc ,
379 .Fn valloc
380 functions are
381 .Sy Standard.
382 .Pp
383 The
384 .Fn freezero ,
385 .Fn reallocarray ,
386 and
387 .Fn recallocarray
388 functions are
389 .Sy Committed .
390 .Pp
391 The
392 .Fn memalign
393 and
394 .Fn alloca
395 functions are
396 .Sy Stable .
397 .Sh MT-LEVEL
398 .Sy Safe.
399 .Sh SEE ALSO
400 .Xr brk 2 ,
401 .Xr getrlimit 2 ,
402 .Xr libbsdmalloc 3LIB ,
403 .Xr libmalloc 3LIB ,
404 .Xr libmapmalloc 3LIB ,
405 .Xr libmtmalloc 3LIB ,
406 .Xr libumem 3LIB ,
407 .Xr umem_alloc 3MALLOC ,
408 .Xr watchmalloc 3MALLOC ,
409 .Xr attributes 5
410 .Sh WARNINGS
411 Undefined results will occur if the size requested for a block of memory
412 exceeds the maximum size of a process's heap, which can be obtained with
413 .Xr getrlimit 2 .
414 .Pp
415 The
416 .Fn alloca
417 function is machine-, compiler-, and most of all, system-dependent.
418 Its use is strongly discouraged.