git: 4da237aee328 - main - alloca.3: Add entry about defining VLAs in same block as alloca() to BUGS

The branch main has been updated by obiwac:

URL: https://cgit.FreeBSD.org/src/commit/?id=4da237aee328f368cd85b659854c4556a39f15ef

commit 4da237aee328f368cd85b659854c4556a39f15ef
Author:     Aymeric Wibo <obiwac@FreeBSD.org>
AuthorDate: 2026-02-19 14:47:06 +0000
Commit:     Aymeric Wibo <obiwac@FreeBSD.org>
CommitDate: 2026-03-13 13:08:31 +0000

    alloca.3: Add entry about defining VLAs in same block as alloca() to BUGS
    
    Refer to alloca() as a (builtin) function or macro, as it could be
    defined as either depending on the compiler.
    
    Paragraph about bug comes from Darwin's libc, and example added to
    illustrate it.
    
    Reviewed by:    bnovkov
    Approved by:    bnovkov
    MFC after:      3 days
    Obtained from:  https://github.com/apple-oss-distributions/libc (partially)
    Sponsored by:   Klara, Inc.
    Differential Revision:  https://reviews.freebsd.org/D55370
---
 share/man/man3/alloca.3 | 40 +++++++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/share/man/man3/alloca.3 b/share/man/man3/alloca.3
index fd88014dbb33..9e905d4487f3 100644
--- a/share/man/man3/alloca.3
+++ b/share/man/man3/alloca.3
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
+.\" Copyright (c) 2026 Aymeric Wibo <obiwac@freebsd.org>
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -25,7 +26,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 29, 2025
+.Dd February 19, 2026
 .Dt ALLOCA 3
 .Os
 .Sh NAME
@@ -38,16 +39,14 @@
 .Sh DESCRIPTION
 The
 .Fn alloca
-function
-allocates
+function or macro allocates
 .Fa size
 bytes of space in the stack frame of the caller.
 This temporary space is automatically freed on
 return.
 .Sh RETURN VALUES
-The
 .Fn alloca
-function returns a pointer to the beginning of the allocated space.
+returns a pointer to the beginning of the allocated space.
 .Sh SEE ALSO
 .Xr brk 2 ,
 .Xr calloc 3 ,
@@ -55,24 +54,20 @@ function returns a pointer to the beginning of the allocated space.
 .Xr malloc 3 ,
 .Xr realloc 3
 .Sh HISTORY
-The
 .Fn alloca
-function appeared in
+appeared in
 .At 32v .
 .\" .Bx ?? .
 .\" The function appeared in 32v, pwb and pwb.2 and in 3bsd 4bsd
 .\" The first man page (or link to a man page that I can find at the
 .\" moment is 4.3...
 .Sh BUGS
-The
 .Fn alloca
-function
 is machine and compiler dependent;
 its use is discouraged.
 .Pp
-The
 .Fn alloca
-function is slightly unsafe because it cannot ensure that the pointer
+is slightly unsafe because it cannot ensure that the pointer
 returned points to a valid and usable block of memory.
 The allocation made may exceed the bounds of the stack, or even go
 further into other objects in memory, and
@@ -81,3 +76,26 @@ cannot determine such an error.
 Avoid
 .Fn alloca
 with large unbounded allocations.
+.Pp
+The use of C99 variable-length arrays and
+.Fn alloca
+in the same function will cause the lifetime of
+.Fn alloca Ns 's
+storage to be limited to the block containing the
+.Fn alloca .
+For example, in the following snippet,
+.Va p Ns 's
+lifetime does not extend outside of the block, whereas it would've if
+.Va vla
+hadn't been defined or had been defined as a fixed-length array:
+.Bd -literal -offset indent
+char *p;
+{
+	const int n = 100;
+	int vla[n];
+	p = alloca(32);
+	strcpy(p, "Hello, world!");
+	printf("Inside: %s\\n", p); /* Valid. */
+}
+printf("Outside: %s\\n", p); /* Undefined. */
+.Ed