From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/alloca.3 | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 man3/alloca.3 (limited to 'man3/alloca.3') diff --git a/man3/alloca.3 b/man3/alloca.3 new file mode 100644 index 0000000..6bf1791 --- /dev/null +++ b/man3/alloca.3 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 +.\" +.\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith +.\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond +.\" 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 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +alloca \- allocate memory that is automatically freed +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.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). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR alloca () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +None. +.SH HISTORY +PWB, 32V. +.SH NOTES +The +.BR alloca () +function is machine- and compiler-dependent. +Because it allocates from the stack, it's faster than +.BR malloc (3) +and +.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 ()! +.PP +By necessity, +.BR alloca () +is a compiler built-in, also known as +.BR __builtin_alloca (). +By default, modern compilers automatically translate all uses of +.BR alloca () +into the built-in, but this is forbidden if standards conformance is requested +.RI ( "\-ansi" , +.IR "\-std=c*" ), +in which case +.I +is required, lest a symbol dependency be emitted. +.PP +The fact that +.BR alloca () +is a built-in means it is impossible to take its address +or to change its behavior by linking with a different library. +.PP +Variable length arrays (VLAs) are part of the C99 standard, +optional since C11, and can be used for a similar purpose. +However, they do not port to standard C++, and, being variables, +live in their block scope and don't have an allocator-like interface, +making them unfit for implementing functionality like +.BR strdupa (3). +.SH BUGS +Due to the nature of the stack, it is impossible to check if the allocation +would overflow the space available, and, hence, neither is indicating an error. +(However, the program is likely to receive a +.B SIGSEGV +signal if it attempts to access unavailable 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) -- cgit v1.2.3