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 .P
  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 .TS
  47 allbox;
  48 lbx lb lb
  49 l l l.
  50 Interface       Attribute       Value
  51 T{
  52 .na
  53 .nh
  54 .BR alloca ()
  55 T}      Thread safety   MT-Safe
  56 .TE
  57 .SH STANDARDS
  58 None.
  59 .SH HISTORY
  60 PWB, 32V.
  61 .SH NOTES
  62 The
  63 .BR alloca ()
  64 function is machine- and compiler-dependent.
  65 Because it allocates from the stack, it's faster than
  66 .BR malloc (3)
  67 and
  68 .BR free (3).
  69 In certain cases,
  70 it can also simplify memory deallocation in applications that use
  71 .BR longjmp (3)
  72 or
  73 .BR siglongjmp (3).
  74 Otherwise, its use is discouraged.
  75 .P
  76 Because the space allocated by
  77 .BR alloca ()
  78 is allocated within the stack frame,
  79 that space is automatically freed if the function return
  80 is jumped over by a call to
  81 .BR longjmp (3)
  82 or
  83 .BR siglongjmp (3).
  84 .P
  85 The space allocated by
  86 .BR alloca ()
  87 is
  88 .I not
  89 automatically deallocated if the pointer that refers to it
  90 simply goes out of scope.
  91 .P
  92 Do not attempt to
  93 .BR free (3)
  94 space allocated by
  95 .BR alloca ()!
  96 .P
  97 By necessity,
  98 .BR alloca ()
  99 is a compiler built-in, also known as
 100 .BR __builtin_alloca ().
 101 By default, modern compilers automatically translate all uses of
 102 .BR alloca ()
 103 into the built-in, but this is forbidden if standards conformance is requested
 104 .RI ( "\-ansi" ,
 105 .IR "\-std=c*" ),
 106 in which case
 107 .I <alloca.h>
 108 is required, lest a symbol dependency be emitted.
 109 .P
 110 The fact that
 111 .BR alloca ()
 112 is a built-in means it is impossible to take its address
 113 or to change its behavior by linking with a different library.
 114 .P
 115 Variable length arrays (VLAs) are part of the C99 standard,
 116 optional since C11, and can be used for a similar purpose.
 117 However, they do not port to standard C++, and, being variables,
 118 live in their block scope and don't have an allocator-like interface,
 119 making them unfit for implementing functionality like
 120 .BR strdupa (3).
 121 .SH BUGS
 122 Due to the nature of the stack, it is impossible to check if the allocation
 123 would overflow the space available, and, hence, neither is indicating an error.
 124 (However, the program is likely to receive a
 125 .B SIGSEGV
 126 signal if it attempts to access unavailable space.)
 127 .P
 128 On many systems
 129 .BR alloca ()
 130 cannot be used inside the list of arguments of a function call, because
 131 the stack space reserved by
 132 .BR alloca ()
 133 would appear on the stack in the middle of the space for the
 134 function arguments.
 135 .SH SEE ALSO
 136 .BR brk (2),
 137 .BR longjmp (3),
 138 .BR malloc (3)