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