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 | .\" | |
82a5ce59 | 5 | .\" @(#)malloc.3 6.4 (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. | |
82a5ce59 JK |
68 | If |
69 | .I ptr | |
70 | is null, | |
71 | .I realloc | |
72 | simply returns the value of | |
73 | .I malloc | |
74 | called with an argument of | |
75 | .IR size . | |
679a4429 | 76 | .PP |
a435d0f0 KM |
77 | In order to be compatible with older versions, |
78 | .I realloc | |
679a4429 KM |
79 | also works if |
80 | .I ptr | |
81 | points to a block freed since the last call of | |
82 | .I malloc, realloc | |
83 | or | |
84 | .IR calloc ; | |
a435d0f0 | 85 | sequences of |
679a4429 KM |
86 | .I free, malloc |
87 | and | |
88 | .I realloc | |
a435d0f0 KM |
89 | were previously used to attempt storage compaction. |
90 | This procedure is no longer recommended. | |
679a4429 KM |
91 | .PP |
92 | .I Calloc | |
a435d0f0 | 93 | allocates space for an array of |
679a4429 KM |
94 | .I nelem |
95 | elements of size | |
96 | .I elsize. | |
97 | The space is initialized to zeros. | |
98 | .PP | |
a435d0f0 KM |
99 | .I Alloca |
100 | allocates | |
101 | .I size | |
102 | bytes of space in the stack frame of the caller. | |
103 | This temporary space is automatically freed on | |
104 | return. | |
105 | .PP | |
679a4429 KM |
106 | Each of the allocation routines returns a pointer |
107 | to space suitably aligned (after possible pointer coercion) | |
108 | for storage of any type of object. | |
71df903f MK |
109 | If the space is of |
110 | .I pagesize | |
111 | or larger, the memory returned will be page-aligned. | |
112 | .SH SEE ALSO | |
113 | brk(2), | |
114 | pagesize(2) | |
679a4429 KM |
115 | .SH DIAGNOSTICS |
116 | .I Malloc, realloc | |
117 | and | |
118 | .I calloc | |
a435d0f0 KM |
119 | return a null pointer (0) if there is no available memory or if the arena |
120 | has been detectably corrupted by storing outside the bounds of a block. | |
679a4429 | 121 | .I Malloc |
a435d0f0 KM |
122 | may be recompiled to check the arena very stringently on every transaction; |
123 | those sites with a source code license may check the source code to see | |
124 | how this can be done. | |
679a4429 KM |
125 | .SH BUGS |
126 | When | |
127 | .I realloc | |
a435d0f0 | 128 | returns 0, the block pointed to by |
679a4429 KM |
129 | .I ptr |
130 | may be destroyed. | |
131 | .PP | |
71df903f MK |
132 | The current implementation of |
133 | .I malloc | |
134 | does not always fail gracefully when system | |
135 | memory limits are approached. | |
136 | It may fail to allocate memory when larger free blocks could be broken | |
137 | up, or when limits are exceeded because the size is rounded up. | |
138 | It is optimized for sizes that are powers of two. | |
139 | .PP | |
a435d0f0 | 140 | .I Alloca |
77bc57f4 | 141 | is machine dependent; its use is discouraged. |