xref: /minix3/lib/libc/stdlib/alloca.3 (revision 84d9c625bfea59e274550651111ae9edfdc40fbd)
1*84d9c625SLionel Sambuc.\"	$NetBSD: alloca.3,v 1.16 2012/10/24 22:56:27 wiz Exp $
22fe8fb19SBen Gras.\"
32fe8fb19SBen Gras.\" Copyright (c) 1980, 1991, 1993
42fe8fb19SBen Gras.\"	The Regents of the University of California.  All rights reserved.
52fe8fb19SBen Gras.\"
62fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
72fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
82fe8fb19SBen Gras.\" are met:
92fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
102fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
112fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
122fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
132fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
142fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors
152fe8fb19SBen Gras.\"    may be used to endorse or promote products derived from this software
162fe8fb19SBen Gras.\"    without specific prior written permission.
172fe8fb19SBen Gras.\"
182fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
192fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
202fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
212fe8fb19SBen Gras.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
222fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
232fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
242fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
252fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
262fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
272fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
282fe8fb19SBen Gras.\" SUCH DAMAGE.
292fe8fb19SBen Gras.\"
302fe8fb19SBen Gras.\"     from: @(#)alloca.3	8.1 (Berkeley) 6/4/93
312fe8fb19SBen Gras.\"
32*84d9c625SLionel Sambuc.Dd October 24, 2012
332fe8fb19SBen Gras.Dt ALLOCA 3
342fe8fb19SBen Gras.Os
352fe8fb19SBen Gras.Sh NAME
362fe8fb19SBen Gras.Nm alloca
372fe8fb19SBen Gras.Nd memory allocator
382fe8fb19SBen Gras.Sh LIBRARY
392fe8fb19SBen Gras.Lb libc
402fe8fb19SBen Gras.Sh SYNOPSIS
412fe8fb19SBen Gras.In stdlib.h
422fe8fb19SBen Gras.Ft void *
432fe8fb19SBen Gras.Fn alloca "size_t size"
442fe8fb19SBen Gras.Sh DESCRIPTION
452fe8fb19SBen GrasThe
462fe8fb19SBen Gras.Fn alloca
472fe8fb19SBen Grasfunction
482fe8fb19SBen Grasallocates
492fe8fb19SBen Gras.Fa size
502fe8fb19SBen Grasbytes of space in the stack frame of the caller.
512fe8fb19SBen GrasThis temporary space is automatically freed on
522fe8fb19SBen Grasreturn.
532fe8fb19SBen Gras.Sh RETURN VALUES
542fe8fb19SBen GrasThe
552fe8fb19SBen Gras.Fn alloca
562fe8fb19SBen Grasfunction returns a pointer to the beginning of the allocated space.
572fe8fb19SBen GrasIf the allocation failed, a
582fe8fb19SBen Gras.Dv NULL
592fe8fb19SBen Graspointer is returned.
602fe8fb19SBen Gras.Sh SEE ALSO
61*84d9c625SLionel Sambuc.Xr cc 1 ,
622fe8fb19SBen Gras.Xr brk 2 ,
632fe8fb19SBen Gras.Xr calloc 3 ,
642fe8fb19SBen Gras.Xr getpagesize 3 ,
652fe8fb19SBen Gras.Xr malloc 3 ,
66*84d9c625SLionel Sambuc.Xr realloc 3 ,
67*84d9c625SLionel Sambuc.Xr security 7
682fe8fb19SBen Gras.Sh CAVEATS
692fe8fb19SBen GrasFew limitations can be mentioned:
702fe8fb19SBen Gras.Bl -bullet
712fe8fb19SBen Gras.It
722fe8fb19SBen GrasThe
732fe8fb19SBen Gras.Fn alloca
74*84d9c625SLionel Sambucfunction is not part of any C standard and its use is not portable.
752fe8fb19SBen Gras.It
762fe8fb19SBen GrasThe
772fe8fb19SBen Gras.Fn alloca
78*84d9c625SLionel Sambucfunction should be supplied by the compiler because the compiler is allowed to
79*84d9c625SLionel Sambucmake assumptions about the stack and frame pointers.
80*84d9c625SLionel SambucThe libc
81*84d9c625SLionel Sambuc.Fn alloca
82*84d9c625SLionel Sambucimplementation cannot account for those assumptions.
83*84d9c625SLionel SambucWhile there is a
84*84d9c625SLionel Sambucmachine dependent implementation of
85*84d9c625SLionel Sambuc.Fn alloca
86*84d9c625SLionel Sambucin libc, its use is discouraged and in most cases it will not work.
87*84d9c625SLionel SambucUsing this implementation will produce linker warnings.
88*84d9c625SLionel Sambuc.It
89*84d9c625SLionel SambucThe
90*84d9c625SLionel Sambuc.Fn alloca
91*84d9c625SLionel Sambucfunction is unsafe because it cannot ensure that the pointer
922fe8fb19SBen Grasreturned points to a valid and usable block of memory.
932fe8fb19SBen GrasThe allocation made may exceed the bounds of the stack, or even go
942fe8fb19SBen Grasfurther into other objects in memory, and
952fe8fb19SBen Gras.Fn alloca
962fe8fb19SBen Grascannot determine such an error.
97*84d9c625SLionel SambucFor that all
982fe8fb19SBen Gras.Fn alloca
99*84d9c625SLionel Sambucallocations should be bounded and limited to a small size.
1002fe8fb19SBen Gras.It
1012fe8fb19SBen GrasSince
1022fe8fb19SBen Gras.Fn alloca
103*84d9c625SLionel Sambucmodifies the stack at runtime and the stack usage of each function frame
104*84d9c625SLionel Sambuccannot be predicted, it makes many compiler security features
105*84d9c625SLionel Sambuc(such as
106*84d9c625SLionel Sambuc.Xr cc 1
107*84d9c625SLionel Sambuc.Fl fstack-protector )
108*84d9c625SLionel Sambucuseless for the calling function.
1092fe8fb19SBen GrasSee
110f14fb602SLionel Sambuc.Xr security 7
1112fe8fb19SBen Grasfor a discussion.
1122fe8fb19SBen Gras.El
1132fe8fb19SBen Gras.\" .Sh HISTORY
1142fe8fb19SBen Gras.\" The
1152fe8fb19SBen Gras.\" .Fn alloca
1162fe8fb19SBen Gras.\" function appeared in
1172fe8fb19SBen Gras.\" .Bx ?? .
1182fe8fb19SBen Gras.\" The function appeared in 32v, pwb and pwb.2 and in 3bsd 4bsd
1192fe8fb19SBen Gras.\" The first man page (or link to a man page that I can find at the
1202fe8fb19SBen Gras.\" moment is 4.3...
121