]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 | |
7 | .\" | |
8 | .\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith <faith@cs.unc.edu> | |
9 | .\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
10 | .\" Modified 2002-07-17, aeb | |
6c3be221 MK |
11 | .\" 2008-01-24, mtk: |
12 | .\" Various rewrites and additions (notes on longjmp() and SIGSEGV). | |
13 | .\" Weaken warning against use of alloca() (as per Debian bug 461100). | |
fea681da | 14 | .\" |
1d767b55 | 15 | .TH ALLOCA 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
fea681da | 16 | .SH NAME |
7d733a85 | 17 | alloca \- allocate memory that is automatically freed |
fea681da | 18 | .SH SYNOPSIS |
c7db92b9 | 19 | .nf |
fea681da | 20 | .B #include <alloca.h> |
68e4db0a | 21 | .PP |
fea681da | 22 | .BI "void *alloca(size_t " size ); |
c7db92b9 | 23 | .fi |
fea681da MK |
24 | .SH DESCRIPTION |
25 | The | |
e511ffb6 | 26 | .BR alloca () |
fea681da MK |
27 | function allocates |
28 | .I size | |
c13182ef MK |
29 | bytes of space in the stack frame of the caller. |
30 | This temporary space is | |
fea681da | 31 | automatically freed when the function that called |
e511ffb6 | 32 | .BR alloca () |
fea681da | 33 | returns to its caller. |
47297adb | 34 | .SH RETURN VALUE |
fea681da | 35 | The |
e511ffb6 | 36 | .BR alloca () |
fea681da | 37 | function returns a pointer to the beginning of the allocated space. |
d9bfdb9c | 38 | If the allocation causes stack overflow, program behavior is undefined. |
fdceb0bd | 39 | .SH ATTRIBUTES |
b02f4317 MK |
40 | For an explanation of the terms used in this section, see |
41 | .BR attributes (7). | |
c466875e MK |
42 | .ad l |
43 | .nh | |
b02f4317 MK |
44 | .TS |
45 | allbox; | |
c466875e | 46 | lbx lb lb |
b02f4317 MK |
47 | l l l. |
48 | Interface Attribute Value | |
49 | T{ | |
fdceb0bd | 50 | .BR alloca () |
b02f4317 MK |
51 | T} Thread safety MT-Safe |
52 | .TE | |
c466875e MK |
53 | .hy |
54 | .ad | |
55 | .sp 1 | |
47297adb | 56 | .SH CONFORMING TO |
9cd5bb15 | 57 | This function is not in POSIX.1. |
847e0d88 | 58 | .PP |
e511ffb6 | 59 | .BR alloca () |
85ac6157 | 60 | originates from PWB and 32V, and appears in all their derivatives. |
d3ae4887 | 61 | .SH NOTES |
6c3be221 MK |
62 | The |
63 | .BR alloca () | |
64 | function is machine- and compiler-dependent. | |
dd004f73 | 65 | Because it allocates from the stack, it's faster than |
66 | .BR malloc (3)/ free (3). | |
0bb9038b MK |
67 | In certain cases, |
68 | it can also simplify memory deallocation in applications that use | |
69 | .BR longjmp (3) | |
70 | or | |
71 | .BR siglongjmp (3). | |
72 | Otherwise, its use is discouraged. | |
847e0d88 | 73 | .PP |
6c3be221 MK |
74 | Because the space allocated by |
75 | .BR alloca () | |
76 | is allocated within the stack frame, | |
77 | that space is automatically freed if the function return | |
78 | is jumped over by a call to | |
79 | .BR longjmp (3) | |
80 | or | |
81 | .BR siglongjmp (3). | |
847e0d88 | 82 | .PP |
49d83458 MK |
83 | The space allocated by |
84 | .BR alloca () | |
85 | is | |
86 | .I not | |
87 | automatically deallocated if the pointer that refers to it | |
88 | simply goes out of scope. | |
89 | .PP | |
6c3be221 MK |
90 | Do not attempt to |
91 | .BR free (3) | |
92 | space allocated by | |
93 | .BR alloca ()! | |
a4ca1d88 | 94 | .PP |
95 | By necessity, | |
e511ffb6 | 96 | .BR alloca () |
a4ca1d88 | 97 | is a compiler built-in, also known as |
98 | .BR __builtin_alloca (). | |
99 | By default, modern compilers automatically translate all uses of | |
100 | .BR alloca () | |
101 | into the built-in, but this is forbidden if standards conformance is requested | |
102 | .RI ( "\-ansi" , | |
103 | .IR "\-std=c*" ), | |
104 | in which case | |
fea681da | 105 | .I <alloca.h> |
a4ca1d88 | 106 | is required, lest a symbol dependency be emitted. |
207050fa | 107 | .PP |
a4ca1d88 | 108 | The fact that |
109 | .BR alloca () | |
110 | is a built-in means it is impossible to take its address | |
111 | or to change its behavior by linking with a different library. | |
dd004f73 | 112 | .PP |
113 | Variable length arrays (VLAs) are part of the C99 standard, | |
114 | optional since C11, and can be used for a similar purpose. | |
115 | However, they do not port to standard C++, and, being variables, | |
116 | live in their block scope and don't have an allocator-like interface, | |
117 | making them unfit for implementing functionality like | |
118 | .BR strdupa (3). | |
fea681da | 119 | .SH BUGS |
b71c0e29 | 120 | Due to the nature of the stack, it is impossible to check if the allocation |
121 | would overflow the space available, and, hence, neither is indicating an error. | |
122 | (However, the program is likely to receive a | |
6c3be221 | 123 | .B SIGSEGV |
b71c0e29 | 124 | signal if it attempts to access unavailable space.) |
847e0d88 | 125 | .PP |
fea681da | 126 | On many systems |
e511ffb6 | 127 | .BR alloca () |
fea681da MK |
128 | cannot be used inside the list of arguments of a function call, because |
129 | the stack space reserved by | |
e511ffb6 | 130 | .BR alloca () |
fea681da MK |
131 | would appear on the stack in the middle of the space for the |
132 | function arguments. | |
47297adb | 133 | .SH SEE ALSO |
fea681da | 134 | .BR brk (2), |
6c3be221 MK |
135 | .BR longjmp (3), |
136 | .BR malloc (3) |