Module Name: src Committed By: jruoho Date: Sun Dec 19 09:30:50 UTC 2010
Modified Files: src/distrib/sets/lists/comp: mi src/share/man/man3: Makefile Added Files: src/share/man/man3: __builtin_return_address.3 Log Message: Document the __builtin_return_address() GNU extension. Again this is well justified due to the wide use of these non-standard extensions in the tree. To generate a diff of this commit: cvs rdiff -u -r1.1555 -r1.1556 src/distrib/sets/lists/comp/mi cvs rdiff -u -r1.65 -r1.66 src/share/man/man3/Makefile cvs rdiff -u -r0 -r1.1 src/share/man/man3/__builtin_return_address.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/distrib/sets/lists/comp/mi diff -u src/distrib/sets/lists/comp/mi:1.1555 src/distrib/sets/lists/comp/mi:1.1556 --- src/distrib/sets/lists/comp/mi:1.1555 Sun Dec 19 08:10:07 2010 +++ src/distrib/sets/lists/comp/mi Sun Dec 19 09:30:49 2010 @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.1555 2010/12/19 08:10:07 jruoho Exp $ +# $NetBSD: mi,v 1.1556 2010/12/19 09:30:49 jruoho Exp $ # # Note: don't delete entries from here - mark them as "obsolete" instead. # @@ -4908,7 +4908,9 @@ ./usr/share/man/cat3/__aligned.0 comp-c-catman .cat ./usr/share/man/cat3/__alignof__.0 comp-c-catman .cat ./usr/share/man/cat3/__arraycount.0 comp-c-catman .cat +./usr/share/man/cat3/__builtin_frame_address.0 comp-c-catman .cat ./usr/share/man/cat3/__builtin_object_size.0 comp-c-catman .cat +./usr/share/man/cat3/__builtin_return_address.0 comp-c-catman .cat ./usr/share/man/cat3/__cacheline_aligned.0 comp-c-catman .cat ./usr/share/man/cat3/__constfunc.0 comp-c-catman .cat ./usr/share/man/cat3/__dead.0 comp-c-catman .cat @@ -10997,7 +10999,9 @@ ./usr/share/man/html3/__aligned.html comp-c-htmlman html ./usr/share/man/html3/__alignof__.html comp-c-htmlman html ./usr/share/man/html3/__arraycount.html comp-c-htmlman html +./usr/share/man/html3/__builtin_frame_address.html comp-c-htmlman html ./usr/share/man/html3/__builtin_object_size.html comp-c-htmlman html +./usr/share/man/html3/__builtin_return_address.html comp-c-htmlman html ./usr/share/man/html3/__cacheline_aligned.html comp-c-htmlman html ./usr/share/man/html3/__constfunc.html comp-c-htmlman html ./usr/share/man/html3/__dead.html comp-c-htmlman html @@ -16886,7 +16890,9 @@ ./usr/share/man/man3/__aligned.3 comp-c-man .man ./usr/share/man/man3/__alignof__.3 comp-c-man .man ./usr/share/man/man3/__arraycount.3 comp-c-man .man +./usr/share/man/man3/__builtin_frame_address.3 comp-c-man .man ./usr/share/man/man3/__builtin_object_size.3 comp-c-man .man +./usr/share/man/man3/__builtin_return_address.3 comp-c-man .man ./usr/share/man/man3/__cacheline_aligned.3 comp-c-man .man ./usr/share/man/man3/__constfunc.3 comp-c-man .man ./usr/share/man/man3/__dead.3 comp-c-man .man Index: src/share/man/man3/Makefile diff -u src/share/man/man3/Makefile:1.65 src/share/man/man3/Makefile:1.66 --- src/share/man/man3/Makefile:1.65 Sun Dec 19 08:10:08 2010 +++ src/share/man/man3/Makefile Sun Dec 19 09:30:50 2010 @@ -1,8 +1,9 @@ -# $NetBSD: Makefile,v 1.65 2010/12/19 08:10:08 jruoho Exp $ +# $NetBSD: Makefile,v 1.66 2010/12/19 09:30:50 jruoho Exp $ # @(#)Makefile 8.2 (Berkeley) 12/13/93 MAN= _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \ - __alignof__.3 __arraycount.3 __insn_barrier.3 \ + __alignof__.3 __arraycount.3 \ + __builtin_return_address.3 __insn_barrier.3 \ assert.3 attribute.3 bits.3 bitstring.3 \ cdefs.3 dirent.3 dlfcn.3 dl_iterate_phdr.3 end.3 \ fast_divide32.3 ffs32.3 gcq.3 \ @@ -15,6 +16,7 @@ MLINKS+=__CONCAT.3 __STRING.3 MLINKS+=__UNCONST.3 __UNVOLATILE.3 +MLINKS+=__builtin_return_address.3 __builtin_frame_address.3 MLINKS+=attribute.3 __dead.3 \ attribute.3 __pure.3 \ attribute.3 __constfunc.3 \ Added files: Index: src/share/man/man3/__builtin_return_address.3 diff -u /dev/null src/share/man/man3/__builtin_return_address.3:1.1 --- /dev/null Sun Dec 19 09:30:50 2010 +++ src/share/man/man3/__builtin_return_address.3 Sun Dec 19 09:30:50 2010 @@ -0,0 +1,67 @@ +.\" $NetBSD: __builtin_return_address.3,v 1.1 2010/12/19 09:30:50 jruoho Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruoho...@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.