Commit | Line | Data |
---|---|---|
679a4429 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
71df903f | 5 | .\" @(#)malloc.3 6.3 (Berkeley) %G% |
679a4429 | 6 | .\" |
2f566ccb | 7 | .TH MALLOC 3 "" |
679a4429 KM |
8 | .UC 4 |
9 | .SH NAME | |
a435d0f0 | 10 | malloc, free, realloc, calloc, alloca \- memory allocator |
679a4429 KM |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B char *malloc(size) | |
14 | .B unsigned size; | |
15 | .PP | |
16 | .B free(ptr) | |
17 | .B char *ptr; | |
18 | .PP | |
19 | .B char *realloc(ptr, size) | |
20 | .B char *ptr; | |
21 | .B unsigned size; | |
22 | .PP | |
23 | .B char *calloc(nelem, elsize) | |
24 | .B unsigned nelem, elsize; | |
a435d0f0 KM |
25 | .PP |
26 | .B char *alloca(size) | |
27 | .B int size; | |
679a4429 KM |
28 | .fi |
29 | .SH DESCRIPTION | |
30 | .I Malloc | |
31 | and | |
32 | .I free | |
71df903f | 33 | provide a general-purpose memory allocation package. |
679a4429 KM |
34 | .I Malloc |
35 | returns a pointer to a block of at least | |
36 | .I size | |
37 | bytes beginning on a word boundary. | |
38 | .PP | |
39 | The argument to | |
40 | .I free | |
41 | is a pointer to a block previously allocated by | |
42 | .IR malloc ; | |
43 | this space is made available for further allocation, | |
44 | but its contents are left undisturbed. | |
45 | .PP | |
a435d0f0 | 46 | Needless to say, grave disorder will result if the space assigned by |
679a4429 KM |
47 | .I malloc |
48 | is overrun or if some random number is handed to | |
49 | .IR free . | |
50 | .PP | |
51 | .I Malloc | |
a435d0f0 KM |
52 | maintains multiple lists of free blocks according to size, |
53 | allocating space from the appropriate list. | |
679a4429 KM |
54 | It calls |
55 | .I sbrk | |
56 | (see | |
a435d0f0 | 57 | .IR brk (2)) |
679a4429 KM |
58 | to get more memory from the system when there is no |
59 | suitable space already free. | |
60 | .PP | |
61 | .I Realloc | |
62 | changes the size of the block pointed to by | |
63 | .I ptr | |
64 | to | |
65 | .I size | |
a435d0f0 KM |
66 | bytes and returns a pointer to the (possibly moved) block. |
67 | The contents will be unchanged up to the lesser of the new and old sizes. | |
679a4429 | 68 | .PP |
a435d0f0 KM |
69 | In order to be compatible with older versions, |
70 | .I realloc | |
679a4429 KM |
71 | also works if |
72 | .I ptr | |
73 | points to a block freed since the last call of | |
74 | .I malloc, realloc | |
75 | or | |
76 | .IR calloc ; | |
a435d0f0 | 77 | sequences of |
679a4429 KM |
78 | .I free, malloc |
79 | and | |
80 | .I realloc | |
a435d0f0 KM |
81 | were previously used to attempt storage compaction. |
82 | This procedure is no longer recommended. | |
679a4429 KM |
83 | .PP |
84 | .I Calloc | |
a435d0f0 | 85 | allocates space for an array of |
679a4429 KM |
86 | .I nelem |
87 | elements of size | |
88 | .I elsize. | |
89 | The space is initialized to zeros. | |
90 | .PP | |
a435d0f0 KM |
91 | .I Alloca |
92 | allocates | |
93 | .I size | |
94 | bytes of space in the stack frame of the caller. | |
95 | This temporary space is automatically freed on | |
96 | return. | |
97 | .PP | |
679a4429 KM |
98 | Each of the allocation routines returns a pointer |
99 | to space suitably aligned (after possible pointer coercion) | |
100 | for storage of any type of object. | |
71df903f MK |
101 | If the space is of |
102 | .I pagesize | |
103 | or larger, the memory returned will be page-aligned. | |
104 | .SH SEE ALSO | |
105 | brk(2), | |
106 | pagesize(2) | |
679a4429 KM |
107 | .SH DIAGNOSTICS |
108 | .I Malloc, realloc | |
109 | and | |
110 | .I calloc | |
a435d0f0 KM |
111 | return a null pointer (0) if there is no available memory or if the arena |
112 | has been detectably corrupted by storing outside the bounds of a block. | |
679a4429 | 113 | .I Malloc |
a435d0f0 KM |
114 | may be recompiled to check the arena very stringently on every transaction; |
115 | those sites with a source code license may check the source code to see | |
116 | how this can be done. | |
679a4429 KM |
117 | .SH BUGS |
118 | When | |
119 | .I realloc | |
a435d0f0 | 120 | returns 0, the block pointed to by |
679a4429 KM |
121 | .I ptr |
122 | may be destroyed. | |
123 | .PP | |
71df903f MK |
124 | The current implementation of |
125 | .I malloc | |
126 | does not always fail gracefully when system | |
127 | memory limits are approached. | |
128 | It may fail to allocate memory when larger free blocks could be broken | |
129 | up, or when limits are exceeded because the size is rounded up. | |
130 | It is optimized for sizes that are powers of two. | |
131 | .PP | |
a435d0f0 | 132 | .I Alloca |
77bc57f4 | 133 | is machine dependent; its use is discouraged. |