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