rename.2: SEE ALSO: add rename(1)

[thirdparty/man-pages.git] / man3 / alloca.3

diff --git a/man3/alloca.3 b/man3/alloca.3
index 637d4a2486403623227169e6af092ee2ffced62b..9dc7695e8eb326e460874040aad2163e0ecbd15b 100644 (file)
--- a/man3/alloca.3
+++ b/man3/alloca.3
@@ -1,6 +1,7 @@
 .\" 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:
@@ -28,6 +29,7 @@
 .\" 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
 .\"
@@ -38,12 +40,12 @@
 .\"     Various rewrites and additions (notes on longjmp() and SIGSEGV).
 .\"     Weaken warning against use of alloca() (as per Debian bug 461100).
 .\"
-.TH ALLOCA 3 2008-01-24 "GNU" "Linux Programmer's Manual"
+.TH ALLOCA 3 2019-03-06 "GNU" "Linux Programmer's Manual"
 .SH NAME
 alloca \- allocate memory that is automatically freed
 .SH SYNOPSIS
 .B #include <alloca.h>
-.sp
+.PP
 .BI "void *alloca(size_t " size );
 .SH DESCRIPTION
 The
@@ -55,14 +57,26 @@ This temporary space is
 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 behavior is undefined.
-.SH "CONFORMING TO"
-This function is not in POSIX.1-2001.
-
+.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.
@@ -83,7 +97,7 @@ it can also simplify memory deallocation in applications that use
 or
 .BR siglongjmp (3).
 Otherwise, its use is discouraged.
-
+.PP
 Because the space allocated by
 .BR alloca ()
 is allocated within the stack frame,
@@ -92,7 +106,14 @@ 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
@@ -108,28 +129,32 @@ This is not done when either the
 .IR "\-std=c89" ,
 .IR "\-std=c99" ,
 or the
-.IR "\-fno\-builtin"
+.IR "\-std=c11"
 option is given
-(and the header
+.BR and
+the header
 .I <alloca.h>
-is not included).
-But beware!
-By default the glibc version of
+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
+.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.
@@ -138,7 +163,7 @@ 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
@@ -146,7 +171,7 @@ 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"
+.SH SEE ALSO
 .BR brk (2),
 .BR longjmp (3),
 .BR malloc (3)