[PATCH 2/2] alloca.3: rewrite NOTES

наб
2021-08-23T21:01:17Z

[-- Attachment #1: Type: text/plain, Size: 3203 bytes --]

This demistifies the internals and removes outdated information
and needless glibc guts

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
man3/alloca.3 | 66 ++++++++++++++++-----------------------------------
1 file changed, 21 insertions(+), 45 deletions(-)

diff --git a/man3/alloca.3 b/man3/alloca.3
index 5bceeabe1..133ca6ab3 100644
--- a/man3/alloca.3
+++ b/man3/alloca.3
@@ -84,20 +84,14 @@ T} Thread safety MT-Safe
.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.
+originates from PWB and 32V, and appears in all their derivatives.
.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).
+Because it allocates from the stack, it's always faster than
+.BR malloc (3)/ free (3).
In certain cases,
it can also simplify memory deallocation in applications that use
.BR longjmp (3)
@@ -125,51 +119,33 @@ 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
+.PP
+By necessity,
+.BR alloca ()
+is a compiler built-in, also known as
+.BR __builtin_alloca ().
+By default, modern compilers automatically translate plain
.BR alloca ()
-with inlined code.
-This is not done when either the
+calls, but this is forbidden if
.IR "\-ansi" ,
.IR "\-std=c89" ,
.IR "\-std=c99" ,
-or the
+or
.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
+are specified, in which case
.I <alloca.h>
-and that contains the lines:
+is required, lest an actual symbol dependency is emitted.
.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.
+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.
.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
+As it's untestable, there is no error indication if the allocation
+would overflow the space available for the stack.
+(However, the program is likely to receive a
.B SIGSEGV
-signal if it attempts to access the unallocated space.)
+signal if it attempts to access that space.)
.PP
On many systems
.BR alloca ()
--
2.20.1