]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 | |
35 | .\" | |
36 | .\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith <faith@cs.unc.edu> | |
37 | .\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
38 | .\" Modified 2002-07-17, aeb | |
6c3be221 MK |
39 | .\" 2008-01-24, mtk: |
40 | .\" Various rewrites and additions (notes on longjmp() and SIGSEGV). | |
41 | .\" Weaken warning against use of alloca() (as per Debian bug 461100). | |
fea681da | 42 | .\" |
fe0fefbf | 43 | .TH ALLOCA 3 2015-03-02 "GNU" "Linux Programmer's Manual" |
fea681da | 44 | .SH NAME |
7d733a85 | 45 | alloca \- allocate memory that is automatically freed |
fea681da MK |
46 | .SH SYNOPSIS |
47 | .B #include <alloca.h> | |
68e4db0a | 48 | .PP |
fea681da MK |
49 | .BI "void *alloca(size_t " size ); |
50 | .SH DESCRIPTION | |
51 | The | |
e511ffb6 | 52 | .BR alloca () |
fea681da MK |
53 | function allocates |
54 | .I size | |
c13182ef MK |
55 | bytes of space in the stack frame of the caller. |
56 | This temporary space is | |
fea681da | 57 | automatically freed when the function that called |
e511ffb6 | 58 | .BR alloca () |
fea681da | 59 | returns to its caller. |
47297adb | 60 | .SH RETURN VALUE |
fea681da | 61 | The |
e511ffb6 | 62 | .BR alloca () |
fea681da | 63 | function returns a pointer to the beginning of the allocated space. |
d9bfdb9c | 64 | If the allocation causes stack overflow, program behavior is undefined. |
fdceb0bd | 65 | .SH ATTRIBUTES |
b02f4317 MK |
66 | For an explanation of the terms used in this section, see |
67 | .BR attributes (7). | |
68 | .TS | |
69 | allbox; | |
70 | lb lb lb | |
71 | l l l. | |
72 | Interface Attribute Value | |
73 | T{ | |
fdceb0bd | 74 | .BR alloca () |
b02f4317 MK |
75 | T} Thread safety MT-Safe |
76 | .TE | |
47297adb | 77 | .SH CONFORMING TO |
9cd5bb15 | 78 | This function is not in POSIX.1. |
847e0d88 | 79 | .PP |
fea681da | 80 | There is evidence that the |
e511ffb6 | 81 | .BR alloca () |
6c3be221 | 82 | function appeared in 32V, PWB, PWB.2, 3BSD, and 4BSD. |
c13182ef MK |
83 | There is a man page for it in 4.3BSD. |
84 | Linux uses the GNU version. | |
d3ae4887 | 85 | .SH NOTES |
6c3be221 MK |
86 | The |
87 | .BR alloca () | |
88 | function is machine- and compiler-dependent. | |
0bb9038b MK |
89 | For certain applications, |
90 | its use can improve efficiency compared to the use of | |
4903137b | 91 | .BR malloc (3) |
0bb9038b MK |
92 | plus |
93 | .BR free (3). | |
94 | In certain cases, | |
95 | it can also simplify memory deallocation in applications that use | |
96 | .BR longjmp (3) | |
97 | or | |
98 | .BR siglongjmp (3). | |
99 | Otherwise, its use is discouraged. | |
847e0d88 | 100 | .PP |
6c3be221 MK |
101 | Because the space allocated by |
102 | .BR alloca () | |
103 | is allocated within the stack frame, | |
104 | that space is automatically freed if the function return | |
105 | is jumped over by a call to | |
106 | .BR longjmp (3) | |
107 | or | |
108 | .BR siglongjmp (3). | |
847e0d88 | 109 | .PP |
6c3be221 MK |
110 | Do not attempt to |
111 | .BR free (3) | |
112 | space allocated by | |
113 | .BR alloca ()! | |
c634028a | 114 | .SS Notes on the GNU version |
fea681da | 115 | Normally, |
6c3be221 | 116 | .BR gcc (1) |
fea681da | 117 | translates calls to |
e511ffb6 | 118 | .BR alloca () |
6c3be221 MK |
119 | with inlined code. |
120 | This is not done when either the | |
121 | .IR "\-ansi" , | |
122 | .IR "\-std=c89" , | |
123 | .IR "\-std=c99" , | |
124 | or the | |
4906c992 | 125 | .IR "\-std=c11" |
6c3be221 | 126 | option is given |
4906c992 AB |
127 | .BR and |
128 | the header | |
6c3be221 | 129 | .I <alloca.h> |
4906c992 | 130 | is not included. |
2b9b829d | 131 | Otherwise, (without an \-ansi or \-std=c* option) the glibc version of |
fea681da MK |
132 | .I <stdlib.h> |
133 | includes | |
134 | .I <alloca.h> | |
4906c992 | 135 | and that contains the lines: |
1a8b02f4 MK |
136 | .nf |
137 | ||
4906c992 | 138 | #ifdef __GNUC__ |
3d32fee8 | 139 | #define alloca(size) __builtin_alloca (size) |
4906c992 | 140 | #endif |
1a8b02f4 MK |
141 | |
142 | .fi | |
fea681da MK |
143 | with messy consequences if one has a private version of this function. |
144 | .LP | |
6c3be221 | 145 | The fact that the code is inlined means that it is impossible |
d9bfdb9c | 146 | to take the address of this function, or to change its behavior |
fea681da MK |
147 | by linking with a different library. |
148 | .LP | |
149 | The inlined code often consists of a single instruction adjusting | |
150 | the stack pointer, and does not check for stack overflow. | |
151 | Thus, there is no NULL error return. | |
152 | .SH BUGS | |
6c3be221 MK |
153 | There is no error indication if the stack frame cannot be extended. |
154 | (However, after a failed allocation, the program is likely to receive a | |
155 | .B SIGSEGV | |
156 | signal if it attempts to access the unallocated space.) | |
847e0d88 | 157 | .PP |
fea681da | 158 | On many systems |
e511ffb6 | 159 | .BR alloca () |
fea681da MK |
160 | cannot be used inside the list of arguments of a function call, because |
161 | the stack space reserved by | |
e511ffb6 | 162 | .BR alloca () |
fea681da MK |
163 | would appear on the stack in the middle of the space for the |
164 | function arguments. | |
47297adb | 165 | .SH SEE ALSO |
fea681da | 166 | .BR brk (2), |
6c3be221 MK |
167 | .BR longjmp (3), |
168 | .BR malloc (3) |