.\" 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:
.\" 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 2002-07-17 "GNU" "Linux Programmer's Manual"
+.TH ALLOCA 3 2019-03-06 "GNU" "Linux Programmer's Manual"
.SH NAME
-alloca \- memory allocator
+alloca \- allocate memory that is automatically freed
.SH SYNOPSIS
.B #include <alloca.h>
-.sp
+.PP
.BI "void *alloca(size_t " size );
.SH DESCRIPTION
The
automatically freed when the function that called
.BR alloca ()
returns to its caller.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR alloca ()
function returns a pointer to the beginning of the allocated space.
-If the allocation causes stack overflow, program behaviour is undefined.
-.SH "CONFORMING TO"
+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).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR alloca ()
+T} Thread safety MT-Safe
+.TE
+.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.
+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.
-This function is not in POSIX.1-2001.
.SH NOTES
-.SH Notes on the GNU Version
+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,
-.B gcc
+.BR gcc (1)
translates calls to
.BR alloca ()
-by inlined code.
-This is not done when either the \-ansi or
-the \-fno\-builtin option is given.
-But beware!
-By default the glibc version of
+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 line:
-.nf
-
- # define alloca(size) __builtin_alloca (size)
-
-.fi
+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.
-.LP
-The fact that the code is inlined, means that it is impossible
-to take the address of this function, or to change its behaviour
+.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.
-.LP
+.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
-The
-.BR alloca ()
-function is machine and compiler dependent.
-On many systems
-its implementation is buggy.
-Its use is discouraged.
-.LP
+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
.BR alloca ()
would appear on the stack in the middle of the space for the
function arguments.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR brk (2),
-.BR pagesize (2),
-.BR calloc (3),
-.BR malloc (3),
-.BR realloc (3)
+.BR longjmp (3),
+.BR malloc (3)
projects / thirdparty / man-pages.git / blobdiff