man3/alloca.3

   1 '\" t
   2 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   6 .\"
   7 .\"     @(#)alloca.3    5.1 (Berkeley) 5/2/91
   8 .\"
   9 .\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith <faith@cs.unc.edu>
  10 .\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  11 .\" Modified 2002-07-17, aeb
  12 .\" 2008-01-24, mtk:
  13 .\"     Various rewrites and additions (notes on longjmp() and SIGSEGV).
  14 .\"     Weaken warning against use of alloca() (as per Debian bug 461100).
  15 .\"
  16 .TH alloca 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 alloca \- allocate memory that is automatically freed
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <alloca.h>
  25 .PP
  26 .BI "void *alloca(size_t " size );
  27 .fi
  28 .SH DESCRIPTION
  29 The
  30 .BR alloca ()
  31 function allocates
  32 .I size
  33 bytes of space in the stack frame of the caller.
  34 This temporary space is
  35 automatically freed when the function that called
  36 .BR alloca ()
  37 returns to its caller.
  38 .SH RETURN VALUE
  39 The
  40 .BR alloca ()
  41 function returns a pointer to the beginning of the allocated space.
  42 If the allocation causes stack overflow, program behavior is undefined.
  43 .SH ATTRIBUTES
  44 For an explanation of the terms used in this section, see
  45 .BR attributes (7).
  46 .ad l
  47 .nh
  48 .TS
  49 allbox;
  50 lbx lb lb
  51 l l l.
  52 Interface       Attribute       Value
  53 T{
  54 .BR alloca ()
  55 T}      Thread safety   MT-Safe
  56 .TE
  57 .hy
  58 .ad
  59 .sp 1
  60 .SH STANDARDS
  61 This function is not in POSIX.1.
  62 .PP
  63 .BR alloca ()
  64 originates from PWB and 32V, and appears in all their derivatives.
  65 .SH NOTES
  66 The
  67 .BR alloca ()
  68 function is machine- and compiler-dependent.
  69 Because it allocates from the stack, it's faster than
  70 .BR malloc (3)
  71 and
  72 .BR free (3).
  73 In certain cases,
  74 it can also simplify memory deallocation in applications that use
  75 .BR longjmp (3)
  76 or
  77 .BR siglongjmp (3).
  78 Otherwise, its use is discouraged.
  79 .PP
  80 Because the space allocated by
  81 .BR alloca ()
  82 is allocated within the stack frame,
  83 that space is automatically freed if the function return
  84 is jumped over by a call to
  85 .BR longjmp (3)
  86 or
  87 .BR siglongjmp (3).
  88 .PP
  89 The space allocated by
  90 .BR alloca ()
  91 is
  92 .I not
  93 automatically deallocated if the pointer that refers to it
  94 simply goes out of scope.
  95 .PP
  96 Do not attempt to
  97 .BR free (3)
  98 space allocated by
  99 .BR alloca ()!
 100 .PP
 101 By necessity,
 102 .BR alloca ()
 103 is a compiler built-in, also known as
 104 .BR __builtin_alloca ().
 105 By default, modern compilers automatically translate all uses of
 106 .BR alloca ()
 107 into the built-in, but this is forbidden if standards conformance is requested
 108 .RI ( "\-ansi" ,
 109 .IR "\-std=c*" ),
 110 in which case
 111 .I <alloca.h>
 112 is required, lest a symbol dependency be emitted.
 113 .PP
 114 The fact that
 115 .BR alloca ()
 116 is a built-in means it is impossible to take its address
 117 or to change its behavior by linking with a different library.
 118 .PP
 119 Variable length arrays (VLAs) are part of the C99 standard,
 120 optional since C11, and can be used for a similar purpose.
 121 However, they do not port to standard C++, and, being variables,
 122 live in their block scope and don't have an allocator-like interface,
 123 making them unfit for implementing functionality like
 124 .BR strdupa (3).
 125 .SH BUGS
 126 Due to the nature of the stack, it is impossible to check if the allocation
 127 would overflow the space available, and, hence, neither is indicating an error.
 128 (However, the program is likely to receive a
 129 .B SIGSEGV
 130 signal if it attempts to access unavailable space.)
 131 .PP
 132 On many systems
 133 .BR alloca ()
 134 cannot be used inside the list of arguments of a function call, because
 135 the stack space reserved by
 136 .BR alloca ()
 137 would appear on the stack in the middle of the space for the
 138 function arguments.
 139 .SH SEE ALSO
 140 .BR brk (2),
 141 .BR longjmp (3),
 142 .BR malloc (3)