| .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 |
| .\" |
| .\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 2002-07-17, aeb |
| .\" 2008-01-24, mtk: |
| .\" Various rewrites and additions (notes on longjmp() and SIGSEGV). |
| .\" Weaken warning against use of alloca() (as per Debian bug 461100). |
| .\" |
| .TH ALLOCA 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| alloca \- allocate memory that is automatically freed |
| .SH SYNOPSIS |
| .nf |
| .B #include <alloca.h> |
| .PP |
| .BI "void *alloca(size_t " size ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR alloca () |
| function allocates |
| .I size |
| bytes of space in the stack frame of the caller. |
| This temporary space is |
| automatically freed when the function that called |
| .BR alloca () |
| returns to its caller. |
| .SH RETURN VALUE |
| The |
| .BR alloca () |
| function returns a pointer to the beginning of the allocated space. |
| If the allocation causes stack overflow, program behavior is undefined. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR alloca () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| This function is not in POSIX.1. |
| .PP |
| There is evidence that the |
| .BR alloca () |
| function appeared in 32V, PWB, PWB.2, 3BSD, and 4BSD. |
| There is a man page for it in 4.3BSD. |
| Linux uses the GNU version. |
| .SH NOTES |
| The |
| .BR alloca () |
| function is machine- and compiler-dependent. |
| For certain applications, |
| its use can improve efficiency compared to the use of |
| .BR malloc (3) |
| plus |
| .BR free (3). |
| In certain cases, |
| it can also simplify memory deallocation in applications that use |
| .BR longjmp (3) |
| or |
| .BR siglongjmp (3). |
| Otherwise, its use is discouraged. |
| .PP |
| Because the space allocated by |
| .BR alloca () |
| is allocated within the stack frame, |
| that space is automatically freed if the function return |
| is jumped over by a call to |
| .BR longjmp (3) |
| or |
| .BR siglongjmp (3). |
| .PP |
| The space allocated by |
| .BR alloca () |
| is |
| .I not |
| automatically deallocated if the pointer that refers to it |
| simply goes out of scope. |
| .PP |
| Do not attempt to |
| .BR free (3) |
| space allocated by |
| .BR alloca ()! |
| .SS Notes on the GNU version |
| Normally, |
| .BR gcc (1) |
| translates calls to |
| .BR alloca () |
| with inlined code. |
| This is not done when either the |
| .IR "\-ansi" , |
| .IR "\-std=c89" , |
| .IR "\-std=c99" , |
| or the |
| .IR "\-std=c11" |
| option is given |
| .BR and |
| the header |
| .I <alloca.h> |
| is not included. |
| Otherwise, (without an \-ansi or \-std=c* option) the glibc version of |
| .I <stdlib.h> |
| includes |
| .I <alloca.h> |
| and that contains the lines: |
| .PP |
| .in +4n |
| .EX |
| #ifdef __GNUC__ |
| #define alloca(size) __builtin_alloca (size) |
| #endif |
| .EE |
| .in |
| .PP |
| with messy consequences if one has a private version of this function. |
| .PP |
| The fact that the code is inlined means that it is impossible |
| to take the address of this function, or to change its behavior |
| by linking with a different library. |
| .PP |
| The inlined code often consists of a single instruction adjusting |
| the stack pointer, and does not check for stack overflow. |
| Thus, there is no NULL error return. |
| .SH BUGS |
| There is no error indication if the stack frame cannot be extended. |
| (However, after a failed allocation, the program is likely to receive a |
| .B SIGSEGV |
| signal if it attempts to access the unallocated space.) |
| .PP |
| On many systems |
| .BR alloca () |
| cannot be used inside the list of arguments of a function call, because |
| the stack space reserved by |
| .BR alloca () |
| would appear on the stack in the middle of the space for the |
| function arguments. |
| .SH SEE ALSO |
| .BR brk (2), |
| .BR longjmp (3), |
| .BR malloc (3) |