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 | .\" | |
77bc57f4 | 5 | .\" @(#)malloc.3 6.2 (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 | |
33 | provide a simple general-purpose memory allocation package. | |
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. | |
101 | .SH DIAGNOSTICS | |
102 | .I Malloc, realloc | |
103 | and | |
104 | .I calloc | |
a435d0f0 KM |
105 | return a null pointer (0) if there is no available memory or if the arena |
106 | has been detectably corrupted by storing outside the bounds of a block. | |
679a4429 | 107 | .I Malloc |
a435d0f0 KM |
108 | may be recompiled to check the arena very stringently on every transaction; |
109 | those sites with a source code license may check the source code to see | |
110 | how this can be done. | |
679a4429 KM |
111 | .SH BUGS |
112 | When | |
113 | .I realloc | |
a435d0f0 | 114 | returns 0, the block pointed to by |
679a4429 KM |
115 | .I ptr |
116 | may be destroyed. | |
117 | .PP | |
a435d0f0 | 118 | .I Alloca |
77bc57f4 | 119 | is machine dependent; its use is discouraged. |