1.\" $NetBSD: STACK.9,v 1.2 2011/04/08 07:55:04 jruoho Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jukka Ruohonen. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 8, 2011 31.Dt STACK 9 32.Os 33.Sh NAME 34.Nm STACK 35.Nd stack macros 36.Sh SYNOPSIS 37.In sys/param.h 38.Ft type 39.Fn STACK_ALLOC "sp" "size" 40.Ft type 41.Fn STACK_MAX "sp" "size" 42.Ft type 43.Fn STACK_ALIGN "sp" "bytes" 44.Ft type 45.Fn STACK_GROW "sp" "size" 46.Ft type 47.Fn STACK_SHRINK "sp" "size" 48.Sh DESCRIPTION 49A stack is an area of memory with a fixed origin but with a variable size. 50A stack pointer points to the most recently referenced location on the stack. 51Initially, when the stack has a size of zero, 52the stack pointer points to the origin of the stack. 53When data items are added to the stack, 54the stack pointer moves away from the origin. 55.Pp 56The 57.Fn STACK_ALLOC 58macro returns a pointer to allocated stack space of some 59.Fa size . 60Given the returned pointer 61.Fa sp 62and 63.Fa size , 64.Fn STACK_MAX 65returns the maximum stack address of the allocated stack space. 66The 67.Fn STACK_ALIGN 68macro can be used to align the stack pointer 69.Fa sp 70by the specified amount of 71.Fa bytes . 72.Pp 73Two basic operations are common to all stacks: 74a data item is added 75.Pq Dq push 76to the location pointed by 77.Fa sp 78or a data item is removed 79.Pq Dq pop 80from the stack. 81The stack pointer must be subsequently adjusted by the size of the data item. 82The 83.Fn STACK_GROW 84and 85.Fn STACK_SHRINK 86macros adjust the stack pointer 87.Fa sp 88by given 89.Fa size . 90.Pp 91A stack may grow either up or down. 92The described macros take this into account by using the 93.Dv __MACHINE_STACK_GROWS_UP 94preprocessor define. 95.Sh SEE ALSO 96.Xr param 3 , 97.Xr queue 3 98