1.\" $NetBSD: __builtin_return_address.3,v 1.1 2010/12/19 09:30:50 jruoho Exp $ 2.\" 3.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd December 19, 2010 28.Dt __BUILTIN_RETURN_ADDRESS 3 29.Os 30.Sh NAME 31.Nm __builtin_return_address 32.Nd the return address of a function 33.Sh SYNOPSIS 34.Ft void * 35.Fn __builtin_return_address "unsigned int level" 36.Ft void * 37.Fn __builtin_frame_address "unsigned int level" 38.Sh DESCRIPTION 39The 40.Fn __builtin_return_address 41is a 42.Tn GNU 43extension for obtaining the return address of the current function 44or one of the callers of the current function. 45.Pp 46The parameter 47.Fa level 48specifies the number of frames that should be scanned up in the call stack. 49A value 0 returns the address of the current function, 50a value 1 requests the address of the caller of the current function, 51a value 2 asks for the address of the caller's caller, and so forth. 52If the top of the call stack has been reached, the function will return 0. 53Note also that on some architectures it is only possible 54to determine the address of the current function. 55In such cases a value 0 is returned. 56Thus, it is usually safe to only use the value 0 for 57.Fa level . 58.Pp 59The 60.Fn __builtin_frame_address 61behaves similarly, but returns the address of the function 62frame rather than the return address of the function. 63.Sh SEE ALSO 64.Xr gcc 1 , 65.Xr __builtin_object_size 3 66.Sh CAVEATS 67These are non-standard, compiler-specific extensions. 68