gcc/doc/gcc/extensions-to-the-c-language-family/getting-the-return-or-frame-address-of-a-function.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _return-address:
   7
   8 Getting the Return or Frame Address of a Function
   9 *************************************************
  10
  11 These functions may be used to get information about the callers of a
  12 function.
  13
  14 .. function:: void * __builtin_return_address (unsigned int level)
  15
  16   This function returns the return address of the current function, or of
  17   one of its callers.  The :samp:`{level}` argument is number of frames to
  18   scan up the call stack.  A value of ``0`` yields the return address
  19   of the current function, a value of ``1`` yields the return address
  20   of the caller of the current function, and so forth.  When inlining
  21   the expected behavior is that the function returns the address of
  22   the function that is returned to.  To work around this behavior use
  23   the :fn-attr:`noinline` function attribute.
  24
  25   The :samp:`{level}` argument must be a constant integer.
  26
  27   On some machines it may be impossible to determine the return address of
  28   any function other than the current one; in such cases, or when the top
  29   of the stack has been reached, this function returns an unspecified
  30   value.  In addition, ``__builtin_frame_address`` may be used
  31   to determine if the top of the stack has been reached.
  32
  33   Additional post-processing of the returned value may be needed, see
  34   ``__builtin_extract_return_addr``.
  35
  36   The stored representation of the return address in memory may be different
  37   from the address returned by ``__builtin_return_address``.  For example,
  38   on AArch64 the stored address may be mangled with return address signing
  39   whereas the address returned by ``__builtin_return_address`` is not.
  40
  41   Calling this function with a nonzero argument can have unpredictable
  42   effects, including crashing the calling program.  As a result, calls
  43   that are considered unsafe are diagnosed when the :option:`-Wframe-address`
  44   option is in effect.  Such calls should only be made in debugging
  45   situations.
  46
  47   On targets where code addresses are representable as ``void *``,
  48
  49   .. code-block:: c++
  50
  51     void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
  52
  53   gives the code address where the current function would return.  For example,
  54   such an address may be used with ``dladdr`` or other interfaces that work
  55   with code addresses.
  56
  57 .. function:: void * __builtin_extract_return_addr (void *addr)
  58
  59   The address as returned by ``__builtin_return_address`` may have to be fed
  60   through this function to get the actual encoded address.  For example, on the
  61   31-bit S/390 platform the highest bit has to be masked out, or on SPARC
  62   platforms an offset has to be added for the true next instruction to be
  63   executed.
  64
  65   If no fixup is needed, this function simply passes through :samp:`{addr}`.
  66
  67 .. function:: void * __builtin_frob_return_addr (void *addr)
  68
  69   This function does the reverse of ``__builtin_extract_return_addr``.
  70
  71 .. function:: void * __builtin_frame_address (unsigned int level)
  72
  73   This function is similar to ``__builtin_return_address``, but it
  74   returns the address of the function frame rather than the return address
  75   of the function.  Calling ``__builtin_frame_address`` with a value of
  76   ``0`` yields the frame address of the current function, a value of
  77   ``1`` yields the frame address of the caller of the current function,
  78   and so forth.
  79
  80   The frame is the area on the stack that holds local variables and saved
  81   registers.  The frame address is normally the address of the first word
  82   pushed on to the stack by the function.  However, the exact definition
  83   depends upon the processor and the calling convention.  If the processor
  84   has a dedicated frame pointer register, and the function has a frame,
  85   then ``__builtin_frame_address`` returns the value of the frame
  86   pointer register.
  87
  88   On some machines it may be impossible to determine the frame address of
  89   any function other than the current one; in such cases, or when the top
  90   of the stack has been reached, this function returns ``0`` if
  91   the first frame pointer is properly initialized by the startup code.
  92
  93   Calling this function with a nonzero argument can have unpredictable
  94   effects, including crashing the calling program.  As a result, calls
  95   that are considered unsafe are diagnosed when the :option:`-Wframe-address`
  96   option is in effect.  Such calls should only be made in debugging
  97   situations.