Debian Codegraph @

upstream/debian-unstable/man3/alloca.3

raw
1 '\" t
2 .\" Copyright 1980-1991, Regents of the University of California.
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH alloca 3 2025-10-29 "Linux man-pages 6.18"
8 .SH NAME
9 alloca \- allocate memory that is automatically freed
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <alloca.h>
16 .P
17 .BI "void *alloca(size_t " size );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR alloca ()
22 function allocates
23 .I size
24 bytes of space in the stack frame of the caller.
25 This temporary space is
26 automatically freed when the function that called
27 .BR alloca ()
28 returns to its caller.
29 .SH RETURN VALUE
30 The
31 .BR alloca ()
32 function returns a pointer to the beginning of the allocated space.
33 If the allocation causes stack overflow, program behavior is undefined.
34 .SH ATTRIBUTES
35 For an explanation of the terms used in this section, see
36 .BR attributes (7).
37 .TS
38 allbox;
39 lbx lb lb
40 l l l.
41 Interface Attribute Value
42 T{
43 .na
44 .nh
45 .BR alloca ()
46 T} Thread safety MT-Safe
47 .TE
48 .SH STANDARDS
49 None.
50 .SH HISTORY
51 PWB, 32V.
52 .SH NOTES
53 The
54 .BR alloca ()
55 function is machine- and compiler-dependent.
56 Because it allocates from the stack, it's faster than
57 .BR malloc (3)
58 and
59 .BR free (3).
60 In certain cases,
61 it can also simplify memory deallocation in applications that use
62 .BR longjmp (3)
63 or
64 .BR siglongjmp (3).
65 Otherwise, its use is discouraged.
66 .P
67 Because the space allocated by
68 .BR alloca ()
69 is allocated within the stack frame,
70 that space is automatically freed if the function return
71 is jumped over by a call to
72 .BR longjmp (3)
73 or
74 .BR siglongjmp (3).
75 .P
76 The space allocated by
77 .BR alloca ()
78 is
79 .I not
80 automatically deallocated if the pointer that refers to it
81 simply goes out of scope;
82 it is automatically deallocated when the caller function returns.
83 .P
84 Do not attempt to
85 .BR free (3)
86 space allocated by
87 .BR alloca ()!
88 .P
89 By necessity,
90 .BR alloca ()
91 is a compiler built-in, also known as
92 .BR __builtin_alloca ().
93 By default, modern compilers automatically translate all uses of
94 .BR alloca ()
95 into the built-in, but this is forbidden if standards conformance is requested
96 .RI ( "\-ansi" ,
97 .IR "\-std=c*" ),
98 in which case
99 .I <alloca.h>
100 is required, lest a symbol dependency be emitted.
101 .P
102 The fact that
103 .BR alloca ()
104 is a built-in means it is impossible to take its address
105 or to change its behavior by linking with a different library.
106 .P
107 Variable length arrays (VLAs) are part of the C99 standard,
108 optional since C11, and can be used for a similar purpose.
109 However, they do not port to standard C++, and, being variables,
110 live in their block scope and don't have an allocator-like interface,
111 making them unfit for implementing functionality like
112 .BR strdupa (3).
113 .SH BUGS
114 .BR alloca ()
115 does not query the system for available stack memory,
116 and does not fall back to using heap if stack storage is unavailable.
117 It therefore cannot indicate an error if the allocation fails.
118 If the allocation fails,
119 the program is likely to receive a
120 .B SIGSEGV
121 signal.
122 .P
123 On many systems
124 .BR alloca ()
125 cannot be used inside the list of arguments of a function call, because
126 the stack space reserved by
127 .BR alloca ()
128 would appear on the stack in the middle of the space for the
129 function arguments.
130 .SH SEE ALSO
131 .BR brk (2),
132 .BR longjmp (3),
133 .BR malloc (3)